@codespar/cli 0.17.0 → 0.18.1

package/templates/checkout-agent/packages/agent-runtime/test/verify-cli.test.ts

@@ -0,0 +1,329 @@
+/**
+ * `codespar-agent verify` at the process boundary: the contracts a person and
+ * a script depend on.
+ *
+ * It runs from a temporary directory with no `agent.yaml` anywhere above it
+ * and no key in the environment, which is the whole claim of wave 5 — the
+ * verifier is someone who has the receipt file and nothing else. The key set
+ * is a local copy, so no test opens a socket.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, generateKeyPairSync, sign as signDetached } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { canonicalize, itemsHash, maskPayee, type ExecutionItem } from "@codespar/agent-core";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const BIN = resolve(import.meta.dirname, "../bin.mjs");
+const KID = "did:web:id.codespar.dev#1";
+const CHAIN = "9f2c4a1b6d0e8f3a5c7b9d1e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f01";
+const RECEIPT_ID = "rcpt_V1StGXR8Z5jdHi6BmyT0sw";
+
+function fixture(over: Record<string, unknown> = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "verify-cli-"));
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const x = Buffer.from(publicKey.export({ format: "der", type: "spki" }).subarray(-32)).toString("base64url");
+  const signature = signDetached(null, Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`, "utf8"), privateKey).toString("base64url");
+  const receipt = {
+    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",
+    receipt_sig_ed25519: signature,
+    receipt_sig_kid: KID,
+    ...over,
+  };
+  const keys = { issuer: "did:web:id.codespar.dev", algorithm: "Ed25519", signing_string: "codespar-receipt:v1:<receipt_id>:<chain>", keys: [{ kid: KID, kty: "OKP", crv: "Ed25519", x, alg: "EdDSA", use: "sig", status: "active", created_at: "2026-09-01T00:00:00.000Z", retired_at: null }] };
+  const receiptPath = join(dir, "receipt.json");
+  const keysPath = join(dir, "codespar-receipt-keys.json");
+  writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + "\n");
+  writeFileSync(keysPath, JSON.stringify(keys, null, 2) + "\n");
+  return { dir, receiptPath, keysPath };
+}
+
+function run(args: string[], cwd: string) {
+  const result = spawnSync(process.execPath, [BIN, "verify", ...args], {
+    cwd,
+    // No CodeSpar key, no model key: a verifier holds nothing.
+    env: { ...process.env, CODESPAR_API_KEY: "", ANTHROPIC_API_KEY: "" },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+describe("codespar-agent verify", () => {
+  it("checks a run's copy from a directory with no agent and no key, and says it proves the signature only (exit 7)", () => {
+    const { dir, receiptPath, keysPath } = fixture();
+    const out = run([receiptPath, "--keys", keysPath], dir);
+    expect(out.code).toBe(7);
+    expect(out.stdout).toContain("SIGNATURE_ONLY");
+    expect(out.stdout).toContain(RECEIPT_ID);
+    expect(out.stdout).toContain("read_required");
+    expect(out.stderr).toContain("carries CodeSpar's signature");
+    expect(out.stderr).toContain("--from-api");
+  });
+
+  it("puts valid JSON and nothing else on stdout with --json; the sentence goes to stderr", () => {
+    const { dir, receiptPath, keysPath } = fixture();
+    const out = run([receiptPath, "--keys", keysPath, "--json"], dir);
+    const lines = out.stdout.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    const report = JSON.parse(lines[0]!) as { verdict: string; kid: string; signing_string: string; message: string };
+    expect(report.verdict).toBe("signature_only");
+    expect(report.kid).toBe(KID);
+    expect(report.signing_string).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
+    expect(out.stderr).toContain(report.message);
+  });
+
+  it("exits 1 and says so on a receipt that does not match its signature", () => {
+    const { dir, receiptPath, keysPath } = fixture({ chain: CHAIN.replace(/^9/, "8") });
+    const out = run([receiptPath, "--keys", keysPath], dir);
+    expect(out.code).toBe(1);
+    expect(out.stdout).toContain("TAMPERED");
+  });
+
+  it("exits 3 on a receipt sealed before Ed25519, and calls it what it is", () => {
+    const { dir, receiptPath, keysPath } = fixture({ receipt_sig_ed25519: null, receipt_sig_kid: null });
+    const out = run([receiptPath, "--keys", keysPath], dir);
+    expect(out.code).toBe(3);
+    expect(out.stdout).toContain("UNSIGNED");
+    expect(out.stderr).toContain("never will");
+  });
+
+  it("exits 4 when the key set does not publish the kid the receipt names", () => {
+    const { dir, receiptPath, keysPath } = fixture({ receipt_sig_kid: "did:web:id.codespar.dev#9" });
+    const out = run([receiptPath, "--keys", keysPath], dir);
+    expect(out.code).toBe(4);
+    expect(out.stdout).toContain("UNKNOWN_KEY");
+  });
+
+  it("exits 5 when the key set cannot be read: unknown, never invalid", () => {
+    const { dir, receiptPath } = fixture();
+    const empty = join(dir, "not-a-key-set.json");
+    writeFileSync(empty, '{"error":"not found"}\n');
+    const out = run([receiptPath, "--keys", empty], dir);
+    expect(out.code).toBe(5);
+    expect(out.stdout).toContain("UNREACHABLE");
+  });
+
+  it("exits 6 rather than calling an arbitrary JSON file an unsigned receipt", () => {
+    const { dir, keysPath } = fixture();
+    const other = join(dir, "something-else.json");
+    writeFileSync(other, '{"hello":"world"}\n');
+    const out = run([other, "--keys", keysPath], dir);
+    expect(out.code).toBe(6);
+    expect(out.stdout).toContain("MALFORMED");
+  });
+
+  it("refuses its arguments with 2, the way the other commands do", () => {
+    const { dir, receiptPath, keysPath } = fixture();
+    expect(run([], dir).code).toBe(2);
+    expect(run([receiptPath, "--keys", keysPath, "--url", "https://example.invalid/k.json"], dir).code).toBe(2);
+    expect(run([receiptPath, "--keys"], dir).code).toBe(2);
+    expect(run([join(dir, "missing.json"), "--keys", keysPath], dir).code).toBe(2);
+    expect(run(["--help"], dir).code).toBe(0);
+  });
+});
+
+/*
+ * The body and the approval (OPEN_QUESTIONS §3, §47). A v4 receipt read, its
+ * chain written out link by link and signed with a key generated here, under
+ * the recipe production published on 2026-09-26.
+ */
+const PUBLISHED = JSON.parse(readFileSync(resolve(import.meta.dirname, "../../agent-core/test/fixtures/production-receipt-keys.json"), "utf8")) as Record<string, unknown>;
+const V4_KID = "did:web:id.codespar.dev#production-2";
+const PAYEE = "escola@exemplo.com.br";
+const ITEMS: ExecutionItem[] = [{ alias: "escola", beneficiary: "Escola Aurora", payee: PAYEE, amount: 185000, currency: "BRL", description: "outubro" }];
+const sha256 = (v: string) => createHash("sha256").update(v, "utf8").digest("hex");
+
+function v4Fixture(sealedItemsHash = itemsHash(ITEMS)) {
+  const dir = mkdtempSync(join(tmpdir(), "verify-cli-v4-"));
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const x = Buffer.from(publicKey.export({ format: "der", type: "spki" }).subarray(-32)).toString("base64url");
+  const mandate = { id: "cm_test_1", nonce: "nonce-1", scope: "contas do mes", currency: "BRL", sig_sha256: sha256("s".repeat(64)) };
+  const quote = { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: PAYEE, session_id: null, sig: "q".repeat(64), at: "2026-09-26T18:00:00.000Z" };
+  const approval = { items_hash: sealedItemsHash, batch_hash: null };
+  const payment = { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_1_0", money_moved: false, at: "2026-09-26T18:00:01.000Z" };
+  const chain = sha256(
+    canonicalize({
+      v: 4,
+      links: [
+        mandate,
+        quote,
+        approval,
+        { rail: payment.rail, provider: payment.provider, tx_id: payment.tx_id, amount_minor: payment.amount_minor, sandbox: true, attempt_id: payment.attempt_id, money_moved: false, at: payment.at },
+      ],
+    }),
+  );
+  const signature = signDetached(null, Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${chain}`, "utf8"), privateKey).toString("base64url");
+  const read = { receipt_id: RECEIPT_ID, state: "paid", chain_version: 4, mandate, quote, approval, payment, delivery: null, chain, receipt_sig: "hmac-not-read-here", receipt_sig_ed25519: signature, receipt_sig_kid: V4_KID, exceptions: [] };
+  const keys = { ...PUBLISHED, keys: [{ kid: V4_KID, kty: "OKP", crv: "Ed25519", x, alg: "EdDSA", use: "sig", status: "active" }] };
+  const artifact = { approval_id: "apr_1", execution_id: "exe_1", items: ITEMS, items_hash: itemsHash(ITEMS), approved_at: "2026-09-26T18:00:00.000Z" };
+
+  // A run's bundle, as the engine writes it: the masked copy naming its artifact, and approval.json beside receipts/.
+  const run = join(dir, "runs", "run_1");
+  mkdirSync(join(run, "receipts"), { recursive: true });
+  const copy = {
+    receipt_id: RECEIPT_ID,
+    state: "paid",
+    mandate: { id: mandate.id },
+    payment: { amount_minor: 185000, payee: maskPayee(PAYEE), attempt_id: payment.attempt_id, money_moved: false, sandbox: true, at: payment.at },
+    chain,
+    receipt_sig: "hmac-not-read-here",
+    receipt_sig_ed25519: signature,
+    receipt_sig_kid: V4_KID,
+    actor: { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" },
+    approval_id: artifact.approval_id,
+  };
+  const paths = {
+    read: join(dir, "receipt-read.json"),
+    keys: join(dir, "codespar-receipt-keys.json"),
+    artifact: join(dir, "approval.json"),
+    copy: join(run, "receipts", `${RECEIPT_ID}.json`),
+    runApprovals: join(run, "approval.json"),
+  };
+  writeFileSync(paths.read, JSON.stringify(read, null, 2) + "\n");
+  writeFileSync(paths.keys, JSON.stringify(keys, null, 2) + "\n");
+  writeFileSync(paths.artifact, JSON.stringify([artifact], null, 2) + "\n");
+  writeFileSync(paths.copy, JSON.stringify(copy, null, 2) + "\n");
+  writeFileSync(paths.runApprovals, JSON.stringify([artifact], null, 2) + "\n");
+  return { dir, read, keys, copy, artifact, paths };
+}
+
+describe("codespar-agent verify, the body and the approval of a v4 receipt read", () => {
+  it("exits 0 when the chain recomputes from the read and the sealed approval is the artifact's", () => {
+    const f = v4Fixture();
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir);
+    expect(out.code).toBe(0);
+    expect(out.stdout).toContain("VERIFIED");
+    expect(out.stdout).toContain("body         recomputed (chain v4)");
+    expect(out.stdout).toContain("approval     matched");
+    expect(out.stderr).toContain("paid against the list artifact apr_1 approved");
+  });
+
+  it("exits 9, approval_mismatch, when the receipt sealed another list than the artifact's", () => {
+    const f = v4Fixture(`sha256:${"9".repeat(64)}`);
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact, "--json"], f.dir);
+    expect(out.code).toBe(9);
+    const report = JSON.parse(out.stdout) as { verdict: string; reason: string; approval_check: { status: string } };
+    expect(report).toMatchObject({ verdict: "approval_mismatch", reason: "items_hash_differs", approval_check: { status: "mismatch" } });
+  });
+
+  it("exits 8, chain_mismatch, when the payee beside a genuine signature was changed", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.read, JSON.stringify({ ...f.read, quote: { ...f.read.quote, payee: "outra@exemplo.com.br" } }));
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir);
+    expect(out.code).toBe(8);
+    expect(out.stdout).toContain("CHAIN_MISMATCH");
+  });
+
+  it("exits 7 for a v2 read, and says the chain is not recomputable without the mandate signature", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.read, JSON.stringify({ ...f.read, chain_version: 2 }));
+    const out = run([f.paths.read, "--keys", f.paths.keys], f.dir);
+    expect(out.code).toBe(7);
+    expect(out.stderr).toContain("not recomputable without the mandate signature");
+  });
+
+  it("refuses an --approval file with more than one artifact unless --approval-id names one", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.artifact, JSON.stringify([f.artifact, { ...f.artifact, approval_id: "apr_2" }]));
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir).code).toBe(2);
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact, "--approval-id", "apr_1"], f.dir).code).toBe(0);
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval-id", "apr_1"], f.dir).code).toBe(2);
+  });
+});
+
+/*
+ * `--from-api`: a run's masked copy, bound through the API's read. A local
+ * server plays the deployment — the receipt route and its well-known key set —
+ * so the read and the key set come from ONE origin, as the command requires.
+ */
+describe("codespar-agent verify --from-api", () => {
+  let server: Server;
+  let baseUrl: string;
+  let served: { read: unknown; keys: unknown } = { read: {}, keys: {} };
+  const asked: string[] = [];
+
+  beforeAll(async () => {
+    server = createServer((req, res) => {
+      asked.push(`${req.method} ${req.url} ${req.headers["authorization"] ? "auth" : "anon"}`);
+      const body = req.url === "/.well-known/codespar-receipt-keys.json" ? served.keys : req.url === `/v1/consumers/receipts/${RECEIPT_ID}` ? served.read : undefined;
+      res.writeHead(body === undefined ? 404 : 200, { "content-type": "application/json" });
+      res.end(JSON.stringify(body ?? { error: { code: "not_found", message: "no" } }));
+    });
+    await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
+    baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  });
+
+  afterAll(async () => {
+    server.closeAllConnections();
+    await new Promise<void>((ok) => server.close(() => ok()));
+  });
+
+  /** The server answers while the command runs, so the process is awaited, never spawned synchronously. */
+  function runAsync(args: string[], cwd: string): Promise<{ code: number | null; stdout: string; stderr: string }> {
+    return new Promise((done) => {
+      const child = spawn(process.execPath, [BIN, "verify", ...args], {
+        cwd,
+        // The placeholder passes the csk_test_ guard and is the one test-key-shaped string the secret scan allows.
+        env: { ...process.env, CODESPAR_API_KEY: "csk_test_your_key_here", CODESPAR_API_URL: baseUrl, ANTHROPIC_API_KEY: "" },
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (d: Buffer) => (stdout += d.toString()));
+      child.stderr.on("data", (d: Buffer) => (stderr += d.toString()));
+      child.on("close", (code) => done({ code, stdout, stderr }));
+    });
+  }
+
+  it("binds the copy's body through the read and checks the run's own artifact: exit 0, and nothing unmasked is written", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api"], f.dir);
+    expect(out.code).toBe(0);
+    expect(out.stdout).toContain("approval     matched");
+    expect(asked).toEqual([`GET /.well-known/codespar-receipt-keys.json anon`, `GET /v1/consumers/receipts/${RECEIPT_ID} auth`]);
+    expect(readFileSync(f.paths.copy, "utf8")).not.toContain(PAYEE);
+  });
+
+  it("exits 9 when the run's artifact is not the list the receipt sealed", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    writeFileSync(f.paths.runApprovals, JSON.stringify([{ ...f.artifact, items: [{ ...ITEMS[0]!, amount: 1 }], items_hash: itemsHash([{ ...ITEMS[0]!, amount: 1 }]) }]));
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(9);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "approval_mismatch", reason: "items_hash_differs" });
+  });
+
+  it("exits 8 when the copy was edited after it was written: the signature does not cover its body, the read does", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    writeFileSync(f.paths.copy, JSON.stringify({ ...f.copy, payment: { ...f.copy.payment, amount_minor: 1 } }));
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(8);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "chain_mismatch", reason: "copy_differs_from_read" });
+  });
+
+  it("answers signature_only, never a failure, when the read cannot be fetched", async () => {
+    const f = v4Fixture();
+    served = { read: undefined as unknown, keys: f.keys };
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(7);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "signature_only", reason: "read_unavailable" });
+  });
+
+  it("refuses a key set from another deployment than the read", async () => {
+    const f = v4Fixture();
+    const out = await runAsync([f.paths.copy, "--from-api", "--url", "https://api.codespar.dev/.well-known/codespar-receipt-keys.json"], f.dir);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("same deployment");
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-cloud-api.test.ts

@@ -0,0 +1,277 @@
+/**
+ * The official backend, without Meta.
+ *
+ * Nothing here reaches the network. What is driven is the half where a
+ * mistake is silent: the signature check (a wrong one that passes is an open
+ * webhook), the webhook parse (a shape misread is a message never answered),
+ * the verification handshake, and the request builder. The send itself is one
+ * `fetch` over a request these functions built, and the one test that touches
+ * `deliver` injects a fetch that asserts what it was handed — so a regression
+ * that started calling Meta would fail here instead of dialling out.
+ *
+ * The shapes come from Meta's published documentation. Nobody on this repo
+ * has a Business account, so none of this has been run against Meta, and the
+ * README says so in those words rather than implying otherwise.
+ */
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import {
+  buildSendRequest,
+  isMetaBaseUrl,
+  loadCloudApiConfig,
+  parseInbound,
+  providerRefusal,
+  verifyChallenge,
+  verifyWebhookSignature,
+  WhatsAppCloudApi,
+  type CloudApiConfig,
+} from "../src/channels/whatsapp/cloud-api.js";
+
+const CONFIG: CloudApiConfig = {
+  baseUrl: "https://graph.facebook.com",
+  phoneNumberId: "111222333",
+  accessToken: "test-token-not-a-credential",
+  verifyToken: "verify-me",
+  appSecret: "app-secret-for-the-test",
+  apiVersion: "v21.0",
+  webhookPort: 3111,
+};
+
+const sign = (body: string, secret = CONFIG.appSecret) => `sha256=${createHmac("sha256", secret).update(body, "utf8").digest("hex")}`;
+
+describe("credentials are absent by default", () => {
+  it("names every variable that is missing rather than saying 'misconfigured'", () => {
+    const { config, missing } = loadCloudApiConfig({});
+    expect(config).toBeUndefined();
+    expect(missing).toEqual(["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN", "WHATSAPP_VERIFY_TOKEN", "WHATSAPP_APP_SECRET"]);
+  });
+
+  it("treats an empty value as absent: a commented-out .env.example must not half-configure a channel", () => {
+    const { config, missing } = loadCloudApiConfig({ WHATSAPP_PHONE_NUMBER_ID: "  ", WHATSAPP_ACCESS_TOKEN: "", WHATSAPP_VERIFY_TOKEN: "v", WHATSAPP_APP_SECRET: "s" });
+    expect(config).toBeUndefined();
+    expect(missing).toEqual(["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN"]);
+  });
+
+  it("defaults the version, the port and Meta's own host, and nothing else", () => {
+    const { config } = loadCloudApiConfig({ WHATSAPP_PHONE_NUMBER_ID: "1", WHATSAPP_ACCESS_TOKEN: "2", WHATSAPP_VERIFY_TOKEN: "3", WHATSAPP_APP_SECRET: "4" });
+    expect(config?.apiVersion).toBe("v21.0");
+    expect(config?.webhookPort).toBe(3111);
+    expect(config?.baseUrl).toBe("https://graph.facebook.com");
+  });
+});
+
+describe("live is decided by the base URL, and only by it", () => {
+  it("is Meta's host and nothing that merely looks like it", () => {
+    expect(isMetaBaseUrl("https://graph.facebook.com")).toBe(true);
+    expect(isMetaBaseUrl("https://graph.facebook.com/")).toBe(true);
+    expect(isMetaBaseUrl("http://127.0.0.1:4290")).toBe(false);
+    expect(isMetaBaseUrl("https://graph.facebook.com.evil.test")).toBe(false);
+    expect(isMetaBaseUrl("not a url")).toBe(false);
+  });
+
+  it("names itself `emulator` and reports `live: false` off Meta, which is what the evidence builder refuses on", () => {
+    const options = { conversation: { contact: "+5511987654321" }, say: () => undefined, fetchImpl: async () => new Response("{}") };
+    const emulator = new WhatsAppCloudApi({ ...options, config: { ...CONFIG, baseUrl: "http://127.0.0.1:4290" } });
+    expect(emulator.live).toBe(false);
+    expect(emulator.name).toBe("emulator");
+    const meta = new WhatsAppCloudApi({ ...options, config: CONFIG });
+    expect(meta.live).toBe(true);
+    expect(meta.name).toBe("cloud-api");
+  });
+
+  it("builds the send against whichever base URL it was given, with the path unchanged", () => {
+    const request = buildSendRequest({ ...CONFIG, baseUrl: "http://127.0.0.1:4290", apiVersion: "v22.0" }, "+5511987654321", { kind: "text", text: "oi" });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(request.url).toBe("http://127.0.0.1:4290/v22.0/111222333/messages");
+  });
+});
+
+describe("a delivery is trusted only when it is signed", () => {
+  const body = JSON.stringify({ object: "whatsapp_business_account" });
+
+  it("accepts the app secret's own signature over the RAW body", () => {
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body), body)).toEqual({ ok: true });
+  });
+
+  it("refuses a body that was re-serialized: the signature is over bytes", () => {
+    const reserialized = JSON.stringify(JSON.parse(body), null, 2);
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body), reserialized).ok).toBe(false);
+  });
+
+  it("refuses another secret, a missing header and a malformed one", () => {
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body, "someone-else"), body).ok).toBe(false);
+    expect(verifyWebhookSignature(CONFIG.appSecret, undefined, body)).toEqual({ ok: false, reason: "missing X-Hub-Signature-256" });
+    expect(verifyWebhookSignature(CONFIG.appSecret, "sha1=abc", body).ok).toBe(false);
+    expect(verifyWebhookSignature(CONFIG.appSecret, "nonsense", body).ok).toBe(false);
+  });
+});
+
+describe("the registration handshake", () => {
+  it("echoes the challenge for the right verify token", () => {
+    expect(verifyChallenge(CONFIG, { "hub.mode": "subscribe", "hub.verify_token": "verify-me", "hub.challenge": "12345" })).toEqual({ status: 200, body: "12345" });
+  });
+
+  it("refuses a wrong token and a wrong mode", () => {
+    expect(verifyChallenge(CONFIG, { "hub.mode": "subscribe", "hub.verify_token": "nope", "hub.challenge": "1" }).status).toBe(403);
+    expect(verifyChallenge(CONFIG, { "hub.mode": "unsubscribe", "hub.verify_token": "verify-me" }).status).toBe(400);
+  });
+});
+
+describe("reading what Meta delivers", () => {
+  const delivery = {
+    object: "whatsapp_business_account",
+    entry: [
+      {
+        changes: [
+          {
+            field: "messages",
+            value: {
+              messaging_product: "whatsapp",
+              metadata: { phone_number_id: "111222333" },
+              messages: [
+                { id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND", from: "5511987654321", timestamp: "1758643200", type: "text", text: { body: "fechado, pago à vista" } },
+                { id: "wamid.SECOND", from: "5511987654321", timestamp: "1758643260", type: "image", image: { id: "media_1" } },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  };
+
+  it("reads the text messages and puts the plus back on the number", () => {
+    const { messages } = parseInbound(delivery);
+    expect(messages).toEqual([{ id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND", from: "+5511987654321", text: "fechado, pago à vista", timestamp: 1758643200 }]);
+  });
+
+  it("names what it dropped instead of turning it into an empty message", () => {
+    expect(parseInbound(delivery).ignored).toEqual([{ id: "wamid.SECOND", type: "image" }]);
+  });
+
+  it("reads a delivery that carries only status updates as no messages", () => {
+    expect(parseInbound({ entry: [{ changes: [{ value: { statuses: [{ id: "wamid.X", status: "delivered" }] } }] }] }).messages).toEqual([]);
+    expect(parseInbound({}).messages).toEqual([]);
+  });
+});
+
+describe("the request that would go to Meta", () => {
+  it("builds the documented /messages call for a text", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "text", text: "Oi, Joana!" });
+    expect("unsupported" in request).toBe(false);
+    if ("unsupported" in request) return;
+    expect(request.url).toBe("https://graph.facebook.com/v21.0/111222333/messages");
+    expect(request.headers["authorization"]).toBe("Bearer test-token-not-a-credential");
+    expect(JSON.parse(request.body)).toEqual({ messaging_product: "whatsapp", recipient_type: "individual", to: "5511987654321", type: "text", text: { preview_url: false, body: "Oi, Joana!" } });
+  });
+
+  it("sends a copy-and-paste as its own plain text message: a code inside a paragraph cannot be tapped", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "instrument", instrument: "pix_copy_paste", value: "00020126580014br.gov.bcb.pix" });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(JSON.parse(request.body).text.body).toBe("00020126580014br.gov.bcb.pix");
+  });
+
+  it("builds a template with its body parameters", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana", "1042"] });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(JSON.parse(request.body).template).toEqual({
+      name: "cobranca_lembrete",
+      language: { code: "pt_BR" },
+      components: [{ type: "body", parameters: [{ type: "text", text: "Joana" }, { type: "text", text: "1042" }] }],
+    });
+  });
+
+  it("says outright that it cannot send an image, instead of pretending", () => {
+    expect(buildSendRequest(CONFIG, "+5511987654321", { kind: "media", media: "qr", data: "00020126" })).toEqual({ unsupported: "media_upload_unimplemented" });
+  });
+});
+
+describe("deliver, with the network replaced by an assertion", () => {
+  it("posts the request the builder produced and returns the provider's message id", async () => {
+    const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async (url, init) => {
+        calls.push({ url: String(url), init });
+        return new Response(JSON.stringify({ messages: [{ id: "wamid.SENT" }] }), { status: 200 });
+      },
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "text", text: "Oi!" });
+    expect(sent).toEqual({ id: "wamid.SENT", state: "sent" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe("https://graph.facebook.com/v21.0/111222333/messages");
+  });
+
+  it("refuses an image without reaching for the network at all", async () => {
+    let called = false;
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async () => {
+        called = true;
+        return new Response("{}", { status: 200 });
+      },
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "media", media: "qr", data: "00020126" });
+    expect(sent.refused?.rule).toBe("media_upload_unimplemented");
+    expect(called).toBe(false);
+  });
+
+  it("reports a provider refusal as a failure and never as a send", async () => {
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async () => new Response(JSON.stringify({ error: { message: "Invalid parameter" } }), { status: 400 }),
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "text", text: "Oi!" });
+    expect(sent.state).toBe("failed");
+    expect(sent.refused?.rule).toBe("provider_refused");
+  });
+});
+
+describe("what Meta's error body says, read rather than collapsed into a status", () => {
+  const body = (error: unknown) => JSON.stringify({ error });
+
+  it("reads 131047 as the window rule it is, so a caller can answer it with a template", () => {
+    const refusal = providerRefusal(400, body({ code: 131047, message: "(#131047) Message failed to send", error_data: { details: "the 24h customer service window closed" } }));
+    expect(refusal.rule).toBe("session_window_closed");
+    expect(refusal.detail).toContain("400/131047");
+    expect(refusal.detail).toContain("the 24h customer service window closed");
+  });
+
+  it("keeps any other code a provider refusal, with the code named", () => {
+    expect(providerRefusal(400, body({ code: 131026, message: "Message undeliverable" }))).toEqual({ rule: "provider_refused", detail: "400/131026 from the Cloud API" });
+  });
+
+  it("does not mistake a body without Meta's envelope for anything but the status", () => {
+    expect(providerRefusal(502, "<html>bad gateway</html>")).toEqual({ rule: "provider_refused", detail: "502 from the Cloud API" });
+  });
+});
+
+describe("a redelivered message is the same message", () => {
+  it("hands a message on once however many times it arrives, and says it dropped the rest", async () => {
+    const lines: string[] = [];
+    const port = 40000 + Math.floor(Math.random() * 20000);
+    const backend = new WhatsAppCloudApi({ config: { ...CONFIG, webhookPort: port }, conversation: { contact: "+5511987654321" }, say: (l) => lines.push(l) });
+    await backend.open();
+    try {
+      const raw = JSON.stringify({
+        entry: [{ changes: [{ value: { messages: [{ id: "wamid.ONCE", from: "5511987654321", timestamp: "1758643200", type: "text", text: { body: "fechado" } }] } }] }],
+      });
+      for (let i = 0; i < 2; i++) {
+        const response = await fetch(`http://127.0.0.1:${port}/`, { method: "POST", headers: { "x-hub-signature-256": sign(raw) }, body: raw });
+        // Still 200: Meta retries anything else, and a duplicate is not an error.
+        expect(response.status).toBe(200);
+      }
+      expect((await backend.next())?.id).toBe("wamid.ONCE");
+      const second = await Promise.race([backend.next(), new Promise((resolve) => setTimeout(() => resolve("nothing"), 200))]);
+      expect(second).toBe("nothing");
+      expect(lines).toContain("[whatsapp] duplicate delivery of wamid.ONCE dropped");
+    } finally {
+      await backend.close();
+    }
+  });
+});