@codespar/cli 0.16.0 → 0.18.0

package/templates/hello-agent/packages/agent-core/src/rail.ts

@@ -2,10 +2,52 @@
  * The payment rail the core dispatches to once an execution is `executing`.
  * Two implementations: the CodeSpar sandbox through the API (needs a
  * `csk_test_` key) and a local stub persisted in state.db for CI and
- * scenarios. Both are idempotent on `attempt_id`: presenting the same
- * attempt again answers the earlier outcome instead of paying twice.
+ * scenarios. Idempotence is OPT-IN on the API and the core always opts in:
+ * every payment carries an explicit `attempt_id`, and presenting the same
+ * attempt again answers from the rail's record of it instead of paying twice
+ * (ent#1671): the original outcome when it settled, "still running" while it
+ * is in flight, "unknown, reconcile" while it is pinned, and a refusal when
+ * the same id arrives with a different payment. A payment sent WITHOUT an id
+ * is a new payment every time; nothing here sends one.
  */
-import type { Actor, ChargeInstrument } from "./types.js";
+import type { ApiOperation, ApiRequestBody } from "@codespar/sdk";
+import type { SpendQuote } from "./quote.js";
+import type { Actor, ApprovalArtifact, ChargeInstrument } from "./types.js";
+
+/**
+ * The `approval` a spend presents (`SpendApproval` in the API's document,
+ * typed since @codespar/sdk 0.16.10): `sha256:<64 lowercase hex>`, as
+ * `itemsHash` and `batchHash` write it. Taken from the SDK so a change on
+ * the API's side fails `tsc` here.
+ */
+export type SpendApproval = NonNullable<ApiRequestBody<ApiOperation<"/v1/consumer-payments/execute", "post">>["approval"]>;
+
+/** What a receipt says it SEALED as the approval link: `batch_hash` is null when the spend sent none. */
+export interface SealedSpendApproval {
+  items_hash: string;
+  batch_hash: string | null;
+}
+
+/** The hashes of what was approved, for a spend of any line of this artifact: the ones the artifact's own HMAC covers. */
+export function spendApprovalOf(artifact: Pick<ApprovalArtifact, "items_hash" | "batch">): SpendApproval {
+  return { items_hash: artifact.items_hash, ...(artifact.batch ? { batch_hash: artifact.batch.batch_hash } : {}) };
+}
+
+const APPROVAL_HASH = /^(sha256:)?[0-9a-f]{64}$/;
+
+/**
+ * The approval a spend presents, or why it may not go out: none, or a hash
+ * the API would refuse (`invalid_approval_hash`: lowercase hex SHA-256, the
+ * `sha256:` prefix optional). The shape and never the content, like the API:
+ * WHICH list is the artifact's business, checked before `executing`.
+ */
+export function checkSpendApproval(payment: { approval?: SpendApproval | undefined }): { ok: true; approval: SpendApproval } | { ok: false; code: "approval_missing" | "approval_malformed"; detail: string } {
+  const { approval } = payment;
+  if (!approval) return { ok: false, code: "approval_missing", detail: "a spend carries the hashes of the approval artifact, or it does not go out" };
+  if (!APPROVAL_HASH.test(approval.items_hash)) return { ok: false, code: "approval_malformed", detail: "the approval's items_hash is not a lowercase hex SHA-256" };
+  if (approval.batch_hash !== undefined && !APPROVAL_HASH.test(approval.batch_hash)) return { ok: false, code: "approval_malformed", detail: "the approval's batch_hash is not a lowercase hex SHA-256" };
+  return { ok: true, approval };
+}
 
 export interface RailPayment {
   attempt_id: string;
@@ -22,6 +64,17 @@ export interface RailPayment {
   beneficiary?: string;
   /** Due date of a receivable, `YYYY-MM-DD`. */
   due_date?: string;
+  /** What was approved for this line, presented with a spend so the sealed receipt names the payee. A charge rail ignores it. */
+  quote?: SpendQuote;
+  /**
+   * The approval artifact's hashes, exactly as the artifact carries them: its
+   * `items_hash`, and for a batch line its `batch.batch_hash`. The API seals
+   * them into the receipt's chain as a link of their own (chain v4,
+   * ent#1670), so whoever holds the receipt read can show THIS payment was
+   * sealed against THAT list. It is the caller's claim, sealed: the API checks
+   * its shape and never its content. A charge rail ignores it.
+   */
+  approval?: SpendApproval;
   /** Section 4.5: carried on every call. The API has no wire field for it yet; see OPEN_QUESTIONS. */
   actor: Actor;
 }
@@ -45,6 +98,13 @@ export type RailOutcome =
       receipt_id: string | null;
       money_moved: boolean;
       sandbox: boolean;
+      /**
+       * The rail answered from its record of an attempt that had ALREADY
+       * settled (`idempotent_replay`, ent#1671): every other field is the
+       * original answer, and nothing moved, was held or was sealed by this
+       * call. Absent on the call that settled it.
+       */
+      replayed?: true;
       raw: unknown;
     }
   | {
@@ -52,6 +112,21 @@ export type RailOutcome =
       status: "failed";
       code: string;
       message: string;
+      /**
+       * The rail holds this `attempt_id` as an attempt that failed and moved
+       * no money, and will refuse it for good (`psp_attempt_conflict`). Set
+       * only on that answer: the id is spent, and a batch line pays under the
+       * next generation of its id (`batchAttemptId`).
+       */
+      spent?: true;
+      /**
+       * The rail holds this `attempt_id` for something else: a DIFFERENT
+       * payment (`attempt_id_conflict`, checked before whatever became of it)
+       * or another project of the organization (`attempt_id_unavailable`).
+       * Nothing was held or sent. Never `spent`: the id is not free and not
+       * burned, it is someone else's, and presenting it again answers the same.
+       */
+      held?: "conflict" | "unavailable";
       raw?: unknown;
     }
   | {
@@ -67,7 +142,17 @@ export interface RailReceipt {
   /** `payment` (the API's sealed receipt) or `charge` (the paid receivable as the API reports it; no seal exists for it today). */
   kind?: "payment" | "charge";
   state: string;
-  mandate: { id: string };
+  /** `sig_sha256` is SHA-256 of the mandate's own signature, which a v4 chain seals in place of it; never the signature itself, which is a bearer proof. */
+  mandate: { id: string; sig_sha256?: string };
+  /**
+   * The chain format the receipt was sealed under (4 once it carries the
+   * approval link), and the approval it sealed, as the API read them back:
+   * `null` when it sealed none. Absent when the rail cannot say — a charge,
+   * which seals nothing.
+   */
+  chain_version?: number;
+  approval?: SealedSpendApproval | null;
+  /** `payee` is the one the receipt SEALED — the quote's, on a payment — and null when it sealed none. Never copied from the execution. */
   payment: { amount_minor: number; payee: string | null; attempt_id: string; money_moved: boolean; sandbox: boolean; at: string };
   /** Null when the API seals nothing for this kind of record. */
   chain: string | null;

package/templates/hello-agent/packages/agent-core/src/receipt-chain.ts

@@ -0,0 +1,270 @@
+/**
+ * `receipt-chain`: the receipt's `chain` recomputed from its body, the way a
+ * party outside CodeSpar does it.
+ *
+ * The Ed25519 signature covers `codespar-receipt:v1:<id>:<chain>`, so on its
+ * own it proves CodeSpar sealed SOME body with that digest. Recomputing the
+ * digest from the receipt read is what binds THIS body — the payee, the
+ * amount, and since chain v4 the approval hashes — to the signature. CodeSpar
+ * publishes how, as data: `chain_recipe` on the unauthenticated
+ * `/.well-known/codespar-receipt-keys.json` (ent#1670). This module reads that
+ * recipe and applies it. It does not carry its own copy of the link shapes: a
+ * recipe it does not understand is an answer ("cannot recompute"), never a
+ * guess, because a verifier that silently skipped a clause would compute a
+ * different digest and blame the receipt.
+ *
+ *   chain = hex(SHA-256(UTF-8(JCS({ "v": chain_version, "links": [...] }))))
+ *
+ * JCS is RFC 8785, implemented below in full rather than imported: it is
+ * thirty lines, the enterprise's own canonicalizer is exactly the code a
+ * verifier must not depend on, and a dependency would be one more thing to
+ * audit for a third party who wants to reimplement this. Like
+ * `receipt-verification`, it imports `node:crypto` and nothing else.
+ */
+import { createHash } from "node:crypto";
+
+/* ── RFC 8785 ────────────────────────────────────────────────── */
+
+/** A high surrogate not followed by a low one, or a low one not preceded by a high one. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/**
+ * The JSON Canonicalization Scheme (RFC 8785) of a JSON value.
+ *
+ * - Objects: members sorted by their names as arrays of UTF-16 code units,
+ *   which is what the default `Array.prototype.sort` compares (section 3.2.3).
+ * - Numbers: the ECMAScript `Number.prototype.toString` serialization, which
+ *   is what `JSON.stringify` emits for a finite number (section 3.2.2.3);
+ *   NaN and the infinities are not JSON and are refused.
+ * - Strings: `JSON.stringify`'s escaping, which is the RFC's (section
+ *   3.2.2.2) — except that JCS works on I-JSON, where a lone surrogate is not
+ *   a string at all, so one is refused instead of escaped.
+ * - No whitespace anywhere.
+ *
+ * `undefined`, functions and other non-JSON values are refused: canonicalizing
+ * something that is not JSON would hash a value nobody can reproduce.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError(`RFC 8785: ${value} is not a JSON number`);
+      return JSON.stringify(value);
+    case "string":
+      if (LONE_SURROGATE.test(value)) throw new TypeError("RFC 8785: a string with a lone surrogate is not I-JSON");
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+      const members = Object.keys(value as Record<string, unknown>).sort();
+      return `{${members
+        .map((name) => {
+          if (LONE_SURROGATE.test(name)) throw new TypeError("RFC 8785: a member name with a lone surrogate is not I-JSON");
+          return `${JSON.stringify(name)}:${canonicalize((value as Record<string, unknown>)[name])}`;
+        })
+        .join(",")}}`;
+    }
+    default:
+      throw new TypeError(`RFC 8785: a ${typeof value} is not a JSON value`);
+  }
+}
+
+/* ── The published recipe ────────────────────────────────────── */
+
+/** One link of the recipe, as `chain_recipe.links[]` publishes it. */
+export interface ChainRecipeLink {
+  link: string;
+  /** The member of the receipt read the link's fields are taken from. */
+  from: string;
+  /** When the link is part of the chain: a clause from a small published vocabulary. */
+  when: string;
+  fields?: string[];
+  fields_by_version?: Record<string, string[]>;
+}
+
+export interface ChainRecipe {
+  canonicalization: string;
+  digest: string;
+  version: { field: string; rule?: string };
+  /** The suffix that marks a field included only when the read has it and it is not null. */
+  optional_marker: string;
+  links: ChainRecipeLink[];
+}
+
+/** The canonicalization this module implements, spelled as the recipe spells it. */
+export const RECIPE_CANONICALIZATION = "RFC 8785 (JCS)";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+export type RecipeRead = { ok: true; recipe: ChainRecipe } | { ok: false; reason: "recipe_unpublished" | "recipe_unrecognized"; message: string };
+
+/**
+ * The `chain_recipe` of a key document, or why there is none this module can
+ * follow. A document without one comes from a deployment older than ent#1670:
+ * nothing is wrong with the receipt, there is just no published way to bind
+ * its body. A recipe whose canonicalization or digest is not the one
+ * implemented here is refused whole rather than followed halfway.
+ */
+export function readChainRecipe(keyDocument: unknown): RecipeRead {
+  // OUTSIDE THE SDK'S TYPES, and the one place it is read: the well-known
+  // document's schema does not declare `chain_recipe` yet (ent#1759), so no
+  // SDK type exists to read it through. It is validated field by field below
+  // instead. When ent#1759 lands and the SDK types it, this read moves onto
+  // that type and the validation stays: a verifier checks what it is served.
+  const raw = isRecord(keyDocument) ? keyDocument["chain_recipe"] : undefined;
+  if (raw === undefined || raw === null) {
+    return { ok: false, reason: "recipe_unpublished", message: "the key set publishes no `chain_recipe`, so the receipt's body cannot be bound to its chain (a deployment older than ent#1670)" };
+  }
+  const unrecognized = (why: string): RecipeRead => ({ ok: false, reason: "recipe_unrecognized", message: `the published \`chain_recipe\` ${why}, so this verifier does not follow it` });
+  if (!isRecord(raw)) return unrecognized("is not an object");
+  if (raw["canonicalization"] !== RECIPE_CANONICALIZATION) return unrecognized(`names the canonicalization ${JSON.stringify(raw["canonicalization"])}, not ${RECIPE_CANONICALIZATION}`);
+  const digest = raw["digest"];
+  if (typeof digest !== "string" || !/\bSHA-256\b/.test(digest) || !/\blowercase hex\b/.test(digest)) return unrecognized(`names the digest ${JSON.stringify(digest)}, not lowercase-hex SHA-256`);
+  const version = raw["version"];
+  if (!isRecord(version) || typeof version["field"] !== "string") return unrecognized("does not name the field that carries the chain version");
+  const marker = raw["optional_marker"];
+  if (typeof marker !== "string" || marker.length === 0) return unrecognized("does not name its optional-field marker");
+  const links = raw["links"];
+  if (!Array.isArray(links) || links.length === 0) return unrecognized("lists no links");
+  const parsed: ChainRecipeLink[] = [];
+  for (const entry of links) {
+    if (!isRecord(entry) || typeof entry["link"] !== "string" || typeof entry["from"] !== "string" || typeof entry["when"] !== "string") return unrecognized("carries a link without `link`, `from` and `when`");
+    const fields = entry["fields"];
+    const byVersion = entry["fields_by_version"];
+    if (fields !== undefined && !isStringArray(fields)) return unrecognized(`gives the link ${entry["link"]} fields that are not a list of names`);
+    if (byVersion !== undefined && !(isRecord(byVersion) && Object.values(byVersion).every(isStringArray))) return unrecognized(`gives the link ${entry["link"]} per-version fields that are not lists of names`);
+    if (fields === undefined && byVersion === undefined) return unrecognized(`gives the link ${entry["link"]} no fields`);
+    parsed.push({
+      link: entry["link"],
+      from: entry["from"],
+      when: entry["when"],
+      ...(fields !== undefined ? { fields } : {}),
+      ...(byVersion !== undefined ? { fields_by_version: byVersion as Record<string, string[]> } : {}),
+    });
+  }
+  return {
+    ok: true,
+    recipe: {
+      canonicalization: RECIPE_CANONICALIZATION,
+      digest,
+      version: { field: version["field"], ...(typeof version["rule"] === "string" ? { rule: version["rule"] } : {}) },
+      optional_marker: marker,
+      links: parsed,
+    },
+  };
+}
+
+/* ── Recomputing ─────────────────────────────────────────────── */
+
+export type ChainRecomputation =
+  | { ok: true; chain: string; version: number }
+  | {
+      ok: false;
+      /**
+       * `chain_version_missing`  the read does not say which version sealed it.
+       * `recipe_unrecognized`    a clause, or a version, the recipe does not
+       *                          define in a way this module can follow.
+       * `mandate_sig_required`   a v1–v3 chain seals the mandate's raw
+       *                          signature, which the read given here does
+       *                          not carry.
+       * `payee_masked`           the quote's payee is a masked copy; the chain
+       *                          sealed the key itself.
+       * `field_missing`          any other field the recipe needs is absent.
+       */
+      reason: "chain_version_missing" | "recipe_unrecognized" | "mandate_sig_required" | "payee_masked" | "field_missing";
+      message: string;
+      version: number | null;
+    };
+
+/** A payee the proof bundle masked (`es***@exemplo.com.br`). No Pix key contains `***`. */
+export function isMaskedPayee(payee: unknown): boolean {
+  return typeof payee === "string" && payee.includes("***");
+}
+
+/** Whether a link applies. `undefined` for a clause the recipe did not publish before this module was written. */
+function applies(when: string, from: string, read: Record<string, unknown>, version: number): boolean | undefined {
+  if (when === "always") return true;
+  if (when === `${from} is not null`) return read[from] !== null && read[from] !== undefined;
+  const byVersion = /^chain_version is (\d+)$/.exec(when);
+  if (byVersion) return version === Number(byVersion[1]);
+  return undefined;
+}
+
+/**
+ * Recompute `chain` from a receipt read (the JSON of
+ * `GET /v1/consumers/receipts/{id}`), following the recipe exactly: links in
+ * the published order, a link whose clause does not hold left out rather than
+ * nulled, values copied as read (`null` included), a field marked optional
+ * included only when present and not null. Timestamps are taken as read: the
+ * API seals them in the form it reads them back (RFC 3339 UTC, milliseconds).
+ *
+ * This is the pure recomputation, for any version. Whether a verifier SHOULD
+ * recompute a given version is policy, and lives in `verifyReceiptRead`.
+ */
+export function recomputeChain(read: Record<string, unknown>, recipe: ChainRecipe): ChainRecomputation {
+  const versionRaw = read[recipe.version.field];
+  if (typeof versionRaw !== "number" || !Number.isSafeInteger(versionRaw) || versionRaw < 1) {
+    return { ok: false, reason: "chain_version_missing", version: null, message: `the read carries no \`${recipe.version.field}\`, so which links were sealed cannot be known` };
+  }
+  const version = versionRaw;
+  const links: Record<string, unknown>[] = [];
+  for (const spec of recipe.links) {
+    const include = applies(spec.when, spec.from, read, version);
+    if (include === undefined) return { ok: false, reason: "recipe_unrecognized", version, message: `the recipe includes the link ${spec.link} "when ${spec.when}", a clause this verifier does not know` };
+    if (!include) continue;
+    const fields = spec.fields ?? spec.fields_by_version?.[String(version)];
+    if (!fields) return { ok: false, reason: "recipe_unrecognized", version, message: `the recipe gives the link ${spec.link} no fields for chain v${version}` };
+    const source = read[spec.from];
+    if (!isRecord(source)) return { ok: false, reason: "field_missing", version, message: `the read carries no \`${spec.from}\` object, which the ${spec.link} link of a v${version} chain is taken from` };
+    const link: Record<string, unknown> = {};
+    for (const field of fields) {
+      const optional = field.endsWith(recipe.optional_marker);
+      const name = optional ? field.slice(0, -recipe.optional_marker.length) : field;
+      const value = source[name];
+      if (optional) {
+        if (value !== undefined && value !== null) link[name] = value;
+        continue;
+      }
+      if (value === undefined) {
+        if (spec.from === "mandate" && name === "sig") {
+          return { ok: false, reason: "mandate_sig_required", version, message: `chain v${version} seals the mandate's own signature, and the read carries none: it is a bearer proof only the tenant holds` };
+        }
+        return { ok: false, reason: "field_missing", version, message: `the read carries no \`${spec.from}.${name}\`, which the ${spec.link} link of a v${version} chain seals` };
+      }
+      if (spec.from === "quote" && name === "payee" && isMaskedPayee(value)) {
+        return { ok: false, reason: "payee_masked", version, message: "the quote's payee is a masked copy; the chain sealed the key itself, so this body cannot be recomputed from it" };
+      }
+      link[name] = value;
+    }
+    links.push(link);
+  }
+  return { ok: true, version, chain: createHash("sha256").update(canonicalize({ v: version, links }), "utf8").digest("hex") };
+}
+
+/* ── The approval link (chain v4) ────────────────────────────── */
+
+export interface SealedApproval {
+  items_hash: string;
+  batch_hash: string | null;
+}
+
+/** The approval a read says was sealed, or `null` when it carries none (every chain before v4). */
+export function readSealedApproval(read: Record<string, unknown>): SealedApproval | null {
+  const approval = read["approval"];
+  if (!isRecord(approval) || typeof approval["items_hash"] !== "string") return null;
+  const batch = approval["batch_hash"];
+  return { items_hash: approval["items_hash"], batch_hash: typeof batch === "string" ? batch : null };
+}
+
+/** Two spellings of one SHA-256: the API seals the value as sent, and the `sha256:` prefix is optional on the wire. */
+export function sameApprovalHash(a: string | null | undefined, b: string | null | undefined): boolean {
+  const bare = (h: string | null | undefined) => (typeof h === "string" ? h.replace(/^sha256:/, "") : null);
+  return bare(a) === bare(b);
+}

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

@@ -17,28 +17,34 @@
  *                          reconciling a payout, or a court — parties that
  *                          have no relationship with CodeSpar at all.
  *
- * This module checks the second. It imports `node:crypto` and nothing else: no
+ * This module checks the second. It imports `node:crypto` and two modules of
+ * this package that import nothing else (`receipt-chain`, `hash`): no
  * CodeSpar SDK, no key material, no token, no network of its own (the key
  * document is passed in, or fetched by a function the caller supplies). A
  * third party can read the forty lines that matter and reimplement them.
  *
- * WHAT A `verified` VERDICT PROVES, exactly: CodeSpar sealed a receipt with
- * THIS id and THIS chain. The chain is a SHA-256 over the four links of the
- * Control Record, so the seller, the amount and the payee are inside it — but
- * recomputing that digest from the receipt body needs the canonical link
- * shapes, which CodeSpar does not publish today. Binding the body to the chain
- * is therefore not something this module can promise, and it does not pretend
- * to: see `docs/OPEN_QUESTIONS.md` §47. It is also why the signature survives
- * the proof bundle's masking — the bundle masks the payee, and the signature
- * covers the id and the digest, not the copy in front of you.
+ * TWO LAYERS, and a verdict says which one it reached. The signature proves
+ * CodeSpar sealed a receipt with THIS id and THIS chain; `verifyReceiptWithKeys`
+ * checks that and nothing else, which is why it survives the proof bundle's
+ * masking — the bundle masks the payee, and the signature covers the id and
+ * the digest, not the copy in front of you. The chain is a SHA-256 over the
+ * links of the Control Record, and since ent#1670 CodeSpar publishes how to
+ * recompute it (`chain_recipe`, beside the keys). `verifyReceiptRead` does:
+ * from the API's receipt READ, under the recipe of the SAME document whose
+ * key verified the signature, it recomputes the chain and holds it against
+ * the signed one — and for a v4 chain, holds the sealed approval link against
+ * the local approval artifact. `verified` from it means all of that held;
+ * `signature_only` means the signature held and the body could not be bound
+ * (a v1–v3 chain, a masked payee, no recipe), which is not a failure and is
+ * not a verification of the body either. See `docs/OPEN_QUESTIONS.md` §47.
  *
- * WHICH KEY SET. `kid` is `<did>#<n>` and the DID is the platform's, so it is
- * the same string on every deployment while the KEY behind it is not: a
- * sandbox receipt checked against the production key set finds a key of that
- * name, fails to verify, and reads `tampered`. The verifier therefore points
- * at ONE deployment's `/.well-known/codespar-receipt-keys.json` — the default
- * is production, and `--url` names another. Nothing in the two documents tells
- * them apart today; `docs/OPEN_QUESTIONS.md` §47 says so and names the ask.
+ * WHICH KEY SET. The verifier points at ONE deployment's
+ * `/.well-known/codespar-receipt-keys.json` — the default is production, and
+ * `--url` names another. Since ent#1641 a deployment names its keys by
+ * namespace (`#production-2`, `#staging-2`), so a receipt checked against the
+ * wrong set finds no key of its name (`unknown_key`); the retired `#1` is
+ * still published by both with different keys, and a receipt sealed under it
+ * checked against the wrong set reads `tampered`. `docs/OPEN_QUESTIONS.md` §47.
  *
  * The signed string is the enterprise's `receiptSigningString`
  * (`packages/api/src/receipt-signature.ts`, ent#1633), reproduced here rather
@@ -46,6 +52,9 @@
  * proves nothing about the signer.
  */
 import { createPublicKey, verify as verifyDetached } from "node:crypto";
+import { itemsHash } from "./hash.js";
+import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type SealedApproval } from "./receipt-chain.js";
+import type { ExecutionItem } from "./types.js";
 
 /** The domain tag. A receipt names the version it was sealed under through
  *  this literal, so a future `v2` does not invalidate a `v1` signature. */
@@ -86,8 +95,51 @@ export function receiptSigningString(receiptId: string, chain: string): string {
  *                  arbitrary JSON file would state that it is a receipt from
  *                  before the capability existed, which is a claim about a
  *                  file nobody checked.
+ *
+ * And three that only the body check (`verifyReceiptRead`) reaches, each
+ * after the signature verified:
+ *
+ *   `signature_only`     the body could not be bound to the chain: a v1–v3
+ *                        chain, a masked payee, no read, no recipe. NOT a
+ *                        failure, and NOT `verified`: the signature is
+ *                        CodeSpar's, and nothing here says the body beside it
+ *                        is the body it sealed.
+ *   `chain_mismatch`     the body, recomputed under the published recipe, is
+ *                        NOT the signed chain. The signature is genuine and
+ *                        the body in front of you is not the one it covers.
+ *   `approval_mismatch`  the body is the signed one, and the approval link it
+ *                        seals is NOT the local artifact's: this payment was
+ *                        not sealed against the list that artifact approved.
  */
-export type ReceiptVerdict = "verified" | "tampered" | "unsigned" | "unknown_key" | "unreachable" | "malformed";
+export type ReceiptVerdict = "verified" | "tampered" | "unsigned" | "unknown_key" | "unreachable" | "malformed" | "signature_only" | "chain_mismatch" | "approval_mismatch";
+
+/** What recomputing the chain from the body found. */
+export interface ChainCheck {
+  /** `recomputed`: equal to the signed chain. `mismatch`: not equal. `not_recomputed`: see `reason`. */
+  status: "recomputed" | "mismatch" | "not_recomputed";
+  version: number | null;
+  /** The digest recomputed from the body, when it could be. */
+  recomputed: string | null;
+  reason: string;
+}
+
+/** What the sealed approval link was held against. Present on a v4 chain that recomputed. */
+export interface ApprovalLinkCheck {
+  /** `matched`: the artifact's hashes are the sealed ones. `mismatch`: they are not. `not_compared`: no artifact was given. */
+  status: "matched" | "mismatch" | "not_compared";
+  sealed: SealedApproval;
+  artifact: { approval_id: string; items_hash: string; batch_hash: string | null } | null;
+  reason: string;
+}
+
+/** The part of an approval artifact the approval link is held against: what was approved, never who. */
+export interface ApprovalClaim {
+  approval_id: string;
+  items_hash: string;
+  /** When present, `items_hash` is recomputed from them first: a hash that does not describe its own list proves nothing about the list. */
+  items?: readonly ExecutionItem[];
+  batch?: { batch_hash: string };
+}
 
 export interface ReceiptVerification {
   verdict: ReceiptVerdict;
@@ -106,6 +158,9 @@ export interface ReceiptVerification {
   reason: string;
   /** One sentence for a person. Never a stack trace. */
   message: string;
+  /** The body check, when one was attempted: only `verifyReceiptRead` attempts it, and only on a signature that verified. */
+  chain_check?: ChainCheck;
+  approval_check?: ApprovalLinkCheck;
 }
 
 /** One published key, RFC 8037 shape, as the JWKS serves it. */
@@ -398,4 +453,125 @@ export const VERDICT_EXIT_CODES: Record<ReceiptVerdict, number> = {
   unknown_key: 4,
   unreachable: 5,
   malformed: 6,
+  signature_only: 7,
+  chain_mismatch: 8,
+  approval_mismatch: 9,
 };
+
+/* ── The body: the chain recomputed from the read ────────────── */
+
+/** The first chain version that seals `sha256(mandate.sig)` instead of the signature, and the approval link. */
+export const FIRST_THIRD_PARTY_CHAIN_VERSION = 4;
+
+/** Whether a JSON is the API's receipt read, rather than the proof bundle's masked copy of one: only the read carries the links. */
+export function isReceiptRead(input: unknown): input is Record<string, unknown> {
+  if (!isRecord(input)) return false;
+  const mandate = input["mandate"];
+  const payment = input["payment"];
+  return isRecord(mandate) && "nonce" in mandate && isRecord(payment) && "rail" in payment;
+}
+
+/** A verified signature whose body could not be bound: `signature_only`, with the reason. */
+export function signatureOnly(signature: ReceiptVerification, reason: string, why: string, version: number | null = null): ReceiptVerification {
+  return {
+    ...signature,
+    verdict: "signature_only",
+    reason,
+    message: `receipt ${signature.receipt_id ?? "(no id)"} carries CodeSpar's signature over its id and chain, and its body is NOT bound to that chain: ${why}`,
+    chain_check: { status: "not_recomputed", version, recomputed: null, reason },
+  };
+}
+
+/**
+ * Verify a receipt READ — the JSON of `GET /v1/consumers/receipts/{id}` —
+ * against a key set already in hand: the signature, then the body, then the
+ * approval. Synchronous and offline, like `verifyReceiptWithKeys`.
+ *
+ * The recipe is taken from the SAME document whose key verified the
+ * signature, never from another: each deployment names its keys by
+ * namespace (§47), so a document that verified the signature is the sealing
+ * deployment's, and its recipe is the one that sealed.
+ *
+ * A v1–v3 chain is never recomputed here, even from a tenant's read that
+ * carries `mandate.sig`: that signature is a bearer proof (it authorizes
+ * spends), a verifier has no business handling it, and the API is retiring
+ * it from the read. Those chains also predate the API's timestamp fix
+ * (ent#1670), so some of them no longer recompute from their read at all —
+ * and a mismatch there would accuse a genuine receipt. They answer
+ * `signature_only`, never `verified` and never `chain_mismatch`.
+ */
+export function verifyReceiptRead(read: unknown, keyDocument: unknown, options: { label?: string; approval?: ApprovalClaim } = {}): ReceiptVerification {
+  const signature = verifyReceiptWithKeys(read, keyDocument, options.label ?? "file");
+  if (signature.verdict !== "verified" || !isRecord(read)) return signature;
+  if (!isReceiptRead(read)) return signatureOnly(signature, "read_required", "this is not the API's receipt read (the proof bundle's copy masks the payee and carries none of the links); recompute from `GET /v1/consumers/receipts/{id}`");
+
+  const recipe = readChainRecipe(keyDocument);
+  if (!recipe.ok) return signatureOnly(signature, recipe.reason, recipe.message);
+
+  const versionRaw = read[recipe.recipe.version.field];
+  if (typeof versionRaw === "number" && versionRaw < FIRST_THIRD_PARTY_CHAIN_VERSION) {
+    return signatureOnly(
+      signature,
+      "mandate_sig_required",
+      `the chain is not recomputable without the mandate signature. Chain v${versionRaw} seals the mandate's raw signature, a bearer proof this verifier does not take; and a receipt sealed before ent#1670 may not recompute from its read at all. It carries no approval link either: that starts at v${FIRST_THIRD_PARTY_CHAIN_VERSION}`,
+      versionRaw,
+    );
+  }
+
+  const recomputed = recomputeChain(read, recipe.recipe);
+  if (!recomputed.ok) return signatureOnly(signature, recomputed.reason, recomputed.message, recomputed.version);
+  const sealedChain = read["chain"];
+  if (recomputed.chain !== sealedChain) {
+    return {
+      ...signature,
+      verdict: "chain_mismatch",
+      reason: "body_does_not_recompute",
+      message: `receipt ${signature.receipt_id} carries a genuine CodeSpar signature over chain ${sealedChain}, and the body beside it recomputes to ${recomputed.chain} under the published recipe (v${recomputed.version}): this body is not the one that was sealed. A payee, an amount, a timestamp or the approval was changed after sealing`,
+      chain_check: { status: "mismatch", version: recomputed.version, recomputed: recomputed.chain, reason: "body_does_not_recompute" },
+    };
+  }
+  const chainCheck: ChainCheck = { status: "recomputed", version: recomputed.version, recomputed: recomputed.chain, reason: "body_recomputes" };
+  const bound = `the body recomputes to the signed chain under the published recipe (v${recomputed.version})`;
+
+  const sealed = readSealedApproval(read);
+  if (!sealed) {
+    // Unreachable through the published recipe (v4 seals the link, and a read without it fails the recomputation above), kept so a future version is not misread.
+    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck };
+  }
+  const approval = options.approval;
+  if (!approval) {
+    return {
+      ...signature,
+      reason: "body_recomputes",
+      message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}. It seals the approval ${sealed.items_hash}${sealed.batch_hash ? ` (batch ${sealed.batch_hash})` : ""}; no approval artifact was given to hold it against`,
+      chain_check: chainCheck,
+      approval_check: { status: "not_compared", sealed, artifact: null, reason: "no_artifact" },
+    };
+  }
+
+  const artifact = { approval_id: approval.approval_id, items_hash: approval.items_hash, batch_hash: approval.batch?.batch_hash ?? null };
+  const mismatch = (reason: string, why: string): ReceiptVerification => ({
+    ...signature,
+    verdict: "approval_mismatch",
+    reason,
+    message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}, and ${why}: this payment was not sealed against the list artifact ${approval.approval_id} approved`,
+    chain_check: chainCheck,
+    approval_check: { status: "mismatch", sealed, artifact, reason },
+  });
+  if (approval.items && itemsHash(approval.items) !== approval.items_hash) {
+    return mismatch("artifact_items_hash_inconsistent", `the artifact's items_hash ${approval.items_hash} is not the hash of the items it lists (${itemsHash(approval.items)})`);
+  }
+  if (!sameApprovalHash(sealed.items_hash, artifact.items_hash)) {
+    return mismatch("items_hash_differs", `it seals items_hash ${sealed.items_hash} where the artifact carries ${artifact.items_hash}`);
+  }
+  if (!sameApprovalHash(sealed.batch_hash, artifact.batch_hash)) {
+    return mismatch("batch_hash_differs", `it seals batch_hash ${sealed.batch_hash ?? "none"} where the artifact carries ${artifact.batch_hash ?? "none"}`);
+  }
+  return {
+    ...signature,
+    reason: "approval_matches",
+    message: `receipt ${signature.receipt_id} was sealed by CodeSpar, ${bound}, and it was paid against the list artifact ${approval.approval_id} approved (${sealed.items_hash}${sealed.batch_hash ? `, batch ${sealed.batch_hash}` : ""}). WHO approved it is in the artifact, under a local key, and nowhere in the seal`,
+    chain_check: chainCheck,
+    approval_check: { status: "matched", sealed, artifact, reason: "approval_matches" },
+  };
+}