@correntelabs/beeai-ashlar-bridge 1.0.0

package/dist/src/x402/manifest-sig.d.ts

@@ -0,0 +1,163 @@
+/**
+ * x402sig1 — detached Ed25519 signature over the discovery manifest.
+ *
+ * Mirrors Martin Sansone's x402-signed-manifest-ref 1.1.0 construction
+ * EXACTLY — Ed25519 over the RFC 8785 (JCS) canonical bytes DIRECTLY,
+ * not over a prehash — because the verifiers that exist today
+ * (Melchiorre's daily sweep, Martin's kit, our own magentix verify
+ * scripts) all check that shape, and the point of signing is to be
+ * counted by checkers we did not write. Field set matches his current
+ * examples/well-known/x402.sig: v, canon, sig_input, alg, kid, sig,
+ * content_digest, signedAt. `kid` is the FULL DNS name of the key
+ * record (DKIM-selector style, e.g. s1._x402key.api.flareclaw.app),
+ * so a verifier never guesses the lookup name.
+ *
+ * Extension over the reference: our manifest is LIVE-TRUTH — the
+ * attestation block and freshness staple re-derive per request, so a
+ * static committed .sig would go stale on the next staple rotation
+ * (≤15 min). We therefore sign PER-SERVE: the .sig route builds the
+ * same manifest body the main route would serve right now and signs
+ * those bytes. The two fetches can still straddle a rotation; the
+ * digest-agreement rule (report signature-invalid ONLY when the
+ * verifier's own canonical sha256 of the manifest it fetched equals
+ * this .sig's content_digest, otherwise undetermined) is what keeps
+ * that race sound — content_digest says exactly which bytes were
+ * signed.
+ *
+ * The signer is a MANIFEST IDENTITY: it holds no funds and can move no
+ * money. Compromise of it can forge discovery manifests and nothing
+ * else — same class as the receipt identity in job-receipt.ts, which
+ * is why sign() is injected and this module never touches a key, a
+ * network, or the clock.
+ */
+import { Buffer } from 'node:buffer';
+export declare const MANIFEST_SIG_VERSION = "x402sig1";
+/** DKIM-style selector — the label the DNS TXT key record lives under. */
+export declare const MANIFEST_SIG_SELECTOR = "s1";
+export interface ManifestSig {
+    v: typeof MANIFEST_SIG_VERSION;
+    canon: 'RFC8785-JCS';
+    sig_input: 'canonical-bytes';
+    alg: 'Ed25519';
+    /** Full DNS name of the TXT record carrying the verifying key. */
+    kid: string;
+    /** base64url Ed25519 signature over the canonical bytes. */
+    sig: string;
+    content_digest: {
+        alg: 'SHA-256';
+        value: string;
+    };
+    signedAt: string;
+}
+/**
+ * Guard before claiming JCS parity: our jcs() below implements the
+ * subset RFC 8785 needs for JSON built from strings, booleans, null,
+ * safe integers, arrays and plain objects. Full ES6 number formatting
+ * (fractions, exponents) is deliberately NOT implemented — a manifest
+ * that needs it must not be signed with this module, loudly.
+ */
+export declare function assertJcsSafe(v: unknown): void;
+/** RFC 8785 JCS canonical form (subset guarded by assertJcsSafe). */
+export declare function jcsCanonical(v: unknown): string;
+/** The DNS name a manifest served for `host` binds its key to. */
+export declare function manifestSigKid(host: string): string;
+export interface BuildManifestSigInput {
+    manifest: unknown;
+    kid: string;
+    /** base64url Ed25519 signature over the given canonical bytes. */
+    sign: (canonicalBytes: Buffer) => string;
+    now: () => number;
+}
+export declare function buildManifestSig({ manifest, kid, sign, now }: BuildManifestSigInput): ManifestSig;
+/**
+ * Independent check of a ManifestSig against a raw base64url Ed25519
+ * public key (the exact string a verifier reads out of the DNS TXT
+ * record's k= tag). Returns the digest-agreement verdict a sweep
+ * should report: 'authentic' | 'signature-invalid' | 'undetermined'.
+ * 'undetermined' means the manifest bytes in hand are not the bytes
+ * the .sig commits to (the per-serve race, or a tampered pairing) —
+ * per Melchiorre's rule that is NOT an accusation of a bad signature.
+ *
+ * MS3 (Melchiorre's digest-agreement rule): `signature-invalid` is
+ * reported ONLY when the verifier's own canonical sha256 equals the
+ * artifact's content_digest, i.e. only once both sides have PROVEN
+ * their canonicalizations agreed. Everything else is undetermined and
+ * the verifier's own to sort out — you do not point at a named company
+ * on evidence that your JCS and theirs disagreed.
+ */
+export declare function verifyManifestSig(manifest: unknown, sig: ManifestSig, publicKeyB64url: string): 'authentic' | 'signature-invalid' | 'undetermined';
+/**
+ * The closed verdict vocabulary a signature sweep reports. Five values,
+ * not three, because two of them exist to stop a harness blaming a host
+ * for something that is not the host's signing:
+ *
+ *   authentic         key at `kid` verifies the canonical bytes
+ *   signature-invalid  digests AGREED and Ed25519 still failed  (MS3)
+ *   undetermined       the bytes in hand are not the bytes signed (MS3),
+ *                      or no key could be read at `kid`
+ *   not-a-signature    the .sig path answered with something carrying no
+ *                      `sig`/`kid` — no signing was attempted at all (MS4)
+ *   unsigned           nothing served at the .sig path
+ *
+ * MS3 and MS4 are MELCHIORRE'S RULES, contributed from his daily sweep
+ * (#domain-discovery, 2026-08-12) and folded in here under his name.
+ * See conformance/x402-manifest-sig/ for the vector set that tests them.
+ */
+export type ManifestSigVerdict = 'authentic' | 'signature-invalid' | 'undetermined' | 'not-a-signature' | 'unsigned';
+export type SigArtifact = {
+    kind: 'signature';
+    sig: ManifestSig;
+} | {
+    kind: 'not-a-signature';
+    reason: string;
+};
+/**
+ * MS4 — Melchiorre's rule: a 200 at the `.sig` path is not a signature.
+ *
+ * Catch-all routing (an SPA fallback, a friendly JSON 404 body, a CDN
+ * error page served with status 200) manufactures PHANTOM SIGNING
+ * ATTEMPTS: the sweep reads a body, fails to verify it, and records the
+ * host as having signed badly. He hit exactly this and had to correct
+ * two named hosts. The artifact must carry `sig` AND `kid` before it
+ * counts as an attempt at all — the same failure shape as a soft 404,
+ * one layer up.
+ *
+ * Deliberately runs BEFORE the suite check (MS1): "is this a signature?"
+ * is a different question from "is this a suite I know?", and answering
+ * them in the wrong order is what produces the phantom attempt. The
+ * ordering is asserted by test.
+ */
+export declare function classifySigArtifact(body: unknown): SigArtifact;
+/**
+ * The verdict a signature sweep should publish for one host, applying
+ * MS3 and MS4 in the order that keeps both honest.
+ *
+ * `sigBody` is whatever the `.sig` path returned parsed as JSON, or
+ * `undefined` when the path served nothing (404, connection refused).
+ * `publicKeyB64url` is the key read from DNS at `sig.kid`, or
+ * `undefined` when no key could be read — which is `undetermined`, not
+ * a bad signature: an unreadable key is a fact about the lookup.
+ */
+export declare function sweepManifestSig(input: {
+    manifest: unknown;
+    sigBody: unknown | undefined;
+    publicKeyB64url: string | undefined;
+}): {
+    verdict: ManifestSigVerdict;
+    rule: string;
+    reason: string;
+};
+export interface Ed25519Signer {
+    /** base64url signature over the given bytes. */
+    sign: (bytes: Buffer) => string;
+    /** Raw 32-byte public key, base64url — the DNS TXT k= value. */
+    publicKeyB64url: string;
+}
+/**
+ * Build a signer from a base64url 32-byte Ed25519 seed (the secret's
+ * stored form). The key object never leaves this closure; callers get
+ * a sign function and the PUBLIC key only.
+ */
+export declare function ed25519SignerFromSeed(seedB64url: string): Ed25519Signer;
+/** The TXT record value verifiers parse (Martin's records.txt format). */
+export declare function manifestSigTxtValue(publicKeyB64url: string): string;

package/dist/src/x402/manifest-sig.js

@@ -0,0 +1,259 @@
+/**
+ * x402sig1 — detached Ed25519 signature over the discovery manifest.
+ *
+ * Mirrors Martin Sansone's x402-signed-manifest-ref 1.1.0 construction
+ * EXACTLY — Ed25519 over the RFC 8785 (JCS) canonical bytes DIRECTLY,
+ * not over a prehash — because the verifiers that exist today
+ * (Melchiorre's daily sweep, Martin's kit, our own magentix verify
+ * scripts) all check that shape, and the point of signing is to be
+ * counted by checkers we did not write. Field set matches his current
+ * examples/well-known/x402.sig: v, canon, sig_input, alg, kid, sig,
+ * content_digest, signedAt. `kid` is the FULL DNS name of the key
+ * record (DKIM-selector style, e.g. s1._x402key.api.flareclaw.app),
+ * so a verifier never guesses the lookup name.
+ *
+ * Extension over the reference: our manifest is LIVE-TRUTH — the
+ * attestation block and freshness staple re-derive per request, so a
+ * static committed .sig would go stale on the next staple rotation
+ * (≤15 min). We therefore sign PER-SERVE: the .sig route builds the
+ * same manifest body the main route would serve right now and signs
+ * those bytes. The two fetches can still straddle a rotation; the
+ * digest-agreement rule (report signature-invalid ONLY when the
+ * verifier's own canonical sha256 of the manifest it fetched equals
+ * this .sig's content_digest, otherwise undetermined) is what keeps
+ * that race sound — content_digest says exactly which bytes were
+ * signed.
+ *
+ * The signer is a MANIFEST IDENTITY: it holds no funds and can move no
+ * money. Compromise of it can forge discovery manifests and nothing
+ * else — same class as the receipt identity in job-receipt.ts, which
+ * is why sign() is injected and this module never touches a key, a
+ * network, or the clock.
+ */
+import { Buffer } from 'node:buffer';
+import { createHash, createPublicKey, createPrivateKey, sign as edSign, verify as edVerify } from 'node:crypto';
+export const MANIFEST_SIG_VERSION = 'x402sig1';
+/** DKIM-style selector — the label the DNS TXT key record lives under. */
+export const MANIFEST_SIG_SELECTOR = 's1';
+/**
+ * Guard before claiming JCS parity: our jcs() below implements the
+ * subset RFC 8785 needs for JSON built from strings, booleans, null,
+ * safe integers, arrays and plain objects. Full ES6 number formatting
+ * (fractions, exponents) is deliberately NOT implemented — a manifest
+ * that needs it must not be signed with this module, loudly.
+ */
+export function assertJcsSafe(v) {
+    if (typeof v === 'string') {
+        // A lone (unpaired) surrogate serializes differently across JCS
+        // implementations — Node's JSON.stringify escapes it, some strict JCS
+        // libraries reject or pass it through — so two honest verifiers can
+        // compute DIFFERENT digests over the same logical value. Where the
+        // string is attacker-influenced (a census detail/record derived from a
+        // remote host response) that is a cross-implementation digest-
+        // disagreement, so reject non-well-formed strings up front.
+        if (typeof v.isWellFormed === 'function'
+            && !v.isWellFormed()) {
+            throw new Error('unsignable string: contains unpaired surrogate (not well-formed UTF-16)');
+        }
+        return;
+    }
+    if (v === null || typeof v === 'boolean')
+        return;
+    if (typeof v === 'number') {
+        if (!Number.isInteger(v) || Math.abs(v) > 2 ** 52) {
+            throw new Error(`non-trivial number ${v}: full JCS ES6 formatting required`);
+        }
+        return;
+    }
+    if (typeof v !== 'object')
+        throw new Error(`unsignable value of type ${typeof v}`);
+    if (Array.isArray(v)) {
+        v.forEach(assertJcsSafe);
+        return;
+    }
+    Object.values(v).forEach(assertJcsSafe);
+}
+/** RFC 8785 JCS canonical form (subset guarded by assertJcsSafe). */
+export function jcsCanonical(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(jcsCanonical).join(',')}]`;
+    return `{${Object.keys(v).sort()
+        .map(k => `${JSON.stringify(k)}:${jcsCanonical(v[k])}`)
+        .join(',')}}`;
+}
+/** The DNS name a manifest served for `host` binds its key to. */
+export function manifestSigKid(host) {
+    return `${MANIFEST_SIG_SELECTOR}._x402key.${host}`;
+}
+export function buildManifestSig({ manifest, kid, sign, now }) {
+    assertJcsSafe(manifest);
+    const bytes = Buffer.from(jcsCanonical(manifest), 'utf8');
+    return {
+        v: MANIFEST_SIG_VERSION,
+        canon: 'RFC8785-JCS',
+        sig_input: 'canonical-bytes',
+        alg: 'Ed25519',
+        kid,
+        sig: sign(bytes),
+        content_digest: {
+            alg: 'SHA-256',
+            value: createHash('sha256').update(bytes).digest('hex'),
+        },
+        signedAt: new Date(now()).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    };
+}
+/**
+ * Independent check of a ManifestSig against a raw base64url Ed25519
+ * public key (the exact string a verifier reads out of the DNS TXT
+ * record's k= tag). Returns the digest-agreement verdict a sweep
+ * should report: 'authentic' | 'signature-invalid' | 'undetermined'.
+ * 'undetermined' means the manifest bytes in hand are not the bytes
+ * the .sig commits to (the per-serve race, or a tampered pairing) —
+ * per Melchiorre's rule that is NOT an accusation of a bad signature.
+ *
+ * MS3 (Melchiorre's digest-agreement rule): `signature-invalid` is
+ * reported ONLY when the verifier's own canonical sha256 equals the
+ * artifact's content_digest, i.e. only once both sides have PROVEN
+ * their canonicalizations agreed. Everything else is undetermined and
+ * the verifier's own to sort out — you do not point at a named company
+ * on evidence that your JCS and theirs disagreed.
+ */
+export function verifyManifestSig(manifest, sig, publicKeyB64url) {
+    if (sig.v !== MANIFEST_SIG_VERSION || sig.canon !== 'RFC8785-JCS'
+        || sig.sig_input !== 'canonical-bytes' || sig.alg !== 'Ed25519') {
+        throw new Error('unexpected suite — refusing to guess at an unknown construction');
+    }
+    assertJcsSafe(manifest);
+    const bytes = Buffer.from(jcsCanonical(manifest), 'utf8');
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== sig.content_digest.value)
+        return 'undetermined';
+    const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKeyB64url }, format: 'jwk' });
+    return edVerify(null, bytes, key, Buffer.from(sig.sig, 'base64url'))
+        ? 'authentic' : 'signature-invalid';
+}
+/**
+ * MS4 — Melchiorre's rule: a 200 at the `.sig` path is not a signature.
+ *
+ * Catch-all routing (an SPA fallback, a friendly JSON 404 body, a CDN
+ * error page served with status 200) manufactures PHANTOM SIGNING
+ * ATTEMPTS: the sweep reads a body, fails to verify it, and records the
+ * host as having signed badly. He hit exactly this and had to correct
+ * two named hosts. The artifact must carry `sig` AND `kid` before it
+ * counts as an attempt at all — the same failure shape as a soft 404,
+ * one layer up.
+ *
+ * Deliberately runs BEFORE the suite check (MS1): "is this a signature?"
+ * is a different question from "is this a suite I know?", and answering
+ * them in the wrong order is what produces the phantom attempt. The
+ * ordering is asserted by test.
+ */
+export function classifySigArtifact(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return { kind: 'not-a-signature', reason: `.sig body is ${Array.isArray(body) ? 'an array' : typeof body}, not a JSON object` };
+    }
+    const b = body;
+    const missing = ['sig', 'kid'].filter((f) => typeof b[f] !== 'string' || b[f].length === 0);
+    if (missing.length > 0) {
+        return { kind: 'not-a-signature', reason: `.sig body carries no ${missing.join(' and no ')} — nothing was signed here` };
+    }
+    return { kind: 'signature', sig: body };
+}
+/**
+ * The verdict a signature sweep should publish for one host, applying
+ * MS3 and MS4 in the order that keeps both honest.
+ *
+ * `sigBody` is whatever the `.sig` path returned parsed as JSON, or
+ * `undefined` when the path served nothing (404, connection refused).
+ * `publicKeyB64url` is the key read from DNS at `sig.kid`, or
+ * `undefined` when no key could be read — which is `undetermined`, not
+ * a bad signature: an unreadable key is a fact about the lookup.
+ */
+export function sweepManifestSig(input) {
+    if (input.sigBody === undefined) {
+        return { verdict: 'unsigned', rule: 'MS6', reason: 'nothing served at the .sig path' };
+    }
+    const artifact = classifySigArtifact(input.sigBody);
+    if (artifact.kind === 'not-a-signature') {
+        return { verdict: 'not-a-signature', rule: 'MS4', reason: artifact.reason };
+    }
+    const sig = artifact.sig;
+    // MS1 — an unknown suite is refused, never guessed at, and refusing
+    // is not an accusation: we cannot check what we cannot parse. Runs
+    // before the key lookup so the rule attribution matches the
+    // standalone checker in conformance/x402-manifest-sig/verify.mjs on
+    // EVERY input, not just the ones in the vector set — the two are
+    // published as one answer and a reader must not be able to make
+    // them disagree.
+    const suite = {
+        v: MANIFEST_SIG_VERSION, canon: 'RFC8785-JCS',
+        sig_input: 'canonical-bytes', alg: 'Ed25519',
+    };
+    for (const [k, want] of Object.entries(suite)) {
+        if (sig[k] !== want) {
+            return {
+                verdict: 'undetermined', rule: 'MS1',
+                reason: `unexpected ${k}=${JSON.stringify(sig[k] ?? null)} (want ${JSON.stringify(want)}) — refusing to guess at an unknown construction`,
+            };
+        }
+    }
+    if (input.publicKeyB64url === undefined) {
+        return { verdict: 'undetermined', rule: 'MS5', reason: `no verifying key readable at ${artifact.sig.kid}` };
+    }
+    let bytes;
+    try {
+        assertJcsSafe(input.manifest);
+        bytes = Buffer.from(jcsCanonical(input.manifest), 'utf8');
+    }
+    catch (e) {
+        return { verdict: 'undetermined', rule: 'MS1', reason: e.message };
+    }
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== artifact.sig.content_digest?.value) {
+        return {
+            verdict: 'undetermined', rule: 'MS3',
+            reason: 'canonical digest of the manifest in hand differs from the .sig content_digest — these are not the bytes that were signed',
+        };
+    }
+    let ok;
+    try {
+        const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: input.publicKeyB64url }, format: 'jwk' });
+        ok = edVerify(null, bytes, key, Buffer.from(artifact.sig.sig, 'base64url'));
+    }
+    catch (e) {
+        return { verdict: 'undetermined', rule: 'MS5', reason: `unusable key material at ${artifact.sig.kid}: ${e.message}` };
+    }
+    return ok
+        ? { verdict: 'authentic', rule: 'MS2', reason: 'key at kid verifies the canonical bytes' }
+        : { verdict: 'signature-invalid', rule: 'MS3', reason: 'digests agreed and Ed25519 verification still failed' };
+}
+/** PKCS#8 DER prefix for a raw 32-byte Ed25519 seed (RFC 8410 shape). */
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+/**
+ * Build a signer from a base64url 32-byte Ed25519 seed (the secret's
+ * stored form). The key object never leaves this closure; callers get
+ * a sign function and the PUBLIC key only.
+ */
+export function ed25519SignerFromSeed(seedB64url) {
+    const seed = Buffer.from(seedB64url.trim(), 'base64url');
+    if (seed.length !== 32)
+        throw new Error(`manifest signing seed must be 32 bytes, got ${seed.length}`);
+    const privateKey = createPrivateKey({
+        key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
+        format: 'der',
+        type: 'pkcs8',
+    });
+    const jwk = createPublicKey(privateKey).export({ format: 'jwk' });
+    if (!jwk.x)
+        throw new Error('failed to derive public key from seed');
+    return {
+        sign: (bytes) => edSign(null, bytes, privateKey).toString('base64url'),
+        publicKeyB64url: jwk.x,
+    };
+}
+/** The TXT record value verifiers parse (Martin's records.txt format). */
+export function manifestSigTxtValue(publicKeyB64url) {
+    return `v=x402key1; alg=Ed25519; k=${publicKeyB64url}`;
+}

package/dist/src/x402/merkle-transcript.d.ts

@@ -0,0 +1,73 @@
+/**
+ * merkle-transcript — RFC 6962 Merkle commitments over a room's draw
+ * transcript, so one draw can be proven without revealing the rest.
+ *
+ * WHY. A room's signed summary currently commits to its transcript FLAT:
+ * sha256(JCS(all nonces)) and sha256(JCS(all seeds)). To prove that a single
+ * draw was in the session you must therefore disclose EVERY draw. For a tenant
+ * showing a third party "draw 7 happened, here is its seed", that is a
+ * full-transcript disclosure to establish one fact.
+ *
+ * A Merkle root replaces that with an inclusion proof of ceil(log2(n)) hashes
+ * that reveals nothing else, while the summary still commits to exactly one
+ * value the enclave signs.
+ *
+ * WHY RFC 6962 RATHER THAN A TREE OF OUR OWN. Certificate Transparency's
+ * Merkle Tree Hash is the transparency-log precedent this audience already
+ * implements, it has published test vectors, and its two hardest details are
+ * already decided in a way that has survived a decade of attack:
+ *
+ *   - DOMAIN SEPARATION. Leaves are hashed with a 0x00 prefix and interior
+ *     nodes with 0x01. Without it an interior node's preimage can be presented
+ *     as a leaf, so a proof for a value that was never in the tree verifies.
+ *   - ODD NODES ARE PROMOTED, NEVER DUPLICATED. The split is at the largest
+ *     power of two BELOW n, so a lone right-hand node carries up unchanged.
+ *     Duplicating it instead is CVE-2012-2459: two distinct transcripts
+ *     collapse to the same root, and a verifier cannot tell which it was
+ *     shown.
+ *
+ * Both are exactly the class of underdetermined value that gets a profile
+ * picked apart in review, so both are pinned by tests below rather than left
+ * to the reader.
+ *
+ * LEAF CONTENT. A leaf commits to {drawId, nonce, seed} in JCS canonical form.
+ * drawId is included deliberately: it is the payment-intent identity, and a
+ * transcript whose leaves omit it cannot distinguish two draws that differ
+ * only by intent — the same gap Tiago Pinto found in the SCITT draft's
+ * execution digest (W3, 2026-08-18), where two distinct payments produced
+ * identical digest inputs.
+ */
+import { Buffer } from 'node:buffer';
+export declare const MERKLE_PROFILE = "x402room-transcript-merkle/1";
+/** RFC 6962 §2.1: MTH({}) = SHA-256 of the empty string. */
+export declare const EMPTY_ROOT: string;
+/** One transcript entry. drawId is part of the commitment, not metadata. */
+export interface TranscriptEntry {
+    drawId: string;
+    nonce: string;
+    seed: string;
+}
+/** RFC 6962 leaf hash: SHA-256(0x00 || entry). */
+export declare function leafHash(entry: TranscriptEntry): Buffer;
+/** RFC 6962 interior hash: SHA-256(0x01 || left || right). */
+export declare function nodeHash(left: Buffer, right: Buffer): Buffer;
+/** The transcript root a signed summary commits to. */
+export declare function transcriptRoot(entries: TranscriptEntry[]): string;
+/**
+ * Merkle Tree Hash over ALREADY-hashed leaves — exposed so the RFC 6962
+ * published vectors can be run through the MODULE's own tree (splitPoint + mth),
+ * not a test-local lookalike. A regression in splitPoint would otherwise pass a
+ * vector suite that only exercises a copy. (Crypto review M1.)
+ */
+export declare function mthOfLeafHashes(leafHashes: Buffer[]): string;
+/**
+ * Inclusion proof for entry `index` — the sibling hashes needed to recompute
+ * the root, bottom-up. RFC 6962 §2.1.1 PATH(m, D[n]).
+ */
+export declare function inclusionProof(entries: TranscriptEntry[], index: number): string[];
+/**
+ * Verify one entry against a root WITHOUT the rest of the transcript. This is
+ * the whole point: the verifier holds the entry, the proof, its index, the
+ * transcript size, and the signed root — and nothing else.
+ */
+export declare function verifyInclusion(entry: TranscriptEntry, index: number, size: number, proof: string[], root: string): boolean;

package/dist/src/x402/merkle-transcript.js

@@ -0,0 +1,159 @@
+/**
+ * merkle-transcript — RFC 6962 Merkle commitments over a room's draw
+ * transcript, so one draw can be proven without revealing the rest.
+ *
+ * WHY. A room's signed summary currently commits to its transcript FLAT:
+ * sha256(JCS(all nonces)) and sha256(JCS(all seeds)). To prove that a single
+ * draw was in the session you must therefore disclose EVERY draw. For a tenant
+ * showing a third party "draw 7 happened, here is its seed", that is a
+ * full-transcript disclosure to establish one fact.
+ *
+ * A Merkle root replaces that with an inclusion proof of ceil(log2(n)) hashes
+ * that reveals nothing else, while the summary still commits to exactly one
+ * value the enclave signs.
+ *
+ * WHY RFC 6962 RATHER THAN A TREE OF OUR OWN. Certificate Transparency's
+ * Merkle Tree Hash is the transparency-log precedent this audience already
+ * implements, it has published test vectors, and its two hardest details are
+ * already decided in a way that has survived a decade of attack:
+ *
+ *   - DOMAIN SEPARATION. Leaves are hashed with a 0x00 prefix and interior
+ *     nodes with 0x01. Without it an interior node's preimage can be presented
+ *     as a leaf, so a proof for a value that was never in the tree verifies.
+ *   - ODD NODES ARE PROMOTED, NEVER DUPLICATED. The split is at the largest
+ *     power of two BELOW n, so a lone right-hand node carries up unchanged.
+ *     Duplicating it instead is CVE-2012-2459: two distinct transcripts
+ *     collapse to the same root, and a verifier cannot tell which it was
+ *     shown.
+ *
+ * Both are exactly the class of underdetermined value that gets a profile
+ * picked apart in review, so both are pinned by tests below rather than left
+ * to the reader.
+ *
+ * LEAF CONTENT. A leaf commits to {drawId, nonce, seed} in JCS canonical form.
+ * drawId is included deliberately: it is the payment-intent identity, and a
+ * transcript whose leaves omit it cannot distinguish two draws that differ
+ * only by intent — the same gap Tiago Pinto found in the SCITT draft's
+ * execution digest (W3, 2026-08-18), where two distinct payments produced
+ * identical digest inputs.
+ */
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { jcsCanonical, assertJcsSafe } from './manifest-sig.js';
+export const MERKLE_PROFILE = 'x402room-transcript-merkle/1';
+const sha256 = (b) => createHash('sha256').update(b).digest();
+/** RFC 6962 §2.1: MTH({}) = SHA-256 of the empty string. */
+export const EMPTY_ROOT = sha256(Buffer.alloc(0)).toString('hex');
+/** RFC 6962 leaf hash: SHA-256(0x00 || entry). */
+export function leafHash(entry) {
+    const canonical = { drawId: entry.drawId, nonce: entry.nonce, seed: entry.seed };
+    assertJcsSafe(canonical);
+    return sha256(Buffer.concat([Buffer.from([0x00]), Buffer.from(jcsCanonical(canonical), 'utf8')]));
+}
+/** RFC 6962 interior hash: SHA-256(0x01 || left || right). */
+export function nodeHash(left, right) {
+    return sha256(Buffer.concat([Buffer.from([0x01]), left, right]));
+}
+/** Largest power of two STRICTLY less than n — RFC 6962's split point. */
+function splitPoint(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+/** Merkle Tree Hash over leaf hashes (RFC 6962 §2.1). */
+function mth(leaves) {
+    if (leaves.length === 0)
+        return sha256(Buffer.alloc(0));
+    if (leaves.length === 1)
+        return leaves[0];
+    const k = splitPoint(leaves.length);
+    return nodeHash(mth(leaves.slice(0, k)), mth(leaves.slice(k)));
+}
+/** The transcript root a signed summary commits to. */
+export function transcriptRoot(entries) {
+    return mth(entries.map(leafHash)).toString('hex');
+}
+/**
+ * Merkle Tree Hash over ALREADY-hashed leaves — exposed so the RFC 6962
+ * published vectors can be run through the MODULE's own tree (splitPoint + mth),
+ * not a test-local lookalike. A regression in splitPoint would otherwise pass a
+ * vector suite that only exercises a copy. (Crypto review M1.)
+ */
+export function mthOfLeafHashes(leafHashes) {
+    return mth(leafHashes).toString('hex');
+}
+/**
+ * Inclusion proof for entry `index` — the sibling hashes needed to recompute
+ * the root, bottom-up. RFC 6962 §2.1.1 PATH(m, D[n]).
+ */
+export function inclusionProof(entries, index) {
+    if (index < 0 || index >= entries.length)
+        throw new Error(`index ${index} outside transcript of ${entries.length}`);
+    const path = [];
+    // RFC 6962 §2.1.1 appends the sibling AFTER the recursive call:
+    //   PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n])
+    // so the path is ordered BOTTOM-UP, deepest sibling first — which is the
+    // order verification consumes it in. Pushing the sibling before recursing
+    // yields a top-down path that verifies for no tree at all.
+    const walk = (leaves, m) => {
+        if (leaves.length <= 1)
+            return;
+        const k = splitPoint(leaves.length);
+        if (m < k) {
+            walk(leaves.slice(0, k), m);
+            path.push(mth(leaves.slice(k)));
+        }
+        else {
+            walk(leaves.slice(k), m - k);
+            path.push(mth(leaves.slice(0, k)));
+        }
+    };
+    walk(entries.map(leafHash), index);
+    return path.map((b) => b.toString('hex'));
+}
+/**
+ * Verify one entry against a root WITHOUT the rest of the transcript. This is
+ * the whole point: the verifier holds the entry, the proof, its index, the
+ * transcript size, and the signed root — and nothing else.
+ */
+export function verifyInclusion(entry, index, size, proof, root) {
+    if (index < 0 || index >= size)
+        return false;
+    // RFC 6962 §2.1.1's OWN verification algorithm. An earlier version
+    // re-split the tree top-down while consuming a bottom-up path, which
+    // verifies for no tree at all: RFC 6962 trees are LEFT-FULL, not balanced,
+    // so a node's side at each level is not recoverable by halving an index.
+    // fn/sn track the leaf's index and the last index at each level, and it is
+    // their parity — not arithmetic on the size — that says which side we are.
+    let fn = index, sn = size - 1;
+    let r = leafHash(entry);
+    for (const p of proof) {
+        // Canonical 64-lowercase-hex only. Buffer.from('hex') silently
+        // truncates at the first invalid pair, so a 65-char string or 64 hex
+        // chars followed by garbage would still decode to 32 bytes and verify —
+        // proof-string malleability. (Crypto review M2.)
+        if (!/^[0-9a-f]{64}$/.test(p))
+            return false;
+        const sibling = Buffer.from(p, 'hex');
+        if (sibling.length !== 32)
+            return false;
+        if (sn === 0)
+            return false; // path longer than the tree
+        if (fn % 2 === 1 || fn === sn) {
+            r = nodeHash(sibling, r);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn >>= 1;
+                sn >>= 1;
+            }
+        }
+        else {
+            r = nodeHash(r, sibling);
+        }
+        fn >>= 1;
+        sn >>= 1;
+    }
+    // sn must be exhausted: a SHORT path leaves tree levels unaccounted for,
+    // and a padded one is rejected above by running out of levels first.
+    return sn === 0 && r.toString('hex') === root;
+}