xytara 3.1.13 → 3.1.15

package/scripts/verify_agent_identity.js

@@ -1,153 +1,153 @@
-"use strict";
-
-// Verifies cryptographic agent identity for delegated-spend credentials:
-// ed25519 key binding + fresh signed-proof enforcement with replay (encoding-
-// agnostic, mandatory/fail-closed), expiry and future-dating guards; key binding
-// carried through rotation; invalid keys not bricking; and byte-for-byte backward
-// compatibility when no key is bound.
-
-const crypto = require("crypto");
-const assert = require("assert");
-const ai = require("../lib/agent_identity");
-const { createSpendCredential, resolveSpendCredential, createAuthorityBinding, rotateAuthorityBinding } = require("../lib/account_auth");
-
-function mkState() {
-  return {
-    accountSpendCredentials: new Map(),
-    accountSpendCredentialsByToken: new Map(),
-    accountAuthorityBindings: new Map(),
-    acceptedAgentSignatures: new Map()
-  };
-}
-
-function signAuth(privateKey, credentialId, timestamp) {
-  const msg = ai.buildSpendAuthMessage(credentialId, String(timestamp));
-  return crypto.sign(null, Buffer.from(msg, "utf8"), privateKey).toString("base64");
-}
-
-function main() {
-  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
-  const pubPem = publicKey.export({ type: "spki", format: "pem" });
-  const pubDerB64 = publicKey.export({ type: "spki", format: "der" }).toString("base64");
-
-  // 1. Key helpers: ref stable across PEM/DER; invalid -> null; sign/verify.
-  const ref = ai.deriveAgentKeyRef(pubPem);
-  assert.ok(ref && ref.startsWith("ed25519-spki-sha256:"), "ref format");
-  assert.strictEqual(ai.deriveAgentKeyRef(pubDerB64), ref, "PEM and DER give the same ref");
-  assert.strictEqual(ai.deriveAgentKeyRef("not a key"), null, "invalid key -> null");
-  const m = "hello";
-  const sig = crypto.sign(null, Buffer.from(m), privateKey).toString("base64");
-  assert.strictEqual(ai.verifyAgentSignature(pubPem, m, sig), true, "valid sig verifies");
-  assert.strictEqual(ai.verifyAgentSignature(pubPem, "tampered", sig), false, "tampered msg fails");
-
-  // 2. No key bound -> bearer-only, unchanged behavior.
-  let state = mkState();
-  const cred0 = createSpendCredential(state, { credential_id: "c0", account_id: "acct" });
-  assert.strictEqual(cred0.identity_bound, false);
-  assert.strictEqual(cred0.agent_key_ref, null);
-  assert.strictEqual(resolveSpendCredential(state, cred0.bearer_token).ok, true, "bearer-only resolves");
-
-  // 3. Invalid key provided -> NOT bricked: stored as bearer-only (consistent view).
-  state = mkState();
-  const credBad = createSpendCredential(state, { credential_id: "cbad", account_id: "acct", agent_public_key: "garbage-not-a-key" });
-  assert.strictEqual(credBad.identity_bound, false, "invalid key is ignored");
-  assert.strictEqual(credBad.agent_key_ref, null);
-  assert.strictEqual(resolveSpendCredential(state, credBad.bearer_token).ok, true, "falls back to bearer-only");
-
-  // 4. Key bound -> signed proof required + enforced.
-  state = mkState();
-  const cred = createSpendCredential(state, { credential_id: "c1", account_id: "acct", agent_public_key: pubPem });
-  assert.strictEqual(cred.identity_bound, true);
-  assert.strictEqual(cred.agent_key_ref, ref);
-
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token).reason, "agent_signature_required", "no proof -> required");
-
-  const ts = Date.now();
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", ts), timestamp: String(ts) }).ok, true, "valid proof authorizes");
-
-  // 5. Replay is encoding-agnostic (canonical decoded-signature key).
-  const ts2 = Date.now() + 1;
-  const sig2 = signAuth(privateKey, "c1", ts2);
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: sig2, timestamp: String(ts2) }).ok, true);
-  const sig2UrlSafe = sig2.replace(/\+/g, "-").replace(/\//g, "_"); // re-encoded, same bytes
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: sig2UrlSafe, timestamp: String(ts2) }).reason, "agent_signature_replayed", "re-encoded replay is caught");
-
-  // 6. Expired (too old) and future-dated proofs rejected.
-  const oldTs = Date.now() - 10 * 60 * 1000;
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", oldTs), timestamp: String(oldTs) }).reason, "agent_signature_expired");
-  const futureTs = Date.now() + 10 * 60 * 1000;
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", futureTs), timestamp: String(futureTs) }).reason, "agent_signature_future");
-
-  // 7. Wrong key -> invalid.
-  const other = crypto.generateKeyPairSync("ed25519");
-  const ts3 = Date.now();
-  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(other.privateKey, "c1", ts3), timestamp: String(ts3) }).reason, "agent_signature_invalid");
-
-  // 8. Fail closed if the replay store is unavailable.
-  const stateNoStore = { accountSpendCredentials: state.accountSpendCredentials, accountSpendCredentialsByToken: state.accountSpendCredentialsByToken, accountAuthorityBindings: new Map() };
-  const ts4 = Date.now();
-  assert.strictEqual(resolveSpendCredential(stateNoStore, cred.bearer_token, { signature: signAuth(privateKey, "c1", ts4), timestamp: String(ts4) }).reason, "agent_replay_store_unavailable");
-
-  // 9. Authority binding threads the key through; rotation preserves it.
-  state = mkState();
-  const binding = createAuthorityBinding(state, { binding_id: "b1", account_id: "acct", agent_public_key: pubPem, max_commit_units: 100 });
-  assert.strictEqual(binding.spend_credential.identity_bound, true, "binding credential key-bound");
-  assert.strictEqual(binding.spend_credential.agent_key_ref, ref);
-  const rotated = rotateAuthorityBinding(state, "b1", {});
-  assert.strictEqual(rotated.successor_authority_binding.spend_credential.identity_bound, true, "rotation preserves key binding");
-  assert.strictEqual(rotated.successor_authority_binding.spend_credential.agent_key_ref, ref, "rotation preserves the same key ref");
-
-  // 10. Request binding (amount/task) — additive, back-compat with everything above.
-  state = mkState();
-  const credB = createSpendCredential(state, { credential_id: "cb", account_id: "acct", agent_public_key: pubPem });
-  const bindReq = { account_id: "acct", units: 10, task_ref: "doc.analyze" };
-  const signBound = (ts, binding) =>
-    crypto.sign(null, Buffer.from(ai.buildSpendAuthMessage("cb", String(ts), ai.buildSpendBindingDigest(binding)), "utf8"), privateKey).toString("base64");
-
-  // 10a. A bound proof matching the request authorizes.
-  let tsb = Date.now();
-  let res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, bindReq);
-  assert.strictEqual(res.ok, true, "bound proof matching the request authorizes");
-
-  // 10b. A proof bound to 10 units cannot authorize a 999-unit request (amount tampering).
-  tsb = Date.now() + 1;
-  res = resolveSpendCredential(state, credB.bearer_token,
-    { signature: signBound(tsb, { account_id: "acct", units: 10, task_ref: "doc.analyze" }), timestamp: String(tsb) },
-    { account_id: "acct", units: 999, task_ref: "doc.analyze" });
-  assert.strictEqual(res.reason, "agent_signature_invalid", "amount-bound proof rejects a different amount");
-
-  // 10c. A proof bound to one task cannot authorize another.
-  tsb = Date.now() + 2;
-  res = resolveSpendCredential(state, credB.bearer_token,
-    { signature: signBound(tsb, { account_id: "acct", units: 10, task_ref: "doc.analyze" }), timestamp: String(tsb) },
-    { account_id: "acct", units: 10, task_ref: "image.render" });
-  assert.strictEqual(res.reason, "agent_signature_invalid", "task-bound proof rejects a different task");
-
-  // 10d. An unbound proof still authorizes by default even when a binding is supplied.
-  tsb = Date.now() + 3;
-  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) }, bindReq);
-  assert.strictEqual(res.ok, true, "unbound proof still authorizes by default (back-compat)");
-
-  // 10e. Strict binding is CALLER-scoped (requestBinding.require=true), not a global flag — so
-  //      it applies only where a binding is supplied (execute path), never the lifecycle paths.
-  const strictBind = { ...bindReq, require: true };
-  tsb = Date.now() + 4;
-  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) }, strictBind);
-  assert.strictEqual(res.reason, "agent_signature_binding_required_or_invalid", "strict refuses an unbound proof");
-  tsb = Date.now() + 5;
-  res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, strictBind);
-  assert.strictEqual(res.ok, true, "strict accepts a matching bound proof");
-  tsb = Date.now() + 6;
-  res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, { require: true });
-  assert.strictEqual(res.reason, "spend_binding_required", "strict requires a request binding");
-
-  // 10f. A key-bound credential on a NON-binding caller (no requestBinding) is unaffected by
-  //      strict mode — the lifecycle paths (reserve/release/reverse) keep working.
-  tsb = Date.now() + 7;
-  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) });
-  assert.strictEqual(res.ok, true, "no-binding caller still authorizes under back-compat");
-
-  console.log("verify_agent_identity: all checks passed");
-}
-
-main();
+"use strict";
+
+// Verifies cryptographic agent identity for delegated-spend credentials:
+// ed25519 key binding + fresh signed-proof enforcement with replay (encoding-
+// agnostic, mandatory/fail-closed), expiry and future-dating guards; key binding
+// carried through rotation; invalid keys not bricking; and byte-for-byte backward
+// compatibility when no key is bound.
+
+const crypto = require("crypto");
+const assert = require("assert");
+const ai = require("../lib/agent_identity");
+const { createSpendCredential, resolveSpendCredential, createAuthorityBinding, rotateAuthorityBinding } = require("../lib/account_auth");
+
+function mkState() {
+  return {
+    accountSpendCredentials: new Map(),
+    accountSpendCredentialsByToken: new Map(),
+    accountAuthorityBindings: new Map(),
+    acceptedAgentSignatures: new Map()
+  };
+}
+
+function signAuth(privateKey, credentialId, timestamp) {
+  const msg = ai.buildSpendAuthMessage(credentialId, String(timestamp));
+  return crypto.sign(null, Buffer.from(msg, "utf8"), privateKey).toString("base64");
+}
+
+function main() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const pubPem = publicKey.export({ type: "spki", format: "pem" });
+  const pubDerB64 = publicKey.export({ type: "spki", format: "der" }).toString("base64");
+
+  // 1. Key helpers: ref stable across PEM/DER; invalid -> null; sign/verify.
+  const ref = ai.deriveAgentKeyRef(pubPem);
+  assert.ok(ref && ref.startsWith("ed25519-spki-sha256:"), "ref format");
+  assert.strictEqual(ai.deriveAgentKeyRef(pubDerB64), ref, "PEM and DER give the same ref");
+  assert.strictEqual(ai.deriveAgentKeyRef("not a key"), null, "invalid key -> null");
+  const m = "hello";
+  const sig = crypto.sign(null, Buffer.from(m), privateKey).toString("base64");
+  assert.strictEqual(ai.verifyAgentSignature(pubPem, m, sig), true, "valid sig verifies");
+  assert.strictEqual(ai.verifyAgentSignature(pubPem, "tampered", sig), false, "tampered msg fails");
+
+  // 2. No key bound -> bearer-only, unchanged behavior.
+  let state = mkState();
+  const cred0 = createSpendCredential(state, { credential_id: "c0", account_id: "acct" });
+  assert.strictEqual(cred0.identity_bound, false);
+  assert.strictEqual(cred0.agent_key_ref, null);
+  assert.strictEqual(resolveSpendCredential(state, cred0.bearer_token).ok, true, "bearer-only resolves");
+
+  // 3. Invalid key provided -> NOT bricked: stored as bearer-only (consistent view).
+  state = mkState();
+  const credBad = createSpendCredential(state, { credential_id: "cbad", account_id: "acct", agent_public_key: "garbage-not-a-key" });
+  assert.strictEqual(credBad.identity_bound, false, "invalid key is ignored");
+  assert.strictEqual(credBad.agent_key_ref, null);
+  assert.strictEqual(resolveSpendCredential(state, credBad.bearer_token).ok, true, "falls back to bearer-only");
+
+  // 4. Key bound -> signed proof required + enforced.
+  state = mkState();
+  const cred = createSpendCredential(state, { credential_id: "c1", account_id: "acct", agent_public_key: pubPem });
+  assert.strictEqual(cred.identity_bound, true);
+  assert.strictEqual(cred.agent_key_ref, ref);
+
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token).reason, "agent_signature_required", "no proof -> required");
+
+  const ts = Date.now();
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", ts), timestamp: String(ts) }).ok, true, "valid proof authorizes");
+
+  // 5. Replay is encoding-agnostic (canonical decoded-signature key).
+  const ts2 = Date.now() + 1;
+  const sig2 = signAuth(privateKey, "c1", ts2);
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: sig2, timestamp: String(ts2) }).ok, true);
+  const sig2UrlSafe = sig2.replace(/\+/g, "-").replace(/\//g, "_"); // re-encoded, same bytes
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: sig2UrlSafe, timestamp: String(ts2) }).reason, "agent_signature_replayed", "re-encoded replay is caught");
+
+  // 6. Expired (too old) and future-dated proofs rejected.
+  const oldTs = Date.now() - 10 * 60 * 1000;
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", oldTs), timestamp: String(oldTs) }).reason, "agent_signature_expired");
+  const futureTs = Date.now() + 10 * 60 * 1000;
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(privateKey, "c1", futureTs), timestamp: String(futureTs) }).reason, "agent_signature_future");
+
+  // 7. Wrong key -> invalid.
+  const other = crypto.generateKeyPairSync("ed25519");
+  const ts3 = Date.now();
+  assert.strictEqual(resolveSpendCredential(state, cred.bearer_token, { signature: signAuth(other.privateKey, "c1", ts3), timestamp: String(ts3) }).reason, "agent_signature_invalid");
+
+  // 8. Fail closed if the replay store is unavailable.
+  const stateNoStore = { accountSpendCredentials: state.accountSpendCredentials, accountSpendCredentialsByToken: state.accountSpendCredentialsByToken, accountAuthorityBindings: new Map() };
+  const ts4 = Date.now();
+  assert.strictEqual(resolveSpendCredential(stateNoStore, cred.bearer_token, { signature: signAuth(privateKey, "c1", ts4), timestamp: String(ts4) }).reason, "agent_replay_store_unavailable");
+
+  // 9. Authority binding threads the key through; rotation preserves it.
+  state = mkState();
+  const binding = createAuthorityBinding(state, { binding_id: "b1", account_id: "acct", agent_public_key: pubPem, max_commit_units: 100 });
+  assert.strictEqual(binding.spend_credential.identity_bound, true, "binding credential key-bound");
+  assert.strictEqual(binding.spend_credential.agent_key_ref, ref);
+  const rotated = rotateAuthorityBinding(state, "b1", {});
+  assert.strictEqual(rotated.successor_authority_binding.spend_credential.identity_bound, true, "rotation preserves key binding");
+  assert.strictEqual(rotated.successor_authority_binding.spend_credential.agent_key_ref, ref, "rotation preserves the same key ref");
+
+  // 10. Request binding (amount/task) — additive, back-compat with everything above.
+  state = mkState();
+  const credB = createSpendCredential(state, { credential_id: "cb", account_id: "acct", agent_public_key: pubPem });
+  const bindReq = { account_id: "acct", units: 10, task_ref: "doc.analyze" };
+  const signBound = (ts, binding) =>
+    crypto.sign(null, Buffer.from(ai.buildSpendAuthMessage("cb", String(ts), ai.buildSpendBindingDigest(binding)), "utf8"), privateKey).toString("base64");
+
+  // 10a. A bound proof matching the request authorizes.
+  let tsb = Date.now();
+  let res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, bindReq);
+  assert.strictEqual(res.ok, true, "bound proof matching the request authorizes");
+
+  // 10b. A proof bound to 10 units cannot authorize a 999-unit request (amount tampering).
+  tsb = Date.now() + 1;
+  res = resolveSpendCredential(state, credB.bearer_token,
+    { signature: signBound(tsb, { account_id: "acct", units: 10, task_ref: "doc.analyze" }), timestamp: String(tsb) },
+    { account_id: "acct", units: 999, task_ref: "doc.analyze" });
+  assert.strictEqual(res.reason, "agent_signature_invalid", "amount-bound proof rejects a different amount");
+
+  // 10c. A proof bound to one task cannot authorize another.
+  tsb = Date.now() + 2;
+  res = resolveSpendCredential(state, credB.bearer_token,
+    { signature: signBound(tsb, { account_id: "acct", units: 10, task_ref: "doc.analyze" }), timestamp: String(tsb) },
+    { account_id: "acct", units: 10, task_ref: "image.render" });
+  assert.strictEqual(res.reason, "agent_signature_invalid", "task-bound proof rejects a different task");
+
+  // 10d. An unbound proof still authorizes by default even when a binding is supplied.
+  tsb = Date.now() + 3;
+  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) }, bindReq);
+  assert.strictEqual(res.ok, true, "unbound proof still authorizes by default (back-compat)");
+
+  // 10e. Strict binding is CALLER-scoped (requestBinding.require=true), not a global flag — so
+  //      it applies only where a binding is supplied (execute path), never the lifecycle paths.
+  const strictBind = { ...bindReq, require: true };
+  tsb = Date.now() + 4;
+  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) }, strictBind);
+  assert.strictEqual(res.reason, "agent_signature_binding_required_or_invalid", "strict refuses an unbound proof");
+  tsb = Date.now() + 5;
+  res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, strictBind);
+  assert.strictEqual(res.ok, true, "strict accepts a matching bound proof");
+  tsb = Date.now() + 6;
+  res = resolveSpendCredential(state, credB.bearer_token, { signature: signBound(tsb, bindReq), timestamp: String(tsb) }, { require: true });
+  assert.strictEqual(res.reason, "spend_binding_required", "strict requires a request binding");
+
+  // 10f. A key-bound credential on a NON-binding caller (no requestBinding) is unaffected by
+  //      strict mode — the lifecycle paths (reserve/release/reverse) keep working.
+  tsb = Date.now() + 7;
+  res = resolveSpendCredential(state, credB.bearer_token, { signature: signAuth(privateKey, "cb", tsb), timestamp: String(tsb) });
+  assert.strictEqual(res.ok, true, "no-binding caller still authorizes under back-compat");
+
+  console.log("verify_agent_identity: all checks passed");
+}
+
+main();

package/scripts/verify_all.js

@@ -4960,4 +4960,4 @@ main().catch((error) => {
   console.error(error);
   process.exit(1);
 });
-
+

package/scripts/verify_bolt_adapter.js

@@ -1,128 +1,128 @@
-"use strict";
-
-// Verifies the BSV/UTXO (BOLT) adapter (lib/bolt_adapter.js). Offline: the chain
-// fetch is injected as a mock, so no network. Exercises config gating, header
-// parsing, and the on-chain amount/address verification + confirmations logic.
-
-const assert = require("assert");
-const m = require("../lib/bolt_adapter");
-
-function setEnv(env) {
-  const saved = {};
-  for (const k in env) {
-    saved[k] = process.env[k];
-    if (env[k] === undefined) delete process.env[k];
-    else process.env[k] = env[k];
-  }
-  return () => {
-    for (const k in saved) {
-      if (saved[k] === undefined) delete process.env[k];
-      else process.env[k] = saved[k];
-    }
-  };
-}
-
-const PAYTO = "1NaxytraPayToAddressExampleXXXXXXXXXX";
-const TXID = "a".repeat(64);
-
-function mockTx(voutValueBsv, address, confirmations) {
-  return async () => ({ status: 200, json: { confirmations, vout: [{ value: voutValueBsv, scriptPubKey: { addresses: [address] } }] } });
-}
-
-async function main() {
-  // 1. Not configured.
-  let restore = setEnv({ XYTARA_BOLT_PROVIDER: undefined });
-  let cfg = m.loadBoltConfig();
-  assert.strictEqual(cfg.provider, null);
-  assert.strictEqual(m.isConfigured(cfg), false);
-  assert.strictEqual((await m.verifyBsvPayment(cfg, TXID)).reason, "bolt_provider_not_configured");
-  restore();
-
-  // 2. Configured (whatsonchain).
-  restore = setEnv({
-    XYTARA_BOLT_PROVIDER: "whatsonchain",
-    XYTARA_BOLT_PAYTO_ADDRESS: PAYTO,
-    XYTARA_BOLT_PRICE_SATS: "1000",
-    XYTARA_BOLT_MIN_CONFIRMATIONS: "1",
-    XYTARA_BOLT_NETWORK: "main"
-  });
-  cfg = m.loadBoltConfig();
-  assert.strictEqual(cfg.provider, "whatsonchain");
-  assert.ok(cfg.apiUrl.includes("whatsonchain.com"));
-
-  // Header parsing.
-  assert.deepStrictEqual(m.parseBoltHeader(`BOLT ${TXID}`), { txid: TXID });
-  assert.strictEqual(m.parseBoltHeader("BOLT not-a-txid"), null);
-  assert.strictEqual(m.parseBoltHeader("Bearer x"), null);
-
-  // Challenge shape.
-  const ch = m.buildBoltChallenge(cfg);
-  assert.strictEqual(ch.address, PAYTO);
-  assert.strictEqual(ch.amount_sats, 1000);
-
-  // Invalid txid -> rejected before any fetch.
-  assert.strictEqual((await m.verifyBsvPayment(cfg, "xyz")).reason, "bolt_txid_invalid");
-
-  // Sufficient payment (0.00002 BSV = 2000 sats to PAYTO, 3 confs) -> ok.
-  let r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.00002, PAYTO, 3));
-  assert.strictEqual(r.ok, true);
-  assert.strictEqual(r.paid_sats, 2000);
-  assert.strictEqual(r.confirmations, 3);
-
-  // --- Per-quote binding: unique exact amount ---
-  const reqSats = m.computeRequiredSats(cfg, { quote_id: "quote_x" });
-  assert.ok(reqSats >= 1000 && reqSats < 1000 + cfg.bindingWindowSats, "required = price + bounded offset");
-  assert.strictEqual(reqSats, m.computeRequiredSats(cfg, { quote_id: "quote_x" }), "deterministic");
-  // Paying the EXACT bound amount -> ok.
-  r = await m.verifyBsvPayment(cfg, TXID, mockTx(reqSats / 1e8, PAYTO, 3), { requiredSats: reqSats });
-  assert.strictEqual(r.ok, true);
-  assert.strictEqual(r.paid_sats, reqSats);
-  assert.strictEqual(r.required_sats, reqSats);
-  // Paying a DIFFERENT amount (even to the right address) -> mismatch, so an
-  // unrelated payment cannot be reused to satisfy this quote.
-  r = await m.verifyBsvPayment(cfg, TXID, mockTx((reqSats + 1) / 1e8, PAYTO, 3), { requiredSats: reqSats });
-  assert.strictEqual(r.reason, "bolt_amount_mismatch");
-  // Challenge advertises the exact amount.
-  const boundChallenge = m.buildBoltChallenge(cfg, { requiredSats: reqSats });
-  assert.strictEqual(boundChallenge.amount_sats, reqSats);
-  assert.strictEqual(boundChallenge.exact, true);
-
-  // Insufficient amount (500 sats < 1000) -> rejected.
-  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.000005, PAYTO, 3));
-  assert.strictEqual(r.ok, false);
-  assert.strictEqual(r.reason, "bolt_amount_insufficient");
-
-  // Paid to the wrong address -> counts as zero -> insufficient.
-  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.001, "1SomeOtherAddressXXXXXXXXXXXXXXXXXXX", 3));
-  assert.strictEqual(r.reason, "bolt_amount_insufficient");
-
-  // Too few confirmations -> rejected.
-  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.00002, PAYTO, 0));
-  assert.strictEqual(r.reason, "bolt_insufficient_confirmations");
-
-  // Default min_confirmations is 1 (not 0) when unset -> mempool (0-conf) rejected.
-  const dflt = setEnv({ XYTARA_BOLT_PROVIDER: "whatsonchain", XYTARA_BOLT_PAYTO_ADDRESS: PAYTO, XYTARA_BOLT_PRICE_SATS: "1000", XYTARA_BOLT_MIN_CONFIRMATIONS: undefined });
-  const dcfg = m.loadBoltConfig();
-  assert.strictEqual(dcfg.minConfirmations, 1);
-  r = await m.verifyBsvPayment(dcfg, TXID, mockTx(0.00002, PAYTO, 0));
-  assert.strictEqual(r.reason, "bolt_insufficient_confirmations");
-  dflt();
-
-  // Tx not found (404) -> rejected.
-  r = await m.verifyBsvPayment(cfg, TXID, async () => ({ status: 404, json: null }));
-  assert.strictEqual(r.reason, "bolt_tx_not_found");
-  restore();
-
-  // 3. Configured but missing payto/price -> explicit reason (no fetch).
-  restore = setEnv({ XYTARA_BOLT_PROVIDER: "whatsonchain", XYTARA_BOLT_PAYTO_ADDRESS: undefined, XYTARA_BOLT_PRICE_SATS: undefined });
-  cfg = m.loadBoltConfig();
-  assert.strictEqual((await m.verifyBsvPayment(cfg, TXID)).reason, "bolt_payto_or_price_missing");
-  restore();
-
-  console.log("verify_bolt_adapter: all BSV/UTXO (BOLT) adapter checks passed");
-}
-
-main().catch((error) => {
-  console.error("verify_bolt_adapter failed:", error && error.message ? error.message : error);
-  process.exitCode = 1;
-});
+"use strict";
+
+// Verifies the BSV/UTXO (BOLT) adapter (lib/bolt_adapter.js). Offline: the chain
+// fetch is injected as a mock, so no network. Exercises config gating, header
+// parsing, and the on-chain amount/address verification + confirmations logic.
+
+const assert = require("assert");
+const m = require("../lib/bolt_adapter");
+
+function setEnv(env) {
+  const saved = {};
+  for (const k in env) {
+    saved[k] = process.env[k];
+    if (env[k] === undefined) delete process.env[k];
+    else process.env[k] = env[k];
+  }
+  return () => {
+    for (const k in saved) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  };
+}
+
+const PAYTO = "1NaxytraPayToAddressExampleXXXXXXXXXX";
+const TXID = "a".repeat(64);
+
+function mockTx(voutValueBsv, address, confirmations) {
+  return async () => ({ status: 200, json: { confirmations, vout: [{ value: voutValueBsv, scriptPubKey: { addresses: [address] } }] } });
+}
+
+async function main() {
+  // 1. Not configured.
+  let restore = setEnv({ XYTARA_BOLT_PROVIDER: undefined });
+  let cfg = m.loadBoltConfig();
+  assert.strictEqual(cfg.provider, null);
+  assert.strictEqual(m.isConfigured(cfg), false);
+  assert.strictEqual((await m.verifyBsvPayment(cfg, TXID)).reason, "bolt_provider_not_configured");
+  restore();
+
+  // 2. Configured (whatsonchain).
+  restore = setEnv({
+    XYTARA_BOLT_PROVIDER: "whatsonchain",
+    XYTARA_BOLT_PAYTO_ADDRESS: PAYTO,
+    XYTARA_BOLT_PRICE_SATS: "1000",
+    XYTARA_BOLT_MIN_CONFIRMATIONS: "1",
+    XYTARA_BOLT_NETWORK: "main"
+  });
+  cfg = m.loadBoltConfig();
+  assert.strictEqual(cfg.provider, "whatsonchain");
+  assert.ok(cfg.apiUrl.includes("whatsonchain.com"));
+
+  // Header parsing.
+  assert.deepStrictEqual(m.parseBoltHeader(`BOLT ${TXID}`), { txid: TXID });
+  assert.strictEqual(m.parseBoltHeader("BOLT not-a-txid"), null);
+  assert.strictEqual(m.parseBoltHeader("Bearer x"), null);
+
+  // Challenge shape.
+  const ch = m.buildBoltChallenge(cfg);
+  assert.strictEqual(ch.address, PAYTO);
+  assert.strictEqual(ch.amount_sats, 1000);
+
+  // Invalid txid -> rejected before any fetch.
+  assert.strictEqual((await m.verifyBsvPayment(cfg, "xyz")).reason, "bolt_txid_invalid");
+
+  // Sufficient payment (0.00002 BSV = 2000 sats to PAYTO, 3 confs) -> ok.
+  let r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.00002, PAYTO, 3));
+  assert.strictEqual(r.ok, true);
+  assert.strictEqual(r.paid_sats, 2000);
+  assert.strictEqual(r.confirmations, 3);
+
+  // --- Per-quote binding: unique exact amount ---
+  const reqSats = m.computeRequiredSats(cfg, { quote_id: "quote_x" });
+  assert.ok(reqSats >= 1000 && reqSats < 1000 + cfg.bindingWindowSats, "required = price + bounded offset");
+  assert.strictEqual(reqSats, m.computeRequiredSats(cfg, { quote_id: "quote_x" }), "deterministic");
+  // Paying the EXACT bound amount -> ok.
+  r = await m.verifyBsvPayment(cfg, TXID, mockTx(reqSats / 1e8, PAYTO, 3), { requiredSats: reqSats });
+  assert.strictEqual(r.ok, true);
+  assert.strictEqual(r.paid_sats, reqSats);
+  assert.strictEqual(r.required_sats, reqSats);
+  // Paying a DIFFERENT amount (even to the right address) -> mismatch, so an
+  // unrelated payment cannot be reused to satisfy this quote.
+  r = await m.verifyBsvPayment(cfg, TXID, mockTx((reqSats + 1) / 1e8, PAYTO, 3), { requiredSats: reqSats });
+  assert.strictEqual(r.reason, "bolt_amount_mismatch");
+  // Challenge advertises the exact amount.
+  const boundChallenge = m.buildBoltChallenge(cfg, { requiredSats: reqSats });
+  assert.strictEqual(boundChallenge.amount_sats, reqSats);
+  assert.strictEqual(boundChallenge.exact, true);
+
+  // Insufficient amount (500 sats < 1000) -> rejected.
+  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.000005, PAYTO, 3));
+  assert.strictEqual(r.ok, false);
+  assert.strictEqual(r.reason, "bolt_amount_insufficient");
+
+  // Paid to the wrong address -> counts as zero -> insufficient.
+  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.001, "1SomeOtherAddressXXXXXXXXXXXXXXXXXXX", 3));
+  assert.strictEqual(r.reason, "bolt_amount_insufficient");
+
+  // Too few confirmations -> rejected.
+  r = await m.verifyBsvPayment(cfg, TXID, mockTx(0.00002, PAYTO, 0));
+  assert.strictEqual(r.reason, "bolt_insufficient_confirmations");
+
+  // Default min_confirmations is 1 (not 0) when unset -> mempool (0-conf) rejected.
+  const dflt = setEnv({ XYTARA_BOLT_PROVIDER: "whatsonchain", XYTARA_BOLT_PAYTO_ADDRESS: PAYTO, XYTARA_BOLT_PRICE_SATS: "1000", XYTARA_BOLT_MIN_CONFIRMATIONS: undefined });
+  const dcfg = m.loadBoltConfig();
+  assert.strictEqual(dcfg.minConfirmations, 1);
+  r = await m.verifyBsvPayment(dcfg, TXID, mockTx(0.00002, PAYTO, 0));
+  assert.strictEqual(r.reason, "bolt_insufficient_confirmations");
+  dflt();
+
+  // Tx not found (404) -> rejected.
+  r = await m.verifyBsvPayment(cfg, TXID, async () => ({ status: 404, json: null }));
+  assert.strictEqual(r.reason, "bolt_tx_not_found");
+  restore();
+
+  // 3. Configured but missing payto/price -> explicit reason (no fetch).
+  restore = setEnv({ XYTARA_BOLT_PROVIDER: "whatsonchain", XYTARA_BOLT_PAYTO_ADDRESS: undefined, XYTARA_BOLT_PRICE_SATS: undefined });
+  cfg = m.loadBoltConfig();
+  assert.strictEqual((await m.verifyBsvPayment(cfg, TXID)).reason, "bolt_payto_or_price_missing");
+  restore();
+
+  console.log("verify_bolt_adapter: all BSV/UTXO (BOLT) adapter checks passed");
+}
+
+main().catch((error) => {
+  console.error("verify_bolt_adapter failed:", error && error.message ? error.message : error);
+  process.exitCode = 1;
+});