xytara 3.1.13 → 3.1.14

package/lib/agent_identity.js

@@ -1,162 +1,162 @@
-"use strict";
-
-// Cryptographic agent identity for delegated-spend credentials.
-//
-// A spend credential may be bound to an agent's ed25519 public key (the same
-// SPKI scheme xoonya's proof engine uses). When it is, presenting the bearer
-// token is no longer sufficient: the caller must also prove control of the
-// private key by signing a fresh challenge. This turns the credential from a
-// pure bearer secret into a key-bound, verifiable delegated authority.
-//
-// Backward-compatible: a credential with no bound key keeps the existing
-// bearer-only behavior. Dependency-free (node crypto; ed25519 verify is native).
-
-const crypto = require("crypto");
-
-// Accept an ed25519 public key as SPKI PEM or base64-encoded SPKI DER.
-// Returns { key: KeyObject, spki_der_b64, key_ref } or null.
-function normalizeAgentPublicKey(input) {
-  if (typeof input !== "string" || !input.trim()) return null;
-  const s = input.trim();
-  let key = null;
-  try {
-    if (s.includes("BEGIN PUBLIC KEY")) {
-      key = crypto.createPublicKey({ key: s, format: "pem" });
-    } else {
-      const der = Buffer.from(s.replace(/\s+/g, ""), "base64");
-      if (der.length === 0) return null;
-      key = crypto.createPublicKey({ key: der, format: "der", type: "spki" });
-    }
-  } catch (_) {
-    return null;
-  }
-  if (!key || key.asymmetricKeyType !== "ed25519") return null;
-  const spki = key.export({ type: "spki", format: "der" });
-  const keyRef = "ed25519-spki-sha256:" + crypto.createHash("sha256").update(spki).digest("hex");
-  return { key, spki_der_b64: spki.toString("base64"), key_ref: keyRef };
-}
-
-// The stable, public fingerprint of an agent key (matches xoonya's ref format).
-function deriveAgentKeyRef(input) {
-  const m = normalizeAgentPublicKey(input);
-  return m ? m.key_ref : null;
-}
-
-// A deterministic digest committing a spend proof to the specific request it authorizes
-// (account + units + task). A signature over a message carrying this digest can only be
-// used for that exact account/amount/task — closing the "fresh signature repurposed for a
-// different (within-cap) action" gap. Returns null when there is nothing to bind.
-function buildSpendBindingDigest(binding) {
-  if (!binding || typeof binding !== "object") return null;
-  const toStr = (v) => (v === undefined || v === null ? "" : String(v).trim());
-  const account = toStr(binding.account_id);
-  const units = toStr(binding.units);
-  const task = toStr(binding.task_ref);
-  if (!account && !units && !task) return null;
-  // JSON array of fixed-order fields: unambiguous / injection-free (JSON escapes the field
-  // values), unlike a delimiter-joined string where a value containing the delimiter could
-  // collide two different (account, units, task) tuples onto the same digest.
-  const canonical = JSON.stringify(["naxytra-spend-binding/v1", account, units, task]);
-  return crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
-}
-
-// The canonical challenge an agent signs to prove key control for a spend action. When a
-// bindingDigest is supplied the message additionally commits to the request (account/amount/
-// task); without it, the legacy unbound message (credential id + timestamp) is produced.
-function buildSpendAuthMessage(credentialId, timestamp, bindingDigest) {
-  const base = `naxytra-spend-auth:${credentialId}:${timestamp}`;
-  return bindingDigest ? `${base}:${bindingDigest}` : base;
-}
-
-// Verify an ed25519 signature (base64) over `message` against the bound key.
-function verifyAgentSignature(publicKeyInput, message, signatureB64) {
-  const m = normalizeAgentPublicKey(publicKeyInput);
-  if (!m) return false;
-  let sig;
-  try {
-    sig = Buffer.from(String(signatureB64 || ""), "base64");
-  } catch (_) {
-    return false;
-  }
-  if (sig.length === 0) return false;
-  try {
-    return crypto.verify(null, Buffer.from(String(message), "utf8"), m.key, sig);
-  } catch (_) {
-    return false;
-  }
-}
-
-// Verify a spend-auth proof for a credential that is key-bound.
-// proof = { signature, timestamp(ms) }. Returns
-//   { ok:true, canonical, message } | { ok:false, reason }.
-// Freshness is bounded in BOTH directions (too old, or too far in the future).
-// `canonical` is the decoded-signature fingerprint callers MUST use as the
-// single-use replay key (so a re-encoded base64 of the same bytes cannot slip
-// past the guard).
-//
-// options = { maxPastSeconds=120, maxFutureSeconds=30, requestBinding, requireBinding }.
-// Freshness is bounded in BOTH directions. When options.requestBinding is supplied, a proof
-// that signed the BOUND message (credential + timestamp + request digest) verifies and is
-// reported as bound:true — that signature is usable ONLY for this exact account/amount/task,
-// so a captured fresh signature cannot be repurposed for a different (even within-cap)
-// request. An unbound signature still verifies (back-compat) UNLESS options.requireBinding is
-// set (strict mode), which refuses anything not request-bound. `canonical` is the decoded-
-// signature fingerprint callers MUST use as the single-use replay key.
-function verifySpendAuthProof(agentPublicKey, credentialId, proof, options = {}) {
-  const opts = options && typeof options === "object" ? options : {};
-  const maxPastSeconds = Number.isFinite(opts.maxPastSeconds) ? opts.maxPastSeconds : 120;
-  const maxFutureSeconds = Number.isFinite(opts.maxFutureSeconds) ? opts.maxFutureSeconds : 30;
-  const requireBinding = Boolean(opts.requireBinding);
-  const bindingDigest = buildSpendBindingDigest(opts.requestBinding);
-
-  const signature = proof && typeof proof.signature === "string" ? proof.signature.trim() : "";
-  const timestampRaw = proof && (proof.timestamp !== undefined && proof.timestamp !== null) ? String(proof.timestamp).trim() : "";
-  if (!signature || !timestampRaw) return { ok: false, reason: "agent_signature_required" };
-  const timestamp = Number(timestampRaw);
-  if (!Number.isFinite(timestamp)) return { ok: false, reason: "agent_signature_timestamp_invalid" };
-  // Timestamp is milliseconds since epoch. Positive age = in the past.
-  const ageSeconds = (Date.now() - timestamp) / 1000;
-  if (ageSeconds > Math.max(1, maxPastSeconds)) return { ok: false, reason: "agent_signature_expired" };
-  if (ageSeconds < -Math.max(0, maxFutureSeconds)) return { ok: false, reason: "agent_signature_future" };
-  if (requireBinding && !bindingDigest) return { ok: false, reason: "spend_binding_required" };
-
-  // Prefer the request-bound message; fall back to the unbound message only when binding is
-  // not strictly required. A bound signature whose digest mismatches the actual request
-  // verifies against neither message -> rejected.
-  let message = null;
-  let bound = false;
-  if (bindingDigest) {
-    const boundMessage = buildSpendAuthMessage(credentialId, timestampRaw, bindingDigest);
-    if (verifyAgentSignature(agentPublicKey, boundMessage, signature)) {
-      message = boundMessage;
-      bound = true;
-    }
-  }
-  if (!message && !requireBinding) {
-    const unboundMessage = buildSpendAuthMessage(credentialId, timestampRaw);
-    if (verifyAgentSignature(agentPublicKey, unboundMessage, signature)) {
-      message = unboundMessage;
-      bound = false;
-    }
-  }
-  if (!message) {
-    return { ok: false, reason: requireBinding ? "agent_signature_binding_required_or_invalid" : "agent_signature_invalid" };
-  }
-  // Canonical replay key = hex of the decoded signature bytes (encoding-agnostic).
-  let canonical;
-  try {
-    canonical = Buffer.from(signature, "base64").toString("hex");
-  } catch (_) {
-    return { ok: false, reason: "agent_signature_invalid" };
-  }
-  return { ok: true, canonical, message, bound, expires_at_ms: timestamp + Math.max(1, maxPastSeconds) * 1000 };
-}
-
-module.exports = {
-  normalizeAgentPublicKey,
-  deriveAgentKeyRef,
-  buildSpendAuthMessage,
-  buildSpendBindingDigest,
-  verifyAgentSignature,
-  verifySpendAuthProof
-};
+"use strict";
+
+// Cryptographic agent identity for delegated-spend credentials.
+//
+// A spend credential may be bound to an agent's ed25519 public key (the same
+// SPKI scheme xoonya's proof engine uses). When it is, presenting the bearer
+// token is no longer sufficient: the caller must also prove control of the
+// private key by signing a fresh challenge. This turns the credential from a
+// pure bearer secret into a key-bound, verifiable delegated authority.
+//
+// Backward-compatible: a credential with no bound key keeps the existing
+// bearer-only behavior. Dependency-free (node crypto; ed25519 verify is native).
+
+const crypto = require("crypto");
+
+// Accept an ed25519 public key as SPKI PEM or base64-encoded SPKI DER.
+// Returns { key: KeyObject, spki_der_b64, key_ref } or null.
+function normalizeAgentPublicKey(input) {
+  if (typeof input !== "string" || !input.trim()) return null;
+  const s = input.trim();
+  let key = null;
+  try {
+    if (s.includes("BEGIN PUBLIC KEY")) {
+      key = crypto.createPublicKey({ key: s, format: "pem" });
+    } else {
+      const der = Buffer.from(s.replace(/\s+/g, ""), "base64");
+      if (der.length === 0) return null;
+      key = crypto.createPublicKey({ key: der, format: "der", type: "spki" });
+    }
+  } catch (_) {
+    return null;
+  }
+  if (!key || key.asymmetricKeyType !== "ed25519") return null;
+  const spki = key.export({ type: "spki", format: "der" });
+  const keyRef = "ed25519-spki-sha256:" + crypto.createHash("sha256").update(spki).digest("hex");
+  return { key, spki_der_b64: spki.toString("base64"), key_ref: keyRef };
+}
+
+// The stable, public fingerprint of an agent key (matches xoonya's ref format).
+function deriveAgentKeyRef(input) {
+  const m = normalizeAgentPublicKey(input);
+  return m ? m.key_ref : null;
+}
+
+// A deterministic digest committing a spend proof to the specific request it authorizes
+// (account + units + task). A signature over a message carrying this digest can only be
+// used for that exact account/amount/task — closing the "fresh signature repurposed for a
+// different (within-cap) action" gap. Returns null when there is nothing to bind.
+function buildSpendBindingDigest(binding) {
+  if (!binding || typeof binding !== "object") return null;
+  const toStr = (v) => (v === undefined || v === null ? "" : String(v).trim());
+  const account = toStr(binding.account_id);
+  const units = toStr(binding.units);
+  const task = toStr(binding.task_ref);
+  if (!account && !units && !task) return null;
+  // JSON array of fixed-order fields: unambiguous / injection-free (JSON escapes the field
+  // values), unlike a delimiter-joined string where a value containing the delimiter could
+  // collide two different (account, units, task) tuples onto the same digest.
+  const canonical = JSON.stringify(["naxytra-spend-binding/v1", account, units, task]);
+  return crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+// The canonical challenge an agent signs to prove key control for a spend action. When a
+// bindingDigest is supplied the message additionally commits to the request (account/amount/
+// task); without it, the legacy unbound message (credential id + timestamp) is produced.
+function buildSpendAuthMessage(credentialId, timestamp, bindingDigest) {
+  const base = `naxytra-spend-auth:${credentialId}:${timestamp}`;
+  return bindingDigest ? `${base}:${bindingDigest}` : base;
+}
+
+// Verify an ed25519 signature (base64) over `message` against the bound key.
+function verifyAgentSignature(publicKeyInput, message, signatureB64) {
+  const m = normalizeAgentPublicKey(publicKeyInput);
+  if (!m) return false;
+  let sig;
+  try {
+    sig = Buffer.from(String(signatureB64 || ""), "base64");
+  } catch (_) {
+    return false;
+  }
+  if (sig.length === 0) return false;
+  try {
+    return crypto.verify(null, Buffer.from(String(message), "utf8"), m.key, sig);
+  } catch (_) {
+    return false;
+  }
+}
+
+// Verify a spend-auth proof for a credential that is key-bound.
+// proof = { signature, timestamp(ms) }. Returns
+//   { ok:true, canonical, message } | { ok:false, reason }.
+// Freshness is bounded in BOTH directions (too old, or too far in the future).
+// `canonical` is the decoded-signature fingerprint callers MUST use as the
+// single-use replay key (so a re-encoded base64 of the same bytes cannot slip
+// past the guard).
+//
+// options = { maxPastSeconds=120, maxFutureSeconds=30, requestBinding, requireBinding }.
+// Freshness is bounded in BOTH directions. When options.requestBinding is supplied, a proof
+// that signed the BOUND message (credential + timestamp + request digest) verifies and is
+// reported as bound:true — that signature is usable ONLY for this exact account/amount/task,
+// so a captured fresh signature cannot be repurposed for a different (even within-cap)
+// request. An unbound signature still verifies (back-compat) UNLESS options.requireBinding is
+// set (strict mode), which refuses anything not request-bound. `canonical` is the decoded-
+// signature fingerprint callers MUST use as the single-use replay key.
+function verifySpendAuthProof(agentPublicKey, credentialId, proof, options = {}) {
+  const opts = options && typeof options === "object" ? options : {};
+  const maxPastSeconds = Number.isFinite(opts.maxPastSeconds) ? opts.maxPastSeconds : 120;
+  const maxFutureSeconds = Number.isFinite(opts.maxFutureSeconds) ? opts.maxFutureSeconds : 30;
+  const requireBinding = Boolean(opts.requireBinding);
+  const bindingDigest = buildSpendBindingDigest(opts.requestBinding);
+
+  const signature = proof && typeof proof.signature === "string" ? proof.signature.trim() : "";
+  const timestampRaw = proof && (proof.timestamp !== undefined && proof.timestamp !== null) ? String(proof.timestamp).trim() : "";
+  if (!signature || !timestampRaw) return { ok: false, reason: "agent_signature_required" };
+  const timestamp = Number(timestampRaw);
+  if (!Number.isFinite(timestamp)) return { ok: false, reason: "agent_signature_timestamp_invalid" };
+  // Timestamp is milliseconds since epoch. Positive age = in the past.
+  const ageSeconds = (Date.now() - timestamp) / 1000;
+  if (ageSeconds > Math.max(1, maxPastSeconds)) return { ok: false, reason: "agent_signature_expired" };
+  if (ageSeconds < -Math.max(0, maxFutureSeconds)) return { ok: false, reason: "agent_signature_future" };
+  if (requireBinding && !bindingDigest) return { ok: false, reason: "spend_binding_required" };
+
+  // Prefer the request-bound message; fall back to the unbound message only when binding is
+  // not strictly required. A bound signature whose digest mismatches the actual request
+  // verifies against neither message -> rejected.
+  let message = null;
+  let bound = false;
+  if (bindingDigest) {
+    const boundMessage = buildSpendAuthMessage(credentialId, timestampRaw, bindingDigest);
+    if (verifyAgentSignature(agentPublicKey, boundMessage, signature)) {
+      message = boundMessage;
+      bound = true;
+    }
+  }
+  if (!message && !requireBinding) {
+    const unboundMessage = buildSpendAuthMessage(credentialId, timestampRaw);
+    if (verifyAgentSignature(agentPublicKey, unboundMessage, signature)) {
+      message = unboundMessage;
+      bound = false;
+    }
+  }
+  if (!message) {
+    return { ok: false, reason: requireBinding ? "agent_signature_binding_required_or_invalid" : "agent_signature_invalid" };
+  }
+  // Canonical replay key = hex of the decoded signature bytes (encoding-agnostic).
+  let canonical;
+  try {
+    canonical = Buffer.from(signature, "base64").toString("hex");
+  } catch (_) {
+    return { ok: false, reason: "agent_signature_invalid" };
+  }
+  return { ok: true, canonical, message, bound, expires_at_ms: timestamp + Math.max(1, maxPastSeconds) * 1000 };
+}
+
+module.exports = {
+  normalizeAgentPublicKey,
+  deriveAgentKeyRef,
+  buildSpendAuthMessage,
+  buildSpendBindingDigest,
+  verifyAgentSignature,
+  verifySpendAuthProof
+};