@metamynd/agentsafe-guard 0.7.0 → 0.12.0

package/README.md

@@ -112,6 +112,47 @@ OWN recorded spend history — a baseline the platform's trust-graph engine lear
 threshold a human pre-sets. Opt-in (`SPEND_ANOMALY_MODE=on`), off by default. Nothing in this
 package's own evaluation changes; documented here because the count moved again.
 
+**0.9.0 — the `keyProvider` seam
+([docs/design/agent-key-custody-local-signer-daemon-plan.md](../../docs/design/agent-key-custody-local-signer-daemon-plan.md)).
+`agentKey` no longer has to be a raw hex key living in this process. Pass
+`keyProvider: 'daemon'` + `daemonSocketPath` instead, and every signature is produced by a
+separate `@metamynd/agentsafe-signer` daemon over a local socket — the key never enters this
+process at all. `agentKey` (unchanged) still works exactly as before and remains the default;
+this is additive, not a replacement.**
+
+**Breaking, disclosed plainly rather than silently shipped**: `buildSignedRequest`,
+`signChallenge`, and `guard.handshake().prove()` are now `async` — they return a `Promise` of
+what they used to return directly, because a `daemon`-backed provider genuinely needs a socket
+round trip to produce a signature, and there is no honest way to make that synchronous. Every
+caller of these three needs an `await` added. `authorize()` and `verifyKey()` were already
+`async` and need no changes. New internal module: `key-providers.mjs` (exports
+`createStaticKeyProvider`, `createDaemonKeyProvider`, and the resolution logic `createGuard`
+itself uses) — still zero external dependencies, `node:crypto` + `node:net` only.
+
+**0.9.1 — `keyProvider: 'daemon'` retries a transient connect failure.** On Windows the signer
+daemon's socket is a pool of independent named-pipe instances (see
+`@metamynd/agentsafe-signer`'s `windows-secure-pipe.mjs`); each instance is consumed by one
+connection and replaced asynchronously, so two signing requests close together could race that
+replacement window and fail with `DAEMON_UNREACHABLE` even though the daemon was healthy.
+`key-providers.mjs` now retries a connection that fails with `ENOENT` for up to 3 seconds before
+giving up — a genuinely unreachable daemon still fails fast on any other error. No API change.
+
+**0.11.0 — `keyProvider: 'daemon'` now supports `signLocalDecision`.** A daemon-custody agent
+gets the same local-first block/escalate/non-value-allow audit reporting the static-key provider
+has had since 0.9.4 — `createDaemonKeyProvider` gained the fifth, optional `signLocalDecision`
+method, and `@metamynd/agentsafe-signer`'s daemon gained the matching `sign-local-decision`
+signing-socket operation. No change for a `createGuard({ agentKey })` caller.
+
+**0.12.0 — passphrase-encrypted managed key delivery**
+([docs/design/passphrase-encrypted-key-delivery-plan.md](../../docs/design/passphrase-encrypted-key-delivery-plan.md)).
+A managed key can now be delivered as ciphertext instead of plaintext: set a passphrase at
+issuance, and `agent.metamynd.json` carries `agentKeyEncrypted` (`agentKey: null`) instead of a
+raw key. `createGuardFromConfig(source, { passphrase })` decrypts it in memory before building
+the guard — see "Passphrase-encrypted managed key" above. New export from `key-providers.mjs`:
+`decryptAgentKeyWithPassword` (a byte-for-byte, `node:crypto`-only reimplementation of the
+backend's `encryptWithPassword`/`decryptWithPassword`, cross-verified against it). Fully
+additive: a config without `agentKeyEncrypted` is loaded exactly as before, no passphrase needed.
+
 ```yaml
 # .github/workflows/governance.yml
 name: Governance
@@ -201,6 +242,11 @@ nonce/replay + atomic cap, and anchored evidence **must** be server-side. If the
 can't be fetched, the guard defers to the authoritative remote gate rather than
 blind-allowing; a value action it can neither evaluate nor seal **fails closed**.
 
+A block/escalate/non-value-allow decided locally is still reported to the gate as a
+best-effort, signed **local decision receipt** — visible in the Activity Log and fleet
+decision-mix, but not anchored/evidence-grade (see "Trust model" below). This never
+blocks or delays the call above it.
+
 ```js
 // default — local-first
 const guard = await createGuardFromConfig('./agent.metamynd.json');
@@ -257,8 +303,29 @@ const guard = await createGuardFromConfig('./agent.metamynd.json', { agentKey: m
 await guard.verifyKey({ ref: config.identityId, challenge: config.challenge, token: ownerToken }); // one-time
 ```
 
-`guard.signChallenge(challenge)` returns just the hex signature if you'd rather submit verify-key
-yourself. (Fastest path: `npm create metamynd-agent@latest -- --byok` does all of this for you.)
+`await guard.signChallenge(challenge)` returns just the hex signature if you'd rather submit
+verify-key yourself. (Fastest path: `npm create metamynd-agent@latest -- --byok` does all of this
+for you.)
+
+### Passphrase-encrypted managed key
+
+If you didn't set a passphrase at issuance, a managed key is delivered **plaintext** — the
+`agentKey` field in `agent.metamynd.json` is usable as-is. Setting a passphrase (Launchpad's
+Identity stage, or `passphrase` on `POST /onboarding/agent`) instead delivers an
+`agentKeyEncrypted` object and leaves `agentKey: null`; decrypt it in memory when you load the
+config:
+
+```js
+const guard = await createGuardFromConfig('./agent.metamynd.json', { passphrase: myPassphrase });
+```
+
+This is strictly better than a plaintext file sitting on disk, in an email attachment, or in a
+`git add .` — but strictly weaker than `keyProvider: 'daemon'` (no key material in this process
+at all): the decrypted key still lives in this process's memory for as long as it runs.
+**Passphrase loss is unrecoverable**, the same as a lost BYOK private key — MetaMynd never sees
+or stores the passphrase itself, so there is nothing to reset. Omitting `{ passphrase }` when the
+config actually needs one throws a clear, specific error rather than the generic "requires
+agentKey or keyProvider" message.
 
 ## 1. Seed a bound agent (once)
 
@@ -331,7 +398,11 @@ const gatedBookFlight = guard.guardTool(
 ```
 
 - If your OpenClaw build has a **pre-tool hook / middleware** instead of raw handlers, call
-  `await guard.authorize({ action, amount, merchant, context })` there and refuse on any non-`allow`.
+  `await guard.authorize({ action, amount, merchant, resource, context })` there and refuse on any
+  non-`allow`. `resource` is a genuine, non-spoofable "what this action touches" declaration —
+  checked against a mandate's `{leftOperand:'resource'}` constraint the same way `merchant` is
+  checked against its own allow-list, and just as much a SIGNED field (tampering with it after
+  signing fails the request with `SIGNATURE_INVALID`, not a silent bypass).
 - **`context`** is what the Standard/SOP atoms read (jurisdiction, model, tool, PII, risk, …). Each
   atom declares what it needs — fetch the catalog at `GET /api/v1/standards/atoms` to see the exact
   fields (`requiredContext`) for the rules your agent is bound to.
@@ -388,8 +459,8 @@ const sandboxed = (ctx) => ctx.action === 'flight-purchase' ? sandboxBook(ctx.ar
 Contract: `async ({ action, args, decision, proceed }) => result`. Call `proceed()` to execute for
 real; return without it to substitute the side-effect. Self-check: `node execution-adapter.smoke.mjs`.
 
-Signed request fields (`amount`, `merchant`) are always applied over the unsigned `context`, so a
-forged context key can never shadow them (MAGP §6.4.2). Run the self-check:
+Signed request fields (`amount`, `merchant`, `resource`) are always applied over the unsigned
+`context`, so a forged context key can never shadow them (MAGP §6.4.2). Run the self-check:
 
 ```powershell
 cd integrations\agentsafe-guard
@@ -410,7 +481,7 @@ drives the initiator side:
 const hs = guard.handshake();
 const { nonceA, message } = hs.hello();              // → send HELLO to the Service
 // Service replies with CHALLENGE { toDid, nonceB, sigB(nonceA) }
-const { sigA, handshakeId } = hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
+const { sigA, handshakeId } = await hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
 // Service replies READY { channelId }
 ```
 
@@ -446,5 +517,10 @@ The gate is a **checkpoint** — enforcement is real when it's actually called.
   only proceeds on `allow`. A rogue agent that skips the call can't get the counterparty to act.
 - **Cooperative:** the agent's own tool layer (this guard) calls the gate and refuses on block/escalate.
 
-Either way, every decision is Ed25519-authenticated, deterministic, and anchored as evidence
-(visible in the dashboard's Regulator log and on HashScan).
+Either way, every decision is Ed25519-authenticated and deterministic. A decision that round-trips
+the gate — a sealed value action, or `mode:'remote'` — is also **anchored as evidence** (visible in
+the dashboard's Regulator log and on HashScan). A purely local-first decision (the default mode's
+block/escalate/non-value-allow — see "Enforcement mode" above) is NOT anchored, but is still
+recorded for Activity Log / decision-mix visibility via a best-effort signed receipt (no hold, no
+spend check, not evidence-grade) — `guardToolLocal()`'s pure-offline path has no server-side trail
+at all, by design.

package/agentsafe-guard.mjs

@@ -14,6 +14,7 @@ import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from '
 import { envelopeHashFor } from './governance-envelope.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
 import { checkSettlementBinding } from './x402.mjs';
+import { resolveKeyProvider, decryptAgentKeyWithPassword } from './key-providers.mjs';
 
 /**
  * Replay a Merkle sibling chain and report whether it reconstructs `root`.
@@ -87,6 +88,14 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
  * Async loader — build a guard from the portable config the one-call `POST /onboarding/agent`
  * endpoint returns: a URL, a file path, or the config object itself. Overrides win over the config.
  *   const guard = await createGuardFromConfig('./agent.metamynd.json');
+ *
+ * Passphrase-encrypted key delivery (docs/design/passphrase-encrypted-key-delivery-plan.md): when
+ * the loaded config carries `agentKeyEncrypted` (no plaintext `agentKey` — the operator set a
+ * passphrase at issuance) and no explicit `agentKey`/`keyProvider` override was given, pass
+ * `{ passphrase }` here to decrypt it IN-MEMORY before the guard is built:
+ *   const guard = await createGuardFromConfig('./agent.metamynd.json', { passphrase: '...' });
+ * The passphrase itself is never sent anywhere by this function — only used locally to derive
+ * the decryption key, matching the one hard invariant the design doc names.
  */
 export async function createGuardFromConfig(source, overrides = {}) {
   let cfg = source;
@@ -94,7 +103,15 @@ export async function createGuardFromConfig(source, overrides = {}) {
     cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : JSON.parse(readFileSync(source, 'utf8'));
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
-  return createGuard({ config: cfg, ...overrides });
+  const { passphrase, ...rest } = overrides;
+  if (cfg?.agentKeyEncrypted && !cfg.agentKey && !rest.agentKey && !rest.keyProvider) {
+    if (!passphrase) {
+      throw new Error("createGuardFromConfig: this config's key is passphrase-encrypted — pass { passphrase }");
+    }
+    const agentKey = decryptAgentKeyWithPassword(cfg.agentKeyEncrypted.ciphertext, passphrase, cfg.agentKeyEncrypted.salt);
+    return createGuard({ config: cfg, agentKey, ...rest });
+  }
+  return createGuard({ config: cfg, ...rest });
 }
 
 export function createGuard(opts = {}) {
@@ -108,18 +125,17 @@ export function createGuard(opts = {}) {
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const api = opts.api ?? cfg?.apiBase ?? cfg?.api;
   const agentDid = opts.agentDid ?? cfg?.agentDid;
-  const agentKey = opts.agentKey ?? cfg?.agentKey;
-  if (!api || !agentDid || !agentKey) throw new Error('createGuard requires { api, agentDid, agentKey } — directly, or via { config } / { configPath } / createGuardFromConfig()');
+  if (!api || !agentDid) throw new Error('createGuard requires { api, agentDid } — directly, or via { config } / { configPath } / createGuardFromConfig() — plus either { agentKey } or { keyProvider }');
   const base = api.replace(/\/$/, '');
   // ExecutionAdapter seam (SAFR §19): an explicit opt wins, else the AGENTSAFE_EXECUTION_MODE env,
   // else live. Applies to every guarded tool unless a tool passes its own adapter.
   const defaultExecutionAdapter = opts.executionAdapter ?? executionAdapterFromEnv() ?? liveExecutionAdapter;
-  const privateKey = crypto.createPrivateKey({ key: Buffer.from(agentKey, 'hex'), format: 'der', type: 'pkcs8' });
-
-  // Ed25519 over the exact canonical message the backend verifies.
-  function sign(message) {
-    return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
-  }
+  // keyProvider seam (docs/design/agent-key-custody-local-signer-daemon-plan.md): defaults to
+  // 'staticKey' (the raw key in THIS process, today's only behavior before this seam existed) —
+  // pass keyProvider:'daemon' + daemonSocketPath to keep the key out of this process entirely.
+  // Every place this file used to call a local sign(message) now calls one of the provider's
+  // four methods instead — see key-providers.mjs for why there are four, not one.
+  const keyProvider = resolveKeyProvider(opts, cfg);
 
   // Tier 1 context-claim binding (opt-in, docs/design/context-claim-binding.md): when
   // on, sign the GovernanceEnvelope hash too, so a counterparty/gate can prove the
@@ -127,12 +143,11 @@ export function createGuard(opts = {}) {
   // subset. Off by default: a bare request stays a valid degenerate envelope, exactly
   // like today, and the wire body carries no envelopeSignature field at all.
   const signContext = opts.signContext ?? cfg?.signContext ?? false;
-  function envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }) {
+  async function envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }) {
     if (!signContext) return undefined;
     // The hash is independent of `signature` (excluded from what it commits to — see
     // governance-envelope.ts), so an empty placeholder here is exact, not approximate.
-    const hash = envelopeHashFor({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: '' });
-    return sign(hash);
+    return keyProvider.signEnvelope({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt });
   }
 
   // --- Enforcement mode (spec §9.2 + local-first plan) --------------------------------------
@@ -167,17 +182,40 @@ export function createGuard(opts = {}) {
    * agent's authorization trustlessly against the agent's policy bundle (§9.3). Same shape
    * `authorize()` posts to the gate; a fresh nonce each call.
    */
-  function buildSignedRequest({ action, amount = 0, currency = 'USD', merchant = '', context = {}, trace, materiality }) {
+  async function buildSignedRequest({ action, amount, currency, merchant, resource, context = {}, trace, materiality }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
-    const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
+    // This object is presented to a COUNTERPARTY (spec §9.3) — but its own docstring also
+    // promises "same shape authorize() posts to the gate", so it must ALSO independently
+    // re-verify if posted straight to /policy/mandate/authorize, not just via a naive
+    // counterparty reconstruction. Found live: signing with amount/currency genuinely
+    // undefined (bothOmitted) produced a message the backend's authMessage() — which
+    // ALWAYS defaults a missing amount/currency to 0/'USD' before reconstructing,
+    // regardless of the wire body — could never verify. Fix: SIGN with the same 0/'USD'
+    // default authorize() and the gate both use, unconditionally; the WIRE body still
+    // keeps a real omission as a real omission. A naive third-party reconstruction (e.g.
+    // today's agentsafe-mcp-guard, which doesn't yet apply this same default) would need
+    // the same fix to correctly re-verify a bothOmitted request — flagged as a follow-up,
+    // not something to leave this function broken against the gate over.
+    const bothOmitted = amount === undefined && currency === undefined;
+    const wireAmount = bothOmitted ? undefined : (amount ?? 0);
+    const wireCurrency = bothOmitted ? undefined : (currency ?? 'USD');
+    const signedAmount = amount ?? 0;
+    const signedCurrency = currency ?? 'USD';
+    // `resource` is independent of amount/currency's bothOmitted pairing — it always signs and
+    // travels exactly as given (undefined stays undefined on the wire, buildAuthMessage's own
+    // internal `?? ''` fallback handles the signed-message side, same as `merchant`).
     // trace/materiality are GovernanceEnvelope fields (SAFR §5) — unsigned metadata; the
-    // signed message stays the action subset, so verification is unchanged.
-    return {
-      agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt,
-      signature: sign(message),
-      envelopeSignature: envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
-    };
+    // signed message stays the action subset, so verification is unchanged. `resource` is
+    // deliberately NOT passed to envelopeSignatureFor: the backend's governance-envelope.ts
+    // action fields don't include it yet either (only amount/currency/merchant) — adding it
+    // to just one side would break Tier-1 envelope-hash verification for any resource-
+    // declaring request. A coordinated backend+guard follow-up, not something to do half here.
+    const [signature, envelopeSignature] = await Promise.all([
+      keyProvider.signAuthorize({ agentDid, action, amount: signedAmount, currency: signedCurrency, merchant, resource, nonce, issuedAt }),
+      envelopeSignatureFor({ action, amount: wireAmount, currency: wireCurrency, merchant, context, trace, materiality, nonce, issuedAt }),
+    ]);
+    return { agentDid, action, amount: wireAmount, currency: wireCurrency, merchant, resource, itinerary: context, trace, materiality, nonce, issuedAt, signature, envelopeSignature };
   }
 
   /**
@@ -185,13 +223,31 @@ export function createGuard(opts = {}) {
    * returns { decision:'allow'|'block'|'escalate', reasonCode, authorizationId, remaining }.
    * A network/gate failure returns a fail-CLOSED block so the agent can't proceed blind.
    */
-  async function authorize({ action, amount = 0, currency = 'USD', merchant = '', context = {}, trace, materiality }) {
+  async function authorize({ action, amount, currency, merchant, resource, context = {}, trace, materiality }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
-    // Build the canonical signed message with policy-core so the guard and the
-    // backend gate produce byte-identical input to Ed25519 (spec §7.3).
-    const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
     try {
+      // This is verified SERVER-SIDE by the gate, which independently reconstructs the signed
+      // message via its own authMessage() (mandate.service.ts) — that function ALSO defaults a
+      // missing amount/currency to 0/'USD' before rebuilding the message, regardless of what the
+      // wire body actually contains. So the client signs with that same 0/'USD' default whenever
+      // a field is genuinely omitted — matching the gate's reconstruction — while the WIRE body
+      // below keeps a real omission as a real omission (not the gate's problem: it defaults on
+      // its own) rather than fabricating amount:0/currency:'USD' for a non-financial action.
+      // `resource` needs no such dance: the gate's authMessage() spreads `...input` directly
+      // (no explicit default), and buildAuthMessage's own internal `f.resource ?? ''` fallback
+      // already matches whatever this client signs when it too is genuinely omitted.
+      const signedAmount = amount ?? 0;
+      const signedCurrency = currency ?? 'USD';
+      // The canonical message itself is built by the key provider (policy-core's
+      // buildAuthMessage, same as the backend gate verifies against — spec §7.3), not here —
+      // see key-providers.mjs for why callers pass structured fields, not a pre-built string.
+      // `resource` deliberately NOT passed to envelopeSignatureFor — see buildSignedRequest's
+      // own comment on why (backend governance-envelope.ts doesn't include it yet either).
+      const [signature, envelopeSignature] = await Promise.all([
+        keyProvider.signAuthorize({ agentDid, action, amount: signedAmount, currency: signedCurrency, merchant, resource, nonce, issuedAt }),
+        envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
+      ]);
       const res = await fetch(`${base}/policy/mandate/authorize`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -199,15 +255,19 @@ export function createGuard(opts = {}) {
         // as unsigned-message metadata; JSON.stringify drops them when undefined, so an
         // agent that omits them (or leaves signContext off) sends the legacy body.
         body: JSON.stringify({
-          agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt,
-          signature: sign(message),
-          envelopeSignature: envelopeSignatureFor({ action, amount, currency, merchant, context, trace, materiality, nonce, issuedAt }),
+          agentDid, action, amount, currency, merchant, resource, itinerary: context, trace, materiality, nonce, issuedAt,
+          signature,
+          envelopeSignature,
         }),
       });
       const body = await res.json().catch(() => null);
       return body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };
     } catch (err) {
-      return { decision: 'block', reasonCode: 'GATE_UNREACHABLE', error: String(err?.message ?? err) };
+      // A daemon-backed keyProvider can fail before the gate is ever reached (the signer, not
+      // the gate, was unreachable) — a distinct reasonCode so this doesn't read as a gate outage
+      // it wasn't. Still fail-CLOSED either way, which is the property that actually matters.
+      const reasonCode = err?.code?.startsWith?.('DAEMON_') ? 'SIGNER_UNREACHABLE' : 'GATE_UNREACHABLE';
+      return { decision: 'block', reasonCode, error: String(err?.message ?? err) };
     }
   }
 
@@ -355,6 +415,37 @@ export function createGuard(opts = {}) {
     return _anchor;
   }
 
+  // Verdicts the backend's /policy/decisions/local will actually accept (local-decision.service.ts's
+  // LOCAL_DECISIONS) — 'quarantine'/'suspend' are containment, a SERVER-state decision whose audit
+  // trail already lives on the server (the `contained` flag this very evaluation read came FROM
+  // the server's own bundle response), so there is nothing new to report for those.
+  const REPORTABLE_LOCAL_DECISIONS = new Set(['allow', 'observe', 'block', 'escalate']);
+
+  /**
+   * Best-effort, NEVER awaited by the caller: reports a purely-local verdict to the gate
+   * for audit VISIBILITY only (Activity Log / fleet decision-mix / regulator log otherwise
+   * show nothing for the large majority of decisions under the default local-first mode —
+   * see docs/design/... and this package's own README "Enforcement mode" section for why
+   * that's a deliberate security tradeoff, not a bug, but one that used to leave zero trail
+   * anywhere). Silently does nothing if the keyProvider doesn't support it (e.g. the daemon
+   * keyProvider, which doesn't implement signLocalDecision in this version) or the verdict
+   * isn't one the endpoint accepts. Never throws, never delays the caller.
+   */
+  function reportLocalDecision(action, decision, reasonCode) {
+    if (typeof keyProvider.signLocalDecision !== 'function') return;
+    if (!REPORTABLE_LOCAL_DECISIONS.has(decision)) return;
+    const nonce = crypto.randomUUID();
+    const issuedAt = new Date().toISOString();
+    void (async () => {
+      const signature = await keyProvider.signLocalDecision({ agentDid, action, decision, reasonCode, nonce, issuedAt });
+      await fetch(`${base}/policy/decisions/local`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ agentDid, action, decision, reasonCode, nonce, issuedAt, signature }),
+      });
+    })().catch(() => {});
+  }
+
   /**
    * LOCAL-FIRST decision (the default). Evaluates the rule layer against the cached
    * bundle with the same policy-core the gate runs — so a block/escalate is decided
@@ -382,8 +473,12 @@ export function createGuard(opts = {}) {
     const local = evaluateLocally({ ..._bundleFor(b, action), request: input });
     // allow/observe both PERMIT; block/escalate/contain are decided locally with no network.
     const permits = local.decision === 'allow' || local.decision === 'observe';
-    if (!permits) return local; // denied/escalated locally, no network
+    if (!permits) {
+      reportLocalDecision(action, local.decision, local.reasonCode); // fire-and-forget — see above
+      return local; // denied/escalated locally, no network
+    }
     if (amount > 0 && sealValueActions) return authorize(input); // seal value action remotely (allow or observe)
+    reportLocalDecision(action, local.decision, local.reasonCode); // non-value permit — fire-and-forget
     return local; // non-value permit — local is sufficient
   }
 
@@ -445,6 +540,12 @@ export function createGuard(opts = {}) {
    * the gate — cooperative-mode, low-latency governance (spec §9.2). Fails CLOSED:
    * any error during local evaluation throws GovernanceBlocked, never allows.
    *
+   * Unlike `guardTool()`'s default local-first path (`authorizeLocal()`), this one makes
+   * NO network call of any kind, ever — that is its entire purpose (pure-offline,
+   * cooperative-mode use). It does NOT report to /policy/decisions/local, so a verdict
+   * decided this way has NO central audit trail at all, by design — a deliberate,
+   * pre-existing tradeoff this package leaves unchanged.
+   *
    * @param {string} action
    * @param {(args:any, decision:any)=>any} handler
    * @param {(args:any)=>{amount?:number,currency?:string,merchant?:string,context?:object}} mapArgs
@@ -514,7 +615,7 @@ export function createGuard(opts = {}) {
    * the DIDs, §4.1.2). Returns { hello, prove } to drive the exchange:
    *   const hs = guard.handshake();
    *   const { nonceA, message } = hs.hello();           // → send HELLO to the Service
-   *   const { sigA, handshakeId } = hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
+   *   const { sigA, handshakeId } = await hs.prove({ nonceA, challenge });  // verifies the Service, → send PROVE
    * `prove` throws HandshakeFailed if the Service's CHALLENGE does not verify.
    */
   function handshake() {
@@ -523,7 +624,7 @@ export function createGuard(opts = {}) {
         const nonceA = crypto.randomUUID();
         return { nonceA, message: { fromDid: agentDid, nonceA, protoVersion: '1.0' } };
       },
-      prove({ nonceA, challenge } = {}) {
+      async prove({ nonceA, challenge } = {}) {
         const { toDid, nonceB, sigB, handshakeId } = challenge ?? {};
         if (!toDid || !nonceB || !sigB) throw new Error('malformed CHALLENGE');
         if (!verifyDidSignature(toDid, nonceA, sigB)) {
@@ -531,7 +632,7 @@ export function createGuard(opts = {}) {
           e.name = 'HandshakeFailed';
           throw e;
         }
-        return { handshakeId, sigA: sign(nonceB), remoteDid: toDid };
+        return { handshakeId, sigA: await keyProvider.signHandshakeNonce(nonceB), remoteDid: toDid };
       },
     };
   }
@@ -700,7 +801,7 @@ export function createGuard(opts = {}) {
     const res = await fetch(`${base}/agent-identity/${encodeURIComponent(ref)}/verify-key`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
-      body: JSON.stringify({ signature: sign(challenge) }),
+      body: JSON.stringify({ signature: await keyProvider.signKeyControlChallenge(challenge) }),
     });
     const body = await res.json().catch(() => null);
     if (!res.ok) {
@@ -711,10 +812,10 @@ export function createGuard(opts = {}) {
     return body?.data ?? { verified: true };
   }
 
-  /** Sign a BYOK challenge with the agent's key (hex) — for integrators who submit verify-key themselves. */
-  function signChallenge(challenge) {
+  /** Sign a BYOK challenge with the agent's key — for integrators who submit verify-key themselves. */
+  async function signChallenge(challenge) {
     if (!challenge) throw new Error('signChallenge requires the challenge nonce');
-    return sign(challenge);
+    return keyProvider.signKeyControlChallenge(challenge);
   }
 
   return { authorize, authorizeLocal, check, loadBundle, policyAnchor: _currentAnchor, watchPolicy, mode, verifyOnChain, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, proof, effectDispatching, effectDispatched, effectUnknown, effectStatus, verifyKey, signChallenge, agentDid, executionAdapter: defaultExecutionAdapter };

package/key-providers.mjs

@@ -0,0 +1,174 @@
+// key-providers.mjs — the keyProvider seam (docs/design/agent-key-custody-local-signer-daemon-plan.md).
+// A KeyProvider has four REQUIRED async methods, matching the four places this package always
+// signs something (see agentsafe-guard.mjs: buildSignedRequest/authorize, the opt-in envelope
+// signature, the mutual-handshake PROVE step, and BYOK key-control-proof) — every built-in
+// provider implements all four, and a caller's own plain-object provider must too. `signLocalDecision`
+// is a FIFTH, OPTIONAL method (both built-in providers implement it — see agentsafe-guard.mjs's
+// authorizeLocal(), which checks for it before attempting to report a local decision) — a
+// caller's own plain-object provider that omits it simply doesn't get that audit-visibility
+// enhancement, with no change to its existing behavior otherwise.
+import crypto from 'node:crypto';
+import net from 'node:net';
+import path from 'node:path';
+import { buildAuthMessage, buildLocalDecisionMessage } from './policy-core.mjs';
+import { envelopeHashFor } from './governance-envelope.mjs';
+
+/**
+ * Today's default: the raw key lives in THIS process (see the design doc's "What this does not
+ * do" for the confidentiality tradeoff that implies). Builds each canonical message locally with
+ * the same policy-core/governance-envelope functions the backend verifies against, then signs.
+ */
+export function createStaticKeyProvider(agentKeyHex) {
+  const privateKey = crypto.createPrivateKey({ key: Buffer.from(agentKeyHex, 'hex'), format: 'der', type: 'pkcs8' });
+  const rawSign = (message) => crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+  return {
+    async signAuthorize(fields) {
+      return rawSign(buildAuthMessage(fields));
+    },
+    async signEnvelope(fields) {
+      return rawSign(envelopeHashFor({ ...fields, signature: '' }));
+    },
+    async signHandshakeNonce(nonce) {
+      return rawSign(nonce);
+    },
+    async signKeyControlChallenge(challengeHex) {
+      return rawSign(challengeHex);
+    },
+    async signLocalDecision(fields) {
+      return rawSign(buildLocalDecisionMessage(fields));
+    },
+  };
+}
+
+/**
+ * Same platform/path translation the signer daemon itself uses (integrations/agentsafe-signer/
+ * daemon.mjs's toPlatformSocketPath) — must stay identical or client and server compute different
+ * pipe names on Windows and never connect. Duplicated rather than imported: this package has no
+ * dependency (workspace or npm) on agentsafe-signer, by design (see that package's own README).
+ */
+function toPlatformSocketPath(logicalPath) {
+  if (process.platform !== 'win32') return logicalPath;
+  const name = crypto.createHash('sha256').update(path.resolve(logicalPath)).digest('hex').slice(0, 32);
+  return `\\\\.\\pipe\\agentsafe-signer-${name}`;
+}
+
+const PROTOCOL_VERSION = 1;
+
+function daemonRequest(socketPath, op, params, { connectTimeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + connectTimeoutMs;
+    function attempt() {
+      const sock = net.connect(toPlatformSocketPath(socketPath));
+      const requestId = crypto.randomUUID();
+      let buf = '';
+      const cleanup = () => sock.destroy();
+      sock.once('error', (err) => {
+        cleanup();
+        // On Windows the signing socket is a pool of independent named-pipe instances (see
+        // agentsafe-signer/windows-secure-pipe.mjs): each instance is consumed by exactly one
+        // connection, then replaced asynchronously. Two requests arriving close enough together
+        // can race that replacement window and transiently find zero live instances (ENOENT) even
+        // though the daemon itself is up and healthy. Retrying briefly is the same tolerance any
+        // client of a local, independently-started daemon needs — not a workaround for a broken
+        // invariant — and matches only ENOENT so a daemon that is genuinely down still fails fast.
+        if (err.code === 'ENOENT' && Date.now() < deadline) {
+          setTimeout(attempt, 20);
+          return;
+        }
+        reject(Object.assign(new Error(`agentsafe-signer daemon unreachable at ${socketPath}: ${err.message}`), { code: 'DAEMON_UNREACHABLE' }));
+      });
+      sock.once('connect', () => {
+        sock.write(JSON.stringify({ protocolVersion: PROTOCOL_VERSION, requestId, op, params }) + '\n');
+      });
+      sock.on('data', (chunk) => {
+        buf += chunk.toString('utf8');
+        const idx = buf.indexOf('\n');
+        if (idx === -1) return;
+        let res;
+        try {
+          res = JSON.parse(buf.slice(0, idx));
+        } catch (err) {
+          cleanup();
+          reject(err);
+          return;
+        }
+        cleanup();
+        if (res.ok) resolve(res.result);
+        else reject(Object.assign(new Error(res.error?.message || res.error?.code || 'daemon rejected request'), { code: res.error?.code }));
+      });
+    }
+    attempt();
+  });
+}
+
+/**
+ * The key never enters this process at all — every signature is produced by a separate
+ * agentsafe-signer daemon over a local socket, which builds the canonical message itself from
+ * these structured fields (never a pre-built string) and returns only the signature.
+ */
+export function createDaemonKeyProvider({ socketPath }) {
+  if (!socketPath) throw new Error('createDaemonKeyProvider requires { socketPath }');
+  return {
+    async signAuthorize(fields) {
+      const { signature } = await daemonRequest(socketPath, 'sign-authorize', fields);
+      return signature;
+    },
+    async signEnvelope(fields) {
+      const { envelopeSignature } = await daemonRequest(socketPath, 'sign-envelope', fields);
+      return envelopeSignature;
+    },
+    async signHandshakeNonce(nonce) {
+      const { signature } = await daemonRequest(socketPath, 'sign-handshake-nonce', { nonce });
+      return signature;
+    },
+    async signKeyControlChallenge(challengeHex) {
+      const { signature } = await daemonRequest(socketPath, 'sign-key-control-challenge', { challenge: challengeHex });
+      return signature;
+    },
+    async signLocalDecision(fields) {
+      const { signature } = await daemonRequest(socketPath, 'sign-local-decision', fields);
+      return signature;
+    },
+  };
+}
+
+/**
+ * Passphrase-encrypted key delivery (docs/design/passphrase-encrypted-key-delivery-plan.md).
+ * A byte-for-byte reimplementation of the backend's `decryptWithPassword`
+ * (backend/src/util/encryption.ts) using only node:crypto — PBKDF2-SHA512/100k-iterations/
+ * 32-byte key derived from (password, salt), then AES-256-GCM decrypt of the `iv:tag:encrypted`
+ * hex-joined triple `encryptWithPassword` produces. MUST stay in lockstep with that function:
+ * two independently-written implementations of "the same algorithm" silently diverging is
+ * exactly the class of bug buildSignedRequest's bothOmitted case already caught once in this
+ * package — see daemon-keyprovider.smoke.mjs's own cross-package pattern for why this is tested
+ * against real backend-produced ciphertext, not just self-consistently.
+ * @param {string} ciphertext  encryptWithPassword()'s combined "iv:tag:encrypted" hex string
+ * @param {string} password    the operator's passphrase — never persisted, used only here
+ * @param {string} salt        the salt returned alongside `ciphertext` at issuance time
+ * @returns {string} the decrypted plaintext (the agent's private key hex)
+ */
+export function decryptAgentKeyWithPassword(ciphertext, password, salt) {
+  const parts = String(ciphertext).split(':');
+  if (parts.length !== 3) throw new Error('decryptAgentKeyWithPassword: invalid encrypted data format');
+  const [ivHex, tagHex, encryptedHex] = parts;
+  // Matches deriveKeyFromPassword exactly: salt is passed as-is (its own hex STRING, UTF-8
+  // encoded by pbkdf2Sync's default), not decoded from hex to raw bytes first.
+  const key = crypto.pbkdf2Sync(password, salt, 100000, 32, 'sha512');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivHex, 'hex'));
+  decipher.setAAD(Buffer.from('hedera-data', 'utf8'));
+  decipher.setAuthTag(Buffer.from(tagHex, 'hex'));
+  return decipher.update(encryptedHex, 'hex', 'utf8') + decipher.final('utf8');
+}
+
+/** Resolves `opts.keyProvider`/`opts.agentKey` into a concrete KeyProvider for createGuard(). */
+export function resolveKeyProvider(opts, cfg) {
+  const kp = opts.keyProvider ?? cfg?.keyProvider;
+  if (kp && typeof kp === 'object' && typeof kp.signAuthorize === 'function') return kp;
+  if (kp === 'daemon' || (kp && typeof kp === 'object' && kp.type === 'daemon')) {
+    const socketPath = opts.daemonSocketPath ?? cfg?.daemonSocketPath ?? (kp && kp.socketPath);
+    return createDaemonKeyProvider({ socketPath });
+  }
+  const agentKey = opts.agentKey ?? cfg?.agentKey;
+  if (!agentKey) throw new Error("createGuard requires a keyProvider, or { agentKey } for the default 'staticKey' provider");
+  return createStaticKeyProvider(agentKey);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.7.0",
+  "version": "0.12.0",
   "description": "Zero-dependency runtime governance for any Node AI agent \u2014 gate tool calls through MetaMynd/AgentSafe (allow / block / escalate) against the agent's mandate, enforced Standards, and SOPs. Ed25519-signed, deterministic, fail-closed.",
   "type": "module",
   "main": "./agentsafe-guard.mjs",
@@ -16,6 +16,7 @@
     "cli.mjs",
     "verify.mjs",
     "agentsafe-guard.mjs",
+    "key-providers.mjs",
     "policy-core.mjs",
     "governance-envelope.mjs",
     "magp-did.mjs",
@@ -25,7 +26,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs",
+    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs",
     "demo": "node demo.mjs"
   },
   "engines": {

package/policy-core.mjs

@@ -2,6 +2,14 @@
 
 // src/policy-core/atom-registry.ts
 var RISK_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+function currencyOutOfScope(ctx, cfgCurrency) {
+  if (cfgCurrency === void 0 || cfgCurrency === null) return false;
+  const allowed = Array.isArray(cfgCurrency) ? cfgCurrency : [cfgCurrency];
+  if (allowed.length === 0) return false;
+  const currency = ctx.currency;
+  const matches = typeof currency === "string" && allowed.some((u) => typeof u === "string" && u.toUpperCase() === currency.toUpperCase());
+  return !matches;
+}
 var ATOM_REGISTRY = {
   "data-source-not-approved": (c, cfg) => !!c.dataSourceId && !(cfg?.approved ?? []).includes(String(c.dataSourceId)),
   "consent-missing": (c) => c.consent === false,
@@ -10,7 +18,11 @@ var ATOM_REGISTRY = {
     const need = RISK_RANK[String(cfg?.level ?? "high")];
     return have !== void 0 && need !== void 0 && have >= need;
   },
-  "amount-over": (c, cfg) => typeof c.amount === "number" && c.amount > Number(cfg?.limit ?? 0),
+  "amount-over": (c, cfg) => {
+    if (typeof c.amount !== "number") return false;
+    if (currencyOutOfScope(c, cfg?.currency)) return true;
+    return c.amount > Number(cfg?.limit ?? 0);
+  },
   // Deny-by-default primitive for value-moving actions. Fires on ABSENCE (like the
   // evidence atoms below, and unlike `amount-over`) OR on a NEGATIVE amount: true when
   // the context carries no usable amount, or one that cannot be trusted for capping —
@@ -31,7 +43,12 @@ var ATOM_REGISTRY = {
   "amount-unknown": (c) => !(typeof c.amount === "number" && Number.isFinite(c.amount) && c.amount >= 0),
   // Total budget: cumulativeSpend is a SERVER-derived, signed-last context field (never
   // shadowable by the agent's itinerary), so this compares already-spent + this amount.
-  "cumulative-over": (c, cfg) => Number(c.cumulativeSpend ?? 0) + Number(c.amount ?? 0) > Number(cfg?.limit ?? 0),
+  // See `currencyOutOfScope` above: a configured currency scope that this request's
+  // currency doesn't match fires the cap outright, same fail-closed reasoning as `amount-over`.
+  "cumulative-over": (c, cfg) => {
+    if (currencyOutOfScope(c, cfg?.currency)) return true;
+    return Number(c.cumulativeSpend ?? 0) + Number(c.amount ?? 0) > Number(cfg?.limit ?? 0);
+  },
   // Fires if any configured term appears in the prompt and/or output text.
   // Used to govern agent responses on content (prohibited claims, sensitive advice).
   "text-matches": (c, cfg) => {
@@ -87,7 +104,25 @@ var ATOM_SPECS = [
     predicate: "amount-over",
     label: "Per-transaction amount over limit",
     description: "Fires when a single action amount exceeds a configured limit (per-transaction cap).",
-    config: [{ key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" }],
+    config: [
+      { key: "limit", type: "number", required: true, description: "Maximum allowed amount for one transaction" },
+      {
+        key: "currency",
+        type: "string[]",
+        required: false,
+        description: `Optional currency scope for the limit (e.g. ['USD'], or ['USD','GBP'] for several). Leave empty to keep the limit currency-blind \u2014 the historical default: the raw number is compared regardless of currency. Once set, a request in a currency outside this list \u2014 or with none supplied at all \u2014 fires this atom regardless of amount (unverifiable is treated as unsafe, not as "smaller"), so the cap can't be cleared by naming a cheaper-looking currency (e.g. 200 JPY vs 200 USD).`
+      }
+    ],
+    // `currency` is NOT listed here even though the executable atom conditionally reads it:
+    // unlike `limit`, the `currency` config is OPTIONAL per atom instance, so whether an agent
+    // needs to supply it depends on how a given molecule configures this atom — something
+    // `requiredContextFor`'s per-predicate (not per-instance) model can't express. Every
+    // authorize request already carries `currency` unconditionally regardless (see
+    // AuthorizeInput), so nothing is actually left unfed by omitting it here — this only
+    // controls the Scenario Bank simulate form / docs "context contract" surfacing, and
+    // forcing it onto every amount-over molecule would spuriously mark scenarios that never
+    // configure a currency scope as unexercised (see cumulative-over-atom.test.ts's sibling
+    // comment below for the same reasoning applied there).
     requiredContext: ["amount"]
   },
   {
@@ -101,8 +136,32 @@ var ATOM_SPECS = [
     predicate: "cumulative-over",
     label: "Total budget over limit",
     description: "Fires when cumulative spend (already-spent + this transaction) exceeds a configured total budget.",
-    config: [{ key: "limit", type: "number", required: true, description: "Maximum total budget across all transactions" }],
-    requiredContext: ["amount"]
+    config: [
+      { key: "limit", type: "number", required: true, description: "Maximum total budget across all transactions" },
+      {
+        key: "currency",
+        type: "string[]",
+        required: false,
+        description: "Optional currency scope for the budget (e.g. ['USD'], or ['USD','GBP'] for several). Leave empty to keep it currency-blind \u2014 the historical default. Once set, a request in a currency outside this list \u2014 or with none supplied at all \u2014 fires this atom regardless of amount, same fail-closed design as amount-over's currency scope."
+      }
+    ],
+    // The executable atom (atom-registry.ts) reads BOTH fields: `cumulativeSpend + amount >
+    // limit`. Omitting `cumulativeSpend` here silently broke two downstream consumers this
+    // catalog is the single source of truth for (see file header): the Scenario Bank's
+    // simulate form never rendered an "already spent" field for any set using this atom —
+    // including its own seeded preset, which supplied `cumulativeSpend` for a form field
+    // that didn't exist — so the control could never actually be exercised from the UI; and
+    // the integration docs' generated "context contract" told real SDK integrators this
+    // atom only needs `amount`, so an agent that never sends `cumulativeSpend` gets it
+    // silently treated as 0 and the total-budget cap never fires in production either.
+    //
+    // `currency`, by contrast, is deliberately NOT added here even though the executable atom
+    // conditionally reads it — see the sibling comment on `amount-over`'s currency config
+    // above: it is optional PER ATOM INSTANCE (only read when a molecule configures a
+    // currency scope), so unlike `cumulativeSpend` (always read), a static per-predicate
+    // requiredContext can't represent it without forcing every set using this atom to demand
+    // a currency it may never need.
+    requiredContext: ["amount", "cumulativeSpend"]
   },
   {
     predicate: "risk-at-or-above",
@@ -357,7 +416,8 @@ function constraintSatisfied(c, req, strict) {
   const left = Object.prototype.hasOwnProperty.call(req.values, c.leftOperand) ? req.values[c.leftOperand] : void 0;
   if (!c.unit) return op(left, c.rightOperand);
   const currency = req.values["mm:currency"];
-  const unitMatches = typeof currency === "string" && currency.toUpperCase() === c.unit.toUpperCase();
+  const allowedUnits = Array.isArray(c.unit) ? c.unit : [c.unit];
+  const unitMatches = typeof currency === "string" && allowedUnits.some((u) => u.toUpperCase() === currency.toUpperCase());
   return unitMatches ? op(left, c.rightOperand) : !strict;
 }
 function targetOf(rule, mandate) {
@@ -454,7 +514,15 @@ function escapeField(v) {
   return v.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
 }
 function buildAuthMessage(f) {
-  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+  return [f.agentDid, f.action, f.amount, f.currency, f.merchant ?? "", f.resource ?? "", f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+function buildLocalDecisionMessage(f) {
+  return [f.agentDid, f.action, f.decision, f.reasonCode, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
+}
+
+// src/policy-core/checkpoint-anchor.ts
+function buildCheckpointAnchorMessage(f) {
+  return [f.agentDid, f.checkpointHash, f.previousCheckpointHash, f.entryCount, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
 
 // src/policy-core/context.ts
@@ -513,6 +581,8 @@ export {
   asOperatingMode,
   authorityFailure,
   buildAuthMessage,
+  buildCheckpointAnchorMessage,
+  buildLocalDecisionMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,