@oxy.so/protocol 1.0.0

package/dist/esm/platform/crypto.native.js

@@ -0,0 +1,196 @@
+/**
+ * Platform Crypto / Storage — React Native Variant
+ *
+ * Companion to `./crypto.ts`. See the doc-comment at the top of that file for
+ * the full design.
+ *
+ * Metro auto-selects this file in any non-web build (`preferNativePlatform`
+ * is `true` for iOS / Android, so `*.native.js` shadows `*.js` during
+ * source-extension resolution inside `node_modules/@oxy.so/protocol/dist/`). On
+ * iOS / Android `<base>.ios.js` / `<base>.android.js` would shadow this file
+ * if they existed, but they don't — `.native.js` is the shared RN variant.
+ *
+ *   - The default variant references Node's `'crypto'` and would crash Metro
+ *     if bundled into an RN app.
+ *   - This variant references the RN-only modules (`expo-crypto`,
+ *     `expo-secure-store`, `@react-native-async-storage/async-storage`),
+ *     each behind Metro's optional-dependency mechanism (see below).
+ *
+ * Both variants expose the same surface; importers don't care which one
+ * they got.
+ *
+ * # Why `try { require('literal') } catch` and not a static import?
+ *
+ * Those three RN modules are declared OPTIONAL peer dependencies in
+ * `package.json`. A static `import` contradicts that: an optional peer that is
+ * omitted does not degrade, it fails to RESOLVE, and Metro aborts the whole
+ * bundle. Because `@oxy.so/core`'s `crypto/polyfill` imports `@oxy.so/protocol`
+ * from its root entry, this file is in the eager graph of EVERY React Native
+ * app on `@oxy.so/core` — so a single undeclared optional peer broke the native
+ * bundle of every app that did not happen to install it, with a resolution
+ * error pointing at a dependency the app never mentions.
+ *
+ * Metro treats a `require()` of a STRING LITERAL that sits inside a `try`
+ * block as an optional dependency: it resolves it when present, and when
+ * absent emits a stub that throws on evaluation instead of failing the build.
+ * The `catch` turns that into a `null` module handle, and the loader below
+ * throws an actionable error naming the missing package the first time the
+ * capability is actually used. Bundle-time hard failure becomes a
+ * capability-scoped runtime failure — which is exactly what "optional peer"
+ * is supposed to mean.
+ *
+ * Two constraints this shape has to respect, both learned the hard way:
+ *
+ *   - The specifier MUST be a literal. A runtime-computed `require(variable)`
+ *     is unresolvable for Metro (that is the bug the shared-identity bridge
+ *     below documents) and silently yields nothing in a consuming repo.
+ *   - The load MUST stay synchronous. `getRandomBytesRN` backs
+ *     `globalThis.crypto.getRandomValues` in `@oxy.so/core`'s polyfill, which
+ *     cannot await anything.
+ *
+ * `expo-modules-core` is a NON-optional peer (every RN app has it via `expo`),
+ * so it stays a plain static import.
+ */
+import { requireOptionalNativeModule } from 'expo-modules-core';
+let expoCryptoModule = null;
+let expoCryptoError;
+try {
+    expoCryptoModule = require('expo-crypto');
+}
+catch (error) {
+    expoCryptoError = error;
+}
+let secureStoreModule = null;
+let secureStoreError;
+try {
+    secureStoreModule = require('expo-secure-store');
+}
+catch (error) {
+    secureStoreError = error;
+}
+let asyncStorageModule = null;
+let asyncStorageError;
+try {
+    // Babel's default-import interop unwraps `.default` for us on a static
+    // import; a raw `require` has to do it by hand. The `?? namespace` fallback
+    // covers a host that hands back a real ESM namespace with no `default`.
+    const namespace = require('@react-native-async-storage/async-storage');
+    asyncStorageModule = namespace.default ?? namespace;
+}
+catch (error) {
+    asyncStorageError = error;
+}
+/**
+ * Actionable error for a missing optional peer. Carries the underlying Metro
+ * resolution message so the failure is never silent — the `catch` above only
+ * defers the report to the point where the capability is actually needed.
+ */
+function missingOptionalPeerError(packageName, capability, cause) {
+    const sentences = [
+        `[oxy.protocol.crypto] '${packageName}' is not installed, so ${capability} is unavailable in this app.`,
+        'It is an optional peer dependency of @oxy.so/protocol that the React Native runtime needs —',
+        `install it with \`npx expo install ${packageName}\`.`,
+    ];
+    if (cause instanceof Error) {
+        sentences.push(`Underlying error: ${cause.message}`);
+    }
+    return new Error(sentences.join(' '));
+}
+// ---------------------------------------------------------------------------
+// Node `crypto` — never available in RN.
+// ---------------------------------------------------------------------------
+export async function loadNodeCrypto() {
+    // Unreachable in practice: every caller gates with `isNodeJS()` before
+    // invoking this. If it somehow does fire, throw immediately with a clear
+    // diagnostic rather than letting Metro / Hermes attempt to find a
+    // non-existent module at runtime.
+    throw new Error("[oxy.protocol.crypto] Node's built-in 'crypto' module is not available " +
+        'in a React Native runtime. Use the RN-specific helpers ' +
+        '(loadExpoCrypto, getRandomBytesRN) or the Web Crypto API (`globalThis.crypto`).');
+}
+// ---------------------------------------------------------------------------
+// expo-crypto — RN cryptographic primitives.
+//
+// The real module satisfies `ExpoCryptoLike` structurally; the structural
+// interface narrows the surface so consumers never pull expo's own types into
+// their compilation (see expoTypes.ts).
+// ---------------------------------------------------------------------------
+export async function loadExpoCrypto() {
+    if (!expoCryptoModule) {
+        throw missingOptionalPeerError('expo-crypto', 'React Native cryptography', expoCryptoError);
+    }
+    return expoCryptoModule;
+}
+// ---------------------------------------------------------------------------
+// expo-secure-store — RN keychain / keystore.
+// ---------------------------------------------------------------------------
+export async function loadSecureStore() {
+    if (!secureStoreModule) {
+        throw missingOptionalPeerError('expo-secure-store', 'on-device identity storage', secureStoreError);
+    }
+    return secureStoreModule;
+}
+// ---------------------------------------------------------------------------
+// @react-native-async-storage/async-storage — RN persistent KV storage.
+// ---------------------------------------------------------------------------
+export async function loadAsyncStorage() {
+    if (!asyncStorageModule) {
+        throw missingOptionalPeerError('@react-native-async-storage/async-storage', 'device/session persistence', asyncStorageError);
+    }
+    // Mirror the shape callers historically used (`module.default.<method>`)
+    // so the call sites don't have to know whether the underlying module
+    // ships ESM or CJS-with-default.
+    return { default: asyncStorageModule };
+}
+/**
+ * Synchronous random-bytes via `expo-crypto.getRandomBytes`.
+ *
+ * Synchronous by contract: `@oxy.so/core`'s crypto polyfill uses this to back
+ * `globalThis.crypto.getRandomValues`, which cannot await. That is why
+ * `expo-crypto` is resolved with a synchronous `require` at module scope rather
+ * than a dynamic `import()`.
+ */
+export function getRandomBytesRN(byteCount) {
+    if (!expoCryptoModule) {
+        throw missingOptionalPeerError('expo-crypto', 'the React Native CSPRNG (crypto.getRandomValues)', expoCryptoError);
+    }
+    return expoCryptoModule.getRandomBytes(byteCount);
+}
+// ---------------------------------------------------------------------------
+// Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only, OPTIONAL).
+//
+// `@oxy.so/expo-oxy-identity` is the in-repo Expo module autolinked into the
+// identity apps (Commons + the reader RPs). We resolve its NATIVE module
+// directly via expo-modules-core's `requireOptionalNativeModule('OxyIdentity')`
+// — a static import Metro always resolves — instead of dynamically importing the
+// module's JS wrapper. A runtime-computed `import(moduleName)` compiled to a
+// `require(variable)` in the CJS build, which Metro cannot resolve in a consuming
+// repo (the bridge silently resolved `null` there — the cross-app SSO bug). Since
+// the native module is what actually holds the shared identity, going through the
+// native registry is both correct and Metro-safe. `requireOptionalNativeModule`
+// returns `null` (never throws) when the module is not autolinked (web, or apps
+// that don't ship it), so `@oxy.so/core`'s `KeyManager` cleanly falls back to its
+// package-private store.
+// ---------------------------------------------------------------------------
+let sharedIdentityBridgePromise = null;
+export function loadSharedIdentityBridge() {
+    if (!sharedIdentityBridgePromise) {
+        sharedIdentityBridgePromise = Promise.resolve().then(() => {
+            const native = requireOptionalNativeModule('OxyIdentity');
+            if (native &&
+                typeof native.getShared === 'function' &&
+                typeof native.putShared === 'function' &&
+                typeof native.hasShared === 'function' &&
+                typeof native.clearShared === 'function') {
+                return {
+                    getShared: native.getShared.bind(native),
+                    putShared: native.putShared.bind(native),
+                    hasShared: native.hasShared.bind(native),
+                    clearShared: native.clearShared.bind(native),
+                };
+            }
+            return null;
+        });
+    }
+    return sharedIdentityBridgePromise;
+}

package/dist/esm/platform/expoTypes.js

@@ -0,0 +1,23 @@
+/**
+ * Structural interfaces for Expo platform modules.
+ *
+ * These replace `typeof import('expo-crypto')` and
+ * `typeof import('expo-secure-store')` in the built declaration files of
+ * `@oxy.so/protocol` and `@oxy.so/core`.
+ *
+ * ## Why structural interfaces instead of `typeof import('expo-*')`?
+ *
+ * Under NodeNext module resolution (used by `@oxy.so/api` and `@oxy.so/node`),
+ * `expo-crypto` ships with `"exports": {}` (empty exports map). TypeScript
+ * traverses into the package anyway via the `types` field, which transitively
+ * loads `expo-modules-core`. That pollution makes `setInterval`/`setTimeout`
+ * resolve to DOM's `number` return type rather than Node's `NodeJS.Timeout`,
+ * producing ~10 spurious `TS2322` / `TS2339` errors in every consumer that
+ * uses Node timer APIs — none of which reference protocol types at all.
+ *
+ * Structural interfaces break the transitive expo-modules-core dependency
+ * entirely: consumers that don't have Expo installed see clean types, and
+ * the actual RN runtime (which DOES have Expo installed) still works because
+ * the real modules satisfy these interfaces structurally.
+ */
+export {};

package/dist/esm/platform/platform.js

@@ -0,0 +1,29 @@
+/**
+ * Platform Detection — runtime predicates.
+ *
+ * Detects the host runtime WITHOUT importing from 'react-native', so the
+ * protocol's crypto modules can be used in web / Node.js / React Native
+ * environments without bundlers failing on react-native imports.
+ *
+ * Only the two predicates the protocol's platform-crypto loaders need live
+ * here. Richer platform detection (`getPlatformOS`, `isWeb`, `isNative`, …)
+ * is an SDK concern and stays in `@oxy.so/core`.
+ */
+/**
+ * Check if running in React Native.
+ *
+ * Selects the React Native crypto variant (`expo-crypto` /
+ * `expo-secure-store` / async-storage) over the Node/web variant.
+ */
+export function isReactNative() {
+    return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+/**
+ * Check if running in Node.js.
+ *
+ * Gates use of Node's built-in `crypto` (the synchronous SHA-256 path and
+ * `randomBytes`) and the `await import('node:crypto')` loader.
+ */
+export function isNodeJS() {
+    return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+}

package/dist/esm/secp256k1.js

@@ -0,0 +1,137 @@
+/**
+ * secp256k1 primitives shared by every Oxy runtime.
+ *
+ * This module owns the curve binding and the wire formats used across Oxy:
+ * 32-byte private keys, compressed or uncompressed SEC1 public keys,
+ * RFC 6979 deterministic ECDSA signatures encoded as DER, and the 32-byte
+ * ECDH x-coordinate. Callers never receive a library-specific key object.
+ */
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+const HEX = /^[0-9a-fA-F]+$/;
+const COMPRESSED_PUBLIC_KEY = /^(02|03)[0-9a-fA-F]{64}$/;
+const UNCOMPRESSED_PUBLIC_KEY = /^04[0-9a-fA-F]{128}$/;
+function bytesToHex(bytes) {
+    let result = "";
+    for (const byte of bytes) {
+        result += byte.toString(16).padStart(2, "0");
+    }
+    return result;
+}
+function hexToBytes(value, label) {
+    if (value.length === 0 || value.length % 2 !== 0 || !HEX.test(value)) {
+        throw new Error(`${label} must be an even-length hexadecimal string`);
+    }
+    const bytes = new Uint8Array(value.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Normalize a legacy short/cased scalar to canonical 32-byte lowercase hex.
+ * The scalar must be within the secp256k1 order; zero and overflow are rejected.
+ */
+export function normalizeSecp256k1PrivateKey(privateKeyHex) {
+    if (typeof privateKeyHex !== "string" ||
+        privateKeyHex.length === 0 ||
+        privateKeyHex.length > 64 ||
+        !HEX.test(privateKeyHex)) {
+        throw new Error("secp256k1 private key must contain 1 to 64 hexadecimal characters");
+    }
+    const normalized = privateKeyHex.toLowerCase().padStart(64, "0");
+    const privateKey = hexToBytes(normalized, "secp256k1 private key");
+    if (!secp256k1.utils.isValidSecretKey(privateKey)) {
+        throw new Error("secp256k1 private key is outside the valid scalar range");
+    }
+    return normalized;
+}
+/** True when a value is a valid secp256k1 scalar (legacy short hex accepted). */
+export function isValidSecp256k1PrivateKey(privateKeyHex) {
+    try {
+        normalizeSecp256k1PrivateKey(privateKeyHex);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parsePrivateKey(privateKeyHex) {
+    return hexToBytes(normalizeSecp256k1PrivateKey(privateKeyHex), "secp256k1 private key");
+}
+function parsePublicKey(publicKeyHex) {
+    if (typeof publicKeyHex !== "string" ||
+        (!COMPRESSED_PUBLIC_KEY.test(publicKeyHex) &&
+            !UNCOMPRESSED_PUBLIC_KEY.test(publicKeyHex))) {
+        throw new Error("secp256k1 public key must be a compressed or uncompressed SEC1 hex key");
+    }
+    const publicKey = hexToBytes(publicKeyHex, "secp256k1 public key");
+    // Parsing validates the SEC1 prefix, coordinate range, and curve equation.
+    secp256k1.Point.fromBytes(publicKey);
+    return publicKey;
+}
+function parseDigest(digestHex) {
+    if (typeof digestHex !== "string" || digestHex.length !== 64) {
+        throw new Error("secp256k1 digest must be exactly 32 bytes of hexadecimal data");
+    }
+    return hexToBytes(digestHex, "secp256k1 digest");
+}
+/** True for a valid compressed or uncompressed SEC1 secp256k1 public key. */
+export function isValidSecp256k1PublicKey(publicKeyHex) {
+    try {
+        parsePublicKey(publicKeyHex);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a canonical private key and its uncompressed public key. */
+export function generateSecp256k1KeyPair() {
+    const privateKey = secp256k1.utils.randomSecretKey();
+    return {
+        privateKey: bytesToHex(privateKey),
+        publicKey: bytesToHex(secp256k1.getPublicKey(privateKey, false)),
+    };
+}
+/** Derive a compressed or uncompressed SEC1 public key from a private scalar. */
+export function deriveSecp256k1PublicKey(privateKeyHex, compressed = false) {
+    return bytesToHex(secp256k1.getPublicKey(parsePrivateKey(privateKeyHex), compressed));
+}
+/** Parse and re-encode a public key in canonical lowercase SEC1 form. */
+export function normalizeSecp256k1PublicKey(publicKeyHex, compressed = false) {
+    const point = secp256k1.Point.fromBytes(parsePublicKey(publicKeyHex));
+    return point.toHex(compressed);
+}
+/**
+ * Sign a 32-byte digest with deterministic RFC 6979 ECDSA and return DER hex.
+ *
+ * `lowS` defaults to false because historical Oxy signatures used elliptic's
+ * default and therefore may occupy either half of the curve order. Verification
+ * accepts both forms; callers that require low-S normalization opt in explicitly.
+ */
+export function signSecp256k1Digest(privateKeyHex, digestHex, options = {}) {
+    const signature = secp256k1.sign(parseDigest(digestHex), parsePrivateKey(privateKeyHex), {
+        lowS: options.lowS ?? false,
+    });
+    return signature.toHex("der");
+}
+/** Verify a DER-encoded ECDSA signature, accepting historical high-S signatures. */
+export function verifySecp256k1Digest(publicKeyHex, digestHex, signatureDerHex) {
+    const publicKey = parsePublicKey(publicKeyHex);
+    const digest = parseDigest(digestHex);
+    const signature = hexToBytes(signatureDerHex, "secp256k1 DER signature");
+    // Parse once up front so malformed or non-DER input is rejected explicitly.
+    secp256k1.Signature.fromBytes(signature, "der");
+    return secp256k1.verify(signature, digest, publicKey, {
+        format: "der",
+        lowS: false,
+    });
+}
+/** Derive the fixed-width 32-byte ECDH x-coordinate shared secret. */
+export function deriveSecp256k1SharedSecret(privateKeyHex, publicKeyHex) {
+    const encodedPoint = secp256k1.getSharedSecret(parsePrivateKey(privateKeyHex), parsePublicKey(publicKeyHex), true);
+    if (encodedPoint.length !== 33) {
+        throw new Error("secp256k1 ECDH returned an unexpected point encoding");
+    }
+    return encodedPoint.slice(1);
+}

package/dist/esm/transparency/checkpoint.js

@@ -0,0 +1,73 @@
+/**
+ * Transparency checkpoint — the signed, hash-linked commitment to a tree root.
+ *
+ * A checkpoint is what the operator PUBLISHES: "at `periodEnd` I committed to
+ * `root` over `treeSize` subjects, and the previous checkpoint hashed to
+ * `prevCheckpointHash`". The `prevCheckpointHash` link makes the checkpoint
+ * sequence itself append-only: once any checkpoint is anchored publicly, none of
+ * its ancestors can be rewritten without breaking the chain of hashes.
+ *
+ * ## Why the signature covers ONLY the five fields
+ *
+ * The signing input is derived from exactly `{index, periodEnd, treeSize, root,
+ * prevCheckpointHash}` — never from the surrounding storage document, and never
+ * from other signatures. That is what makes a checkpoint CO-SIGNABLE: the
+ * operator and any number of independent witnesses (e.g. user-run
+ * `@oxy.so/node` deployments) each sign the identical bytes with their own key,
+ * with zero coordination and in any order. Two conflicting roots for one
+ * `index`, each carrying valid signatures, is then transferable proof of
+ * equivocation that needs no cooperation from the operator to demonstrate.
+ *
+ * Extra fields on the object passed in are ignored by design, so handing this a
+ * database document cannot change what was signed.
+ */
+import { canonicalize } from '../envelope/canonicalJson.js';
+import { sha256 } from '../envelope/recordId.js';
+import { signMessage, verifySignature } from '../envelope/sign.js';
+import { deriveSecp256k1PublicKey } from '../secp256k1.js';
+/** Domain prefix for checkpoint signing bytes. */
+const CHECKPOINT_PREFIX = 'oxy.transparency.checkpoint.v1:';
+/** The one signature algorithm the protocol emits. */
+const ALG = 'ES256K-DER-SHA256';
+/**
+ * The exact bytes every co-signer signs: the canonical JSON of the five signed
+ * fields under the checkpoint domain prefix. Key order in the input object is
+ * irrelevant; extra properties are dropped.
+ */
+export function checkpointSigningInput(fields) {
+    return `${CHECKPOINT_PREFIX}${canonicalize({
+        index: fields.index,
+        periodEnd: fields.periodEnd,
+        treeSize: fields.treeSize,
+        root: fields.root,
+        prevCheckpointHash: fields.prevCheckpointHash,
+    })}`;
+}
+/**
+ * The content address of a checkpoint — what the NEXT checkpoint's
+ * `prevCheckpointHash` references.
+ */
+export async function checkpointHash(fields) {
+    return sha256(checkpointSigningInput(fields));
+}
+/**
+ * Sign a checkpoint with an explicit private key. Used by the operator and,
+ * identically, by every witness that co-signs the same checkpoint.
+ */
+export async function signCheckpoint(fields, privateKeyHex) {
+    return {
+        publicKey: deriveSecp256k1PublicKey(privateKeyHex),
+        alg: ALG,
+        signature: await signMessage(checkpointSigningInput(fields), privateKeyHex),
+    };
+}
+/**
+ * Verify one signature over a checkpoint's signed fields.
+ *
+ * Confirms the signature matches the embedded `publicKey` for exactly these
+ * fields. It does NOT establish that the key belongs to a trusted operator or an
+ * accepted witness — that policy lives with the verifier's key list.
+ */
+export async function verifyCheckpointSignature(fields, signature) {
+    return verifySignature(checkpointSigningInput(fields), signature.signature, signature.publicKey);
+}

package/dist/esm/transparency/tree.js

@@ -0,0 +1,189 @@
+/**
+ * Transparency Merkle tree — leaf hashing, root computation, and inclusion
+ * proofs over a snapshot of chain heads.
+ *
+ * ## What this is for
+ *
+ * A per-subject hash chain proves nobody edited a record. It does NOT prove the
+ * SERVER didn't serve two different histories to two parties (equivocation), or
+ * quietly drop a record. That gap is closed by committing to every subject's
+ * chain head at once, publishing the commitment, and letting anyone verify that
+ * their own head is inside it — which is exactly what this tree does. The
+ * commitment (the root) is what gets signed into a checkpoint (`./checkpoint`)
+ * and anchored on a public chain.
+ *
+ * ## Shape
+ *
+ * The tree follows RFC 6962 (Certificate Transparency) so the algorithms are
+ * standard and independently reimplementable: leaves and interior nodes are
+ * hashed under DISTINCT domain prefixes (a leaf hash can never be reinterpreted
+ * as an interior node), an odd level splits so the LEFT subtree is the largest
+ * power of two below the size, and a single-leaf tree's root is the leaf itself.
+ *
+ * A built tree keeps every LEVEL, not just its leaves, because that is what
+ * makes serving proofs cheap: {@link inclusionProof} reads siblings straight out
+ * of the levels instead of re-hashing subtrees, so one build amortizes over all
+ * the proofs cut from it (a checkpoint is built once and proved thousands of
+ * times, once per subject that audits it).
+ *
+ * Crucially, {@link verifyInclusionProof} needs only the verifier's OWN leaf,
+ * its index, the tree size, the audit path, and the signed root — never the
+ * other leaves. So a device or node can audit its own history against a
+ * published checkpoint without downloading anyone else's data.
+ *
+ * The leaf order is fixed by {@link buildTransparencyTreeFromHeads}: ascending
+ * by `subjectDid` in UTF-16 code-unit order. Order is part of the commitment, so
+ * every implementation MUST sort identically or the roots diverge.
+ */
+import { sha256 } from '../envelope/recordId.js';
+import { canonicalize } from '../envelope/canonicalJson.js';
+/** Domain prefix for a leaf hash. Distinct from {@link NODE_PREFIX}. */
+const LEAF_PREFIX = 'oxy.transparency.leaf.v1:';
+/** Domain prefix for an interior node hash. Distinct from {@link LEAF_PREFIX}. */
+const NODE_PREFIX = 'oxy.transparency.node.v1:';
+/** The pre-image of {@link EMPTY_TRANSPARENCY_ROOT}. */
+const EMPTY_PREIMAGE = 'oxy.transparency.empty.v1';
+/**
+ * The root of a tree with zero leaves: `sha256("oxy.transparency.empty.v1")`.
+ *
+ * Hard-coded because hashing is async and this is needed as a value; a Jest
+ * regression test pins it against the live hash of {@link EMPTY_PREIMAGE}.
+ */
+export const EMPTY_TRANSPARENCY_ROOT = '315338df4bc34de7d057b583a082268016888323c79c0376586406a64f441b1e';
+/**
+ * Hash one subject's head into a leaf.
+ *
+ * The pre-image is the canonical JSON of the three committed fields under the
+ * leaf domain prefix — so a DID containing a delimiter-like character cannot
+ * forge another subject's leaf (JSON escaping makes the encoding unambiguous),
+ * and a leaf can never collide with an interior node.
+ */
+export async function transparencyLeafHash(entry) {
+    const preimage = canonicalize({
+        subjectDid: entry.subjectDid,
+        seq: entry.seq,
+        headRecordId: entry.headRecordId,
+    });
+    return sha256(`${LEAF_PREFIX}${preimage}`);
+}
+/** Hash an interior node over its ordered children. */
+async function nodeHash(left, right) {
+    return sha256(`${NODE_PREFIX}${left}${right}`);
+}
+/**
+ * Build a tree over already-hashed leaves, in the given order.
+ *
+ * Levels are built bottom-up, each one pairing the level below and carrying a
+ * trailing odd node up unchanged — which yields exactly RFC 6962's tree, whose
+ * recursive definition splits at the largest power of two below the size.
+ * `transparency.test.ts` pins that equivalence against a direct transcription of
+ * the RFC's MTH for every size up to 40, so the shape can never silently drift.
+ *
+ * The order IS part of the commitment — prefer
+ * {@link buildTransparencyTreeFromHeads}, which owns the canonical ordering.
+ */
+export async function buildTransparencyTree(leaves) {
+    const levels = [[...leaves]];
+    let current = levels[0];
+    while (current.length > 1) {
+        const pairCount = Math.floor(current.length / 2);
+        const parents = await Promise.all(Array.from({ length: pairCount }, (_unused, pair) => nodeHash(current[pair * 2], current[pair * 2 + 1])));
+        if (current.length % 2 === 1) {
+            parents.push(current[current.length - 1]);
+        }
+        levels.push(parents);
+        current = parents;
+    }
+    const top = levels[levels.length - 1];
+    return {
+        root: top.length === 1 ? top[0] : EMPTY_TRANSPARENCY_ROOT,
+        treeSize: leaves.length,
+        levels,
+    };
+}
+/**
+ * Build the canonical tree for a snapshot of chain heads.
+ *
+ * Sorts ascending by `subjectDid` in UTF-16 code-unit order — NEVER
+ * `localeCompare`, whose order is locale-dependent and would make two
+ * verifiers compute different roots from identical data.
+ *
+ * Throws on a duplicate `subjectDid`: a snapshot must commit to exactly one head
+ * per subject, and silently keeping one of two would hide the other's history.
+ */
+export async function buildTransparencyTreeFromHeads(entries) {
+    const ordered = [...entries].sort((a, b) => a.subjectDid < b.subjectDid ? -1 : a.subjectDid > b.subjectDid ? 1 : 0);
+    const indexBySubject = {};
+    ordered.forEach((entry, index) => {
+        if (indexBySubject[entry.subjectDid] !== undefined) {
+            throw new Error(`Duplicate subject in transparency snapshot: ${entry.subjectDid}`);
+        }
+        indexBySubject[entry.subjectDid] = index;
+    });
+    const leaves = await Promise.all(ordered.map(transparencyLeafHash));
+    return { ...(await buildTransparencyTree(leaves)), indexBySubject };
+}
+/**
+ * The audit path proving `index` is committed in `tree` (RFC 6962 PATH): each
+ * step is the sibling subtree hash, leaf-adjacent first.
+ *
+ * Pure index arithmetic over the tree's levels — no hashing, so cutting a proof
+ * costs O(log n) array reads however large the checkpoint is.
+ */
+export function inclusionProof(tree, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= tree.treeSize) {
+        throw new Error(`Leaf index ${index} is outside a tree of ${tree.treeSize} leaves`);
+    }
+    const proof = [];
+    let position = index;
+    for (let level = 0; level < tree.levels.length - 1; level += 1) {
+        const nodes = tree.levels[level];
+        const sibling = position % 2 === 0 ? position + 1 : position - 1;
+        // A trailing odd node is carried up unpaired, so it contributes no step.
+        if (sibling < nodes.length) {
+            proof.push(nodes[sibling]);
+        }
+        position = Math.floor(position / 2);
+    }
+    return proof;
+}
+/**
+ * Verify an audit path against a committed root (RFC 6962 §2.1.1).
+ *
+ * Recomputes the root from the leaf upward using only the path, so the verifier
+ * never needs another subject's data. Returns `false` for every failure mode —
+ * tampered leaf, replayed index, truncated path, foreign root — rather than
+ * throwing, so callers treat auditing as a boolean.
+ */
+export async function verifyInclusionProof(check) {
+    const { leaf, index, treeSize, proof, root } = check;
+    if (!Number.isInteger(index) || !Number.isInteger(treeSize)) {
+        return false;
+    }
+    if (index < 0 || treeSize <= 0 || index >= treeSize) {
+        return false;
+    }
+    let fn = index;
+    let sn = treeSize - 1;
+    let computed = leaf;
+    for (const sibling of proof) {
+        if (sn === 0) {
+            // The path claims more levels than the tree has.
+            return false;
+        }
+        if (fn % 2 === 1 || fn === sn) {
+            computed = await nodeHash(sibling, computed);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            computed = await nodeHash(computed, sibling);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    // `sn > 0` means the path was truncated before reaching the root.
+    return sn === 0 && computed === root;
+}