@forestrie/receipt-verify 3.0.1 → 3.2.0

package/dist/verify-receipt-against-checkpoint-chain.js

@@ -0,0 +1,205 @@
+/**
+ * The checkpoint-chain trust root (FOR-368 Phase 3; owner ruling D8): fold a
+ * retained `.sth` chain under the caller's roots with per-link delegation
+ * limits ({@link makeCheckpointLinkVerifier}), match the receipt's peak
+ * against ANY authenticated link, then judge certificate expiry on the
+ * links covering the now-bound leaf ({@link checkCheckpointLinkExpiry}).
+ * Lifted from mcp-verify 0.6.1's `verifyAtCheckpointChain`; forestrie-cli,
+ * which matches peaks its own way, can use the pieces instead.
+ *
+ * Later links' signed consistency proofs commit an earlier accumulator
+ * forward, so burial never turns an honest receipt tamper-shaped. Retention
+ * limits coverage, never validity: a receipt newer than the chain fails
+ * closed with a refresh remedy.
+ *
+ * Pure over bytes; no network (canopy rule C1).
+ */
+import { calculateRoot, peakMMRIndexes } from "@forestrie/merklelog";
+import { verifyCheckpointChain, } from "./checkpoint-chain.js";
+import { checkCheckpointLinkExpiry, makeCheckpointLinkVerifier, } from "./checkpoint-link-verifier.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import { summarizeKs256AttestationUsage } from "./ks256-attestation-usage.js";
+import { inclusionWalkEndIndex } from "./inclusion-walk-end.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { parseReceipt } from "./parse-receipt.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+/**
+ * Verify a receipt against a retained checkpoint chain.
+ *
+ * The receipt's own signature is not checked: the authenticated chain is
+ * the authority, and the peak is ALWAYS recomputed from the leaf
+ * (`idtimestamp ‖ inner`) and the inclusion path, never taken from an
+ * attached payload. A match binds the leaf's idtimestamp (through the leaf
+ * hash) and its mmrIndex (through the matched peak's POSITION, which must be
+ * the node the inclusion walk reaches: the leaf hash alone does not commit
+ * its position, and an empty path commits none).
+ * Links are searched newest first; the newest cover is reported.
+ */
+export async function verifyReceiptAgainstCheckpointChain(input) {
+    const attestations = input.attestations ?? [];
+    const empty = {
+        links: [],
+        records: [],
+        attestations: summarizeKs256AttestationUsage(attestations, []),
+    };
+    if (input.rootKeys.length === 0) {
+        return { ...empty, ok: false, stage: "input", reason: "no_trust_key" };
+    }
+    let forestChainId = input.forestChainId;
+    if (input.forestGenesisCbor !== undefined) {
+        let fromGenesis;
+        try {
+            fromGenesis = BigInt(decodeChainBindingFromGenesis(input.forestGenesisCbor).chainId);
+        }
+        catch {
+            return {
+                ...empty,
+                ok: false,
+                stage: "input",
+                reason: "forest_genesis_invalid",
+            };
+        }
+        if (forestChainId !== undefined && forestChainId !== fromGenesis) {
+            return {
+                ...empty,
+                ok: false,
+                stage: "input",
+                reason: "forest_chain_id_mismatch",
+            };
+        }
+        forestChainId = fromGenesis;
+    }
+    const verifier = makeCheckpointLinkVerifier({
+        rootKeys: input.rootKeys,
+        attestations,
+        forestChainId,
+    });
+    const chain = await verifyCheckpointChain({
+        checkpoints: [...input.checkpoints],
+        verifySignature: verifier.verifySignature,
+        ...(input.trustedBase !== undefined
+            ? { trustedBase: input.trustedBase }
+            : {}),
+    });
+    const linkFailure = verifier.failure();
+    const common = {
+        links: chain.links,
+        records: verifier.records,
+        attestations: summarizeKs256AttestationUsage(attestations, verifier.records, linkFailure),
+    };
+    if (!chain.ok) {
+        return {
+            ...common,
+            ok: false,
+            stage: "chain",
+            reason: linkFailure?.reason ?? `checkpoint_chain_${chain.reason}`,
+            at: chain.at,
+            detail: chain.detail,
+            ...(linkFailure !== undefined ? { linkFailure } : {}),
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseReceipt(input.receiptCbor);
+    }
+    catch {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    if (input.idtimestampBe8.length < 8) {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "idtimestamp_invalid",
+        };
+    }
+    const idtimestamp = readU64Be(input.idtimestampBe8.slice(-8));
+    // parseReceipt always sets mmrIndex; leafIndex wins when present, as in
+    // every other peak recompute in this package.
+    const leafMmrIndex = parsed.proof.leafIndex ?? parsed.proof.mmrIndex;
+    if (leafMmrIndex === undefined) {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    const links = chain.links;
+    const final = links[links.length - 1];
+    if (leafMmrIndex >= final.treeSize2) {
+        return {
+            ...common,
+            ok: false,
+            stage: "anchor",
+            reason: "receipt_newer_than_checkpoint_chain",
+        };
+    }
+    let peak;
+    try {
+        peak = await calculateRoot(new SubtleHasher(), await univocityLeafHash(idtimestamp, input.inner), parsed.proof, leafMmrIndex);
+    }
+    catch {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    // The peak the path claims to reach. A leaf hash does not commit its
+    // position (and an empty path commits none), so a value match alone would
+    // leave mmrIndex a caller claim: the matched peak must sit at this index.
+    const peakIndex = inclusionWalkEndIndex(leafMmrIndex, parsed.proof.path.length);
+    for (let i = links.length - 1; i >= 0; i--) {
+        const link = links[i];
+        const p = link.treeSize2 > 0n
+            ? peakMMRIndexes(link.treeSize2 - 1n).indexOf(peakIndex)
+            : -1;
+        if (p < 0 || !bytesEqual(link.accumulator[p] ?? new Uint8Array(), peak)) {
+            continue;
+        }
+        // The leaf hash, inclusion path and peak position now bind idtimestamp
+        // and mmrIndex to an authenticated accumulator, so expiry can be judged
+        // on them.
+        const expiry = checkCheckpointLinkExpiry(verifier.records, {
+            mmrIndex: leafMmrIndex,
+            idtimestamp,
+        });
+        if (!expiry.ok) {
+            return {
+                ...common,
+                ok: false,
+                stage: "delegation",
+                reason: expiry.reason,
+                at: expiry.at,
+            };
+        }
+        return { ...common, ok: true, matchedLink: i, matchedPeak: p };
+    }
+    return {
+        ...common,
+        ok: false,
+        stage: "anchor",
+        reason: "peak_not_in_checkpoint_chain",
+    };
+}
+function readU64Be(be8) {
+    let v = 0n;
+    for (const b of be8)
+        v = (v << 8n) | BigInt(b);
+    return v;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let x = 0;
+    for (let i = 0; i < a.length; i++)
+        x |= a[i] ^ b[i];
+    return x === 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -30,9 +30,11 @@
     "@noble/hashes": "^1.7.1",
     "@forestrie/chain-rpc": "0.3.0",
     "@forestrie/encoding": "0.9.1",
-    "@forestrie/merklelog": "0.5.0"
+    "@forestrie/merklelog": "0.5.0",
+    "@forestrie/delegation-cose": "0.4.0"
   },
   "devDependencies": {
+    "@noble/curves": "^1.9.7",
     "esbuild": "^0.24.0",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"

package/src/checkpoint-chain-receipt-outcome.ts

@@ -0,0 +1,67 @@
+/**
+ * The typed result of {@link verifyReceiptAgainstCheckpointChain}: the
+ * verdict, where it was decided, and everything a reporter needs (folded
+ * links, per-link delegation records, attestation usage).
+ */
+import type { CheckpointChainLink } from "./checkpoint-chain.js";
+import type {
+  CheckpointLinkFailure,
+  CheckpointLinkRecord,
+} from "./checkpoint-link-record.js";
+import type { Ks256AttestationUsage } from "./ks256-attestation-usage.js";
+
+/**
+ * Where a failing run stopped:
+ * - `input`: the caller's inputs (no root keys, a forest genesis without a
+ *   chain binding).
+ * - `chain`: the checkpoint chain did not fold or a link was refused.
+ * - `parse`: the receipt or idtimestamp did not parse.
+ * - `anchor`: the chain folded but the receipt's leaf-derived peak is in no
+ *   link (`peak_not_in_checkpoint_chain`), or the leaf is past the chain
+ *   (`receipt_newer_than_checkpoint_chain`; refresh, not tamper).
+ * - `delegation`: the receipt matched, but a link covering its leaf was
+ *   signed under an expired certificate (`delegation_expired`).
+ */
+export type CheckpointChainReceiptStage =
+  | "input"
+  | "chain"
+  | "parse"
+  | "anchor"
+  | "delegation";
+
+/** Fields every outcome carries, pass or fail. */
+type OutcomeCommon = {
+  /** The authenticated links (the verified prefix on a chain failure). */
+  links: CheckpointChainLink[];
+  /** Per-link delegation facts, one per authenticated link. */
+  records: CheckpointLinkRecord[];
+  /** Every supplied attestation, as used or unused with a reason. */
+  attestations: Ks256AttestationUsage;
+};
+
+/** A receipt anchored in a retained checkpoint chain, or why not. */
+export type CheckpointChainReceiptOutcome =
+  | (OutcomeCommon & {
+      ok: true;
+      /** Index of the newest link whose accumulator holds the peak. */
+      matchedLink: number;
+      /** Index of the matching peak within that link's accumulator. */
+      matchedPeak: number;
+    })
+  | (OutcomeCommon & {
+      ok: false;
+      stage: CheckpointChainReceiptStage;
+      /**
+       * Stable reason: a {@link CheckpointLinkFailure} reason, a
+       * `CheckpointChainResult` reason prefixed `checkpoint_chain_`, a
+       * receipt parse reason, or one of the anchor/delegation reasons
+       * above.
+       */
+      reason: string;
+      /** Offending link index, for `chain` and `delegation`. */
+      at?: number;
+      /** Human detail from the chain fold, when it failed there. */
+      detail?: string;
+      /** The per-link verifier's refusal, when it caused a `chain` failure. */
+      linkFailure?: CheckpointLinkFailure;
+    });

package/src/checkpoint-link-record.ts

@@ -0,0 +1,74 @@
+/**
+ * What the per-link checkpoint verifier learned about each link of a
+ * retained `.sth` chain ({@link makeCheckpointLinkVerifier}). Consumers
+ * (mcp-verify, forestrie-cli) report these facts; the post-match expiry
+ * check ({@link checkCheckpointLinkExpiry}) reads them.
+ */
+import type { DelegationConstraints } from "./resolve-delegated-verify-key.js";
+
+/**
+ * Which key verified a link's checkpoint signature, and what vouched for it:
+ *
+ * - `es256-root`: an ES256 root key verified the checkpoint directly (no
+ *   certificate, or the root signed despite one).
+ * - `delegated`: the label-1000 certificate's delegated key verified it, and
+ *   an ES256 root (or passkey root) vouched for the certificate.
+ * - `ks256-root`: the delegated key verified it, and a KS256 root vouched for
+ *   the certificate: by ecrecover, or by an ERC-1271 attestation when
+ *   {@link CheckpointLinkRecord.attestationNeeded}.
+ */
+export type CheckpointLinkVerifiedBy =
+  | "es256-root"
+  | "ks256-root"
+  | "delegated";
+
+/** One authenticated link of a checkpoint chain. */
+export type CheckpointLinkRecord = {
+  /** Position in the supplied checkpoint list (fold order). */
+  index: number;
+  /** The checkpoint's SIGNED tree size (protected label -65933). */
+  signedSize: bigint;
+  /**
+   * The delegation certificate's limits, `null` when the link carries no
+   * certificate or the certificate declares none of labels 3/4/8/9.
+   */
+  constraints: DelegationConstraints | null;
+  verifiedBy: CheckpointLinkVerifiedBy;
+  /**
+   * Hex (no `0x`) of the digest of the attestation this link needed, set
+   * only when {@link attestationNeeded}.
+   */
+  attestationUsed?: string;
+  /**
+   * Index, in the caller's attestation list, of the attestation made for
+   * this link's certificate (digest and signature hash match), whether or
+   * not the link needed it.
+   */
+  attestationIndex?: number;
+  /**
+   * Indexes of attestations made for this link's certificate that were
+   * tried before {@link attestationIndex} and failed their own checks
+   * (address, chain id, magic).
+   */
+  attestationsRejected?: number[];
+  /**
+   * The link verified only because of an attestation: re-resolving its
+   * certificate under the same roots without one fails. Pure and offline.
+   */
+  attestationNeeded: boolean;
+};
+
+/** Why the per-link verifier refused a link. */
+export type CheckpointLinkFailure = {
+  index: number;
+  /**
+   * `delegation_invalid`, a KS256 reason (`ks256_root_not_recovered`,
+   * `ks256_attestation_*`, `delegation_not_ks256`), `delegation_out_of_range`,
+   * `signature_invalid` or `proof_malformed`.
+   */
+  reason: string;
+  /** As {@link CheckpointLinkRecord.attestationIndex}. */
+  attestationIndex?: number;
+  /** As {@link CheckpointLinkRecord.attestationsRejected}. */
+  attestationsRejected?: number[];
+};

package/src/checkpoint-link-verifier.ts

@@ -0,0 +1,241 @@
+/**
+ * Per-link trust for a retained checkpoint chain: the `verifySignature`
+ * callback {@link verifyCheckpointChain} takes, plus the delegation limits
+ * each link's label-1000 certificate imposes. Lifted from mcp-verify 0.6.1
+ * (`src/core/verify-shared.ts`) so mcp-verify and forestrie-cli share one
+ * copy; see mcp-verify `docs/trust-roots.md` ("Delegation limits under
+ * checkpoint-chain").
+ *
+ * The limits mirror univocity's on-chain check
+ * ([delegationVerifier.sol](https://github.com/forestrie/univocity/blob/main/src/checkpoints/lib/delegationVerifier.sol)):
+ * a checkpoint of claimed size `S` is anchored only when its delegation
+ * covers `mmrIndex = S > 0 ? S - 1 : 0`, i.e. `mmrStart <= mmrIndex <=
+ * mmrEnd`. Here `S` is the checkpoint's SIGNED tree size (label -65933), so
+ * a link the contract would refuse is refused offline too
+ * (`delegation_out_of_range`). Expiry needs a leaf the receipt binds and is
+ * judged after the receipt matched ({@link checkCheckpointLinkExpiry}).
+ *
+ * Pure over bytes; no network (canopy rule C1).
+ */
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import { checkpointConsistencyProof } from "./checkpoint-chain.js";
+import type {
+  CheckpointLinkFailure,
+  CheckpointLinkRecord,
+  CheckpointLinkVerifiedBy,
+} from "./checkpoint-link-record.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import {
+  idtimestampToUnixSeconds,
+  resolveDelegatedVerifyKey,
+  type DelegationConstraints,
+} from "./resolve-delegated-verify-key.js";
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
+
+/** The per-link verifier and what it has learned so far. */
+export type CheckpointLinkVerifier = {
+  /** Pass as `verifyCheckpointChain({ verifySignature })`. */
+  verifySignature: (
+    checkpointBytes: Uint8Array,
+    detachedPayload: Uint8Array,
+  ) => Promise<boolean>;
+  /** One record per link that verified, in fold order. */
+  records: CheckpointLinkRecord[];
+  /** Set when the verifier refused a link; the chain fold stops there. */
+  failure(): CheckpointLinkFailure | undefined;
+};
+
+/**
+ * Build the per-link signature verifier for {@link verifyCheckpointChain}.
+ *
+ * For each checkpoint, in fold order: resolve its label-1000 certificate
+ * under `rootKeys` (with the attestation made for that certificate, if any),
+ * verify the COSE signature over the FOLDED accumulator (the detached
+ * payload the fold computes, never one read from the checkpoint; ADR-0046),
+ * then enforce the certificate's size bound against the signed size. KS256
+ * roots vouch only for certificates; only ES256 roots may verify a
+ * checkpoint directly.
+ *
+ * The callback must be used for exactly one fold: link indices are the call
+ * count.
+ *
+ * @param opts.rootKeys - ES256 keys and KS256 addresses, from genesis or
+ *   caller-known log keys.
+ * @param opts.attestations - ERC-1271 attestations for KS256 contract
+ *   roots; each certificate takes the one with its digest and signature
+ *   hash ({@link selectKs256Attestation}).
+ * @param opts.forestChainId - The forest genesis chain id every attestation
+ *   must carry; without it a contract root fails
+ *   `ks256_attestation_chain_unbound`.
+ */
+export function makeCheckpointLinkVerifier(opts: {
+  rootKeys: readonly RootVerifyKey[];
+  attestations?: readonly Ks256Attestation[] | undefined;
+  forestChainId?: bigint | undefined;
+}): CheckpointLinkVerifier {
+  const rootKeys = [...opts.rootKeys];
+  const attestations = opts.attestations ?? [];
+  const es256Roots = rootKeys.filter(
+    (k): k is CryptoKey => !isParsedKs256RootKey(k),
+  );
+  const records: CheckpointLinkRecord[] = [];
+  let failure: CheckpointLinkFailure | undefined;
+  let calls = 0;
+
+  const verifySignature = async (
+    checkpointBytes: Uint8Array,
+    detachedPayload: Uint8Array,
+  ): Promise<boolean> => {
+    const index = calls++;
+    const chosen = await resolveWithKs256Attestations(
+      checkpointBytes,
+      rootKeys,
+      attestations,
+      opts.forestChainId,
+    );
+    const resolution = chosen.resolution;
+    const fail = (reason: string): false => {
+      failure = { index, reason };
+      if (chosen.selected !== undefined) {
+        failure.attestationIndex = chosen.selected;
+      }
+      if (chosen.rejected.length > 0) {
+        failure.attestationsRejected = chosen.rejected;
+      }
+      return false;
+    };
+
+    if (resolution.kind === "broken") {
+      return fail(resolution.reason ?? "delegation_invalid");
+    }
+
+    let signedSize: bigint;
+    try {
+      signedSize = checkpointConsistencyProof(checkpointBytes).signedTreeSize2;
+    } catch {
+      // The fold read the same label moments ago; fail closed.
+      return fail("proof_malformed");
+    }
+
+    const candidates: { key: CryptoKey; delegated: boolean }[] = [
+      ...(resolution.kind === "resolved"
+        ? [{ key: resolution.delegatedKey, delegated: true }]
+        : []),
+      ...es256Roots.map((key) => ({ key, delegated: false })),
+    ];
+    let signer: { key: CryptoKey; delegated: boolean } | undefined;
+    for (const c of candidates) {
+      if (
+        await verifyCoseSign1WithParsedKey(checkpointBytes, c.key, {
+          logPrefix: "checkpoint-chain",
+          detachedPayload,
+        })
+      ) {
+        signer = c;
+        break;
+      }
+    }
+    if (signer === undefined) return fail("signature_invalid");
+
+    // A resolved certificate's limits bind the link even when a root key
+    // verified it directly: stricter than univocity, which would not accept
+    // a root signature alongside a certificate at all.
+    const constraints =
+      resolution.kind === "resolved" ? resolution.constraints : null;
+    if (constraints !== null) {
+      const bound = checkCheckpointLinkSizeBound(constraints, signedSize);
+      if (!bound.ok) return fail(bound.reason);
+    }
+
+    let verifiedBy: CheckpointLinkVerifiedBy = "es256-root";
+    if (signer.delegated) {
+      const viaEs256 = await resolveDelegatedVerifyKey(
+        checkpointBytes,
+        es256Roots,
+      );
+      verifiedBy = viaEs256.kind === "resolved" ? "delegated" : "ks256-root";
+    }
+    // Only a selected attestation can carry a certificate (a diagnostic
+    // stand-in never matches), so "needed" implies "selected".
+    const attestationNeeded =
+      chosen.selected !== undefined &&
+      resolution.kind === "resolved" &&
+      (await resolveDelegatedVerifyKey(checkpointBytes, rootKeys)).kind ===
+        "broken";
+
+    const record: CheckpointLinkRecord = {
+      index,
+      signedSize,
+      constraints,
+      verifiedBy,
+      attestationNeeded,
+    };
+    if (chosen.rejected.length > 0) {
+      record.attestationsRejected = chosen.rejected;
+    }
+    if (chosen.selected !== undefined) {
+      record.attestationIndex = chosen.selected;
+      if (attestationNeeded) {
+        record.attestationUsed = bytesToHex(
+          attestations[chosen.selected]!.digest,
+        );
+      }
+    }
+    records.push(record);
+    return true;
+  };
+
+  return { verifySignature, records, failure: () => failure };
+}
+
+/**
+ * The size bound univocity enforces on a checkpoint, judged from signed
+ * data alone: with `mmrIndex = signedSize > 0 ? signedSize - 1 : 0`, reject
+ * `mmrIndex < mmrStart || mmrIndex > mmrEnd` (`delegationVerifier.sol`,
+ * `_Univocity.sol` passes `claimedSize > 0 ? claimedSize - 1 : 0`).
+ *
+ * @returns `delegation_out_of_range` on either side of the window.
+ */
+export function checkCheckpointLinkSizeBound(
+  constraints: DelegationConstraints,
+  signedSize: bigint,
+): { ok: true } | { ok: false; reason: "delegation_out_of_range" } {
+  const mmrIndex = signedSize > 0n ? signedSize - 1n : 0n;
+  if (mmrIndex < constraints.mmrStart || mmrIndex > constraints.mmrEnd) {
+    return { ok: false, reason: "delegation_out_of_range" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Expiry, judged only AFTER a receipt matched the chain, when its leaf's
+ * idtimestamp and mmrIndex are bound by the leaf hash and inclusion path
+ * rather than being caller claims. A link whose signed size covers the leaf
+ * (`signedSize > leaf.mmrIndex`) was signed after the leaf was sequenced, so
+ * a leaf time past `expiresAt` proves signing past the key's lifetime. A
+ * link that does not cover the leaf says nothing about its time. Never
+ * wall-clock; no `issuedAt` bound (a certificate is legitimately signed a
+ * few seconds after the leaf it first covers).
+ *
+ * @param records - From {@link makeCheckpointLinkVerifier}.
+ * @param leaf.idtimestamp - The bound leaf's snowflake idtimestamp.
+ * @returns The first offending link as `at`.
+ */
+export function checkCheckpointLinkExpiry(
+  records: readonly CheckpointLinkRecord[],
+  leaf: { mmrIndex: bigint; idtimestamp: bigint },
+): { ok: true } | { ok: false; reason: "delegation_expired"; at: number } {
+  const leafSeconds = idtimestampToUnixSeconds(leaf.idtimestamp);
+  for (const r of records) {
+    if (r.constraints === null) continue;
+    if (r.signedSize > leaf.mmrIndex && leafSeconds > r.constraints.expiresAt) {
+      return { ok: false, reason: "delegation_expired", at: r.index };
+    }
+  }
+  return { ok: true };
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/decode-trust-root-cbor.ts

@@ -44,7 +44,16 @@ function parseAlgInt(raw: unknown): number | null {
   return null;
 }
 
-function ks256RootFromAddress(address: Uint8Array): ParsedKs256RootKey {
+/**
+ * Wrap a 20-byte KS256 root address as a {@link ParsedKs256RootKey}.
+ *
+ * @throws When `address` is not 20 bytes: a key of any other length would
+ *   fail {@link isParsedKs256RootKey} and be mistaken for an ES256 key.
+ */
+export function ks256RootFromAddress(address: Uint8Array): ParsedKs256RootKey {
+  if (address.length !== 20) {
+    throw new Error("KS256 root address must be 20 bytes");
+  }
   return { kind: "KS256", alg: COSE_ALG_KS256, address };
 }
 

package/src/inclusion-walk-end.ts

@@ -0,0 +1,38 @@
+/**
+ * Where an MMR inclusion walk ends. A leaf hash
+ * (`SHA-256(idtimestamp ‖ inner)`) does not commit the leaf's position, and
+ * a path of length 0 commits nothing more, so matching a recomputed peak by
+ * VALUE alone leaves the receipt's claimed `mmrIndex` unbound. Requiring the
+ * matched accumulator peak to sit at the node index the walk reaches binds
+ * it: interior nodes commit their position (`H(pos ‖ left ‖ right)`), and
+ * an empty path must start at the peak itself.
+ *
+ * Mirrors the position arithmetic of `calculateRoot` in
+ * [@forestrie/merklelog](https://github.com/forestrie/canopy/blob/main/packages/merklelog/src/mmr/algorithms.ts)
+ * (go-merklelog `mmr/proof.go`), without hashing.
+ */
+import { indexHeight } from "@forestrie/merklelog";
+
+/**
+ * The zero-based MMR index of the node an inclusion path of `pathLength`
+ * siblings reaches from `leafMmrIndex`: the peak the path claims to prove.
+ */
+export function inclusionWalkEndIndex(
+  leafMmrIndex: bigint,
+  pathLength: number,
+): bigint {
+  let height = indexHeight(leafMmrIndex);
+  // 1-based position, as calculateRoot tracks it.
+  let pos = leafMmrIndex + 1n;
+  for (let i = 0; i < pathLength; i++) {
+    // `indexHeight(pos)` is the height of the node AFTER the current one:
+    // higher means the current node is a right child.
+    if (indexHeight(pos) > height) {
+      pos += 1n;
+    } else {
+      pos += 2n << BigInt(height);
+    }
+    height += 1;
+  }
+  return pos - 1n;
+}