@metamynd/agentsafe-signer 0.19.2 → 0.20.0

package/daemon.mjs

@@ -6,7 +6,7 @@ import net from 'node:net';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { buildAuthMessage, buildCheckpointAnchorMessage, buildLocalDecisionMessage } from './policy-core.mjs';
+import { buildAgentSettleMessage, buildAuthMessage, buildCheckpointAnchorMessage, buildLocalDecisionMessage } from './policy-core.mjs';
 import { envelopeHashFor } from './governance-envelope.mjs';
 import { buildPayloadBindingMessage, buildPayloadRebindMessage, isPayloadDigest } from './payload-binding.mjs';
 import { KeyStore, KeyStoreError } from './keystore.mjs';
@@ -18,7 +18,7 @@ export const MAX_LINE_BYTES = 64 * 1024;
 export const FRESHNESS_MS = 5 * 60 * 1000;
 export const CLOCK_SKEW_MS = 30 * 1000;
 
-const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'sign-service-call', 'get-identity', 'ping']);
+const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-settle', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'sign-service-call', 'get-identity', 'ping']);
 
 // sign-log-checkpoint is in BOTH role sets, unlike every other sign-* op: it authenticates the
 // daemon's own log-tamper-evidence checkpoint (T11), which every daemon keeps regardless of
@@ -28,7 +28,7 @@ const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payloa
 // (agentsafe-guard.mjs's reportLocalDecision()); a service-role daemon never evaluates a
 // mandate locally, so it has nothing to report.
 const SIGNING_OPS_BY_ROLE = {
-  agent: new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']),
+  agent: new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-settle', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']),
   // sign-service-call is SERVICE-role only: a Service's own settlement-surface call (claim / capture / void / …,
   // MAGP §8.7.6). An agent never claims or settles its own holds — an agent-role daemon signing one would let an
   // agent impersonate the counterparty that executes for it.
@@ -40,6 +40,8 @@ const DEFAULT_RATE_LIMITS = {
   'sign-envelope': { max: 20, windowMs: 10_000 },
   // One per bound authorize, plus one per late binding (a modified hold): never more than sign-authorize itself.
   'sign-payload': { max: 20, windowMs: 10_000 },
+  // An agent settling its OWN unclaimed hold (capture or void): at most one per authorize.
+  'sign-settle': { max: 20, windowMs: 10_000 },
   'sign-handshake-nonce': { max: 10, windowMs: 60_000 },
   'sign-key-control-challenge': { max: 3, windowMs: 60 * 60 * 1000 },
   // Local decisions are reported for every locally-decided block/escalate/non-value-allow, not
@@ -56,6 +58,9 @@ const DEFAULT_RATE_LIMITS = {
   'sign-service-call': { max: 120, windowMs: 10_000 },
 };
 
+// MAGP §8.7.4 — an agent's own unclaimed settlement: capture signs amountCharged, bookingRef, settlementTxHash; void, reason.
+const SETTLE_FIELD_COUNTS = { capture: 3, void: 1 };
+
 // MAGP §8.7.6 — the issuer's own layout (backend counterparty-auth.ts buildCounterpartyMessage):
 //   MAGP-SERVICE-v1 | action | authorizationId | ...fields | nonce | issuedAt   (each field "\" and "|" escaped)
 // The per-action field counts are the ones the issuer reconstructs the message from; anything else could
@@ -269,6 +274,8 @@ export class SignerDaemon {
         return this.#handleSignEnvelope(params);
       case 'sign-payload':
         return this.#handleSignPayload(params);
+      case 'sign-settle':
+        return this.#handleSignSettle(params);
       case 'sign-handshake-nonce':
         return this.#handleSignHandshakeNonce(params);
       case 'sign-key-control-challenge':
@@ -381,6 +388,30 @@ export class SignerDaemon {
     return { signature: this.#sign(Buffer.from(message, 'utf8')) };
   }
 
+  /**
+   * An agent settling its OWN hold that nobody has claimed (MAGP §8.7.4): capture it, or void it. The issuer accepts an
+   * unclaimed settlement only from that hold's agent, a counterparty the owner registered, or — for an open testnet owner —
+   * anyone. Built from validated fields under the fixed MAGP-SETTLE-v1 prefix, which no other message this daemon signs
+   * starts with; it names the agent, so it is never a counterparty's signature (sign-service-call, MAGP-SERVICE-v1), and an
+   * agent cannot use it to claim. Agent-role only.
+   */
+  #handleSignSettle(params = {}) {
+    this.#assertRateLimit('sign-settle');
+    const { verb, agentDid, authorizationId, nonce, issuedAt, fields } = params;
+    if (!Object.hasOwn(SETTLE_FIELD_COUNTS, verb)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'verb must be capture|void');
+    if (typeof agentDid !== 'string' || typeof nonce !== 'string' || typeof issuedAt !== 'string') throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'missing required field');
+    if (nonce.length === 0 || nonce.length > 128) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid nonce');
+    if (typeof authorizationId !== 'string' || !UUID_RE.test(authorizationId)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'authorizationId must be a UUID');
+    if (!Array.isArray(fields) || fields.length !== SETTLE_FIELD_COUNTS[verb] || !fields.every((v) => typeof v === 'string' && v.length <= 512)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', `fields must be ${SETTLE_FIELD_COUNTS[verb]} string(s) for ${verb}`);
+    }
+    if (verb === 'capture' && !isFiniteNonNegative(Number(fields[0]))) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'amountCharged must be finite and non-negative');
+    this.#assertIdentity(agentDid);
+    if (!freshnessOk(issuedAt)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'issuedAt outside freshness window');
+    const message = buildAgentSettleMessage({ verb, agentDid, authorizationId, nonce, issuedAt, fields });
+    return { signature: this.#sign(Buffer.from(message, 'utf8')) };
+  }
+
   /**
    * A Service's own settlement-surface call, signed as its identity (MAGP §8.7.6): the claim that makes it the one
    * party allowed to settle the hold, and the capture / void / unknown / reconcile that follow. Without this a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-signer",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Local signer daemon for AgentSafe agent/service keys \u2014 the key never enters the calling guard's own process. See docs/design/agent-key-custody-local-signer-daemon-plan.md.",
   "type": "module",
   "main": "./daemon.mjs",

package/policy-core.mjs

@@ -732,6 +732,10 @@ function buildLegacyAuthMessageV1(f) {
 function buildLocalDecisionMessage(f) {
   return [f.agentDid, f.action, f.decision, f.reasonCode, f.nonce, f.issuedAt].map((v) => escapeField(String(v))).join("|");
 }
+var AGENT_SETTLE_PREFIX = "MAGP-SETTLE-v1";
+function buildAgentSettleMessage(f) {
+  return [AGENT_SETTLE_PREFIX, f.verb, f.agentDid, f.authorizationId, f.nonce, f.issuedAt, ...f.fields].map((v) => escapeField(String(v))).join("|");
+}
 
 // src/policy-core/checkpoint-anchor.ts
 function buildCheckpointAnchorMessage(f) {
@@ -782,6 +786,7 @@ function operatingModeGate(mode, ctx) {
   }
 }
 export {
+  AGENT_SETTLE_PREFIX,
   ATOM_DEFAULT_REQUIRED_CONTEXT,
   ATOM_REGISTRY,
   ATOM_SPECS,
@@ -801,6 +806,7 @@ export {
   applySignedLast,
   asOperatingMode,
   authorityFailure,
+  buildAgentSettleMessage,
   buildAuthMessage,
   buildCheckpointAnchorMessage,
   buildLegacyAuthMessageV1,