@observer-protocol/hermes-gate 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @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.
+
+The gate checks three things on every call:
+
+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.
+
+## Prerequisites
+
+- Node 20 or later
+- npm
+
+## Install
+
+```
+npm install @observer-protocol/hermes-gate
+```
+
+## Quickstart
+
+### 1. Generate key material
+
+```
+npx hermes-gate bootstrap generate
+```
+
+Writes six files to `./output/`:
+
+| 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 |
+
+All four key files are written at mode 600 by generate.
+
+### 2. Move the principal key offline
+
+The principal key is only needed to re-issue credentials. It must not stay on the server:
+
+```
+cp output/principal-key.json /path/to/offline/storage
+rm output/principal-key.json
+```
+
+### 3. Start the gate
+
+```
+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
+```
+
+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.
+
+## Production: two-server G1 setup
+
+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:
+
+```
+sudo npx hermes-gate bootstrap provision \
+  --agent-user atlas \
+  --wallet-user atlas-wallet
+```
+
+Then confirm the boundary is secure:
+
+```
+sudo npx hermes-gate bootstrap verify \
+  --agent-user atlas \
+  --wallet-user atlas-wallet
+```
+
+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.
+
+## Runtime configuration
+
+| 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 |
+
+## MCP config
+
+Add to your Claude Desktop or Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "hermes-gate": {
+      "command": "node",
+      "args": ["/opt/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"
+      }
+    }
+  }
+}
+```
+
+Point `args[0]` at the mcp-server.js from your installed or deployed copy of the package.
+
+## Bootstrap flags
+
+`generate` accepts optional flags to customize the mandate:
+
+```
+npx hermes-gate bootstrap generate \
+  --output-dir ./output \
+  --allowed-rails ethereum-mainnet,lightning \
+  --ceiling-amount 500 \
+  --ceil-currency USDT
+```
+
+`provision` requires `--agent-user` and `--wallet-user`. The optional `--output-dir` defaults to `./output`.
+
+`verify` requires `--agent-user` and `--wallet-user`. Must be run as root or with passwordless sudo configured.
+
+## 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_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.
+
+## Threat model
+
+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)
+
+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.
+
+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
+
+Apache-2.0

package/bin/hermes-gate.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { generate, provision, verify } from '../src/bootstrap.js'
+
+const [,, cmd, sub, ...rest] = process.argv
+
+function parseFlags (args) {
+  const flags = {}
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+      flags[key] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true
+    }
+  }
+  return flags
+}
+
+if (cmd !== 'bootstrap') {
+  console.error('Usage: hermes-gate bootstrap <generate|provision|verify> [flags]')
+  process.exit(1)
+}
+
+const flags = parseFlags(rest)
+
+switch (sub) {
+  case 'generate':
+    generate({
+      outputDir: flags.outputDir || './output',
+      agentLabel: flags.agentLabel,
+      allowedRails: flags.allowedRails ? flags.allowedRails.split(',') : undefined,
+      ceilingAmount: flags.ceilingAmount,
+      ceilCurrency: flags.ceilCurrency
+    })
+    break
+
+  case 'provision':
+    provision({
+      agentUser: flags.agentUser,
+      walletUser: flags.walletUser,
+      outputDir: flags.outputDir || './output'
+    })
+    break
+
+  case 'verify':
+    verify({
+      agentUser: flags.agentUser,
+      walletUser: flags.walletUser
+    })
+    break
+
+  default:
+    console.error('Usage: hermes-gate bootstrap <generate|provision|verify>')
+    process.exit(1)
+}

package/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+// @observer-protocol/hermes-gate
+
+'use strict'
+
+export { SpendGate, GateError } from './src/gate.js'
+export { generate, provision, verify } from './src/bootstrap.js'
+export { evaluateSpend, skillManifest } from './src/skill.js'

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@observer-protocol/hermes-gate",
+  "version": "0.1.0",
+  "description": "Fail-closed spend gate for Hermes agent operators — OP trust enforcement over a WDK wallet",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "hermes-gate": "./bin/hermes-gate.js"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "observer-protocol",
+    "hermes",
+    "wdk",
+    "spend-gate",
+    "did",
+    "agent-identity"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@observer-protocol/wdk-protocol-trust": "^0.2.0-beta.2"
+  },
+  "scripts": {
+    "test": "node --test tests/gate.test.js tests/bootstrap.test.js",
+    "gate": "node src/mcp-server.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/src/bootstrap.js

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: Apache-2.0
+// Part of @observer-protocol/hermes-gate
+
+'use strict'
+
+import { randomBytes } from 'node:crypto'
+import { writeFileSync, mkdirSync, cpSync, chmodSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { join } from 'node:path'
+import {
+  createDidKeyAgent,
+  signDocument,
+  DELEGATION_SCHEMA_V2_1,
+  BOOTSTRAP_PATH_PRINCIPAL,
+  BOOTSTRAP_PATH_AGENT,
+  BOOTSTRAP_PATH_WALLET
+} from '@observer-protocol/wdk-protocol-trust'
+
+function hex (bytes) {
+  return Buffer.from(bytes).toString('hex')
+}
+
+function toISO (d) {
+  return d.toISOString().replace(/\.\d+Z$/, 'Z')
+}
+
+/**
+ * Generate all key material, a signed SpendMandate, and a WalletBindingCredential
+ * locally. No network required. Writes to `./output/`.
+ *
+ * The WBC is ALWAYS produced so every default community install is protected by
+ * the BIND→LINK→AUTHORIZE gate. The passthrough (no-WBC) path in runRuntimeAdapter
+ * is reserved for deliberate enterprise callers who explicitly opt out — it is
+ * never the community default.
+ *
+ * Both credentials are signed with DataIntegrityProof / eddsa-jcs-2022 via
+ * signDocument(), which is the only proof suite accepted by the policy engine.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.outputDir] - Output directory (default: ./output)
+ * @param {string} [opts.agentLabel] - Label for the agent (default: agent)
+ * @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)
+ * @returns {{ principalDid: string, agentDid: string, walletDid: string, mandateId: string }}
+ */
+export function generate (opts = {}) {
+  const {
+    outputDir = './output',
+    agentLabel = 'agent',
+    allowedRails = ['ethereum-mainnet', 'lightning'],
+    ceilingAmount = '100',
+    ceilCurrency = 'USDT'
+  } = opts
+
+  mkdirSync(outputDir, { recursive: true })
+
+  // 1. Principal key (operator — store offline)
+  const principalSeed = randomBytes(32)
+  const principal = createDidKeyAgent(principalSeed, BOOTSTRAP_PATH_PRINCIPAL)
+
+  // 2. Agent identity key (agent user — carries no spend authority)
+  const agentSeed = randomBytes(32)
+  const agent = createDidKeyAgent(agentSeed, BOOTSTRAP_PATH_AGENT)
+
+  // 3. Wallet identity key (wallet-service user — the wallet the WBC binds to)
+  // BOOTSTRAP_PATH_WALLET is the canonical path. The WBC binds the DID derived
+  // from this path; if wallet-service derives its DID with a different path, the
+  // BIND step DENYs every call. Both sides must import this constant.
+  const walletSeed = randomBytes(32)
+  const wallet = createDidKeyAgent(walletSeed, BOOTSTRAP_PATH_WALLET)
+
+  const now = new Date()
+  const validFrom = toISO(now)
+  const validUntil = toISO(new Date(now.getTime() + 365 * 24 * 60 * 60 * 1000))
+
+  // 4. Issue SpendMandate: principal → agent
+  //
+  // allowed_transaction_categories is NOT included. Its enforcement depends on
+  // config.transactionCategory being set at runtime; in the default community
+  // install that field is not provided, so including it would silently DENY
+  // every transaction (category check fires fail-closed). The ceiling + rail
+  // constraints are the enforceable guards. Category-gating requires runtime
+  // config to back it.
+  const mandate = {
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    type: ['VerifiableCredential', 'ObserverDelegationCredential'],
+    id: `urn:uuid:hermes-spend-mandate-${hex(randomBytes(8))}`,
+    issuer: principal.did,
+    validFrom,
+    validUntil,
+    credentialSchema: {
+      id: DELEGATION_SCHEMA_V2_1,
+      type: 'JsonSchema'
+    },
+    credentialSubject: {
+      id: agent.did,
+      authorizationLevel: 'recurring',
+      authorizationConfig: {
+        recurring: {
+          ceiling_amount: ceilingAmount,
+          ceiling_currency: ceilCurrency
+        }
+      },
+      actionScope: {
+        allowed_rails: allowedRails,
+        per_transaction_ceiling: {
+          amount: ceilingAmount,
+          currency: ceilCurrency
+        }
+      },
+      delegationScope: { may_delegate_further: false },
+      enforcementMode: 'pre_transaction_check'
+    }
+  }
+
+  const signedMandate = signDocument(mandate, principal)
+
+  // 5. Issue WalletBindingCredential: principal binds wallet.did to itself.
+  //
+  // The LINK step (dev mode) checks: wbc.issuer === mandate.issuer.
+  // Both are principal.did, so the LINK check passes for every default install.
+  //
+  // At runtime, ctx.wallet_id must equal wbc.credentialSubject.walletAddress
+  // (the BIND address check). The wallet service uses wallet.did as its
+  // identifier and passes it as ctx.wallet_id to the gate.
+  const wbc = signDocument({
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    id: `urn:uuid:hermes-wbc-${hex(randomBytes(8))}`,
+    type: ['VerifiableCredential', 'WalletBindingCredential'],
+    issuer: principal.did,
+    validFrom,
+    validUntil,
+    credentialSubject: {
+      id: principal.did,
+      walletAddress: wallet.did,
+      rail: allowedRails[0],
+      issuanceMode: 'dev'
+    }
+  }, principal)
+
+  // 6. Write output files
+  const principalKeyPath = join(outputDir, 'principal-key.json')
+  writeFileSync(principalKeyPath, JSON.stringify({
+    _note: 'PRINCIPAL KEY — store offline, never on server',
+    seed_hex: hex(principalSeed),
+    did: principal.did,
+    public_key_hex: hex(principal.publicKey)
+  }, null, 2))
+  chmodSync(principalKeyPath, 0o600)
+
+  const agentKeyPath = join(outputDir, 'agent-identity-key.json')
+  writeFileSync(agentKeyPath, JSON.stringify({
+    _note: 'AGENT IDENTITY KEY — agent user only, mode 600',
+    seed_hex: hex(agentSeed),
+    did: agent.did,
+    public_key_hex: hex(agent.publicKey),
+    label: agentLabel
+  }, null, 2))
+  chmodSync(agentKeyPath, 0o600)
+
+  const walletSeedPath = join(outputDir, 'wallet-seed.json')
+  writeFileSync(walletSeedPath, JSON.stringify({
+    _note: 'WALLET SEED — wallet-service user only, mode 600',
+    seed_hex: hex(walletSeed)
+  }, null, 2))
+  chmodSync(walletSeedPath, 0o600)
+
+  const walletKeyPath = join(outputDir, 'wallet-identity-key.json')
+  writeFileSync(walletKeyPath, JSON.stringify({
+    _note: 'WALLET IDENTITY KEY — wallet-service user only, mode 600',
+    seed_hex: hex(walletSeed),
+    did: wallet.did,
+    public_key_hex: hex(wallet.publicKey)
+  }, null, 2))
+  chmodSync(walletKeyPath, 0o600)
+
+  writeFileSync(join(outputDir, 'spend-mandate.json'), JSON.stringify(signedMandate, null, 2))
+  writeFileSync(join(outputDir, 'wbc.json'), JSON.stringify(wbc, null, 2))
+
+  console.log('Generated key material in', outputDir)
+  console.log()
+  console.log('  Principal DID:', principal.did)
+  console.log('  Agent DID:    ', agent.did)
+  console.log('  Wallet DID:   ', wallet.did)
+  console.log('  Mandate ID:   ', signedMandate.id)
+  console.log('  Valid:        ', validFrom, '→', validUntil)
+  console.log()
+  console.log('PLACEMENT INSTRUCTIONS:')
+  console.log()
+  console.log('  principal-key.json       → store OFFLINE (e.g. encrypted drive). Never on server.')
+  console.log('  agent-identity-key.json  → /home/<agent-user>/identity/did-key.json  (mode 600, chown <agent-user>)')
+  console.log('  wallet-seed.json         → /home/<wallet-user>/secrets/wallet-seed.json  (mode 600, chown <wallet-user>)')
+  console.log('  wallet-identity-key.json → /home/<wallet-user>/secrets/wallet-key.json  (mode 600, chown <wallet-user>)')
+  console.log('  spend-mandate.json       → /home/<agent-user>/spend-mandate.json  (mode 644)')
+  console.log('  wbc.json                 → /home/<agent-user>/wbc.json  (mode 644)')
+  console.log()
+  console.log('START THE GATE:')
+  console.log()
+  console.log('  HERMES_MANDATE_PATH=/home/<agent-user>/spend-mandate.json \\')
+  console.log('  HERMES_AGENT_DID=' + agent.did + ' \\')
+  console.log('  node /path/to/hermes-gate/src/mcp-server.js')
+  console.log()
+  console.log('  WBC auto-discovery: the gate looks for wbc.json in the same directory as the mandate.')
+  console.log('  No HERMES_WBC_PATH needed when wbc.json is placed alongside spend-mandate.json.')
+  console.log('  Set HERMES_WBC_PATH explicitly to load wbc.json from a different path.')
+  console.log()
+  console.log('Run `hermes-gate bootstrap provision` to copy files to the correct locations.')
+
+  return { principalDid: principal.did, agentDid: agent.did, walletDid: wallet.did, mandateId: signedMandate.id }
+}
+
+/**
+ * Provision key material from ./output/ to the correct system paths.
+ *
+ * @param {{ agentUser: string, walletUser: string, outputDir?: string }} opts
+ */
+export function provision ({ agentUser, walletUser, outputDir = './output' }) {
+  if (!agentUser || !walletUser) throw new Error('--agent-user and --wallet-user required')
+
+  const agentHome = `/home/${agentUser}`
+  const walletHome = `/home/${walletUser}`
+
+  execSync(`mkdir -p ${agentHome}/identity ${walletHome}/secrets`)
+
+  cpSync(join(outputDir, 'agent-identity-key.json'), `${agentHome}/identity/did-key.json`)
+  cpSync(join(outputDir, 'wallet-seed.json'), `${walletHome}/secrets/wallet-seed.json`)
+  cpSync(join(outputDir, 'wallet-identity-key.json'), `${walletHome}/secrets/wallet-key.json`)
+  cpSync(join(outputDir, 'spend-mandate.json'), `${agentHome}/spend-mandate.json`)
+  cpSync(join(outputDir, 'wbc.json'), `${agentHome}/wbc.json`)
+
+  execSync(`chown -R ${agentUser}:${agentUser} ${agentHome}/identity ${agentHome}/spend-mandate.json ${agentHome}/wbc.json`)
+  execSync(`chmod 600 ${agentHome}/identity/did-key.json`)
+  execSync(`chmod 644 ${agentHome}/spend-mandate.json`)
+  execSync(`chmod 644 ${agentHome}/wbc.json`)
+
+  execSync(`chown -R ${walletUser}:${walletUser} ${walletHome}/secrets`)
+  execSync(`chmod 700 ${walletHome}`)
+  execSync(`chmod 700 ${walletHome}/secrets`)
+  execSync(`chmod 600 ${walletHome}/secrets/wallet-seed.json`)
+  execSync(`chmod 600 ${walletHome}/secrets/wallet-key.json`)
+
+  console.log('Provisioned:')
+  console.log(' ', `${agentHome}/identity/did-key.json  (600)`)
+  console.log(' ', `${agentHome}/spend-mandate.json  (644)`)
+  console.log(' ', `${agentHome}/wbc.json  (644)`)
+  console.log(' ', `${walletHome}/secrets/wallet-seed.json  (600)`)
+  console.log(' ', `${walletHome}/secrets/wallet-key.json  (600)`)
+  console.log()
+  console.log('Run `hermes-gate bootstrap verify` to confirm G1 boundary.')
+}
+
+/**
+ * G1 boundary verification. Runs the three cross-boundary deny tests.
+ * Exits non-zero if any boundary check passes (meaning it should have been denied).
+ *
+ * @param {{ agentUser: string, walletUser: string }} opts
+ */
+export function verify ({ agentUser, walletUser }) {
+  if (!agentUser || !walletUser) throw new Error('--agent-user and --wallet-user required')
+
+  const agentHome = `/home/${agentUser}`
+  const walletHome = `/home/${walletUser}`
+
+  const checks = [
+    {
+      label: `${agentUser} cannot read ${walletUser}'s wallet seed`,
+      cmd: `sudo -u ${agentUser} cat ${walletHome}/secrets/wallet-seed.json`
+    },
+    {
+      label: `${agentUser} cannot list ${walletUser}'s secrets dir`,
+      cmd: `sudo -u ${agentUser} ls ${walletHome}/secrets/`
+    },
+    {
+      label: `${walletUser} cannot read ${agentUser}'s identity key`,
+      cmd: `sudo -u ${walletUser} cat ${agentHome}/identity/did-key.json`
+    }
+  ]
+
+  let passed = 0
+  let failed = 0
+
+  for (const { label, cmd } of checks) {
+    try {
+      execSync(cmd, { stdio: 'pipe' })
+      console.error(`FAIL [boundary broken]: ${label}`)
+      failed++
+    } catch (e) {
+      const out = ((e.stderr || '') + (e.stdout || '')).toString()
+      if (/[Pp]ermission denied|cannot open|[Nn]o such file/.test(out)) {
+        console.log(`PASS [access denied]:   ${label}`)
+        passed++
+      } else if (/sudo:/.test(out)) {
+        console.error(`INCONCLUSIVE [sudo not configured]: ${label}`)
+        console.error('  Run as root or configure passwordless sudo for this user')
+        failed++
+      } else {
+        console.error(`INCONCLUSIVE [unexpected error]: ${label}`)
+        console.error(`  ${out.trim().split('\n')[0] || '(no stderr)'}`)
+        failed++
+      }
+    }
+  }
+
+  console.log()
+  console.log(`G1 boundary: ${passed}/${checks.length} checks passed`)
+
+  if (failed > 0) {
+    console.error(`${failed} boundary check(s) failed — G1 boundary is NOT secure.`)
+    process.exit(1)
+  } else {
+    console.log('G1 boundary verified.')
+  }
+}

package/src/gate.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// Part of @observer-protocol/hermes-gate
+
+'use strict'
+
+import { runRuntimeAdapter } from '@observer-protocol/wdk-protocol-trust'
+
+export class GateError extends Error {
+  constructor (code, detail) {
+    super(detail || code)
+    this.code = code
+  }
+}
+
+/**
+ * Fail-closed spend gate backed by a signed SpendMandate.
+ *
+ * Instantiated by the wallet-service user (atlas-wallet). Holds no wallet seed.
+ *
+ * Every evaluate() call re-reads and re-verifies the mandate from disk.
+ * Mandate integrity comes from the DataIntegrityProof / eddsa-jcs-2022 Ed25519
+ * proof, not filesystem secrecy (the file is 644). Re-verification catches key
+ * rotation on the issuer side without a gate restart.
+ *
+ * COMMUNITY GATE SECURITY CAVEAT — action-input is agent-stated intent, not
+ * decoded on-chain bytes. A skill that declares amount: 5 but builds a
+ * transaction for 500 is caught by the enterprise RuntimeAdapter (which decodes
+ * actual on-chain bytes via ResolvedTransfer) and NOT by this gate. This is the
+ * headline v1 limitation: SpendGate enforces against what the agent declares,
+ * not what the transaction executes. The enterprise path (wdk-op-policy +
+ * runRuntimeAdapter) closes this gap via ProposalBinding.
+ */
+export class SpendGate {
+  /**
+   * @param {object} opts
+   * @param {string} opts.mandatePath                  - Path to the signed spend-mandate.json (644)
+   * @param {string} opts.agentDid                     - The agent's did:key (public)
+   * @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'
+   */
+  constructor ({ mandatePath, agentDid, trustedIssuers, walletBindingCredentialPath, issuanceMode }) {
+    if (!mandatePath || typeof mandatePath !== 'string') throw new GateError('CONFIG', 'mandatePath required')
+    if (!agentDid || typeof agentDid !== 'string') throw new GateError('CONFIG', 'agentDid required')
+    this._config = {
+      mandatePath,
+      agentDid,
+      trustedIssuers: trustedIssuers || [],
+      walletBindingCredentialPath,
+      issuanceMode
+    }
+  }
+
+  /**
+   * Evaluate a proposed spend action. Re-reads and re-verifies the mandate on
+   * every call. Optionally enforces BIND+LINK when walletBindingCredentialPath
+   * is configured.
+   *
+   * @param {{
+   *   rail: string,
+   *   amount: string,
+   *   currency: string,
+   *   category?: string,
+   *   wallet_id?: string
+   * }} action - Flat MCP surface. wallet_id is the signing wallet DID/address;
+   *   required only when BIND address verification is desired.
+   * @returns {Promise<{ allow: boolean, reasons: object[], advisories: object[], mandateValidUntil: string }>}
+   */
+  async evaluate (action) {
+    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')) {
+      throw new GateError('MANDATE_READ', result.reasons[0].message)
+    }
+    if (!result.allow && result.reasons.some(r => r.ruleField === 'mandate_invalid')) {
+      throw new GateError('MANDATE_INVALID', result.reasons[0].message)
+    }
+    if (!result.allow && result.reasons.some(r => r.ruleField === 'self_signed_mandate')) {
+      throw new GateError('SELF_SIGNED_MANDATE', result.reasons[0].message)
+    }
+    if (!result.allow && result.reasons.some(r => r.ruleField === 'subject_mismatch')) {
+      throw new GateError('SUBJECT_MISMATCH', result.reasons[0].message)
+    }
+    if (!result.allow && result.reasons.some(r => r.ruleField === 'untrusted_issuer')) {
+      throw new GateError('UNTRUSTED_ISSUER', result.reasons[0].message)
+    }
+    return {
+      allow: result.allow,
+      reasons: result.reasons,
+      advisories: result.advisories,
+      mandateValidUntil: result.mandateValidUntil
+    }
+  }
+}

package/src/mcp-server.js

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: Apache-2.0
+// Part of @observer-protocol/hermes-gate
+
+'use strict'
+
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js'
+import { SpendGate } from './gate.js'
+
+// ── Config from environment ───────────────────────────────────────────────
+
+const MANDATE_PATH = process.env.HERMES_MANDATE_PATH || `${process.env.HOME}/spend-mandate.json`
+const IDENTITY_PATH = process.env.HERMES_IDENTITY_PATH || `${process.env.HOME}/identity/did-key.json`
+const WBC_PATH = (() => {
+  if (process.env.HERMES_WBC_PATH) return process.env.HERMES_WBC_PATH
+  const candidate = join(dirname(resolve(MANDATE_PATH)), 'wbc.json')
+  return existsSync(candidate) ? candidate : null
+})()
+
+if (!WBC_PATH) {
+  console.error('WARNING: No WalletBindingCredential configured.')
+  console.error('  HERMES_WBC_PATH is unset and wbc.json was not found alongside the mandate.')
+  console.error('  Gate is in pe-042 PASSTHROUGH mode — wallet identity is NOT verified.')
+  console.error('  This is only valid for enterprise callers explicitly opting out.')
+  console.error('  Community installs: run `hermes-gate bootstrap generate` and either set')
+  console.error('  HERMES_WBC_PATH=<path/to/wbc.json> or place wbc.json alongside the mandate.')
+}
+
+// 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
+  try {
+    const id = JSON.parse(readFileSync(IDENTITY_PATH, 'utf8'))
+    return id.did || id.agent?.did
+  } catch (err) {
+    throw new Error(`Cannot load agent identity from ${IDENTITY_PATH}: ${err.message}`)
+  }
+}
+
+function loadMandateIssuer () {
+  try {
+    const m = JSON.parse(readFileSync(MANDATE_PATH, 'utf8'))
+    return typeof m.issuer === 'object' ? m.issuer?.id : m.issuer
+  } catch {
+    return null
+  }
+}
+
+// ── Input parsing (fail-closed) ───────────────────────────────────────────
+
+/**
+ * Parse and validate gate_evaluate / gate_execute action input.
+ * Throws on any malformed, missing, or out-of-range field.
+ * Caller catches and returns { allow: false }.
+ *
+ * @param {unknown} params
+ * @returns {{ rail: string, amount: string, currency: string, category?: string, note?: string }}
+ */
+function parseAction (params) {
+  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+    throw new Error('params must be a non-null object')
+  }
+  const { rail, amount, currency, category, note, wallet_id } = params
+
+  if (typeof rail !== 'string' || rail.trim().length === 0) {
+    throw new Error('rail must be a non-empty string')
+  }
+  if (typeof amount !== 'string' || amount.trim().length === 0) {
+    throw new Error('amount must be a non-empty string')
+  }
+  // Reject negative, zero, or non-numeric amounts
+  if (!/^[0-9]+(\.[0-9]+)?$/.test(amount.trim()) || parseFloat(amount) <= 0) {
+    throw new Error('amount must be a positive decimal string')
+  }
+  if (typeof currency !== 'string' || currency.trim().length === 0) {
+    throw new Error('currency must be a non-empty string')
+  }
+
+  return {
+    rail: rail.trim(),
+    amount: amount.trim(),
+    currency: currency.trim(),
+    ...(typeof category === 'string' && category ? { category: category.trim() } : {}),
+    ...(typeof note === 'string' && note ? { note: note.trim() } : {}),
+    ...(typeof wallet_id === 'string' && wallet_id ? { wallet_id: wallet_id.trim() } : {})
+  }
+}
+
+// ── Server setup ──────────────────────────────────────────────────────────
+
+const agentDid = loadAgentDid()
+const mandateIssuer = loadMandateIssuer()
+const gate = new SpendGate({
+  mandatePath: MANDATE_PATH,
+  agentDid,
+  trustedIssuers: mandateIssuer ? [mandateIssuer] : [],
+  walletBindingCredentialPath: WBC_PATH || undefined
+})
+
+const server = new Server(
+  { name: 'hermes-gate', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+)
+
+// ── Tool: gate_evaluate (fail-closed boundary) ────────────────────────────
+
+async function handleGateEvaluate (params) {
+  try {
+    const action = parseAction(params)
+    return await gate.evaluate(action)
+  } catch (err) {
+    return {
+      allow: false,
+      reasons: [{ ruleType: 'gate_error', ruleField: 'input', message: err.message }],
+      advisories: [],
+      mandateValidUntil: ''
+    }
+  }
+}
+
+// ── Tool: gate_execute ────────────────────────────────────────────────────
+
+async function handleGateExecute (params) {
+  const decision = await handleGateEvaluate(params)
+  if (!decision.allow) {
+    return {
+      allowed: false,
+      reasons: decision.reasons,
+      advisories: decision.advisories,
+      pec: null,
+      tx_ref: null
+    }
+  }
+  // Actual wallet signing is the wallet-service's responsibility.
+  // This stub returns the decision and signals to the caller to proceed.
+  // The wallet-service integration replaces this stub with actual WDK submission.
+  return {
+    allowed: true,
+    reasons: [],
+    advisories: decision.advisories,
+    pec: null,       // PolicyEvaluationCredential — emitted by buildSettlementAttestation
+    tx_ref: null,    // set by wallet-service after submission
+    _note: 'Submission stub — integrate with WDK wallet client for live execution'
+  }
+}
+
+// ── Tool: gate_status (informational, no re-verify) ──────────────────────
+
+function handleGateStatus () {
+  let mandateValidUntil = null
+  let mandateIssuerOut = null
+  try {
+    const m = JSON.parse(readFileSync(MANDATE_PATH, 'utf8'))
+    mandateValidUntil = m.validUntil || null
+    mandateIssuerOut = typeof m.issuer === 'object' ? m.issuer?.id : m.issuer || null
+  } catch {
+    // status is informational
+  }
+  return {
+    gate_up: true,
+    agent_did: agentDid,
+    mandate_valid_until: mandateValidUntil,
+    mandate_issuer: mandateIssuerOut,
+    mandate_path: MANDATE_PATH
+  }
+}
+
+// ── MCP tool definitions ──────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'gate_evaluate',
+    description: 'Evaluate whether a proposed spend is within the agent\'s SpendMandate. Returns allow/deny with reasons.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        rail: { type: 'string', description: 'Payment rail (e.g. ethereum-mainnet, lightning)' },
+        amount: { type: 'string', description: 'Proposed amount as a positive decimal string' },
+        currency: { type: 'string', description: 'Currency or token symbol (e.g. USDT, sats)' },
+        category: { type: 'string', description: 'Transaction category (e.g. payment)' },
+        wallet_id: { type: 'string', description: 'Wallet DID or address — required for BIND address verification when WBC is configured' },
+        note: { type: 'string', description: 'Optional human-readable note' }
+      },
+      required: ['rail', 'amount', 'currency']
+    }
+  },
+  {
+    name: 'gate_execute',
+    description: 'Evaluate and, if allowed, signal wallet-service to submit spend. Returns decision + tx_ref when allowed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        rail: { type: 'string' },
+        amount: { type: 'string' },
+        currency: { type: 'string' },
+        category: { type: 'string' },
+        wallet_id: { type: 'string', description: 'Wallet DID or address — triggers BIND address verification' },
+        tx_details: { type: 'object', description: 'Rail-specific transaction parameters' }
+      },
+      required: ['rail', 'amount', 'currency']
+    }
+  },
+  {
+    name: 'gate_status',
+    description: 'Return gate health and mandate metadata. Does not re-verify the mandate.',
+    inputSchema: { type: 'object', properties: {} }
+  }
+]
+
+// ── Request handlers ──────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params
+
+  let result
+  switch (name) {
+    case 'gate_evaluate':
+      result = await handleGateEvaluate(args)
+      break
+    case 'gate_execute':
+      result = await handleGateExecute(args)
+      break
+    case 'gate_status':
+      result = handleGateStatus()
+      break
+    default:
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+        isError: true
+      }
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+  }
+})
+
+// ── Start ─────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+console.error(`hermes-gate MCP server running (agent: ${agentDid})`)

package/src/skill.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Part of @observer-protocol/hermes-gate
+//
+// agentskills.io skill — thin wrapper over the gate_evaluate MCP tool.
+// Zero enforcement logic: the gate enforces, this skill surfaces the decision.
+
+'use strict'
+
+/**
+ * Evaluate a spend action via the gate MCP server.
+ *
+ * @param {{ rail: string, amount: string, currency: string, category?: string, note?: string }} action
+ * @param {{ callTool: (name: string, args: object) => Promise<object> }} mcpClient
+ * @returns {Promise<{ allow: boolean, reasons: object[], advisories: object[], mandateValidUntil: string }>}
+ */
+export async function evaluateSpend (action, mcpClient) {
+  return mcpClient.callTool('gate_evaluate', action)
+}
+
+/**
+ * agentskills.io skill manifest — describes this skill to the Hermes skill registry.
+ */
+export const skillManifest = {
+  name: 'hermes-spend-gate',
+  version: '0.1.0',
+  description: 'Fail-closed spend gate — evaluates proposed spends against the agent\'s OP-issued SpendMandate',
+  tools: ['gate_evaluate', 'gate_execute', 'gate_status'],
+  permissions: ['mcp:gate_evaluate', 'mcp:gate_execute'],
+  author: 'observer-protocol',
+  homepage: 'https://github.com/observer-protocol/hermes-gate'
+}