@hashborn/verify 0.0.0-stage → 0.1.2

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * hashborn-verify <verify link | attestation.json | - | record id | record page URL>
+ *
+ * Verifies one Hashborn attestation with SHA-256 alone and prints the verdict. Exit code 0 when
+ * it is valid, 1 otherwise (invalid, malformed, not found, or the API did not answer).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { parseAttestation, parseVerifyLink } from './attestation.js';
+import { DEFAULT_BASE_URL } from './constants.js';
+import { HashbornError } from './errors.js';
+import { RECORD_ID_RE, verifyRemote } from './remote.js';
+import { verifyAttestation } from './verify.js';
+const USAGE = `Usage: hashborn-verify <input> [--base-url <url>] [--json]
+
+<input> is one of:
+  a verify link     https://hashborn.com/verify?attestation=...
+  a JSON file       path to an attestation saved as JSON, or - to read it from stdin
+  a record id       0x followed by 72 hex characters, as on /records/<id>
+  a record page     https://hashborn.com/records/<id>
+
+A record is read from the public API (default ${DEFAULT_BASE_URL}, or the record page's site)
+and verified here; the server's own verdict is never used. Exit code 0 when valid, 1 otherwise.`;
+function readStdin() {
+    return readFileSync(0, 'utf8');
+}
+function print(result) {
+    const lines = [result.valid ? 'valid' : `invalid: ${result.reason ?? 'unknown reason'}`];
+    const row = (label, value) => {
+        if (value !== null && value !== undefined && value !== '')
+            lines.push(`  ${label.padEnd(9)}${String(value)}`);
+    };
+    row('domain', result.domain);
+    row('signer', result.pqAddress);
+    row('leaf', result.leaf);
+    row('root', result.root);
+    row('message', result.messageHash);
+    if ('remote' in result) {
+        const r = result.remote;
+        row('record', result.valid ? 'its published text hashes to the signed message' : null);
+        row('anchored', `${r.txHash} block ${r.blockNumber}${r.chainId ? ` chain ${r.chainId}` : ''} at ${r.anchoredAt}`);
+    }
+    if (result.hashCalls)
+        row('hashes', `${result.hashCalls} SHA-256 calls on the chains`);
+    console.log(lines.join('\n'));
+}
+async function main(argv) {
+    let baseUrl;
+    let json = false;
+    const inputs = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') {
+            console.log(USAGE);
+            return 0;
+        }
+        else if (a === '--json')
+            json = true;
+        else if (a === '--base-url')
+            baseUrl = argv[++i];
+        else if (a.startsWith('--base-url='))
+            baseUrl = a.slice('--base-url='.length);
+        else
+            inputs.push(a);
+    }
+    if (inputs.length !== 1 || (baseUrl !== undefined && !baseUrl)) {
+        console.error(USAGE);
+        return 1;
+    }
+    const input = inputs[0].trim();
+    // A record page URL, https://<site>/records/<id>, is read from that site unless --base-url says otherwise.
+    const recordPage = /^(https?:\/\/[^/?#]+)\/records\/(0x[0-9a-fA-F]{72})(?:[/?#]|$)/i.exec(input);
+    let result;
+    try {
+        if (RECORD_ID_RE.test(input)) {
+            result = await verifyRemote(input, baseUrl ? { baseUrl } : {});
+        }
+        else if (recordPage) {
+            result = await verifyRemote(recordPage[2], { baseUrl: baseUrl ?? recordPage[1] });
+        }
+        else if (input === '-') {
+            result = verifyAttestation(parseAttestation(readStdin()));
+        }
+        else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(input) || input.includes('attestation=')) {
+            result = verifyAttestation(parseVerifyLink(input));
+        }
+        else if (existsSync(input)) {
+            result = verifyAttestation(parseAttestation(readFileSync(input, 'utf8')));
+        }
+        else {
+            result = verifyAttestation(parseVerifyLink(input));
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Nothing to judge when the record was not found or the API did not answer.
+        const noVerdict = err instanceof HashbornError && (err.code === 'not-found' || err.code === 'network');
+        if (json)
+            console.log(JSON.stringify({ valid: false, error: message }, null, 2));
+        else
+            console.log(`${noVerdict ? 'error' : 'invalid'}: ${message}`);
+        return 1;
+    }
+    if (json) {
+        const { remote, ...rest } = result;
+        console.log(JSON.stringify(remote ? { ...rest, record: remote.record, anchored: { txHash: remote.txHash, block: remote.blockNumber, chainId: remote.chainId, at: remote.anchoredAt } } : rest, null, 2));
+    }
+    else {
+        print(result);
+    }
+    return result.valid ? 0 : 1;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/constants.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Protocol v1 constants and the public JSON types. Copied from the reference implementation in
+ * apps/web (lib/pq/contract.ts and lib/types.ts); test/cross.test.ts pins them to it.
+ */
+export type Hex = `0x${string}`;
+/**
+ * Fixed parameters of protocol v1: SHA-256, n = 32, w = 16, 67 chains, height 8, 256 leaves.
+ * Signature = 4 + 67 x 32 + 8 x 32 = 2,404 bytes. Public key = root || pubSeed.
+ */
+export declare const PQ: {
+    readonly hash: "SHA-256";
+    readonly n: 32;
+    readonly w: 16;
+    readonly len1: 64;
+    readonly len2: 3;
+    readonly len: 67;
+    readonly chainSteps: 15;
+    readonly height: 8;
+    readonly leaves: 256;
+    readonly signatureBytes: 2404;
+    readonly publicKeyBytes: 64;
+};
+/** Protocol name. It prefixes every domain and the pq address hash, and never changes. */
+export declare const PROTOCOL_DOMAIN = "pqc-rh";
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Attestation domains, protocol v1. Every digest is
+ * SHA-256(domain || "\n" || canonical JSON of the fields, keys sorted).
+ */
+export declare const DOMAINS: {
+    readonly identity: "pqc-rh/identity/v1";
+    readonly proof: "pqc-rh/proof/v1";
+    readonly agent: "pqc-rh/agent/v1";
+    readonly agentAction: "pqc-rh/agent-action/v1";
+    readonly transfer: "pqc-rh/transfer/v1";
+    readonly rwa: "pqc-rh/rwa/v1";
+    readonly vaultWithdraw: "pqc-rh/vault-withdraw/v2";
+    readonly statement: "pqc-rh/statement/v1";
+    readonly official: "pqc-rh/official/v1";
+};
+export type Domain = (typeof DOMAINS)[keyof typeof DOMAINS];
+/**
+ * Scheme ids an attestation may name. Protocol v1 signs with `wots-merkle` only; the others are
+ * reserved for many-time keys certified by a WOTS leaf.
+ */
+export declare const SCHEME_IDS: readonly ["wots-merkle", "ml-dsa-65", "slh-dsa-sha2-128s", "falcon-512", "ml-dsa-87", "slh-dsa-shake-128f", "falcon-1024", "secp256k1-ml-dsa-65"];
+export type SchemeId = (typeof SCHEME_IDS)[number];
+/** A WOTS + Merkle signature, 4 + 67 x 32 + 8 x 32 = 2,404 bytes on the wire. */
+export interface MerkleSignature {
+    leaf: number;
+    /** 67 x 32 bytes, hex. */
+    wots: Hex;
+    /** 8 x 32 bytes, hex, sibling at every level from the leaf up. */
+    auth: Hex[];
+}
+/** One signed statement: what was signed, by which leaf of which identity, anchored where. */
+export interface Attestation {
+    version: 1;
+    scheme: SchemeId;
+    domain: Domain;
+    /** pq1 + base58(SHA-256("pqc-rh" || pubSeed || root)[0..20]) */
+    pqAddress: string;
+    root: Hex;
+    pubSeed: Hex;
+    height: 8;
+    /** The digest the leaf signed. */
+    messageHash: Hex;
+    signature: MerkleSignature;
+    /** Registry transaction that anchored it, null while pending. */
+    txHash: Hex | null;
+    anchoredAt: string | null;
+}
+/** Field values allowed inside an attestation digest. Nested objects and arrays are not allowed. */
+export type DigestFields = Record<string, string | number | boolean | null>;
+/** The site that serves verify links and the public API. */
+export declare const DEFAULT_BASE_URL = "https://hashborn.com";
+/** Where records are anchored: PQRegistry on Robinhood Chain. */
+export declare const REGISTRY: {
+    readonly chainId: 4663;
+    readonly address: "0xD791A8Eb2b8C48E5340579A9f91F983AB9597c56";
+};

package/dist/constants.js

@@ -0,0 +1,60 @@
+/**
+ * Protocol v1 constants and the public JSON types. Copied from the reference implementation in
+ * apps/web (lib/pq/contract.ts and lib/types.ts); test/cross.test.ts pins them to it.
+ */
+/**
+ * Fixed parameters of protocol v1: SHA-256, n = 32, w = 16, 67 chains, height 8, 256 leaves.
+ * Signature = 4 + 67 x 32 + 8 x 32 = 2,404 bytes. Public key = root || pubSeed.
+ */
+export const PQ = {
+    hash: 'SHA-256',
+    n: 32,
+    w: 16,
+    len1: 64,
+    len2: 3,
+    len: 67,
+    chainSteps: 15,
+    height: 8,
+    leaves: 256,
+    signatureBytes: 2404,
+    publicKeyBytes: 64,
+};
+/** Protocol name. It prefixes every domain and the pq address hash, and never changes. */
+export const PROTOCOL_DOMAIN = 'pqc-rh';
+export const PROTOCOL_VERSION = 1;
+/**
+ * Attestation domains, protocol v1. Every digest is
+ * SHA-256(domain || "\n" || canonical JSON of the fields, keys sorted).
+ */
+export const DOMAINS = {
+    identity: 'pqc-rh/identity/v1',
+    proof: 'pqc-rh/proof/v1',
+    agent: 'pqc-rh/agent/v1',
+    agentAction: 'pqc-rh/agent-action/v1',
+    transfer: 'pqc-rh/transfer/v1',
+    rwa: 'pqc-rh/rwa/v1',
+    vaultWithdraw: 'pqc-rh/vault-withdraw/v2',
+    statement: 'pqc-rh/statement/v1',
+    official: 'pqc-rh/official/v1',
+};
+/**
+ * Scheme ids an attestation may name. Protocol v1 signs with `wots-merkle` only; the others are
+ * reserved for many-time keys certified by a WOTS leaf.
+ */
+export const SCHEME_IDS = [
+    'wots-merkle',
+    'ml-dsa-65',
+    'slh-dsa-sha2-128s',
+    'falcon-512',
+    'ml-dsa-87',
+    'slh-dsa-shake-128f',
+    'falcon-1024',
+    'secp256k1-ml-dsa-65',
+];
+/** The site that serves verify links and the public API. */
+export const DEFAULT_BASE_URL = 'https://hashborn.com';
+/** Where records are anchored: PQRegistry on Robinhood Chain. */
+export const REGISTRY = {
+    chainId: 4663,
+    address: '0xD791A8Eb2b8C48E5340579A9f91F983AB9597c56',
+};

package/dist/digest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Attestation digests, protocol v1:
+ *   digest = SHA-256(domain || "\n" || canonical JSON of the fields)
+ * Canonical JSON: one object, keys sorted by UTF-16 code unit, no whitespace, values limited to
+ * strings, finite numbers, booleans and null. Amounts and anything beyond 2^53 are strings; a
+ * nested object or array is rejected so two encoders can never disagree on the bytes.
+ */
+import type { DigestFields, Hex } from './constants.js';
+export declare function canonicalJson(fields: DigestFields): string;
+/**
+ * The digest a leaf signs for `fields` under `domain`. Byte-exact with the site, so a record's
+ * fields recompute its `messageHash`.
+ */
+export declare function digest(domain: string, fields: DigestFields): Hex;
+/**
+ * The digest of a record exactly as published (the `record` bytes of a PQRegistry anchor, already
+ * canonical JSON): SHA-256(domain || "\n" || record). This is what the registry computes on chain.
+ */
+export declare function recordDigest(domain: string, record: string): Hex;

package/dist/digest.js

@@ -0,0 +1,48 @@
+/**
+ * Attestation digests, protocol v1:
+ *   digest = SHA-256(domain || "\n" || canonical JSON of the fields)
+ * Canonical JSON: one object, keys sorted by UTF-16 code unit, no whitespace, values limited to
+ * strings, finite numbers, booleans and null. Amounts and anything beyond 2^53 are strings; a
+ * nested object or array is rejected so two encoders can never disagree on the bytes.
+ */
+import { toHex, utf8ToBytes } from './bytes.js';
+import { HashbornError } from './errors.js';
+import { H } from './hash.js';
+export function canonicalJson(fields) {
+    if (fields === null || typeof fields !== 'object' || Array.isArray(fields)) {
+        throw new HashbornError('digest fields must be a plain object');
+    }
+    const proto = Object.getPrototypeOf(fields);
+    if (proto !== Object.prototype && proto !== null)
+        throw new HashbornError('digest fields must be a plain object');
+    const keys = Object.keys(fields).sort();
+    const parts = keys.map((key) => {
+        const value = fields[key];
+        const ok = value === null ||
+            typeof value === 'string' ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value));
+        if (!ok)
+            throw new HashbornError(`digest field "${key}" must be a string, finite number, boolean or null`);
+        return `${JSON.stringify(key)}:${JSON.stringify(value)}`;
+    });
+    return `{${parts.join(',')}}`;
+}
+/**
+ * The digest a leaf signs for `fields` under `domain`. Byte-exact with the site, so a record's
+ * fields recompute its `messageHash`.
+ */
+export function digest(domain, fields) {
+    return recordDigest(domain, canonicalJson(fields));
+}
+/**
+ * The digest of a record exactly as published (the `record` bytes of a PQRegistry anchor, already
+ * canonical JSON): SHA-256(domain || "\n" || record). This is what the registry computes on chain.
+ */
+export function recordDigest(domain, record) {
+    if (typeof domain !== 'string' || domain.length === 0)
+        throw new HashbornError('domain must be a non-empty string');
+    if (typeof record !== 'string')
+        throw new HashbornError('record must be a string');
+    return toHex(H(utf8ToBytes(`${domain}\n${record}`)));
+}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown on malformed input: bad hex, wrong sizes, a link that is not base64url, JSON that is
+ * not an attestation, a record the API does not have. A well-formed attestation whose signature
+ * is wrong is not an error: `verifyAttestation` returns `{valid: false}` with a reason instead.
+ *
+ * `code` is `unsupported` for a well-formed value this protocol version does not define (another
+ * version, scheme, height or domain), `not-found` for a record id the API does not know, `network`
+ * for an API that did not answer, and `malformed` otherwise.
+ */
+export declare class HashbornError extends Error {
+    readonly code: 'malformed' | 'unsupported' | 'not-found' | 'network';
+    name: string;
+    constructor(message: string, code?: 'malformed' | 'unsupported' | 'not-found' | 'network');
+}
+/** @deprecated The class under its name in `@hashborne/verify`; the same class, kept so old imports and `instanceof` checks still work. */
+export declare const HashborneError: typeof HashbornError;

package/dist/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Thrown on malformed input: bad hex, wrong sizes, a link that is not base64url, JSON that is
+ * not an attestation, a record the API does not have. A well-formed attestation whose signature
+ * is wrong is not an error: `verifyAttestation` returns `{valid: false}` with a reason instead.
+ *
+ * `code` is `unsupported` for a well-formed value this protocol version does not define (another
+ * version, scheme, height or domain), `not-found` for a record id the API does not know, `network`
+ * for an API that did not answer, and `malformed` otherwise.
+ */
+export class HashbornError extends Error {
+    code;
+    name = 'HashbornError';
+    constructor(message, code = 'malformed') {
+        super(message);
+        this.code = code;
+    }
+}
+/** @deprecated The class under its name in `@hashborne/verify`; the same class, kept so old imports and `instanceof` checks still work. */
+export const HashborneError = HashbornError;

package/dist/hash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one hash and the one address layout of protocol v1.
+ *
+ * ADRS is 32 bytes, four big-endian u32 fields then 16 zero bytes:
+ *   type   0 chain step, 1 leaf public key, 2 tree node, 3 secret key PRF
+ *   a      leaf index (chain, leaf) or node height (node)
+ *   b      chain index (chain) or node index (node)
+ *   c      chain step (chain only)
+ *
+ * F(pubSeed, ADRS, x) = SHA-256(pubSeed || ADRS || x).
+ */
+export declare const ADRS: {
+    readonly chain: 0;
+    readonly leaf: 1;
+    readonly node: 2;
+};
+export declare function adrs(type: number, a: number, b: number, c?: number): Uint8Array;
+/** SHA-256 over the concatenation of `parts`. */
+export declare function H(...parts: Uint8Array[]): Uint8Array;
+/** The tweakable hash of one chain step. */
+export declare function F(pubSeed: Uint8Array, address: Uint8Array, x: Uint8Array): Uint8Array;

package/dist/hash.js

@@ -0,0 +1,35 @@
+/**
+ * The one hash and the one address layout of protocol v1.
+ *
+ * ADRS is 32 bytes, four big-endian u32 fields then 16 zero bytes:
+ *   type   0 chain step, 1 leaf public key, 2 tree node, 3 secret key PRF
+ *   a      leaf index (chain, leaf) or node height (node)
+ *   b      chain index (chain) or node index (node)
+ *   c      chain step (chain only)
+ *
+ * F(pubSeed, ADRS, x) = SHA-256(pubSeed || ADRS || x).
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { concatBytes } from '@noble/hashes/utils.js';
+export const ADRS = { chain: 0, leaf: 1, node: 2 };
+export function adrs(type, a, b, c = 0) {
+    const out = new Uint8Array(32);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, type, false);
+    view.setUint32(4, a, false);
+    view.setUint32(8, b, false);
+    view.setUint32(12, c, false);
+    return out;
+}
+/** SHA-256 over the concatenation of `parts`. */
+export function H(...parts) {
+    return sha256(parts.length === 1 ? parts[0] : concatBytes(...parts));
+}
+/** The tweakable hash of one chain step. */
+export function F(pubSeed, address, x) {
+    const buf = new Uint8Array(96);
+    buf.set(pubSeed, 0);
+    buf.set(address, 32);
+    buf.set(x, 64);
+    return sha256(buf);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @hashborn/verify: verify Hashborn (protocol pqc-rh v1) records with SHA-256 alone. It supersedes
+ * @hashborne/verify, the same code under the product's earlier name.
+ * Pure functions, no network, except `fetchRecord` and `verifyRemote`, which read the public API
+ * and then verify the published bytes here.
+ */
+export { DEFAULT_BASE_URL, DOMAINS, PQ, PROTOCOL_DOMAIN, PROTOCOL_VERSION, REGISTRY, SCHEME_IDS, type Attestation, type DigestFields, type Domain, type Hex, type MerkleSignature, type SchemeId, } from './constants.js';
+export { HashbornError, HashborneError } from './errors.js';
+export { verifyAttestation, verifyRecord, verifySignature, type FailureCode, type RecordVerifyResult, type SignatureCheck, type VerifyResult, } from './verify.js';
+export { canonicalJson, digest, recordDigest } from './digest.js';
+export { manifestRoot } from './merkle.js';
+export { pqAddress } from './address.js';
+export { decodeSignature, encodeSignature } from './signature.js';
+export { ATTESTATION_MAX_BYTES, checkAttestation, encodeVerifyLink, parseAttestation, parseVerifyLink, } from './attestation.js';
+export { fetchRecord, verifyRemote, type FetchLike, type FetchOptions, type RemoteRecord, type RemoteVerifyResult, } from './remote.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @hashborn/verify: verify Hashborn (protocol pqc-rh v1) records with SHA-256 alone. It supersedes
+ * @hashborne/verify, the same code under the product's earlier name.
+ * Pure functions, no network, except `fetchRecord` and `verifyRemote`, which read the public API
+ * and then verify the published bytes here.
+ */
+export { DEFAULT_BASE_URL, DOMAINS, PQ, PROTOCOL_DOMAIN, PROTOCOL_VERSION, REGISTRY, SCHEME_IDS, } from './constants.js';
+export { HashbornError, HashborneError } from './errors.js';
+export { verifyAttestation, verifyRecord, verifySignature, } from './verify.js';
+export { canonicalJson, digest, recordDigest } from './digest.js';
+export { manifestRoot } from './merkle.js';
+export { pqAddress } from './address.js';
+export { decodeSignature, encodeSignature } from './signature.js';
+export { ATTESTATION_MAX_BYTES, checkAttestation, encodeVerifyLink, parseAttestation, parseVerifyLink, } from './attestation.js';
+export { fetchRecord, verifyRemote, } from './remote.js';

package/dist/merkle.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Merkle trees, protocol v1.
+ *
+ * Identity tree: leaf l_i = SHA-256(pubSeed || ADRS(1, i) || pk_i,0 || ... || pk_i,66) and
+ * node n_h,j = SHA-256(pubSeed || ADRS(2, h, j) || left || right), height 8, 256 leaves.
+ * Verifying climbs the auth path from the leaf and compares the result with the root.
+ *
+ * Manifest tree (RWA documents): leaves are the documents' SHA-256 hashes in the given order,
+ * node = SHA-256(0x01 || left || right), an odd node is paired with itself. The root is always
+ * a node, so a manifest root can never equal a single document hash.
+ */
+import { type Hex } from './constants.js';
+export declare function leafHash(pubSeed: Uint8Array, leaf: number, pks: Uint8Array[]): Uint8Array;
+export declare function nodeHash(pubSeed: Uint8Array, height: number, index: number, left: Uint8Array, right: Uint8Array): Uint8Array;
+/** Recomputes the root from a leaf hash and its auth path. */
+export declare function climb(pubSeed: Uint8Array, leaf: number, leafValue: Uint8Array, auth: Uint8Array[], height: number): Uint8Array;
+export declare function manifestRootBytes(hashes: Uint8Array[]): Uint8Array;
+/**
+ * Merkle root over a list of 32-byte document hashes (RWA manifests), in the given order.
+ * An empty list throws. Compare the result with the `manifestRoot` field of an RWA record.
+ */
+export declare function manifestRoot(hashes: readonly Hex[]): Hex;

package/dist/merkle.js

@@ -0,0 +1,69 @@
+/**
+ * Merkle trees, protocol v1.
+ *
+ * Identity tree: leaf l_i = SHA-256(pubSeed || ADRS(1, i) || pk_i,0 || ... || pk_i,66) and
+ * node n_h,j = SHA-256(pubSeed || ADRS(2, h, j) || left || right), height 8, 256 leaves.
+ * Verifying climbs the auth path from the leaf and compares the result with the root.
+ *
+ * Manifest tree (RWA documents): leaves are the documents' SHA-256 hashes in the given order,
+ * node = SHA-256(0x01 || left || right), an odd node is paired with itself. The root is always
+ * a node, so a manifest root can never equal a single document hash.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { fromHex, toHex } from './bytes.js';
+import { PQ } from './constants.js';
+import { HashbornError } from './errors.js';
+import { ADRS, H, adrs } from './hash.js';
+export function leafHash(pubSeed, leaf, pks) {
+    const buf = new Uint8Array(64 + pks.length * PQ.n);
+    buf.set(pubSeed, 0);
+    buf.set(adrs(ADRS.leaf, leaf, 0), 32);
+    pks.forEach((pk, i) => buf.set(pk, 64 + i * PQ.n));
+    return sha256(buf);
+}
+export function nodeHash(pubSeed, height, index, left, right) {
+    return H(pubSeed, adrs(ADRS.node, height, index), left, right);
+}
+/** Recomputes the root from a leaf hash and its auth path. */
+export function climb(pubSeed, leaf, leafValue, auth, height) {
+    if (auth.length !== height)
+        throw new HashbornError(`auth path must have ${height} nodes`);
+    let node = leafValue;
+    let index = leaf;
+    for (let h = 0; h < height; h++) {
+        const sibling = auth[h];
+        const parentIndex = index >> 1;
+        node = (index & 1) === 1 ? nodeHash(pubSeed, h + 1, parentIndex, sibling, node) : nodeHash(pubSeed, h + 1, parentIndex, node, sibling);
+        index = parentIndex;
+    }
+    return node;
+}
+const MANIFEST_NODE_PREFIX = new Uint8Array([1]);
+export function manifestRootBytes(hashes) {
+    if (hashes.length === 0)
+        throw new HashbornError('a manifest needs at least one document hash');
+    let level = hashes.map((h, i) => {
+        if (h.length !== PQ.n)
+            throw new HashbornError(`document hash ${i} must be ${PQ.n} bytes`);
+        return h;
+    });
+    do {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const left = level[i];
+            const right = i + 1 < level.length ? level[i + 1] : left;
+            next.push(H(MANIFEST_NODE_PREFIX, left, right));
+        }
+        level = next;
+    } while (level.length > 1);
+    return level[0];
+}
+/**
+ * Merkle root over a list of 32-byte document hashes (RWA manifests), in the given order.
+ * An empty list throws. Compare the result with the `manifestRoot` field of an RWA record.
+ */
+export function manifestRoot(hashes) {
+    if (!Array.isArray(hashes))
+        throw new HashbornError('manifest leaves must be an array of 32-byte hex hashes');
+    return toHex(manifestRootBytes(hashes.map((h, i) => fromHex(h, PQ.n, `leaves[${i}]`))));
+}

package/dist/remote.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Reading a published record from the Hashborn API and verifying it here. The API is only a
+ * transport: the server's own `verified` flag is never read. The record text, signature, root and
+ * pubSeed it returns are checked locally with SHA-256, exactly as `verifyRecord` checks them.
+ *
+ * Source: `GET /api/v1/records/<id>`. When that answer carries no signature (the v1 record view
+ * leaves the 2,404 signature bytes out), the published bytes are read from
+ * `GET /api/index?q=record&id=<id>`, the same index route the site's pages read.
+ */
+import { type Attestation, type DigestFields, type Hex } from './constants.js';
+import { type RecordVerifyResult } from './verify.js';
+/** The subset of `fetch` this module uses; the global `fetch` fits it. */
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface FetchOptions {
+    /** Site that serves the API. Default https://hashborn.com. Redirects are followed (fetch's default), so an earlier address that redirects here keeps working. */
+    baseUrl?: string;
+    /** A fetch implementation. Default the global `fetch`. */
+    fetch?: FetchLike;
+}
+/** One anchored record as published, with its attestation built from the published bytes. */
+export interface RemoteRecord {
+    /** Anchoring transaction hash followed by the log index as 4 bytes. */
+    id: Hex;
+    attestation: Attestation;
+    /** The record text exactly as anchored (canonical JSON). */
+    record: string;
+    /** The record's fields, or null when the text is not a flat JSON object. */
+    fields: DigestFields | null;
+    /** The leaf the anchor burned. */
+    leaf: number;
+    /** The registered wallet that anchored it. */
+    wallet: Hex;
+    txHash: Hex;
+    blockNumber: number;
+    /** ISO time of the anchoring block. */
+    anchoredAt: string;
+    chainId: number | null;
+    /** Which route served the signature bytes. */
+    source: 'v1' | 'index';
+}
+export declare const RECORD_ID_RE: RegExp;
+/**
+ * Reads one anchored record (id = anchoring transaction hash + log index, as on
+ * `/records/<id>`) and builds its attestation from the published bytes. Does not verify: pass the
+ * result to `verifyRecord(r.attestation, r.record)`, or call `verifyRemote`.
+ * Throws a HashbornError (`not-found`, `network`, `malformed`) when there is nothing to verify.
+ */
+export declare function fetchRecord(id: string, options?: FetchOptions): Promise<RemoteRecord>;
+export interface RemoteVerifyResult extends RecordVerifyResult {
+    id: Hex;
+    remote: RemoteRecord;
+}
+/**
+ * `fetchRecord` then `verifyRecord` here, on the published bytes: the record text must hash to
+ * `messageHash`, the signature must climb to the identity's root, and the leaf the anchor burned
+ * must be the leaf that signed. The server's own verdict is never used.
+ */
+export declare function verifyRemote(id: string, options?: FetchOptions): Promise<RemoteVerifyResult>;