casbin-receipt-watcher

Casbin WatcherEx implementation that signs every policy mutation with Ed25519, producing independently verifiable Veritas Acta receipts.

The first WatcherEx implementation with a cryptographic audit trail.

Install

npm install casbin-receipt-watcher casbin

Usage

import { newEnforcer } from 'casbin';
import { ReceiptWatcher } from 'casbin-receipt-watcher';

const watcher = new ReceiptWatcher({
  privateKeyHex: process.env.SIGNING_KEY,
  issuerId: 'casbin:my-service',
});

const enforcer = await newEnforcer('model.conf', 'policy.csv');
enforcer.setWatcher(watcher);

// Every policy change now produces a signed receipt
await enforcer.addPolicy('alice', '/api/data', 'read');

// Inspect receipts
console.log(watcher.receipts);

What it does

Every time a Casbin policy is modified (add, remove, save), the watcher:

1. Captures the mutation details (section, ptype, params)
2. Canonicalizes the event using JCS (RFC 8785)
3. Signs with Ed25519 (RFC 8032)
4. Emits a signed receipt to configured output(s)

Receipts are independently verifiable by anyone, offline, forever:

import { verifyReceipt } from 'casbin-receipt-watcher';

const valid = verifyReceipt(receipt); // true if untampered

Or with the Veritas Acta CLI:

npx @veritasacta/verify receipt.json

Configuration

new ReceiptWatcher({
  // Required: Ed25519 private key (hex, 64+ chars)
  privateKeyHex: '...',

  // Optional: issuer identifier (default: "casbin:default")
  issuerId: 'casbin:my-service',

  // Optional: output destination(s) (default: console)
  output: [
    { type: 'console' },
    { type: 'callback', fn: (receipt) => db.insert(receipt) },
    { type: 'http', url: 'https://api.example.com/receipts' },
    { type: 'file', path: '/var/log/casbin-receipts.jsonl' },
  ],
});

Receipt format

{
  "receipt_id": "rec_casbin_a8f3b291c4d5e6f7",
  "receipt_version": "1.0",
  "issuer_id": "casbin:my-service",
  "event_time": "2026-04-15T03:22:41.891Z",
  "event_type": "policy_mutation",
  "mutation_type": "add_policy",
  "section": "p",
  "ptype": "p",
  "params": [["alice", "/api/data", "read"]],
  "model_hash": "sha256:b7e2...",
  "public_key": "4437ca56815c0516...",
  "signature": "4cde814b7889e987..."
}

WatcherEx methods covered

| Method | Receipt mutation_type | |--------|----------------------| | updateForAddPolicy | add_policy | | updateForRemovePolicy | remove_policy | | updateForRemoveFilteredPolicy | remove_filtered_policy | | updateForSavePolicy | save_policy | | updateForAddPolicies | add_policies | | updateForRemovePolicies | remove_policies |

Standards

• Ed25519 (RFC 8032) for digital signatures
• JCS (RFC 8785) for deterministic JSON canonicalization
• Veritas Acta receipt format for interoperability

Related

• protect-mcp - MCP gateway with Cedar policies + receipt signing
• @veritasacta/verify - Offline receipt verification CLI
• Veritas Acta - Open protocol for verifiable machine decisions

License

MIT