@metamynd/agentsafe-signer 0.19.2 → 0.20.1

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.1",
   "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

@@ -43,6 +43,57 @@ function riskFloorFor(mandate, target) {
   }
   return floor;
 }
+var DEFAULT_AMOUNT_SHARE_HIGH = 0.7;
+function grantsFor(mandate, target) {
+  return (mandate?.permission ?? []).filter((p) => !!p && typeof p === "object" && (p.target ?? mandate?.target) === target);
+}
+function perTxnCapFor(mandate, target) {
+  let cap = null;
+  for (const p of grantsFor(mandate, target)) {
+    for (const c of p.constraint ?? []) {
+      if (c?.leftOperand !== "mm:payAmount") continue;
+      const n = Number(c.rightOperand);
+      if (Number.isFinite(n) && n > 0 && (cap === null || n < cap)) cap = n;
+    }
+  }
+  return cap;
+}
+function hasMerchantAllowList(mandate, target) {
+  return grantsFor(mandate, target).some((p) => (p.constraint ?? []).some((c) => c?.leftOperand === "mm:merchant"));
+}
+function riskSignalSettings(mandate, target) {
+  const grants = grantsFor(mandate, target);
+  if (grants.length === 0) return { amountShare: DEFAULT_AMOUNT_SHARE_HIGH, newMerchant: true };
+  let amountShare = null;
+  let newMerchant = false;
+  for (const p of grants) {
+    const s = p.riskSignals;
+    if (s === false) continue;
+    const cfg = s && typeof s === "object" ? s : {};
+    const share = cfg.amountShare === false ? null : cfg.amountShare === void 0 ? DEFAULT_AMOUNT_SHARE_HIGH : Number(cfg.amountShare);
+    if (share !== null && Number.isFinite(share) && share > 0 && share <= 1 && (amountShare === null || share < amountShare)) amountShare = share;
+    if (cfg.newMerchant !== false) newMerchant = true;
+  }
+  return { amountShare, newMerchant };
+}
+function riskSignalsFor(mandate, target, amount, opts = {}) {
+  const out = [];
+  const tier = riskFloorFor(mandate, target);
+  if (tier) out.push({ signal: "owner-tier", level: tier, detail: `the owner's risk tier for ${target}` });
+  const settings = riskSignalSettings(mandate, target);
+  const n = typeof amount === "number" ? amount : Number(amount);
+  const cap = perTxnCapFor(mandate, target);
+  if (settings.amountShare !== null && cap !== null && Number.isFinite(n) && n > 0 && n >= settings.amountShare * cap) {
+    out.push({ signal: "amount-share", level: "high", detail: `${Math.round(n / cap * 100)}% of the ${cap} per-transaction cap (review from ${Math.round(settings.amountShare * 100)}%)` });
+  }
+  if (opts.newMerchant === true && settings.newMerchant && !hasMerchantAllowList(mandate, target)) {
+    out.push({ signal: "new-merchant", level: "high", detail: "the first payment to this merchant" });
+  }
+  return out;
+}
+function effectiveRiskFloor(mandate, target, amount, opts = {}) {
+  return maxRisk(...riskSignalsFor(mandate, target, amount, opts).map((s) => s.level));
+}
 function requiresPayloadBindingFor(mandate, target) {
   if (!mandate) return false;
   for (const p of mandate.permission ?? []) {
@@ -732,6 +783,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,12 +837,14 @@ function operatingModeGate(mode, ctx) {
   }
 }
 export {
+  AGENT_SETTLE_PREFIX,
   ATOM_DEFAULT_REQUIRED_CONTEXT,
   ATOM_REGISTRY,
   ATOM_SPECS,
   AUTH_MESSAGE_V2_TAG,
   CATALOGUED_ATOMS,
   CONTEXT_UNVERIFIABLE,
+  DEFAULT_AMOUNT_SHARE_HIGH,
   JURISDICTION_ATOM,
   MODES_BY_RANK,
   MODE_RANK,
@@ -801,6 +858,7 @@ export {
   applySignedLast,
   asOperatingMode,
   authorityFailure,
+  buildAgentSettleMessage,
   buildAuthMessage,
   buildCheckpointAnchorMessage,
   buildLegacyAuthMessageV1,
@@ -809,10 +867,12 @@ export {
   canAuthorize,
   contextFieldProblem,
   documentEnforcesJurisdiction,
+  effectiveRiskFloor,
   evaluate,
   evaluateBoundStandards,
   evaluateMandate,
   evaluateStandardRules,
+  hasMerchantAllowList,
   isAuthorityFailure,
   isOperatingMode,
   isProvenance,
@@ -823,6 +883,7 @@ export {
   moreRestrictive,
   normalizeRiskLevel,
   operatingModeGate,
+  perTxnCapFor,
   provenanceOf,
   releaseHold,
   remainingBudget,
@@ -830,6 +891,8 @@ export {
   requiredContextOf,
   requiresPayloadBindingFor,
   riskFloorFor,
+  riskSignalSettings,
+  riskSignalsFor,
   sumEventField,
   validateMolecules
 };