@metamynd/agentsafe-guard 0.8.0 → 0.12.1

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) };
     }
   }
 
@@ -237,7 +297,7 @@ export function createGuard(opts = {}) {
    * @param {Array<{standardKey:string,document:object}>} [p.standards] enforced Standards bound to the agent
    * @param {Array<{standardKey:string,document:object}>} [p.sops]      active SOPs assigned to the agent
    * @param {object} [p.mandate]  the ODRL mandate document (omit to skip the mandate layer)
-   * @param {{action:string,amount?:number,merchant?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
+   * @param {{action:string,amount?:number,currency?:string,merchant?:string,resource?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
    * @returns {{decision:'allow'|'block'|'escalate',reasonCode:string|null,authorizationId:null,remaining:null,proofRef:null}}
    */
   function evaluateLocally({ contained = null, operatingMode = null, standards = [], sops = [], mandate, request }) {
@@ -250,7 +310,7 @@ export function createGuard(opts = {}) {
       const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
       return { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
     }
-    const { action, amount = 0, currency = 'USD', merchant = '', context = {}, cumulativeSpend = amount, now } = request;
+    const { action, amount = 0, currency = 'USD', merchant = '', resource = null, context = {}, cumulativeSpend = amount, now } = request;
     // Operating-mode autonomy ladder (Phase 2.5b): the trust-driven posture rides as a
     // SIBLING (like `contained`) and biases the edge verdict identically to the gate.
     // READ_ONLY denies a value-bearing action up-front; SUPERVISED/RESTRICTED only
@@ -266,7 +326,11 @@ export function createGuard(opts = {}) {
       standards,
       sops,
       mandate,
-      context: applySignedLast(context, { action, agentDid, amount }),
+      // currency/merchant/resource are signed fields too, same as action/agentDid/amount —
+      // omitting them here means a currency-scoped amount-over/cumulative-over Standards/SOP
+      // atom always sees currency as absent and fires closed. Mirrors mandate.service.ts's
+      // ruleCtx (PR #588) and the same fix in agentsafe-mcp-guard.mjs's verdictFromBundle.
+      context: applySignedLast(context, { action, agentDid, amount, currency, merchant, resource }),
       mandateRequest: mandate
         ? {
             target: action,
@@ -281,6 +345,9 @@ export function createGuard(opts = {}) {
               // amount, since undefined never equals a real unit. Defaults to 'USD' to match
               // the same default this file already uses for authorize()/buildSignedRequest().
               'mm:currency': currency,
+              // Unprefixed `resource` (not `mm:resource`) to match the constraint's own
+              // leftOperand (ResourceService.scopeConstraint()) — mirrors mandate.service.ts.
+              resource,
             }),
           }
         : undefined,
@@ -312,14 +379,29 @@ export function createGuard(opts = {}) {
     return b;
   }
 
-  /** Map a fetched bundle into the shape evaluateLocally expects, for one action. */
+  /**
+   * Map a fetched bundle into the shape evaluateLocally expects, for one action.
+   *
+   * `mandateFound` distinguishes "no mandate matches THIS action" from "omit mandate to
+   * skip the layer" (evaluateLocally's own documented, intentional behavior for a caller
+   * that never resolves one at all, e.g. guardToolLocal's caller-supplied bundle) — found
+   * live: this used to fall back to `mandates[0]` (an ARBITRARY, possibly unrelated
+   * mandate for a completely different action) rather than correctly reporting no
+   * authority for this one, and `authorizeLocal` never distinguished either case from a
+   * genuinely-mandate-less bundle, so an ungranted action with no Standard/SOP rule
+   * happening to also catch it was silently ALLOWED instead of NO_PERMISSION_FOR_ACTION.
+   */
   function _bundleFor(b, action) {
+    const mandates = b.mandates ?? [];
+    const match = mandates.find((m) => m.action === action);
     return {
       contained: b.contained ?? null,
       operatingMode: b.operatingMode ?? null,
       standards: (b.standards ?? []).map((s) => ({ standardKey: s.id ?? s.standardKey ?? 'standard', document: s.document })).filter((s) => s.document),
       sops: (b.sops ?? []).map((s) => ({ standardKey: s.id ?? s.sopId ?? 'sop', document: s.document })).filter((s) => s.document),
-      mandate: ((b.mandates ?? []).find((m) => m.action === action) ?? (b.mandates ?? [])[0])?.document,
+      mandate: match?.document,
+      mandateFound: !!match,
+      anyMandates: mandates.length > 0,
     };
   }
 
@@ -355,6 +437,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
@@ -379,11 +492,34 @@ export function createGuard(opts = {}) {
       const sig = b?.proof?.signature;
       if (!anchor?.sigDigest || !sig || _sha256(sig) !== anchor.sigDigest) return authorize(input);
     }
-    const local = evaluateLocally({ ..._bundleFor(b, action), request: input });
+    const { mandateFound, anyMandates, ...bundleForAction } = _bundleFor(b, action);
+    // No mandate covers this action at all — refuse outright rather than let evaluateLocally
+    // silently allow (its documented "omit mandate to skip the layer" behavior is for a
+    // caller that never intended a mandate check, not for one that looked and found none).
+    // Standards/SOP containment still applies first — a suspended/quarantined agent is
+    // refused for THAT reason, not misreported as merely lacking this one action.
+    if (!mandateFound) {
+      const contained = bundleForAction.contained;
+      if (contained && contained.status) {
+        const decision = contained.status === 'quarantined' ? 'quarantine' : 'suspend';
+        const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
+        const local = { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
+        reportLocalDecision(action, local.decision, local.reasonCode);
+        return local;
+      }
+      const local = { decision: 'block', reasonCode: anyMandates ? 'NO_PERMISSION_FOR_ACTION' : 'NO_MANDATE', authorizationId: null, remaining: null, proofRef: null };
+      reportLocalDecision(action, local.decision, local.reasonCode);
+      return local;
+    }
+    const local = evaluateLocally({ ...bundleForAction, 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 +581,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 +656,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 +665,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 +673,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 +842,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 +853,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.8.0",
+  "version": "0.12.1",
   "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

@@ -514,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
@@ -573,6 +581,8 @@ export {
   asOperatingMode,
   authorityFailure,
   buildAuthMessage,
+  buildCheckpointAnchorMessage,
+  buildLocalDecisionMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,