@observer-protocol/hermes-gate 0.1.0 → 0.1.1

package/README.md

@@ -1,157 +1,302 @@
 # @observer-protocol/hermes-gate
 
-Fail-closed spend gate for Hermes agent operators. Enforces a signed SpendMandate and WalletBindingCredential (WBC) before any payment action, using the Observer Protocol BIND→LINK→AUTHORIZE pipeline.
+A fail-closed spend gate for Hermes agents. Set what your agent can pay and how much; enforced below the skill layer so a hostile skill cannot move money outside the rules you set.
 
-The gate checks three things on every call:
+> **Status: community tier.** Binding-on-chain enforcement is on the roadmap. See *What this protects against* for exactly where the line is. We would rather you know the boundary than discover it.
 
-1. **BIND** — `wallet_id` in the request matches the wallet address bound in the WBC
-2. **LINK** — WBC issuer matches the mandate issuer (same principal)
-3. **AUTHORIZE** — amount, rail, and currency are within the mandate's ceilings and allowed rails
+---
 
-Any step that fails returns `allow: false` and stops.
+## What it is
+
+`hermes-gate` sits between your agent and its wallet. Your agent asks to spend; the gate checks the request against a spend mandate you signed, and allows or denies. Fail-closed: anything it cannot verify is denied, not waved through. The gate runs as an MCP server your Hermes agent calls.
+
+You are the principal. You anoint your own agent with your own key and issue your own spend mandate. No external service is in the loop, no account, no domain. The gate verifies offline.
+
+---
 
 ## Prerequisites
 
 - Node 20 or later
 - npm
+- For `provision` and `verify`: a Linux server, root access, and two dedicated system users (agent user and wallet-service user)
+
+---
 
-## Install
+## Install and generate
 
 ```
-npm install @observer-protocol/hermes-gate
+npx @observer-protocol/hermes-gate bootstrap generate
 ```
 
-## Quickstart
-
-### 1. Generate key material
+After a global install (`npm install -g @observer-protocol/hermes-gate`), the same command is:
 
 ```
-npx hermes-gate bootstrap generate
+hermes-gate bootstrap generate
 ```
 
-Writes six files to `./output/`:
+`generate` creates three keys, one mandate, and one wallet-binding credential:
 
-| File | Placement | Mode |
-|------|-----------|------|
-| `principal-key.json` | **Move offline immediately** | 600 |
-| `agent-identity-key.json` | `/home/<agent-user>/identity/did-key.json` | 600 |
-| `wallet-seed.json` | `/home/<wallet-user>/secrets/wallet-seed.json` | 600 |
-| `wallet-identity-key.json` | `/home/<wallet-user>/secrets/wallet-key.json` | 600 |
-| `spend-mandate.json` | `/home/<agent-user>/spend-mandate.json` | 644 |
-| `wbc.json` | `/home/<agent-user>/wbc.json` | 644 |
+1. **Principal key** (`principal-key.json`): a `did:key`, self-contained, no domain required. You sign your mandate with this key. It is written at mode 600 and must be moved offline immediately after generate runs.
+2. **Agent identity key** (`agent-identity-key.json`): the key the agent user holds on the server. It carries no spend authority; mode 600.
+3. **Wallet identity key** (`wallet-identity-key.json`) and **wallet seed** (`wallet-seed.json`): held by the wallet-service user. The wallet-binding credential ties this key to your mandate. Both written at mode 600.
+4. **SpendMandate** (`spend-mandate.json`): your spending rules, signed by your principal key; mode 644.
+5. **WalletBindingCredential** (`wbc.json`): your principal signs that this wallet address is bound to the mandate; mode 644.
 
-All four key files are written at mode 600 by generate.
+All six files go to `./output/` by default.
 
-### 2. Move the principal key offline
+---
 
-The principal key is only needed to re-issue credentials. It must not stay on the server:
+## Move the principal key offline
+
+This step is not optional.
+
+`./output/principal-key.json` contains the key material that signed your mandate. The gate does not need it at runtime. Move it off the server before the gate starts:
 
 ```
 cp output/principal-key.json /path/to/offline/storage
 rm output/principal-key.json
 ```
 
-### 3. Start the gate
+An attacker with the principal key can re-issue credentials. An attacker with only the agent key or wallet key cannot rewrite your mandate.
 
-```
-HERMES_MANDATE_PATH=./output/spend-mandate.json \
-  HERMES_AGENT_DID=<agent-did-from-generate-output> \
-  node node_modules/@observer-protocol/hermes-gate/src/mcp-server.js
-```
+---
+
+## The two-user boundary
+
+The bootstrap provisions two system users, and this is the security model, not optional ceremony.
+
+The **agent user** holds the agent identity key. It carries no spend authority and cannot read the wallet seed.
+
+The **wallet-service user** holds the wallet seed. It is the only path to signing.
+
+Your agent reaches spend authorization only through the gate's narrow MCP interface. A hostile skill running as the agent has no path to the wallet seed: it has to go through the gate, and the gate fails closed.
 
-WBC auto-discovery: if `HERMES_WBC_PATH` is unset, the gate looks for `wbc.json` in the same directory as the mandate. Placing `wbc.json` alongside `spend-mandate.json` means no extra config is needed.
+---
 
-If neither `HERMES_WBC_PATH` nor an adjacent `wbc.json` is found, the gate starts in passthrough mode and logs a loud warning to stderr. This path is reserved for enterprise callers who explicitly opt out of wallet binding. Community installs should always have a WBC.
+## Wire up the gate
 
-## Production: two-server G1 setup
+After `generate`, `./output/` contains `spend-mandate.json` and `wbc.json` in the same directory. The gate auto-discovers `wbc.json` when it sits alongside the mandate; no `HERMES_WBC_PATH` is needed.
 
-For OS-level isolation between the agent identity (who the agent is) and the wallet seed (what it can spend), use provision and verify. Run these as root on the target server:
+`generate` prints the exact start command for your agent DID:
 
 ```
-sudo npx hermes-gate bootstrap provision \
-  --agent-user atlas \
-  --wallet-user atlas-wallet
+HERMES_MANDATE_PATH=/home/<agent-user>/spend-mandate.json \
+  HERMES_AGENT_DID=did:key:z6Mk... \
+  node /path/to/hermes-gate/src/mcp-server.js
 ```
 
-Then confirm the boundary is secure:
+With `wbc.json` alongside the mandate, the gate comes up in bound mode with no additional configuration.
+
+If neither `HERMES_WBC_PATH` nor an adjacent `wbc.json` is found at startup, the gate logs this to stderr and enters passthrough mode:
 
 ```
-sudo npx hermes-gate bootstrap verify \
-  --agent-user atlas \
-  --wallet-user atlas-wallet
+WARNING: No WalletBindingCredential configured.
+  HERMES_WBC_PATH is unset and wbc.json was not found alongside the mandate.
+  Gate is in pe-042 PASSTHROUGH mode — wallet identity is NOT verified.
+  ...
 ```
 
-Provision places files at the paths and modes listed above and sets directory permissions (`chmod 700 /home/<wallet-user>/secrets`). Verify runs three cross-boundary deny tests and exits non-zero if any boundary is broken.
+Passthrough means the wallet-binding check is skipped; a wrong wallet ID returns `allow:true`. This is not a valid community install. Never ignore the warning.
 
-## Runtime configuration
+**For Hermes** (`~/.hermes/config.yaml`), add the gate manually:
 
-| Variable | Default | Notes |
-|----------|---------|-------|
-| `HERMES_MANDATE_PATH` | `~/spend-mandate.json` | Path to the signed SpendMandate |
-| `HERMES_AGENT_DID` | read from `HERMES_IDENTITY_PATH` | Agent DID (did:key:...) |
-| `HERMES_IDENTITY_PATH` | `~/identity/did-key.json` | Agent identity key file; ignored when `HERMES_AGENT_DID` is set |
-| `HERMES_WBC_PATH` | auto-discovered | Path to wbc.json; auto-discovered from mandate directory if unset |
+```yaml
+mcp_servers:
+  hermes-gate:
+    command: node
+    args:
+      - /path/to/hermes-gate/src/mcp-server.js
+    env:
+      HERMES_MANDATE_PATH: /home/atlas/spend-mandate.json
+      HERMES_AGENT_DID: "did:key:z6Mk..."
+    timeout: 30
+```
 
-## MCP config
+`wbc.json` alongside the mandate is auto-discovered. Set `HERMES_WBC_PATH` explicitly only if it lives at a different path.
 
-Add to your Claude Desktop or Claude Code MCP settings:
+**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "hermes-gate": {
       "command": "node",
-      "args": ["/opt/hermes-gate/src/mcp-server.js"],
+      "args": ["/path/to/hermes-gate/src/mcp-server.js"],
       "env": {
         "HERMES_MANDATE_PATH": "/home/atlas/spend-mandate.json",
-        "HERMES_AGENT_DID": "did:key:z6Mk...",
-        "HERMES_WBC_PATH": "/home/atlas/wbc.json"
+        "HERMES_AGENT_DID": "did:key:z6Mk..."
       }
     }
   }
 }
 ```
 
-Point `args[0]` at the mcp-server.js from your installed or deployed copy of the package.
+---
+
+## Runtime env vars
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `HERMES_MANDATE_PATH` | `~/spend-mandate.json` | Path to the signed SpendMandate |
+| `HERMES_AGENT_DID` | read from `HERMES_IDENTITY_PATH` | Agent DID; set explicitly to skip the identity file |
+| `HERMES_IDENTITY_PATH` | `~/identity/did-key.json` | Agent identity key file; ignored when `HERMES_AGENT_DID` is set |
+| `HERMES_WBC_PATH` | auto-discovered | Path to wbc.json; auto-discovered from mandate directory if unset |
+| `HERMES_LEDGER_PATH` | alongside mandate | Path to the JSONL spend ledger; set when mandate declares `cumulative_budget` |
+
+---
+
+## Customize your mandate
+
+Set your limits at generate time with flags:
+
+```
+npx @observer-protocol/hermes-gate bootstrap generate \
+  --ceiling-amount 250 \
+  --ceil-currency USDT \
+  --allowed-rails ethereum-mainnet,lightning
+```
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--output-dir` | `./output` | Where to write generated files |
+| `--ceiling-amount` | `100` | Per-transaction ceiling |
+| `--ceil-currency` | `USDT` | Currency for the ceiling |
+| `--allowed-rails` | `ethereum-mainnet,lightning` | Comma-separated list of allowed rails |
+| `--daily-cap-amount` | none | Rolling 24h cumulative cap; enables ledger enforcement |
+| `--daily-cap-currency` | same as `--ceil-currency` | Currency for the daily cap |
+
+The ceiling applies to each individual transaction. A spend on a rail not in `--allowed-rails` is denied. If `--daily-cap-amount` is set, the gate also enforces a rolling 24h cumulative cap via a spend ledger — see below.
 
-## Bootstrap flags
+---
 
-`generate` accepts optional flags to customize the mandate:
+## Rolling daily cap
+
+When `--daily-cap-amount` is set, `generate` adds a `cumulative_budget` field to the mandate. At runtime the gate enforces a rolling 24h cumulative cap in addition to the per-transaction ceiling.
 
 ```
-npx hermes-gate bootstrap generate \
-  --output-dir ./output \
-  --allowed-rails ethereum-mainnet,lightning \
-  --ceiling-amount 500 \
+npx @observer-protocol/hermes-gate bootstrap generate \
+  --ceiling-amount 10 \
+  --daily-cap-amount 30 \
   --ceil-currency USDT
 ```
 
-`provision` requires `--agent-user` and `--wallet-user`. The optional `--output-dir` defaults to `./output`.
+This generates a mandate where:
+- Each individual transaction is capped at 10 USDT.
+- The total authorized in any rolling 24h window is capped at 30 USDT.
+- Call #4 of four 10-USDT calls returns `allow: false` with `ruleType: 'cumulativeCap'`.
+
+**How it works.** The gate maintains a JSONL spend ledger at `HERMES_LEDGER_PATH` (default: alongside the mandate). On each `gate_evaluate`, after the full BIND-LINK-AUTHORIZE gate passes, the gate sums ledger entries from the trailing 24h for the same rail and currency. If the sum plus the proposed amount would exceed the cap, the call is denied. On allow, the entry is recorded.
+
+**Rolling window, not calendar day.** The window is `(now - 86400000ms)` to `now` — not a midnight reset. No timezone dependency, no gameable boundary.
 
-`verify` requires `--agent-user` and `--wallet-user`. Must be run as root or with passwordless sudo configured.
+**Counts authorizations, not settlements.** The entry is written when the gate approves, not when the wallet service settles. Since `gate_execute` is a stub at the lite tier, counting settled transactions would never decrement the cap.
+
+**Durable across restart.** The ledger is a file on disk. Restarting the gate process does not reset the cap. The rolling window query picks up prior entries naturally.
+
+**Security boundary.** The ledger is on the agent-user side of the G1 boundary, mode 600. A malicious skill cannot reach it — it can only call `gate_evaluate`, and the gate controls the response. A fully-compromised gate process (which could delete the ledger file) is the binding-tier threat, out of scope for lite. The per-transaction ceiling and rail restriction remain enforced by the mandate signature regardless of ledger state.
+
+**To override the ledger path:**
+
+```
+HERMES_LEDGER_PATH=/home/atlas/spend-ledger.jsonl \
+  hermes-gate ...
+```
+
+The gate creates the ledger file on startup if it does not exist.
+
+---
+
+## Production: provision and verify
+
+For OS-level key isolation, run `provision` as root after `generate`:
+
+```
+sudo npx @observer-protocol/hermes-gate bootstrap provision \
+  --agent-user atlas \
+  --wallet-user atlas-wallet
+```
+
+Flags:
+
+| Flag | Required | Notes |
+|------|----------|-------|
+| `--agent-user` | yes | System user that runs the agent |
+| `--wallet-user` | yes | System user that runs the wallet service |
+| `--output-dir` | no | Source directory; defaults to `./output` |
+
+`provision` copies files and sets permissions:
+
+| File | Destination | Mode |
+|------|-------------|------|
+| `agent-identity-key.json` | `/home/<agent-user>/identity/did-key.json` | 600 |
+| `spend-mandate.json` | `/home/<agent-user>/spend-mandate.json` | 644 |
+| `wbc.json` | `/home/<agent-user>/wbc.json` | 644 |
+| `wallet-seed.json` | `/home/<wallet-user>/secrets/wallet-seed.json` | 600 |
+| `wallet-identity-key.json` | `/home/<wallet-user>/secrets/wallet-key.json` | 600 |
+
+The wallet-service user's home directory and secrets directory are set to mode 700.
+
+Then confirm the boundary is secure:
+
+```
+sudo npx @observer-protocol/hermes-gate bootstrap verify \
+  --agent-user atlas \
+  --wallet-user atlas-wallet
+```
+
+Flags: `--agent-user` and `--wallet-user` (required). No `--output-dir`.
+
+`verify` runs three cross-boundary deny tests. PASS means access was correctly denied. INCONCLUSIVE means sudo is not configured for this user; run as root or configure passwordless sudo. The command exits non-zero if any boundary is broken.
+
+---
 
 ## Gate tools
 
-**`gate_evaluate`** — Check whether a proposed spend is within the mandate. Returns `allow: true/false` with reasons. Call this before any payment action. Required params: `rail`, `amount` (positive decimal string), `currency`. Optional: `wallet_id` (required for BIND check when WBC is configured), `category`, `note`.
+**`gate_evaluate`**: Check whether a proposed spend is within the mandate. Call this before any payment. Returns `allow: true/false` with reasons.
+
+Required params: `rail` (string), `amount` (positive decimal string), `currency` (string).
+Optional: `wallet_id` (string, required for the BIND wallet-address check when a WBC is configured), `category`, `note`.
+
+**`gate_execute`**: Evaluate and, if allowed, signal the wallet service to submit. Returns the decision and a `tx_ref` placeholder (set by the wallet service after submission). The gate does not submit transactions itself.
+
+**`gate_status`**: Return gate health and mandate metadata (agent DID, mandate issuer, valid-until). Does not re-verify the mandate signature.
+
+---
+
+## Secrets and output/
+
+`generate` writes all four key files at mode 600. `output/` is in `.gitignore`.
+
+After generate:
+- Move `principal-key.json` offline immediately. Do not leave it on the server.
+- Do not commit `output/` or any key file.
+- `spend-mandate.json` and `wbc.json` are signed credentials readable by the gate (mode 644). They contain no key material.
+
+---
+
+## What this protects against, and what it does not
+
+**It protects against the malicious-skill threat.** A hostile skill, a prompt injection, a poisoned MCP server: anything trying to make your agent act outside your mandate is stopped at the gate, fail-closed. This is the threat the agent community has been burned by, and this tier closes it.
+
+**The current limit: the gate enforces against your agent's stated intent.** Your agent tells the gate what it is about to do, and the gate checks that against your mandate. This trusts your agent to report its own actions honestly. It is complete protection against external manipulation of an honest agent.
+
+**What it does not yet catch: a compromised or erratic agent that misreports.** If your own agent is itself compromised, hallucinating, or manipulated into building a transaction whose actual bytes differ from what it declares, this tier checks the declaration, not the wire. Closing that gap is the binding tier, on the roadmap.
+
+**Rails.** Binding enforcement is live for EVM stablecoins (USDT, USDC). Lightning support is advisory in this tier: the gate surfaces a decision but does not hard-enforce the Lightning payment. Binding Lightning enforcement lands with the binding tier. If you need a hard deny on Lightning today, that enforcement is not there yet.
 
-**`gate_execute`** — Evaluate and, if allowed, signal the wallet service to submit. Returns the decision plus `tx_ref` (set by the wallet service after submission). The gate does not submit the transaction itself.
+---
 
-**`gate_status`** — Return gate health and mandate metadata (agent DID, mandate issuer, valid-until). Does not re-verify the mandate signature.
+## Roadmap: the binding tier
 
-## Threat model
+The same gate, wired one level deeper: into your wallet's signing path instead of beside it, so it enforces against the actual transaction rather than your agent's description of it. This protects against the agent-itself threat (a rogue, hallucinating, or out-of-scope agent), and brings binding Lightning enforcement. It is the same product at a deeper integration depth. You will not switch; you will deepen the gate you already run.
 
-This gate enforces against agent-declared intent: the action the agent states (`rail`, `amount`, `currency`, `wallet_id`) is what gets checked.
+---
 
-What this gate blocks:
-- Spends above the mandate ceiling
-- Spends on disallowed rails
-- Calls where `wallet_id` does not match the bound wallet address
-- Calls with expired mandates
-- Any input that fails to parse (fail-closed)
+## Honest summary
 
-What this gate does not block: an agent that correctly states intent but submits a malformed or mismatched transaction directly to the wallet service after gate approval. That boundary is the wallet service's responsibility.
+`hermes-gate` (community tier): a fail-closed spend gate that a malicious skill cannot bypass, enforcing per-transaction ceilings, rolling 24h cumulative caps, and rail restrictions against your agent's intended spends, binding on EVM stablecoins, advisory on Lightning, installed in one command with the wallet you already have. The binding tier, which enforces against decoded on-chain transactions and protects against your own agent going off-script, is the roadmap.
 
-For stricter enforcement, use the `RuntimeAdapter` in `@observer-protocol/wdk-protocol-trust`, which decodes actual WDK transaction proposals and applies spend rules at the proposal layer before signing.
+---
 
 ## License
 

package/bin/hermes-gate.js

@@ -33,7 +33,9 @@ switch (sub) {
       agentLabel: flags.agentLabel,
       allowedRails: flags.allowedRails ? flags.allowedRails.split(',') : undefined,
       ceilingAmount: flags.ceilingAmount,
-      ceilCurrency: flags.ceilCurrency
+      ceilCurrency: flags.ceilCurrency,
+      dailyCapAmount: flags.dailyCapAmount,
+      dailyCapCurrency: flags.dailyCapCurrency
     })
     break
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@observer-protocol/hermes-gate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Fail-closed spend gate for Hermes agent operators — OP trust enforcement over a WDK wallet",
   "type": "module",
   "main": "index.js",
@@ -29,7 +29,7 @@
     "@observer-protocol/wdk-protocol-trust": "^0.2.0-beta.2"
   },
   "scripts": {
-    "test": "node --test tests/gate.test.js tests/bootstrap.test.js",
+    "test": "node --test tests/gate.test.js tests/bootstrap.test.js tests/ledger.test.js",
     "gate": "node src/mcp-server.js"
   },
   "exports": {

package/src/bootstrap.js

@@ -42,6 +42,8 @@ function toISO (d) {
  * @param {string[]} [opts.allowedRails] - Rails to permit (default: ethereum-mainnet + lightning)
  * @param {string} [opts.ceilingAmount] - Per-tx ceiling amount (default: 100)
  * @param {string} [opts.ceilCurrency] - Ceiling currency (default: USDT)
+ * @param {string} [opts.dailyCapAmount] - Rolling 24h cumulative cap; if set, adds cumulative_budget to mandate
+ * @param {string} [opts.dailyCapCurrency] - Currency for daily cap (defaults to ceilCurrency)
  * @returns {{ principalDid: string, agentDid: string, walletDid: string, mandateId: string }}
  */
 export function generate (opts = {}) {
@@ -50,7 +52,9 @@ export function generate (opts = {}) {
     agentLabel = 'agent',
     allowedRails = ['ethereum-mainnet', 'lightning'],
     ceilingAmount = '100',
-    ceilCurrency = 'USDT'
+    ceilCurrency = 'USDT',
+    dailyCapAmount = null,
+    dailyCapCurrency = null
   } = opts
 
   mkdirSync(outputDir, { recursive: true })
@@ -107,7 +111,14 @@ export function generate (opts = {}) {
         per_transaction_ceiling: {
           amount: ceilingAmount,
           currency: ceilCurrency
-        }
+        },
+        ...(dailyCapAmount ? {
+          cumulative_budget: {
+            amount: dailyCapAmount,
+            currency: dailyCapCurrency || ceilCurrency,
+            period: '24h'
+          }
+        } : {})
       },
       delegationScope: { may_delegate_further: false },
       enforcementMode: 'pre_transaction_check'
@@ -185,6 +196,9 @@ export function generate (opts = {}) {
   console.log('  Wallet DID:   ', wallet.did)
   console.log('  Mandate ID:   ', signedMandate.id)
   console.log('  Valid:        ', validFrom, '→', validUntil)
+  if (dailyCapAmount) {
+    console.log('  Daily cap:    ', dailyCapAmount, (dailyCapCurrency || ceilCurrency), '/ 24h rolling window (enforced via ledger)')
+  }
   console.log()
   console.log('PLACEMENT INSTRUCTIONS:')
   console.log()

package/src/gate.js

@@ -3,6 +3,7 @@
 
 'use strict'
 
+import { readFileSync } from 'node:fs'
 import { runRuntimeAdapter } from '@observer-protocol/wdk-protocol-trust'
 
 export class GateError extends Error {
@@ -38,8 +39,9 @@ export class SpendGate {
    * @param {string[]} [opts.trustedIssuers]           - Issuer DIDs the gate trusts
    * @param {string} [opts.walletBindingCredentialPath] - Path to wbc.json; when set, enforces BIND+LINK
    * @param {'dev'|'full'} [opts.issuanceMode]         - Governs LINK check; defaults to 'dev'
+   * @param {import('./spend-ledger.js').SpendLedger} [opts.spendLedger] - Ledger for rolling 24h cap; required when mandate declares cumulative_budget
    */
-  constructor ({ mandatePath, agentDid, trustedIssuers, walletBindingCredentialPath, issuanceMode }) {
+  constructor ({ mandatePath, agentDid, trustedIssuers, walletBindingCredentialPath, issuanceMode, spendLedger }) {
     if (!mandatePath || typeof mandatePath !== 'string') throw new GateError('CONFIG', 'mandatePath required')
     if (!agentDid || typeof agentDid !== 'string') throw new GateError('CONFIG', 'agentDid required')
     this._config = {
@@ -49,6 +51,7 @@ export class SpendGate {
       walletBindingCredentialPath,
       issuanceMode
     }
+    this._spendLedger = spendLedger || null
   }
 
   /**
@@ -67,7 +70,24 @@ export class SpendGate {
    * @returns {Promise<{ allow: boolean, reasons: object[], advisories: object[], mandateValidUntil: string }>}
    */
   async evaluate (action) {
+    // Read cumulative_budget from mandate before calling runRuntimeAdapter so
+    // we have cap metadata ready if allow:true. Re-read matches runRuntimeAdapter's
+    // own re-read on every call, picking up key rotation without a gate restart.
+    let dailyCap = null
+    if (this._spendLedger) {
+      try {
+        const raw = JSON.parse(readFileSync(this._config.mandatePath, 'utf8'))
+        const budget = raw.credentialSubject?.actionScope?.cumulative_budget
+        if (budget?.amount && budget?.currency) {
+          dailyCap = { amount: parseFloat(budget.amount), currency: budget.currency }
+        }
+      } catch {
+        // mandate read failure is surfaced below by runRuntimeAdapter
+      }
+    }
+
     const result = await runRuntimeAdapter(action, this._config)
+
     // Surface GateError on gate-internal failures so callers can distinguish
     // mandate/config issues from policy denials.
     if (!result.allow && result.reasons.some(r => r.ruleField === 'mandate_read')) {
@@ -85,6 +105,28 @@ export class SpendGate {
     if (!result.allow && result.reasons.some(r => r.ruleField === 'untrusted_issuer')) {
       throw new GateError('UNTRUSTED_ISSUER', result.reasons[0].message)
     }
+
+    // Cumulative cap enforcement — runs after the full BIND→LINK→AUTHORIZE gate
+    // passes. The check lives here (stateful orchestration layer), not inside
+    // withinScope, preserving withinScope's I/O-free evaluator invariant.
+    if (result.allow && this._spendLedger && dailyCap && dailyCap.currency === action.currency) {
+      const windowSum = this._spendLedger.sumWindow(action.rail, action.currency)
+      const proposed = parseFloat(action.amount)
+      if (windowSum + proposed > dailyCap.amount) {
+        return {
+          allow: false,
+          reasons: [{
+            ruleType: 'cumulativeCap',
+            ruleField: 'cumulative_budget',
+            message: `Rolling 24h cap exceeded: ${windowSum.toFixed(2)} + ${proposed} > ${dailyCap.amount} ${dailyCap.currency} on rail ${action.rail}`
+          }],
+          advisories: result.advisories,
+          mandateValidUntil: result.mandateValidUntil
+        }
+      }
+      this._spendLedger.record({ rail: action.rail, amount: action.amount, currency: action.currency })
+    }
+
     return {
       allow: result.allow,
       reasons: result.reasons,

package/src/mcp-server.js

@@ -12,6 +12,7 @@ import {
   ListToolsRequestSchema
 } from '@modelcontextprotocol/sdk/types.js'
 import { SpendGate } from './gate.js'
+import { SpendLedger } from './spend-ledger.js'
 
 // ── Config from environment ───────────────────────────────────────────────
 
@@ -32,6 +33,32 @@ if (!WBC_PATH) {
   console.error('  HERMES_WBC_PATH=<path/to/wbc.json> or place wbc.json alongside the mandate.')
 }
 
+// Spend ledger for rolling 24h cumulative cap. Created only when the mandate
+// declares cumulative_budget (or HERMES_LEDGER_PATH is set explicitly).
+// Default path: alongside the mandate, on the agent-user side of the G1 boundary.
+const LEDGER_PATH = process.env.HERMES_LEDGER_PATH || join(dirname(resolve(MANDATE_PATH)), 'spend-ledger.jsonl')
+
+function loadSpendLedger () {
+  if (process.env.HERMES_LEDGER_PATH) {
+    return new SpendLedger(process.env.HERMES_LEDGER_PATH)
+  }
+  try {
+    const m = JSON.parse(readFileSync(MANDATE_PATH, 'utf8'))
+    if (m.credentialSubject?.actionScope?.cumulative_budget) {
+      return new SpendLedger(LEDGER_PATH)
+    }
+  } catch {
+    // mandate unreadable at startup — gate will surface this on first evaluate
+  }
+  return null
+}
+
+const spendLedger = loadSpendLedger()
+if (spendLedger) {
+  spendLedger.prune()
+  console.error(`hermes-gate: rolling 24h cap active — ledger at ${LEDGER_PATH}`)
+}
+
 // Load agent DID from identity file (agent-user's key, not wallet seed)
 function loadAgentDid () {
   if (process.env.HERMES_AGENT_DID) return process.env.HERMES_AGENT_DID
@@ -100,7 +127,8 @@ const gate = new SpendGate({
   mandatePath: MANDATE_PATH,
   agentDid,
   trustedIssuers: mandateIssuer ? [mandateIssuer] : [],
-  walletBindingCredentialPath: WBC_PATH || undefined
+  walletBindingCredentialPath: WBC_PATH || undefined,
+  spendLedger: spendLedger || undefined
 })
 
 const server = new Server(

package/src/spend-ledger.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// Part of @observer-protocol/hermes-gate
+
+'use strict'
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const WINDOW_MS = 24 * 60 * 60 * 1000       // 24h rolling window
+const PRUNE_AFTER_MS = 25 * 60 * 60 * 1000   // prune entries older than this
+
+/**
+ * Append-only JSONL spend ledger for rolling 24h cumulative cap enforcement.
+ *
+ * Written on each authorized spend — when the full BIND→LINK→AUTHORIZE gate
+ * returns allow:true. Single writer (one gate process); no concurrent access.
+ *
+ * Security boundary: the ledger secures against the malicious-skill threat
+ * (lite tier). A malicious skill can only call gate_evaluate; it cannot reach
+ * the filesystem. A fully-compromised gate process that deletes the ledger
+ * resets the cap — that is the binding-tier threat, out of scope for lite.
+ *
+ * The ledger file must be:
+ *   - Mode 600, owned by the gate process user (agent-user side of G1 boundary)
+ *   - Not readable by the wallet-service user
+ */
+export class SpendLedger {
+  /**
+   * @param {string} path - Absolute path to the .jsonl ledger file
+   */
+  constructor (path) {
+    if (!path || typeof path !== 'string') throw new Error('SpendLedger: path required')
+    this._path = path
+    mkdirSync(dirname(path), { recursive: true })
+    if (!existsSync(path)) {
+      writeFileSync(path, '', { encoding: 'utf8', mode: 0o600 })
+    }
+  }
+
+  /**
+   * Record an authorized spend. Call when the full gate returns allow:true.
+   * @param {{ rail: string, amount: string, currency: string }} entry
+   */
+  record ({ rail, amount, currency }) {
+    const line = JSON.stringify({ ts: Date.now(), rail, amount, currency })
+    appendFileSync(this._path, line + '\n', { encoding: 'utf8' })
+  }
+
+  /**
+   * Sum authorized spends in the last 24h for a given rail+currency pair.
+   * Rolling window: entries where ts >= (now - 24h). Timezone-agnostic.
+   * @param {string} rail
+   * @param {string} currency
+   * @returns {number}
+   */
+  sumWindow (rail, currency) {
+    const cutoff = Date.now() - WINDOW_MS
+    let total = 0
+    try {
+      const lines = readFileSync(this._path, 'utf8').split('\n')
+      for (const line of lines) {
+        if (!line.trim()) continue
+        try {
+          const e = JSON.parse(line)
+          if (e.ts >= cutoff && e.rail === rail && e.currency === currency) {
+            total += parseFloat(e.amount) || 0
+          }
+        } catch {
+          // malformed line — skip
+        }
+      }
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      // file not found = no prior spends; return 0
+    }
+    return total
+  }
+
+  /**
+   * Prune entries older than 25h. Atomic rewrite via temp file + rename.
+   * Safe to call at startup to bound file growth across restarts.
+   */
+  prune () {
+    const cutoff = Date.now() - PRUNE_AFTER_MS
+    try {
+      const lines = readFileSync(this._path, 'utf8').split('\n')
+      const kept = []
+      for (const line of lines) {
+        if (!line.trim()) continue
+        try {
+          const e = JSON.parse(line)
+          if (e.ts >= cutoff) kept.push(line)
+        } catch {
+          // drop malformed lines on prune
+        }
+      }
+      const tmp = this._path + '.tmp'
+      writeFileSync(tmp, kept.join('\n') + (kept.length ? '\n' : ''), { encoding: 'utf8', mode: 0o600 })
+      renameSync(tmp, this._path)
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      // file doesn't exist yet — nothing to prune
+    }
+  }
+}