@codespar/cli 0.14.1 → 0.16.0

package/templates/hello-agent/packages/agent-core/test/receipt-verification.test.ts

@@ -0,0 +1,316 @@
+/**
+ * The wave-5 contract: a party with the receipt JSON and the published key set
+ * reaches the right answer, and the wrong answers stay apart from each other.
+ *
+ * The signatures here are made with stock `node:crypto` and a key generated in
+ * the test, never with the module under test: a test that signed with the
+ * verifier's own helper would prove the helper agrees with itself. The signed
+ * string is written out literally for the same reason — if the enterprise ever
+ * changes the shape, this line fails rather than following it.
+ *
+ * No network: the key set is a document, or a fetcher the test supplies.
+ */
+import { createPublicKey, generateKeyPairSync, sign as signDetached, verify as nodeVerify, type KeyObject } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_RECEIPT_KEYS_URL,
+  RECEIPT_SIGNATURE_DOMAIN,
+  VERDICT_EXIT_CODES,
+  receiptKeysUrl,
+  receiptSigningString,
+  verifyReceipt,
+  verifyReceiptWithKeys,
+  type PublishedReceiptKey,
+} from "../src/receipt-verification.js";
+
+const KID = "did:web:id.codespar.dev#1";
+const CHAIN = "9f2c4a1b6d0e8f3a5c7b9d1e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f01";
+const RECEIPT_ID = "rcpt_V1StGXR8Z5jdHi6BmyT0sw";
+
+function keypair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32);
+  return { privateKey, x: Buffer.from(raw).toString("base64url") };
+}
+
+function publishedKey(x: string, over: Partial<PublishedReceiptKey> = {}): PublishedReceiptKey {
+  return { kid: KID, kty: "OKP", crv: "Ed25519", x, alg: "EdDSA", use: "sig", status: "active", ...over };
+}
+
+function keySet(...keys: PublishedReceiptKey[]) {
+  return { issuer: "did:web:id.codespar.dev", algorithm: "Ed25519", signing_string: `${RECEIPT_SIGNATURE_DOMAIN}:<receipt_id>:<chain>`, keys };
+}
+
+function seal(privateKey: KeyObject, receiptId = RECEIPT_ID, chain = CHAIN): string {
+  return signDetached(null, Buffer.from(`codespar-receipt:v1:${receiptId}:${chain}`, "utf8"), privateKey).toString("base64url");
+}
+
+function receipt(over: Record<string, unknown> = {}) {
+  return {
+    receipt_id: RECEIPT_ID,
+    state: "paid",
+    mandate: { id: "mnd_1" },
+    payment: { amount_minor: 12345, payee: "es***@exemplo.com.br", attempt_id: "att_1", money_moved: false, sandbox: true, at: "2026-09-24T12:00:00.000Z" },
+    chain: CHAIN,
+    receipt_sig: "hmac-half-not-read-here",
+    receipt_sig_ed25519: null,
+    receipt_sig_kid: null,
+    ...over,
+  };
+}
+
+describe("the signed string", () => {
+  it("is the enterprise's, byte for byte", () => {
+    expect(receiptSigningString(RECEIPT_ID, CHAIN)).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
+    expect(RECEIPT_SIGNATURE_DOMAIN).toBe("codespar-receipt:v1");
+  });
+
+  it("names the key set of a deployment from its base url", () => {
+    expect(receiptKeysUrl("https://api.codespar.dev")).toBe(DEFAULT_RECEIPT_KEYS_URL);
+    expect(receiptKeysUrl("https://staging.example/v1/anything")).toBe("https://staging.example/.well-known/codespar-receipt-keys.json");
+  });
+});
+
+describe("verified", () => {
+  it("accepts a receipt CodeSpar sealed, and says which key signed it", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("verified");
+    expect(report.receipt_id).toBe(RECEIPT_ID);
+    expect(report.kid).toBe(KID);
+    expect(report.key_status).toBe("active");
+    expect(report.signing_string).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
+  });
+
+  it("accepts a signature made by a RETIRED key: rotation retires, it does not revoke", () => {
+    const { privateKey, x } = keypair();
+    const retired = publishedKey(x, { status: "retired", retired_at: "2026-09-01T00:00:00.000Z" });
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(retired, publishedKey("ignored", { kid: "did:web:id.codespar.dev#2" })));
+    expect(report.verdict).toBe("verified");
+    expect(report.key_status).toBe("retired");
+  });
+
+  it("still verifies the proof bundle's masked copy: the signature covers the id and the chain, not the body", () => {
+    const { privateKey, x } = keypair();
+    const sealed = receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID });
+    const masked = { ...sealed, payment: { ...sealed.payment, payee: "es***@exemplo.com.br" }, raw: undefined };
+    expect(verifyReceiptWithKeys(masked, keySet(publishedKey(x))).verdict).toBe("verified");
+  });
+});
+
+describe("tampered", () => {
+  it("refuses a receipt whose chain was changed after it was sealed", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID, chain: CHAIN.replace(/^9/, "8") }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.reason).toBe("signature_does_not_match");
+  });
+
+  it("refuses a signature lifted from another receipt: the id is in the signed string", () => {
+    const { privateKey, x } = keypair();
+    const other = seal(privateKey, "rcpt_somebodyelsesreceipt", CHAIN);
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: other, receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+  });
+
+  it("refuses a signature made by a key that is not the published one, and names the deployment case", () => {
+    const { privateKey } = keypair();
+    const other = keypair();
+    // The shape of the staging-receipt-against-production-keys mistake: both
+    // deployments publish a key called `did:web:id.codespar.dev#1` and the two
+    // are not the same key, so the message has to offer that reading.
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey(other.x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.message).toContain("deployment");
+  });
+
+  it("refuses a signature that is not 64 base64url bytes", () => {
+    const { x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: "not-a-signature", receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.reason).toBe("signature_malformed");
+  });
+});
+
+describe("unsigned", () => {
+  it("is not a failure: it says the receipt predates the capability, and that the HMAC is unaffected", () => {
+    const report = verifyReceiptWithKeys(receipt(), keySet());
+    expect(report.verdict).toBe("unsigned");
+    expect(report.message).toContain("never will");
+    expect(report.message).toContain("HMAC");
+    expect(report.kid).toBeNull();
+  });
+
+  it("answers the same when the two fields are absent rather than null", () => {
+    const { receipt_sig_ed25519: _sig, receipt_sig_kid: _kid, ...older } = receipt();
+    expect(verifyReceiptWithKeys(older, keySet()).verdict).toBe("unsigned");
+  });
+
+  it("answers without a key set at all, and without fetching one", async () => {
+    let fetched = 0;
+    const report = await verifyReceipt(receipt(), {
+      url: "https://example.invalid/keys.json",
+      fetch: async () => {
+        fetched += 1;
+        return keySet();
+      },
+    });
+    expect(report.verdict).toBe("unsigned");
+    expect(fetched).toBe(0);
+  });
+
+  it("covers a paid charge, which the API seals nothing for", () => {
+    const charge = { receipt_id: "chg_1", kind: "charge", state: "paid", chain: null, receipt_sig: null, receipt_sig_ed25519: null, receipt_sig_kid: null };
+    expect(verifyReceiptWithKeys(charge, keySet()).verdict).toBe("unsigned");
+  });
+});
+
+describe("unknown_key", () => {
+  it("refuses to guess when the kid is not published", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: "did:web:id.codespar.dev#9" }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("unknown_key");
+    expect(report.kid).toBe("did:web:id.codespar.dev#9");
+    expect(report.message).toContain("retired keys published");
+  });
+
+  it("does not fall back to the only key in the set", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: "did:web:other.example#1" }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("unknown_key");
+  });
+});
+
+describe("unreachable", () => {
+  it("is what a failed fetch answers — never `tampered`", async () => {
+    const { privateKey } = keypair();
+    const report = await verifyReceipt(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), {
+      url: "https://example.invalid/keys.json",
+      fetch: async () => {
+        throw new Error("getaddrinfo ENOTFOUND example.invalid");
+      },
+    });
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("fetch_failed");
+    expect(report.message).toContain("Nothing is proved and nothing is disproved");
+  });
+
+  it("is what a document that is not a key set answers", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), { error: "not found" });
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("key_document_unreadable");
+  });
+
+  it("is what an unusable published key answers: a key we cannot read tells us nothing about the signature", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey("AAAA")));
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("key_unusable");
+  });
+
+  it("fetches the published set and verifies against it when the fetch works", async () => {
+    const { privateKey, x } = keypair();
+    const seen: string[] = [];
+    const report = await verifyReceipt(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), {
+      fetch: async (url) => {
+        seen.push(url);
+        return keySet(publishedKey(x));
+      },
+    });
+    expect(seen).toEqual([DEFAULT_RECEIPT_KEYS_URL]);
+    expect(report.verdict).toBe("verified");
+  });
+});
+
+describe("malformed", () => {
+  it("does not call an arbitrary JSON file an unsigned receipt", () => {
+    const report = verifyReceiptWithKeys({ hello: "world" }, keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("receipt_id_missing");
+  });
+
+  it("refuses a signature whose kid was deleted, instead of reading it as unsigned", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: null }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("kid_missing");
+  });
+
+  it("refuses a kid whose signature was deleted", () => {
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_kid: KID }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("signature_missing");
+  });
+
+  it("refuses a signed receipt whose chain was deleted: the signed string cannot be rebuilt", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID, chain: null }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("chain_missing");
+  });
+
+  it("refuses a JSON array or a string", () => {
+    expect(verifyReceiptWithKeys([], keySet()).verdict).toBe("malformed");
+    expect(verifyReceiptWithKeys("rcpt_1", keySet()).verdict).toBe("malformed");
+  });
+});
+
+describe("the exit codes", () => {
+  it("keep every verdict apart, and do not call an unsigned receipt a success", () => {
+    expect(VERDICT_EXIT_CODES.verified).toBe(0);
+    expect(new Set(Object.values(VERDICT_EXIT_CODES)).size).toBe(Object.keys(VERDICT_EXIT_CODES).length);
+    expect(Object.values(VERDICT_EXIT_CODES)).not.toContain(2); // 2 is the usage error every other command uses
+  });
+});
+
+describe("the check a third party reimplements", () => {
+  it("is four lines of node:crypto over the published JWK", () => {
+    const { privateKey, x } = keypair();
+    const signature = seal(privateKey);
+    // Exactly what someone outside CodeSpar writes, with no code of ours.
+    const ok = nodeVerify(
+      null,
+      Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`, "utf8"),
+      createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x }, format: "jwk" }),
+      Buffer.from(signature, "base64url"),
+    );
+    expect(ok).toBe(true);
+    expect(verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: signature, receipt_sig_kid: KID }), keySet(publishedKey(x))).verdict).toBe("verified");
+  });
+});
+
+/**
+ * The one fixture that is not this test's own: a receipt the CodeSpar sandbox
+ * actually sealed (bills-agent, staging, 2026-09-24), as the proof bundle
+ * wrote it, and the key set that deployment publishes, as it was served. Every
+ * other case here signs with a key the test made, which proves the module is
+ * self-consistent; this one proves it agrees with the signer.
+ *
+ * Offline: both are files. If the API ever changes the signed string, this is
+ * the case that fails.
+ */
+describe("a receipt the sandbox really sealed", () => {
+  const dir = join(import.meta.dirname, "fixtures");
+  const real = JSON.parse(readFileSync(join(dir, "staging-receipt.json"), "utf8")) as Record<string, unknown>;
+  const realKeys = JSON.parse(readFileSync(join(dir, "staging-receipt-keys.json"), "utf8")) as unknown;
+
+  it("verifies against the key set that deployment publishes", () => {
+    const report = verifyReceiptWithKeys(real, realKeys, "staging");
+    expect(report.verdict).toBe("verified");
+    expect(report.kid).toBe("did:web:id.codespar.dev#1");
+    expect(report.signing_string).toBe(`codespar-receipt:v1:${real["receipt_id"] as string}:${real["chain"] as string}`);
+  });
+
+  it("is refused when one character of the chain changes", () => {
+    const chain = real["chain"] as string;
+    const edited = { ...real, chain: chain.slice(0, -1) + (chain.endsWith("0") ? "1" : "0") };
+    expect(verifyReceiptWithKeys(edited, realKeys, "staging").verdict).toBe("tampered");
+  });
+
+  it("is refused when the receipt id changes, which is why the id is in the signed string", () => {
+    expect(verifyReceiptWithKeys({ ...real, receipt_id: "rcpt_0000000000000000000000" }, realKeys, "staging").verdict).toBe("tampered");
+  });
+});

package/templates/hello-agent/packages/agent-core/test/receivables.test.ts

@@ -0,0 +1,316 @@
+/**
+ * The receivable side of the core (collections-agent): a charge is ISSUED,
+ * not settled, when the rail accepts it; the execution stays `executing`
+ * until the payer acts, and closes from a lookup (the poll) or from a
+ * `commerce.charge.*` event (the webhook). Never twice, never on prose.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { outcomeOf, type ChargeView } from "../src/api/charge-rail.js";
+import { hmacSigner } from "../src/approval.js";
+import { ProofBundle } from "../src/bundle.js";
+import { ExecutionEngine, type EngineDeps, type PolicyExtension } from "../src/engine.js";
+import { itemsHash } from "../src/hash.js";
+import { StateStore } from "../src/state/store.js";
+import { LocalMandateStatusStub } from "../src/stubs/mandate-status.js";
+import { StubChargeRail, type StubChargeRailOptions } from "../src/stubs/charge-rail.js";
+import { testGuardrails, testManifest, testMandate } from "./helpers.js";
+
+const DEBTOR = "11144477735";
+const OTHER = "22233344450";
+
+function receivables(options: { mode?: "human" | "mandate"; rail?: StubChargeRailOptions; policyExtension?: PolicyExtension; dir?: string } = {}) {
+  const dir = options.dir ?? mkdtempSync(join(tmpdir(), "agent-core-recv-"));
+  let now = new Date("2026-09-23T18:00:00Z");
+  const clock = () => now;
+  const store = new StateStore(join(dir, "state.db"));
+  const gate = new LocalMandateStatusStub(store, clock);
+  const rail = new StubChargeRail(store, { clock, ...(options.rail ?? {}) });
+  const bundle = new ProofBundle(join(dir, "runs"), "run_recv");
+  const mode = options.mode ?? "mandate";
+  const deps: EngineDeps = {
+    store,
+    rail,
+    status: gate,
+    signer: hmacSigner("test", Buffer.alloc(32, 2)),
+    manifest: testManifest({ name: "collections-agent", escalate_above: {}, maturity: { "bolepix-receivables": "sandbox" } }),
+    guardrails: testGuardrails({ approval: mode, escalate_above: {} }),
+    mandate: testMandate({
+      agent_id: "collections-agent",
+      purpose: "cobranca",
+      merchant_pin_kind: "document",
+      merchant_allowlist: [DEBTOR, OTHER],
+      beneficiaries: [{ alias: "acordo-1", name: "Joana Devedora", payee: DEBTOR }],
+    }),
+    bundle,
+    mode,
+    runId: "run_recv",
+    onBehalfOf: "merchant_demo",
+    clock,
+    policyExtension: options.policyExtension,
+  };
+  const engine = new ExecutionEngine(deps);
+  return { dir, store, rail, bundle, engine, setNow: (d: Date) => (now = d) };
+}
+
+describe("a receivable is accepted, then settled by the payer", () => {
+  it("execute leaves the execution executing (awaiting_settlement) with the instrument; two looks later it is settled with the charge as receipt", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 108000, due_date: "2026-09-30", description: "acordo 1042, a vista" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("approved");
+    expect(d.execution.items[0]?.due_date).toBe("2026-09-30");
+
+    const issued = await h.engine.execute(d.execution.id);
+    expect(issued.state).toBe("executing");
+    expect(issued.reason).toBe("awaiting_settlement");
+    expect(issued.outcomes[0]).toMatchObject({ status: "accepted", instrument: { payable: false, status: "PROCESSING" } });
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("sent");
+
+    const registered = await h.engine.reconcile(issued.id);
+    expect(registered.state).toBe("executing");
+    expect(registered.outcomes[0]?.instrument).toMatchObject({ payable: true, status: "PENDING" });
+    expect(registered.outcomes[0]?.instrument?.pix_copy_paste).toContain("br.gov.bcb.pix");
+
+    const paid = await h.engine.reconcile(issued.id);
+    expect(paid.state).toBe("settled");
+    expect(paid.history.map((t) => t.to)).toEqual(["approved", "executing", "settled"]);
+    expect(paid.outcomes[0]).toMatchObject({ status: "settled", receipt_id: paid.outcomes[0]!.transaction_id });
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("done");
+    expect(h.bundle.listReceipts()).toHaveLength(1);
+    const events = h.bundle.readEvents();
+    expect(events.filter((e) => e["type"] === "commerce.charge.paid")).toHaveLength(1);
+    expect(events.filter((e) => e["type"] === "charge.instrument").map((e) => (e["payload"] as { payable: boolean }).payable)).toEqual([false, true]);
+    // A third look changes nothing and issues nothing.
+    expect((await h.engine.reconcile(issued.id)).state).toBe("settled");
+    expect(h.rail.issueCount).toBe(1);
+  });
+
+  it("a receivable nobody pays closes failed with charge_expired, never settled", async () => {
+    const h = receivables({ rail: { payer: "expires" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    await h.engine.reconcile(issued.id);
+    const closed = await h.engine.reconcile(issued.id);
+    expect(closed.state).toBe("failed");
+    expect(closed.reason).toBe("charge_expired");
+    expect(h.bundle.listReceipts()).toHaveLength(0);
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("failed");
+  });
+
+  it("the poll logs an observed state once, however many times it sees it", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    for (let i = 0; i < 5; i += 1) await h.engine.reconcile(issued.id);
+    const events = h.store.listEvents({ execution_id: issued.id });
+    // Five looks, one observed state (PENDING, payable): one line. The instrument log names the two states the charge went through.
+    expect(events.filter((e) => e.type === "rail.reconcile")).toHaveLength(1);
+    expect(events.filter((e) => e.type === "charge.instrument")).toHaveLength(2);
+    expect(events.filter((e) => e.type === "execution.awaiting_settlement")).toHaveLength(1);
+  });
+
+  it("killed after the issuance and resumed: one charge, one settlement", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    let died = false;
+    const flaky = receivables({ dir: h.dir, rail: { afterDispatch: () => { died = true; throw new Error("killed"); } } });
+    await expect(flaky.engine.execute(d.execution.id)).rejects.toThrow("killed");
+    expect(died).toBe(true);
+    // The row says executing and the outbox says sent: resume reconciles, never re-issues.
+    const again = receivables({ dir: h.dir });
+    const stuck = again.store.getExecution(d.execution.id)!;
+    expect(stuck.state).toBe("executing");
+    const first = await again.engine.resumePending(stuck.id);
+    expect(first.state).toBe("executing");
+    expect(first.outcomes[0]?.status).toBe("accepted");
+    const settled = await again.engine.reconcile(stuck.id);
+    expect(settled.state).toBe("settled");
+    expect(again.rail.issueCount).toBe(0);
+    expect((again.store as unknown as { db: { prepare(sql: string): { get(): { n: number } } } }).db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get().n).toBe(1);
+  });
+
+  it("an instalment agreement is N receivables; the execution settles when every parcel is paid", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 40000, due_date: "2026-09-30" }, { payee: "acordo-1", amount: 40000, due_date: "2026-10-30" }, { payee: "acordo-1", amount: 40000, due_date: "2026-11-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.total).toBe(120000);
+    const issued = await h.engine.execute(d.execution.id);
+    expect(issued.outcomes.map((o) => o.status)).toEqual(["accepted", "accepted", "accepted"]);
+    expect(h.rail.issueCount).toBe(3);
+    const a2 = issued.outcomes[2]!.attempt_id;
+    h.rail.decide(a2, "never");
+    await h.engine.reconcile(issued.id);
+    const partly = await h.engine.reconcile(issued.id);
+    expect(partly.state).toBe("executing");
+    expect(partly.outcomes.map((o) => o.status)).toEqual(["settled", "settled", "accepted"]);
+    h.rail.decide(a2, "pays");
+    const done = await h.engine.reconcile(issued.id);
+    expect(done.state).toBe("settled");
+    expect(h.bundle.listReceipts()).toHaveLength(3);
+  });
+});
+
+describe("the webhook path: commerce.charge.* by attempt id or by the rail's charge id", () => {
+  it("paid twice settles once; paid before created is fine; expired after paid moves nothing", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    const chargeId = issued.outcomes[0]!.transaction_id!;
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_1", type: "commerce.charge.paid", transaction_id: chargeId })).toEqual({ applied: true, reason: "settled" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_1", type: "commerce.charge.paid", transaction_id: chargeId })).toEqual({ applied: false, reason: "duplicate event id" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_created_late", type: "commerce.charge.created", transaction_id: chargeId })).toMatchObject({ applied: false });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_2", type: "commerce.charge.paid", transaction_id: chargeId })).toMatchObject({ applied: false, reason: "execution already settled" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_expired_late", type: "commerce.charge.expired", transaction_id: chargeId })).toMatchObject({ applied: false, reason: "execution already settled" });
+    const settled = h.store.getExecution(issued.id)!;
+    expect(settled.state).toBe("settled");
+    expect(settled.outcomes[0]).toMatchObject({ status: "settled", transaction_id: chargeId, receipt_id: chargeId });
+    expect(h.store.listEvents({ execution_id: issued.id }).filter((e) => e.type === "execution.transition" && (e.payload as { to: string }).to === "settled")).toHaveLength(1);
+    // The settlement came by event, so the bundle holds no receipt yet; collectReceipts fetches it once.
+    expect(h.bundle.listReceipts()).toHaveLength(0);
+    expect(await h.engine.collectReceipts(issued.id)).toEqual([chargeId]);
+    expect(await h.engine.collectReceipts(issued.id)).toEqual([]);
+    expect(h.bundle.listReceipts()).toHaveLength(1);
+  });
+
+  it("expired by event closes failed with charge_expired; a later paid for the same charge moves nothing", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    const attempt = issued.outcomes[0]!.attempt_id;
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_exp", type: "commerce.charge.expired", attempt_id: attempt })).toEqual({ applied: true, reason: "failed" });
+    expect(h.store.getExecution(issued.id)!.reason).toBe("charge_expired");
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_after", type: "commerce.charge.paid", attempt_id: attempt })).toMatchObject({ applied: false });
+  });
+
+  it("an event naming a charge this kit never issued is not applied", () => {
+    const h = receivables();
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_x", type: "commerce.charge.paid", transaction_id: "chg_someone_elses" })).toEqual({ applied: false, reason: "unknown attempt" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_y", type: "commerce.charge.paid" })).toMatchObject({ applied: false });
+  });
+});
+
+describe("the kit's envelope runs at every gate, and only tightens", () => {
+  const envelope: PolicyExtension = (execution) => {
+    const principal = 120000;
+    if (execution.total < principal * 0.85) return { reason: "outside_envelope", detail: `total ${execution.total} is below the floor of ${principal * 0.85} (15% off ${principal})` };
+    return undefined;
+  };
+
+  it("a proposal below the discount floor is denied at draft, even in human mode", async () => {
+    const h = receivables({ mode: "human", policyExtension: envelope });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 1000, due_date: "2026-09-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("denied");
+    expect(d.execution.reason).toBe("outside_envelope");
+  });
+
+  it("a debtor without an open agreement is not a payee: denied in mandate, blocked for the human, never approvable", async () => {
+    const h = receivables({ mode: "human", policyExtension: envelope });
+    const d = await h.engine.draft({ items: [{ payee: "99988877766", amount: 120000, due_date: "2026-09-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("awaiting_approval");
+    expect(d.execution.blocking_reasons).toEqual(["beneficiary_not_allowed"]);
+    expect(h.engine.approve(d.execution.id, { id: "usr_operator", channel: "terminal" }).state).toBe("denied");
+  });
+
+  it("the due date is part of the items_hash: moving it after approval is another charge", () => {
+    const a = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL", due_date: "2026-09-30" }]);
+    const b = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL", due_date: "2026-10-30" }]);
+    const c = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL" }]);
+    expect(a).not.toBe(b);
+    expect(a).not.toBe(c);
+  });
+});
+
+describe("outcomeOf: the API's charge view, mapped by fields and never by prose", () => {
+  const base: ChargeView = {
+    id: "chg_1",
+    status: "PENDING",
+    local_status: "pending",
+    status_conflict: false,
+    method: "boleto",
+    currency: "BRL",
+    amount: 1080.5,
+    amount_minor: 108050,
+    due_date: "2026-09-30",
+    payable: true,
+    boleto_bar_code: "1".repeat(44),
+    boleto_bank_line: "2".repeat(47),
+    pix_copy_paste: "000201...",
+    credit_correlation_armed: true,
+    payment_in_flight: false,
+    settlement: null,
+    issuance_unconfirmed: false,
+  };
+  it("maps the five states", () => {
+    expect(outcomeOf(base)).toMatchObject({ status: "accepted", transaction_id: "chg_1", instrument: { payable: true, status: "PENDING", pix_copy_paste: "000201..." } });
+    expect(outcomeOf({ ...base, status: "PROCESSING", payable: false, pix_copy_paste: null })).toMatchObject({ status: "accepted", instrument: { payable: false } });
+    expect(outcomeOf({ ...base, local_status: "settled", status: "CONFIRMED", settlement: "confirmed" })).toMatchObject({ status: "settled", transaction_id: "chg_1", receipt_id: "chg_1", money_moved: false });
+    expect(outcomeOf({ ...base, local_status: "expired", status: "CANCELLED" })).toMatchObject({ status: "failed", code: "charge_expired" });
+    expect(outcomeOf({ ...base, status: "EXPIRED" })).toMatchObject({ status: "failed", code: "charge_expired" });
+    expect(outcomeOf({ ...base, status: "CANCELLED" })).toMatchObject({ status: "failed", code: "charge_cancelled" });
+    expect(outcomeOf({ ...base, id: null, issuance_unconfirmed: true })).toEqual({ status: "in_flight" });
+  });
+  it("a payment notified and not yet credited is still accepted: nothing settles on a notification", () => {
+    expect(outcomeOf({ ...base, payment_in_flight: true, settlement: "pending" })).toMatchObject({ status: "accepted" });
+  });
+});
+
+describe("CodeSparChargeRail: what crosses the wire on a create", () => {
+  it("sends consumer_id, method boleto, due_date, the attempt id as idempotency_key and the amount in major units; refuses without a consumer", async () => {
+    const { CodeSparChargeRail } = await import("../src/api/charge-rail.js");
+    const calls: Array<{ path: string; body: Record<string, unknown> }> = [];
+    const api = {
+      post: async (path: string, opts: { body: Record<string, unknown> }) => {
+        calls.push({ path, body: opts.body });
+        return { id: "chg_wire_1", status: "PROCESSING", local_status: "pending", status_conflict: false, method: "boleto", currency: "BRL", amount: 1080, amount_minor: 108000, due_date: "2026-09-30", payable: false, boleto_bar_code: null, boleto_bank_line: null, pix_copy_paste: null, credit_correlation_armed: false, payment_in_flight: false, settlement: null, issuance_unconfirmed: false };
+      },
+      get: async () => { throw new Error("not called"); },
+    };
+    const rail = new CodeSparChargeRail(api as never);
+    const base = { attempt_id: "att_x_0", mandate_id: "pol_1", amount_minor: 108000, currency: "BRL", payee: DEBTOR, beneficiary: "Joana Ribeiro", purpose: "cobranca", agent_id: "collections-agent", description: "Acordo #1042 - parcela 1/1", due_date: "2026-09-30", actor: { type: "agent" as const, agent: "collections-agent@0.1.0", on_behalf_of: "merchant_demo_loja" } };
+    expect(await rail.pay(base)).toMatchObject({ status: "failed", code: "consumer_id_required" });
+    expect(calls).toHaveLength(0);
+    const out = await rail.pay({ ...base, consumer_id: "merchant_demo_loja" });
+    expect(out).toMatchObject({ status: "accepted", transaction_id: "chg_wire_1", instrument: { payable: false, status: "PROCESSING" } });
+    expect(calls[0]).toEqual({ path: "/v1/charges", body: { consumer_id: "merchant_demo_loja", amount: 1080, currency: "BRL", method: "boleto", description: "Acordo #1042 - parcela 1/1", buyer: { name: "Joana Ribeiro", document: DEBTOR }, due_date: "2026-09-30", idempotency_key: "att_x_0" } });
+  });
+});
+
+describe("paySandboxCharge: the SDK's typed call to the payer route", () => {
+  it("posts to /v1/test/charges/{id}/pay with the key, the project header and the amount; refuses a live key before any request", async () => {
+    const { paySandboxCharge } = await import("../src/api/sandbox-payer.js");
+    const seen: Array<{ url: string; init: RequestInit }> = [];
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      seen.push({ url: String(url), init: init ?? {} });
+      return new Response(JSON.stringify({ charge_id: "chg_1", status: "paid", local_status: "settled", simulated: true, settled_against: "sandbox_fixture", money_moved: false, quoted_minor: 1000, paid_minor: 1000, payment: "full", idempotent_replay: false }), { status: 200, headers: { "content-type": "application/json" } });
+    }) as typeof fetch;
+    try {
+      const live = await paySandboxCharge({ apiKey: ["csk", "live", "0000000000"].join("_") }, "chg_1").catch((e: Error) => e);
+      expect(live).toBeInstanceOf(Error);
+      expect(seen).toHaveLength(0);
+      const out = await paySandboxCharge({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/", projectId: "prj_1" }, "chg_1", 1000);
+      expect(out).toMatchObject({ ok: true, state: { charge_id: "chg_1", status: "paid", simulated: true, money_moved: false } });
+      expect(seen[0]?.url).toBe("https://api.example.test/v1/test/charges/chg_1/pay");
+      const headers = new Headers(seen[0]?.init.headers);
+      expect(headers.get("authorization")).toBe("Bearer csk_test_unit_0000");
+      expect(headers.get("x-codespar-project")).toBe("prj_1");
+      expect(headers.get("content-type")).toBe("application/json");
+      expect(seen[0]?.init.body).toBe(JSON.stringify({ amount_minor: 1000 }));
+      const bare = await paySandboxCharge({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/", projectId: "prj_1" }, "chg_1");
+      expect(bare).toMatchObject({ ok: true });
+      expect(seen[1]?.init.body).toBe("{}");
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+});

package/templates/hello-agent/packages/agent-core/test/secrets.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createCodeSparClient } from "../src/api/client.js";
+import { assertTestKey, isTestKey, NotATestKeyError, redactKey } from "../src/secrets.js";
+
+// Built at runtime so the secret scan (which refuses key-shaped literals) stays honest about this file.
+const TEST = ["csk", "test", "0123456789abcdef"].join("_");
+const LIVE = ["csk", "live", "0123456789"].join("_");
+
+describe("sandbox by construction", () => {
+  it("accepts only csk_test_ keys", () => {
+    expect(isTestKey(TEST)).toBe(true);
+    expect(isTestKey(LIVE)).toBe(false);
+    expect(isTestKey("csk_test_")).toBe(false);
+    expect(isTestKey(undefined)).toBe(false);
+    expect(() => assertTestKey(LIVE)).toThrow(NotATestKeyError);
+  });
+
+  it("refuses to build an API client with a live key, before any network", () => {
+    expect(() => createCodeSparClient({ apiKey: LIVE })).toThrow(NotATestKeyError);
+    expect(() => createCodeSparClient({ apiKey: undefined })).toThrow(NotATestKeyError);
+    expect(createCodeSparClient({ apiKey: TEST })).toBeDefined();
+  });
+
+  it("redacts keys for logs", () => {
+    expect(redactKey(TEST)).toBe("csk_test_…cdef");
+    expect(redactKey(TEST)).not.toContain("0123456789");
+  });
+});