@orangecheck/stamp-ots 0.1.1 → 0.2.0

package/src/anchor.ts

@@ -1,28 +1,19 @@
-// Anchor-verification helper. See SPEC.md §6.3.
+// Anchor verification. See SPEC.md §6.3.
 //
-// Full OTS proof verification requires:
-//   1. Parsing the proof's Merkle path from digest to calendar root.
-//   2. Walking that path to the declared Bitcoin Merkle root.
-//   3. Fetching the Bitcoin block header at the declared height and comparing
-//      its Merkle root.
+// A confirmed anchor holds when all three are true:
+//   1. the proof commits to the envelope id and walks to a Bitcoin
+//      attestation at the declared height;
+//   2. the message at that attestation equals the Merkle root in the block
+//      header at that height;
+//   3. that header double-SHA256es to the declared block hash.
 //
-// Step 1 needs a real OTS proof parser. We expose two composition points:
-//
-//   A) `makeAnchorVerifier({ walkProof, headerSource })` — you bring the
-//      parser, we provide the glue that compares Merkle roots against the
-//      block header.
-//
-//   B) `makeDefaultAnchorVerifier({ headerSource })` — dynamic-imports the
-//      `opentimestamps` npm package (optional peer dependency) and wires
-//      it into (A). One import, full verification.
-//
-// In both cases the resulting function is what `@orangecheck/stamp-core`
-// expects at the `verifyOtsAnchor` input of `verify()` — no further adaptation
-// needed. The envelope id is passed directly into the hook by stamp-core; we
-// drop the old broken `adaptAnchorVerifier` that tried to derive the digest
-// from the block hash.
+// The resulting function is what `@orangecheck/stamp-core` expects at the
+// `verifyOtsAnchor` input of `verify()`.
+
+import { sha256 } from '@noble/hashes/sha2';
 
 import { base64Decode, hexDecode, hexEncode } from './base64.js';
+import { bitcoinAnchors, bytesEqual, parseProof } from './ots.js';
 import type {
     AnchorVerificationInput,
     AnchorVerificationResult,
@@ -33,39 +24,53 @@ import type {
 export interface AnchorVerifierConfig {
     /**
      * Parse the proof bytes and return the Merkle root the proof walks to,
-     * plus the declared block height. Returns null if parsing failed or the
-     * proof isn't anchored.
+     * plus its block height. Optional: the built-in OTS parser is used when
+     * omitted. `blockHeight` is the declared height, for proofs that carry
+     * attestations at more than one height.
      */
-    walkProof: (input: {
+    walkProof?: (input: {
         proofBytes: Uint8Array;
         digest: Uint8Array;
+        blockHeight?: number;
     }) => Promise<{ merkleRoot: Uint8Array; blockHeight: number } | null>;
     /**
-     * Source of Bitcoin block headers. Can be a full node, SPV, or a
-     * pre-computed headers snapshot.
+     * Source of Bitcoin block headers: a full node, SPV, a headers snapshot,
+     * or `mempoolHeaderSource()`. This is the verifier's trust anchor.
      */
     headerSource: BlockHeaderSource;
 }
 
-/**
- * Build a concrete anchor verifier from a proof walker plus a header source.
- *
- * The returned function matches the `verifyOtsAnchor` shape expected by
- * `@orangecheck/stamp-core`'s `verify()`:
- *
- *   (proofB64, blockHeight, blockHash, envelopeId) => Promise<boolean>
- *
- * Wire it in as:
- *
- *   verify({ envelope, verifyOtsAnchor: makeAnchorVerifier({...}) })
- */
+/** Built-in walker: parse the OTS proof and pick the Bitcoin attestation. */
+export async function walkOtsProof(input: {
+    proofBytes: Uint8Array;
+    digest: Uint8Array;
+    blockHeight?: number;
+}): Promise<{ merkleRoot: Uint8Array; blockHeight: number } | null> {
+    try {
+        const anchors = bitcoinAnchors(parseProof(input.proofBytes, input.digest));
+        return anchors.find((a) => a.blockHeight === input.blockHeight) ?? anchors[0] ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/** Block hash (display hex) of an 80-byte header. */
+export function blockHashOf(header: Uint8Array): string {
+    return hexEncode(sha256(sha256(header)).reverse());
+}
+
 export function makeAnchorVerifier(
     cfg: AnchorVerifierConfig
 ): (proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean> {
+    const walkProof = cfg.walkProof ?? walkOtsProof;
     const verifier: AnchorVerifier = async (
         input: AnchorVerificationInput
     ): Promise<AnchorVerificationResult> => {
-        const walked = await cfg.walkProof({ proofBytes: input.proofBytes, digest: input.digest });
+        const walked = await walkProof({
+            proofBytes: input.proofBytes,
+            digest: input.digest,
+            blockHeight: input.blockHeight,
+        });
         if (!walked) {
             return { ok: false, reason: 'proof could not be walked to a Bitcoin commitment' };
         }
@@ -76,23 +81,18 @@ export function makeAnchorVerifier(
             };
         }
         const header = await cfg.headerSource.getHeaderAt(input.blockHeight);
-        if (!header) {
+        if (!header || header.byteLength !== 80) {
             return { ok: false, reason: `no block header available at height ${input.blockHeight}` };
         }
-        // Bitcoin block header is 80 bytes; merkle root at offset 36, 32 bytes,
-        // little-endian. Proof walkers vary in convention — compare both
-        // endiannesses to stay compatible across implementations.
-        if (header.byteLength < 80) {
-            return { ok: false, reason: 'malformed Bitcoin header (too short)' };
+        if (blockHashOf(header) !== input.blockHash.toLowerCase()) {
+            return { ok: false, reason: 'block header does not hash to the declared block hash' };
         }
-        const headerMerkleLE = header.subarray(36, 68);
-        const headerMerkleBE = new Uint8Array(headerMerkleLE).reverse();
-        const matchesLE = bytesEqual(headerMerkleLE, walked.merkleRoot);
-        const matchesBE = bytesEqual(headerMerkleBE, walked.merkleRoot);
-        if (!matchesLE && !matchesBE) {
+        // OTS attests to the Merkle root in header byte order (offset 36).
+        const headerMerkle = header.subarray(36, 68);
+        if (!bytesEqual(headerMerkle, walked.merkleRoot)) {
             return { ok: false, reason: 'block header Merkle root does not match walked proof root' };
         }
-        return { ok: true, merkleRoot: hexEncode(matchesBE ? headerMerkleBE : headerMerkleLE) };
+        return { ok: true, merkleRoot: hexEncode(headerMerkle) };
     };
 
     return async (proofB64, blockHeight, blockHash, envelopeId) => {
@@ -107,98 +107,41 @@ export function makeAnchorVerifier(
 }
 
 /**
- * Default anchor verifier that dynamically imports the `opentimestamps` npm
- * package and wires it into `makeAnchorVerifier`. The import is lazy so
- * consumers who only need calendar submission don't pay the dep cost.
- *
- * Install `opentimestamps` alongside `@orangecheck/stamp-ots` to use this:
- *
- *   npm i @orangecheck/stamp-ots opentimestamps
- *
- * Then:
- *
- *   const verifyOtsAnchor = await makeDefaultAnchorVerifier({ headerSource });
- *   await verify({ envelope, verifyOtsAnchor });
- *
- * Throws if `opentimestamps` isn't resolvable. That's intentional — callers
- * who haven't installed it should use `makeAnchorVerifier` with their own
- * walker instead, so the failure surfaces immediately rather than silently
- * reporting every stamp as unverified.
+ * Anchor verifier using the built-in OTS parser. Kept async for callers of the
+ * 0.1 API, which lazily loaded an optional parser here.
  */
 export async function makeDefaultAnchorVerifier(opts: {
     headerSource: BlockHeaderSource;
 }): Promise<
     (proofB64: string, blockHeight: number, blockHash: string, envelopeId: string) => Promise<boolean>
 > {
-    const walkProof = await loadOpenTimestampsWalker();
-    return makeAnchorVerifier({ walkProof, headerSource: opts.headerSource });
+    return makeAnchorVerifier({ headerSource: opts.headerSource });
 }
 
-type OtsWalker = AnchorVerifierConfig['walkProof'];
-
-async function loadOpenTimestampsWalker(): Promise<OtsWalker> {
-    // Dynamic import so the dep is optional. If the package isn't installed,
-    // the error is explicit and actionable.
-    let ots: unknown;
-    try {
-        ots = await import(/* webpackIgnore: true */ 'opentimestamps' as string);
-    } catch (e) {
-        throw new Error(
-            '@orangecheck/stamp-ots: makeDefaultAnchorVerifier requires the optional peer dependency `opentimestamps`. ' +
-                `Install it with \`npm i opentimestamps\` or supply your own walkProof via makeAnchorVerifier. ` +
-                `Underlying error: ${e instanceof Error ? e.message : String(e)}`
-        );
-    }
-
-    // Normalize the module shape. `opentimestamps` publishes both CJS-default
-    // and named exports across its versions.
-    const mod = (ots as { default?: unknown }).default ?? ots;
-    const modAny = mod as Record<string, unknown>;
-
-    type DetachedLike = { deserialize(bytes: Uint8Array): unknown; timestamp: unknown };
-    type TimestampLike = {
-        verify(): Promise<Map<string, { height: number; timestamp?: unknown }>>;
-        msg: Uint8Array;
-    };
-
-    const DetachedCtor =
-        (modAny.DetachedTimestampFile as { deserialize(b: Uint8Array): DetachedLike } | undefined) ??
-        (modAny.default as Record<string, unknown> | undefined)?.DetachedTimestampFile as
-            | { deserialize(b: Uint8Array): DetachedLike }
-            | undefined;
-
-    if (!DetachedCtor || typeof DetachedCtor.deserialize !== 'function') {
-        throw new Error(
-            '@orangecheck/stamp-ots: unexpected shape from `opentimestamps` package — ' +
-                'expected DetachedTimestampFile.deserialize. If you are using a non-standard build, ' +
-                'pass your own walkProof via makeAnchorVerifier instead.'
-        );
-    }
-
-    return async ({ proofBytes }) => {
-        try {
-            const detached = DetachedCtor.deserialize(proofBytes);
-            const ts = detached.timestamp as TimestampLike;
-            const attestations = await ts.verify();
-            const first = attestations.values().next();
-            if (first.done) return null;
-            const { height, timestamp } = first.value;
-            if (typeof height !== 'number' || !timestamp) return null;
-            // The attestation provides the block height; the merkle root the
-            // walker produces is the timestamp.msg bytes the walker committed
-            // against. opentimestamps resolves that through its internal
-            // proof chain; reading ts.msg gives the final digest it committed.
-            const merkleRoot = (timestamp as { msg?: Uint8Array }).msg;
-            if (!merkleRoot) return null;
-            return { merkleRoot, blockHeight: height };
-        } catch {
-            return null;
-        }
-    };
+export interface MempoolHeaderSourceOptions {
+    /** Esplora-compatible API base. Default https://mempool.space/api. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
 }
 
-function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.byteLength !== b.byteLength) return false;
-    for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
-    return true;
+/**
+ * Block headers from an Esplora-compatible API. The verifier checks each
+ * header against the declared block hash, so this source is trusted only to
+ * report which block is at a height.
+ */
+export function mempoolHeaderSource(opts: MempoolHeaderSourceOptions = {}): BlockHeaderSource {
+    const base = (opts.baseUrl ?? 'https://mempool.space/api').replace(/\/+$/, '');
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    return {
+        async getHeaderAt(height) {
+            const h = await fetchImpl(`${base}/block-height/${height}`);
+            if (!h.ok) return null;
+            const hash = (await h.text()).trim();
+            if (!/^[0-9a-f]{64}$/.test(hash)) return null;
+            const r = await fetchImpl(`${base}/block/${hash}/header`);
+            if (!r.ok) return null;
+            const hex = (await r.text()).trim();
+            return /^[0-9a-f]{160}$/.test(hex) ? hexDecode(hex) : null;
+        },
+    };
 }

package/src/calendar.ts

@@ -2,11 +2,9 @@
 // of the calendar protocol that an OC Stamp implementation needs:
 //
 //   POST <url>/digest          body = raw digest bytes        -> pending proof bytes
-//   GET  <url>/timestamp/<hex>                                -> upgraded proof bytes, or 404
+//   GET  <url>/timestamp/<hex(commitment)>                    -> continuation, or 404
 //
-// The client is thin by design. It does not parse proof bytes; that is a
-// separate concern addressed by whichever OTS proof library the consumer
-// plugs in (see verifyOtsAnchor in ./anchor.ts).
+// The client moves bytes only; ./ots.ts parses them.
 
 import type { CalendarClient } from './types.js';
 import { hexEncode } from './base64.js';
@@ -62,12 +60,12 @@ export function createCalendarClient(url: string, opts: HttpCalendarOptions = {}
             const buf = await resp.arrayBuffer();
             return new Uint8Array(buf);
         },
-        async fetchProof(digest, signal) {
-            if (digest.byteLength !== 32) {
-                throw new Error('OTS: digest must be exactly 32 bytes');
+        async fetchProof(commitment, signal) {
+            if (commitment.byteLength === 0 || commitment.byteLength > 64) {
+                throw new Error('OTS: commitment must be 1-64 bytes');
             }
             const ac = withTimeout(signal, timeoutMs);
-            const resp = await fetchImpl(`${base}/timestamp/${hexEncode(digest)}`, {
+            const resp = await fetchImpl(`${base}/timestamp/${hexEncode(commitment)}`, {
                 method: 'GET',
                 headers: { Accept: 'application/vnd.opentimestamps.v1' },
                 signal: ac.signal,

package/src/index.ts

@@ -6,5 +6,22 @@ export { submitToCalendars } from './submit.js';
 export type { SubmitOptions } from './submit.js';
 export { upgradeProof } from './upgrade.js';
 export type { UpgradeOptions } from './upgrade.js';
-export { makeAnchorVerifier, makeDefaultAnchorVerifier } from './anchor.js';
-export type { AnchorVerifierConfig } from './anchor.js';
+export {
+    blockHashOf,
+    makeAnchorVerifier,
+    makeDefaultAnchorVerifier,
+    mempoolHeaderSource,
+    walkOtsProof,
+} from './anchor.js';
+export type { AnchorVerifierConfig, MempoolHeaderSourceOptions } from './anchor.js';
+export {
+    attestations,
+    bitcoinAnchors,
+    mergeAt,
+    parseDetached,
+    parseProof,
+    parseTimestamp,
+    pendingCommitments,
+    serializeTimestamp,
+} from './ots.js';
+export type { OtsAttestation, OtsOp, OtsTimestamp } from './ots.js';

package/src/ots-fixture.test-helper.ts

@@ -0,0 +1,24 @@
+// A real OpenTimestamps proof: opentimestamps-client examples/hello-world.txt.ots,
+// committing to sha256("Hello World!\n") and anchored in Bitcoin block 358391.
+
+import { base64Decode } from './base64.js';
+
+export const HELLO_DIGEST = '03ba204e50d126e4674c005e04d82e84c21366780af1f43bd54a37816b6ab340';
+
+export const HELLO_OTS_FILE = base64Decode(
+    'AE9wZW5UaW1lc3RhbXBzAABQcm9vZgC/ieLohOiSlAEIA7ogTlDRJuRnTABeBNguhMITZngK8fQ71Uo3gWtqs0AD' +
+    '8cgBAQAAAAHkgvnTLsw7ple2nYmAEIV7VEV6kEl5gv9W+XxOxY5vmAEAAABrSDBFAiEAslOt0dHPkIRDOKR1oE/x' +
+    'P8nnvSQrB3Yt6gf1YIst42cCIACyaMqcM0KzdpzdBiiRMXzc74eqwxC2hV6dk4mOu+jsASECDY5NEH0rM5sAUO/d' +
+    'S0oJJFqgVgSPElOWN06moqsHCcb/////AmUz5gUAAAAAGXapFAvwV9QPu6Z0SGJRX1tVojEN5XcviKyghgEAAAAA' +
+    'ABl2qRTwBoisAAAAAAgI8SCph/cWxTORPDFMeONdNYhMrJQ/pCysSdKyxp9AA/hfiAgI8SDexVs0h+Hj9yKkm1Wn' +
+    'eDIVhieF9KOss5KEYBn3HcZKnQgI8SCyyhj0heCAR44CXas9RktBbA4ey2Ypya786MghTQQkMggI8CARsOkGYRlv' +
+    '9LCBPD7aFBurXpFgSDe996DJ3zfbDjoRmAgI8CDDS8GkoQk//RSMAWseZkdCkU6Tnvq+TT01ZRWRSybZ4ggI8CDD' +
+    '5ufDjGn2ryTCvjTrrEglft5h7AohuVNeREMne+MGRggI8SAHmL+GBuAAJOXV1UvwyWD2Kd+52taRV0VbbyZSwOje' +
+    'gQgI8CA/mtptYLqiRABrsKrVFEitL6+51LZIegmZz/JrkfD1NggI8SDHAwGelZqN0/rvdIm7MoukhVdHWOcJHwFG' +
+    'TrZYcsl1yAgI8CDL/v/1E/+EuRXj/tb515lnZjD4Nk6ipsdVf62UpbXXiAgI8SAL4jcJhZkTur1EYLvd+O0hPnyH' +
+    'c6Sx+s4w+Kz98JO3BQgIAAWIlg1z1xkBA/fvFQ==');
+
+export const BLOCK_HEIGHT = 358391;
+export const BLOCK_HASH = '000000000000000003e892881a8cdcdc117c06d444057c98b6f04a9ee75a2319';
+export const BLOCK_HEADER_HEX =
+    '02000000b96394585a281b7e5f438fd1c9ed492645a1fd61cb3802040000000000000000007ee445d23ad061af4a36b809501fab1ac4f2d7e7a739817dd0cbb7ec661b8a1e376755f58616186272def6';

package/src/ots.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { hexDecode, hexEncode } from './base64.js';
+import { bitcoinAnchors, parseDetached, parseProof, serializeTimestamp } from './ots.js';
+import { BLOCK_HEADER_HEX, BLOCK_HEIGHT, HELLO_DIGEST, HELLO_OTS_FILE } from './ots-fixture.test-helper.js';
+
+describe('OTS proof parsing', () => {
+    it('walks a detached proof to the Merkle root in the attested block header', () => {
+        const { digest, timestamp } = parseDetached(HELLO_OTS_FILE);
+        expect(hexEncode(digest)).toBe(HELLO_DIGEST);
+        const [anchor] = bitcoinAnchors(timestamp);
+        expect(anchor?.blockHeight).toBe(BLOCK_HEIGHT);
+        expect(hexEncode(anchor!.merkleRoot)).toBe(BLOCK_HEADER_HEX.slice(72, 136));
+    });
+
+    it('serializes a parsed timestamp back to the same bytes', () => {
+        const { timestamp } = parseDetached(HELLO_OTS_FILE);
+        const bare = serializeTimestamp(timestamp);
+        expect(hexEncode(bare)).toBe(hexEncode(HELLO_OTS_FILE.subarray(HELLO_OTS_FILE.length - bare.length)));
+    });
+
+    it('accepts the bare timestamp encoding rooted at the digest', () => {
+        const bare = serializeTimestamp(parseDetached(HELLO_OTS_FILE).timestamp);
+        expect(bitcoinAnchors(parseProof(bare, hexDecode(HELLO_DIGEST)))[0]?.blockHeight).toBe(BLOCK_HEIGHT);
+    });
+
+    it('refuses a detached proof for a different digest', () => {
+        expect(() => parseProof(HELLO_OTS_FILE, hexDecode('00'.repeat(32)))).toThrow(/different digest/);
+    });
+
+    it('rejects truncated proofs', () => {
+        expect(() => parseDetached(HELLO_OTS_FILE.subarray(0, HELLO_OTS_FILE.length - 5))).toThrow();
+    });
+});