@integraledger/lcp-verify 0.9.0

package/src/index.ts

@@ -0,0 +1,277 @@
+/**
+ * `verify` — the walk at the caller-specified `depth` (default `"structural"`). Pure over
+ * its supplied inputs (the fetched ATR bytes, the enumerated settlements, the ATA chain, the acceptance)
+ * — the imperative shell that fetches them via live ports is the buyer gate's. The report is honest about
+ * coverage: a step whose inputs are absent is `not-attempted(<why>)`.
+ *
+ * At STRUCTURAL depth `verified` is always `false` (a presence/absence readout → class, not a verdict).
+ * At MECHANICAL depth `verified` is an honest function of the walk via `computeVerified` — raised `true`
+ * iff every class-required step is `proved` and no step `failed`.
+ *
+ * `supportedClass` is an HONEST READOUT, never a target: the record is *shaped for* `claimedClass`, and
+ * the structural walk can only CONFIRM-OR-IMPEACH that shape — any `failed` step downgrades it to `TC-0`;
+ * the walk never raises it (raising requires the mechanical verification `computeVerified` supplies).
+ */
+import type {
+  Bounds,
+  ChainWalkResult,
+  SignatureVerifier,
+  SignedAcceptance,
+} from "@integraledger/lcp-authority";
+import {
+  type CompositionInput,
+  discoveryIntegrityStep,
+  frcNonGatingStep,
+  offerBoundStep,
+  operationsStep,
+  proportionalityStep,
+} from "./composition.js";
+import type {
+  StepOutcome,
+  VerificationReport,
+  VerificationStep,
+  VerifyDepth,
+} from "./report.js";
+import {
+  computeVerified,
+  type StepName,
+  type TransactionClass,
+} from "./required.js";
+import {
+  type AuthorityLink,
+  acceptanceStep,
+  authorityStep,
+  authorityStepFromWalk,
+  commitmentStep,
+  fingerprintStep,
+  type PlacementInput,
+  type RecordIdentity,
+  recourseStep,
+  referencePlacementStep,
+  resolvePartyStep,
+  settlementStep,
+} from "./steps.js";
+
+export {
+  type CompositionInput,
+  type CompositionReadout,
+  discoveryIntegrityStep,
+  frcNonGatingStep,
+  offerBoundStep,
+  operationsStep,
+  proportionalityStep,
+  readCompositionSlots,
+} from "./composition.js";
+export {
+  jcsCanonicalize,
+  type StepOutcome,
+  serializeReport,
+  type VerificationReport,
+  type VerificationStep,
+  type VerifyDepth,
+} from "./report.js";
+export {
+  computeVerified,
+  REQUIRED_STEPS,
+  type StepName,
+  type TransactionClass,
+} from "./required.js";
+export {
+  type AuthorityLink,
+  acceptanceStep,
+  authorityStep,
+  authorityStepFromWalk,
+  commitmentStep,
+  fingerprintStep,
+  type PlacementInput,
+  RCS4_REQUIRED_ROLES,
+  type RecordIdentity,
+  recourseStep,
+  referencePlacementStep,
+  resolvePartyStep,
+  settlementStep,
+} from "./steps.js";
+
+/**
+ * Everything a verification walk is given. **The caller gathers the inputs; `verify()` opens no network
+ * connection of its own** — it takes `atrBytes`, not a reference to fetch, and takes `settlements` rather
+ * than enumerating them. That is what makes the walk pure and reproducible.
+ *
+ * Nearly every field is optional, and this is the type's central property: an absent input yields an
+ * `indeterminate` or `not-attempted` step, never a pass. `coverage` is how the report stays honest about
+ * that — it states which ports and bindings were actually supplied, so a thin walk cannot read as a
+ * thorough one.
+ */
+export interface VerifyInput {
+  /** The settlement's chain-anchored time (every validity check is evaluated against it). */
+  asOf: string;
+  /** Which ports/bindings were supplied — coverage is honest depth. */
+  coverage: { ports: string[]; bindings: string[] };
+  /** The retrieved ATR bytes (absent ⇒ the fingerprint step is indeterminate). */
+  atrBytes?: Uint8Array;
+  /** The atrHash the settlement committed (nonce/salt) — the fingerprint is checked against it. */
+  settledAtrHash?: string;
+  /** Settlements found for the fingerprint across supplied forward-indexable bindings. */
+  settlements?: unknown[];
+  /** The buyer's presented signed acceptance over the fingerprint (TRM-6). */
+  acceptance?: SignedAcceptance;
+  /** The port that checks the acceptance's signature. Absent ⇒ the acceptance step cannot prove — a
+   *  signature nobody checked is not evidence of a signature. The EVM impl is `binding-evm-common`'s. */
+  acceptanceVerifier?: SignatureVerifier;
+  /**
+   * The ATA chain to check for attenuation + as-of revocation/expiry, ALREADY FLATTENED.
+   *
+   * Whoever produced this array is a trusted oracle — every field on a link is a derived fact the step
+   * takes at face value. Prefer `authorityWalk`, which removes that trust. This door stays open because
+   * a foreign conformance subject may legitimately derive its links some other way.
+   */
+  authorityChain?: AuthorityLink[];
+  /**
+   * The custody walk's readout (`authority.walkChain`) — the PREFERRED authority input.
+   *
+   * `authorityChain` cannot express what the walk found: a spliced link, an issuer discontinuity, a root
+   * issued by someone other than the declared principal, a leaf granted to anyone but the acceptance
+   * signer. Flattening a `refused` walk throws those away and hands over links that then read as a clean
+   * `not-attempted`, so the report says the record simply did not carry a chain when in fact it carried
+   * a contradictory one. Supplied here, the refusal reaches the report WITH its halt class, and the
+   * walk's own gap depths pass through verbatim.
+   *
+   * Mutually exclusive with `authorityChain` — supplying both is a contradiction, not a precedence
+   * question, so it throws rather than silently picking one (the same ruling `makeProposalRecord` makes
+   * on its own exactly-one-of invariant).
+   */
+  authorityWalk?: ChainWalkResult;
+  /** The accepted commitment vs the leaf grant's bounds (ATA-4). */
+  commitment?: { commitment: Bounds; leafBounds: Bounds };
+  /** Both parties' resolutions, each at a stated assurance (IDN-1/IDN-3) — the record's `identity` slot. */
+  identity?: RecordIdentity;
+  /** The retained evidence package's manifest roles (RCS-4 completeness; `RCS4_REQUIRED_ROLES` is the floor). */
+  evidenceRoles?: readonly string[];
+  /** The class the record is shaped for (default TC-2). The taxonomy is closed (TC-0..TC-4); a caller
+   *  at a trust boundary validates untyped input before calling (Zod there, not here). */
+  claimedClass?: TransactionClass;
+  /** Verification depth (default "structural"). Mechanical depth lets `verified` be raised honestly. */
+  depth?: VerifyDepth;
+  /** The TC-4 commerce-plane slots. Absent ⇒ the composition steps are NOT appended to the walk
+   *  (TC-0..TC-3 reports are byte-identical). Present ⇒ the four required composition steps + the
+   *  impeachment-only `frc-non-gating` step are appended and flow through the existing machinery. */
+  composition?: CompositionInput;
+  /** The reference recovered from a commerce protocol's own document. Absent ⇒ the
+   *  `reference-placement` step is NOT appended and every existing report stays byte-identical. Present ⇒
+   *  the step is appended and flows through the same machinery as every other: it impeaches when it FAILS
+   *  and never blocks by its absence. REPORTED, never REQUIRED — no class lists it. */
+  placement?: PlacementInput;
+}
+
+/** Run the walk at the caller-specified `depth` (default `"structural"`) and emit the vector-anchored, JCS-serializable report. */
+export async function verify(input: VerifyInput): Promise<VerificationReport> {
+  if (input.authorityWalk !== undefined && input.authorityChain !== undefined)
+    throw new Error(
+      "verify: authorityWalk and authorityChain are mutually exclusive — a walked chain is already the readout, and flattening it alongside would ask which of two answers about the same chain to believe",
+    );
+  const steps: VerificationStep[] = [
+    {
+      name: "atr-fingerprint",
+      outcome: await fingerprintStep(input.atrBytes, input.settledAtrHash),
+    },
+    {
+      name: "settlement-enumeration",
+      outcome: settlementStep(input.settlements),
+    },
+    {
+      name: "buyer-acceptance",
+      outcome: await acceptanceStep(
+        input.acceptance,
+        input.settledAtrHash,
+        input.acceptanceVerifier,
+      ),
+    },
+    {
+      name: "authority-attenuation",
+      // One step name either way: the report's shape does not change with how the caller obtained its
+      // chain, only how much the walk was able to say about it.
+      outcome:
+        input.authorityWalk !== undefined
+          ? authorityStepFromWalk(input.authorityWalk)
+          : authorityStep(input.authorityChain),
+    },
+    { name: "commitment-vs-leaf", outcome: commitmentStep(input.commitment) },
+    {
+      name: "recourse-elections",
+      outcome: recourseStep(input.atrBytes, input.evidenceRoles),
+    },
+    { name: "resolve-party", outcome: resolvePartyStep(input.identity) },
+  ];
+
+  // Append the TC-4 composition steps ONLY when a composition slot is supplied — the slot is additive:
+  // a TC-0..TC-3 report that supplies none is byte-identical to one produced without the slot existing.
+  // The appended steps flow through the same `anyFailed`/`computeVerified` machinery as every other.
+  if (input.composition !== undefined) {
+    steps.push(
+      { name: "offer-bound", outcome: offerBoundStep(input.composition) },
+      { name: "operations-bound", outcome: operationsStep(input.composition) },
+      {
+        name: "discovery-integrity",
+        outcome: discoveryIntegrityStep(input.composition),
+      },
+      {
+        name: "proportionality-declared",
+        outcome: proportionalityStep(input.composition),
+      },
+      {
+        name: "frc-non-gating",
+        outcome: frcNonGatingStep(input.composition),
+      },
+    );
+  }
+
+  // Append the reference-placement step ONLY when a placement slot is supplied — its own `if`, because a
+  // placement is independent of a composition and a record may carry either, both, or neither. Absent ⇒
+  // nothing is appended and existing reports stay byte-identical, which is what makes the slot additive.
+  // Supplied ⇒ it flows through the same `anyFailed`/`computeVerified` machinery as every other step, so
+  // a placement that CONTRADICTS the record impeaches `supportedClass` to TC-0 — the one power the step
+  // grants it. Without this block the step would appear in no report and impeach nothing.
+  if (input.placement !== undefined) {
+    steps.push({
+      name: "reference-placement",
+      outcome: referencePlacementStep(input.placement, input.settledAtrHash),
+    });
+  }
+
+  const anyFailed = steps.some((s) => s.outcome.status === "failed");
+  const found = input.settlements ?? [];
+  const depth = input.depth ?? "structural";
+  const claimed = input.claimedClass ?? "TC-2";
+  const stepsForVerified = steps.map((s) => ({
+    name: s.name as StepName,
+    outcome: s.outcome,
+  }));
+
+  return {
+    verified: computeVerified(stepsForVerified, claimed, depth),
+    // The BUYER's stated level: the report's assurance answers "at what assurance did the party who
+    // committed resolve?" — the seller's own level rides in the record's identity slot and the package.
+    // `buyer` is optional-chained on purpose: `RecordIdentity` requires it, but this readout must be TOTAL
+    // over the same half-shaped input `resolvePartyStep` is total over (an untyped caller, a foreign
+    // conformance subject). A walk that throws on a malformed record cannot report the malformation.
+    //
+    // The fallback is NOT a ladder value. `wallet-signature-only` would be conservative in
+    // direction, since it never inflates, but still a level the verifier elected for a record that stated
+    // none, and the floor of a ladder reads as a finding rather than as silence. `no-assurance-stated` is
+    // the SAME token `resolvePartyStep` emits for this condition (steps.ts), so absence has one spelling
+    // across the step and the report instead of contradicting itself inside a single run.
+    assurance: input.identity?.buyer?.assurance ?? "no-assurance-stated",
+    supportedClass: anyFailed ? "TC-0" : claimed,
+    asOf: input.asOf,
+    steps,
+    coverage: input.coverage,
+    settlements: { found, multiplySettled: found.length > 1 },
+  };
+}
+
+/** Discriminant helper — did any step fail (the honest impeachment signal)? */
+export function anyStepFailed(report: VerificationReport): boolean {
+  return report.steps.some(
+    (s: VerificationStep) => (s.outcome as StepOutcome).status === "failed",
+  );
+}

package/src/report.ts

@@ -0,0 +1,100 @@
+/**
+ * The `VerificationReport` and its **deterministic serialization — RFC 8785 (JCS) canonical JSON**.
+ * The protocol promises byte-identical reports across independent implementations: the report is RECOMPUTED by
+ * every verifier, and JCS is exactly the multi-producer-convergence case it exists for. This is NOT the
+ * ATR rule and the two must never be conflated — canonicalization is banned for the *ATR* because it has
+ * one producer and the exact received bytes are the fingerprint; the *report* has many producers.
+ *
+ * All monetary values in reports are decimal-integer base-unit STRINGS, so JCS's
+ * ECMAScript number serialization never touches money. JCS = recursively sort object keys by UTF-16 code
+ * units (JS default string sort), then serialize with JSON's escaping + ECMAScript number formatting
+ * (which already match RFC 8785 §3.2.2). Confirmed byte-for-byte against an independent JCS implementation.
+ */
+import type { HaltClass } from "@integraledger/lcp-binding-core";
+
+/** Verification depth: structural (presence/absence readout, verified always false) vs mechanical
+ *  (inputs gathered over live ports; verified is an honest function of the walk). */
+export type VerifyDepth = "structural" | "mechanical";
+
+/** A step outcome — aligned to `report.schema.json`. */
+export type StepOutcome =
+  | { status: "proved" }
+  | { status: "failed"; haltClass: HaltClass }
+  | { status: "indeterminate" } // unretrievable ATR — not a failure
+  | { status: "not-attempted"; depth: string };
+
+/** One named step of the walk and how it came out. The `name` is a {@link StepName} in this
+ *  implementation but is typed as `string` here so a foreign implementation's report is representable —
+ *  a report type that cannot hold another engine's step cannot be used to compare against it. */
+export interface VerificationStep {
+  name: string;
+  outcome: StepOutcome;
+}
+
+/** The output of a verification walk — the artifact a stranger reads instead of re-running it.
+ *
+ *  Read `steps` before `verified`. `verified` is a summary that is FALSE at structural depth by
+ *  construction, so a `false` may mean "impeached" or merely "not attempted mechanically", and only the
+ *  step list distinguishes them. `supportedClass` is what the record honestly supports, not what the
+ *  caller asked for. Several fields are `string` rather than a union on purpose: this type has to be able
+ *  to hold another implementation's answer, including a wrong one. */
+export interface VerificationReport {
+  /** Honest function of depth: `false` at structural (presence/absence → class); at mechanical, raised by
+   *  `computeVerified` iff every class-required step is `proved` and none `failed`. */
+  verified: boolean;
+  /** The stated assurance level — never a bare boolean. One of the four ladder values
+   *  (`wallet-signature-only` | `domain-controlled` | `attested` | `legal-party`), or
+   *  `no-assurance-stated` where the record states none. Left as `string` rather than a union for the same
+   *  reason `supportedClass` is: a foreign implementation's report must be representable before it can be
+   *  compared, and a type that refuses to hold a wrong value cannot report one. */
+  assurance: string;
+  /** The transaction class the record honestly supports — an honest readout, never a target. */
+  supportedClass: string;
+  /** The settlement's chain-anchored time every validity check is evaluated against. */
+  asOf: string;
+  steps: VerificationStep[];
+  /** Supplied ports/bindings — coverage is part of honest depth. */
+  coverage: { ports: string[]; bindings: string[] };
+  settlements: { found: unknown[]; multiplySettled: boolean };
+}
+
+/**
+ * Emit the canonical text DIRECTLY from the sorted key list — never by re-assigning sorted keys onto an
+ * object and handing it to `JSON.stringify`. JS object property order puts integer-like keys FIRST, in
+ * ascending numeric order, whatever the insertion order (the same engine behaviour `kernel.assemble`
+ * refuses integer-like slot names over), so the object round-trip silently re-sorts `{"10":…,"9":…}` to
+ * `9,10` while RFC 8785 §3.2.3 requires UTF-16 code-unit order — `"1" (0x31) < "9" (0x39)`. Two conformant
+ * implementations would then disagree byte-for-byte on the same report, which is the one thing this buys.
+ * Reachable through `settlements.found` (caller-supplied objects). Pinned by `vectors/report/serialization.json`.
+ */
+function serializeCanonical(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(serializeCanonical).join(",")}]`;
+  if (v !== null && typeof v === "object") {
+    const obj = v as Record<string, unknown>;
+    // Default Array#sort compares by UTF-16 code units — exactly RFC 8785's ordering.
+    const parts = Object.keys(obj)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${serializeCanonical(obj[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  // Primitives: JSON's own escaping + ECMAScript number formatting already match RFC 8785 §3.2.2.
+  return JSON.stringify(v) as string;
+}
+
+/** RFC 8785 JCS canonical JSON string for any JSON value (keys sorted by UTF-16 code units, no whitespace). */
+export function jcsCanonicalize(value: unknown): string {
+  // Round-trip through JSON first so `toJSON`, dropped `undefined`/function members, and non-finite
+  // numbers resolve EXACTLY as JSON.stringify defines them; `serializeCanonical` then sees pure JSON
+  // and owns only the ordering rule.
+  const json = JSON.stringify(value);
+  if (json === undefined)
+    throw new Error(
+      "value is not JSON-serializable (JCS is defined only over JSON values)",
+    );
+  return serializeCanonical(JSON.parse(json));
+}
+
+/** The report's canonical bytes (UTF-8 of its JCS form) — the byte-for-byte target. */
+export function serializeReport(report: VerificationReport): Uint8Array {
+  return new TextEncoder().encode(jcsCanonicalize(report));
+}

package/src/required.ts

@@ -0,0 +1,99 @@
+import type { VerifyDepth } from "./report.js";
+
+export type { VerifyDepth };
+/** The transaction-class ladder. Higher classes require strictly more steps, so a record supporting TC-3
+ *  supports every class below it. A class is a CLAIM about what a record can support — it is never a
+ *  quality score, and nothing in this package tries to reach a higher one. */
+export type TransactionClass = "TC-0" | "TC-1" | "TC-2" | "TC-3" | "TC-4";
+/** Every step the walk can append, in one closed union. Closed because `REQUIRED_STEPS` is keyed by these
+ *  names and a typo would silently make a required step unfindable — which `computeVerified` would read as
+ *  "not proved", failing safe but for the wrong reason. */
+export type StepName =
+  | "atr-fingerprint"
+  | "settlement-enumeration"
+  | "buyer-acceptance"
+  | "authority-attenuation"
+  | "commitment-vs-leaf"
+  | "recourse-elections"
+  | "resolve-party"
+  // The TC-4 composition steps:
+  | "offer-bound"
+  | "operations-bound"
+  | "discovery-integrity"
+  | "proportionality-declared"
+  | "frc-non-gating"
+  // The reference-placement step is REPORTED, NEVER REQUIRED. Deliberately absent from every entry in REQUIRED_STEPS below,
+  // for the same reason frc-non-gating is: it impeaches when it FAILS (the reference found in the
+  // protocol's native field contradicts the record) but its ABSENCE never blocks. A protocol that never
+  // settles has nothing to enumerate, and letting a placement stand in for a settlement rung would let a
+  // record that moved no money read as classed — the exact inflation the center lock forbids.
+  | "reference-placement";
+
+/** PAY + IDN — the attribution rungs every class from TC-1 up carries. */
+const TC1: readonly StepName[] = ["settlement-enumeration", "resolve-party"];
+/** + TRM/WLD: the fingerprint step IS the weld check (recomputed hash vs the hash the settlement committed). */
+const TC2: readonly StepName[] = [...TC1, "atr-fingerprint"];
+/** + TRM-6 + ATA + RCS-1/2/4 — the definition of the class, verbatim. */
+const TC3: readonly StepName[] = [
+  ...TC2,
+  "buyer-acceptance",
+  "authority-attenuation",
+  "commitment-vs-leaf",
+  "recourse-elections",
+];
+
+/**
+ * What each class MECHANICALLY requires to be `proved` before `verified` can hold, derived row-for-row from
+ * The class requirements (see `vectors/verify/mechanical.json`, the authored-from-spec truth table):
+ *
+ *   PAY (value settles) ................. `settlement-enumeration`      TC-1 +
+ *   IDN (identity, stated assurance) .... `resolve-party`               TC-1 +
+ *   TRM/WLD (fingerprint + weld) ........ `atr-fingerprint`             TC-2 +
+ *   TRM-6 (signed acceptance) ........... `buyer-acceptance`            TC-3 +
+ *   ATA (authority + delegation chain) .. `authority-attenuation`, `commitment-vs-leaf`   TC-3 +
+ *   RCS-1/2/4 (forum, law, package) ..... `recourse-elections`          TC-3 +
+ *   OFR/OPS/DSC (commerce plane) ........ the four composition steps    TC-4
+ *
+ * The ladder is CUMULATIVE: a class requires every rung below it, which is why TC-4 cannot hold without the
+ * TC-3 acceptance. It is also EXACT: a class never requires a step it does not depend on — TRM is not a TC-1
+ * rung, so a TC-1 record with an unattempted fingerprint still verifies.
+ *
+ * DECLARED GAP — ASP (spend authority, verifiable bounds) is marked from TC-1 and has NO step here: the bounds
+ * live inside the rail's own settlement authorization (an EIP-3009 `value`, an escrow `PaymentInfo` cap) and
+ * `verify` is pure over supplied inputs with no rail decoder. RCS-4 reaches it indirectly — `recourse-elections`
+ * requires the `spend artifact` role in the retained package, so the artifact is kept and referenced even though
+ * its bounds are not re-derived here. Closing it properly is a rail-decoder work item, named rather than omitted.
+ *
+ * `frc-non-gating` is DELIBERATELY absent from TC-4: it impeaches when it FAILS (a signal that gated settlement)
+ * but its ABSENCE never blocks (FRC is a downstream consequence, not a v1 requirement).
+ */
+export const REQUIRED_STEPS: Record<TransactionClass, readonly StepName[]> = {
+  "TC-0": [],
+  "TC-1": TC1,
+  "TC-2": TC2,
+  "TC-3": TC3,
+  "TC-4": [
+    ...TC3,
+    "offer-bound",
+    "operations-bound",
+    "discovery-integrity",
+    "proportionality-declared",
+  ],
+};
+
+/** Whether a walk affirms the claimed class. Three rules, in order: **structural depth is always `false`**
+ *  (a presence/absence readout never affirms liveness), any `failed` step impeaches the whole walk, and
+ *  otherwise every step required by the claimed class must be `proved`. A step that is absent, or
+ *  `indeterminate`, is not `proved` — absent inputs never prove. */
+export function computeVerified(
+  steps: readonly { name: StepName; outcome: { status: string } }[],
+  claimedClass: TransactionClass,
+  depth: VerifyDepth,
+): boolean {
+  if (depth === "structural") return false; // structural = presence/absence readout, never affirms liveness
+  if (steps.some((s) => s.outcome.status === "failed")) return false; // any failure impeaches
+  const required = REQUIRED_STEPS[claimedClass];
+  return required.every(
+    (name) => steps.find((s) => s.name === name)?.outcome.status === "proved",
+  );
+}