@hcs-witness/verify 0.0.0 → 1.0.0

package/dist/check.js

@@ -0,0 +1,100 @@
+/**
+ * Évaluateur JSON Schema minimal : couvre exactement les constructions
+ * des schémas exportés (type, const, anyOf, properties, required,
+ * additionalProperties, patternProperties, items, pattern, minLength,
+ * minimum). Ce n'est PAS un moteur JSON Schema général — les schémas
+ * sont fixes et internes au format de preuve HCS Witness.
+ */
+const regexCache = new Map();
+function regex(pattern) {
+    let r = regexCache.get(pattern);
+    if (r === undefined) {
+        r = new RegExp(pattern);
+        regexCache.set(pattern, r);
+    }
+    return r;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkType(type, value) {
+    switch (type) {
+        case "object":
+            return isObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            return false;
+    }
+}
+export function checkSchema(schema, value) {
+    if (schema.anyOf !== undefined) {
+        return schema.anyOf.some((s) => checkSchema(s, value));
+    }
+    if (schema.const !== undefined && value !== schema.const) {
+        return false;
+    }
+    if (schema.type !== undefined && !checkType(schema.type, value)) {
+        return false;
+    }
+    if (typeof value === "string") {
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            return false;
+        }
+        if (schema.pattern !== undefined && !regex(schema.pattern).test(value)) {
+            return false;
+        }
+    }
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            return false;
+        }
+    }
+    if (Array.isArray(value)) {
+        const items = schema.items;
+        if (items !== undefined &&
+            !value.every((item) => checkSchema(items, item))) {
+            return false;
+        }
+    }
+    if (isObject(value)) {
+        for (const key of schema.required ?? []) {
+            if (!(key in value))
+                return false;
+        }
+        const props = schema.properties ?? {};
+        const patterns = Object.entries(schema.patternProperties ?? {}).map(([p, s]) => ({ r: regex(p), s }));
+        const strict = schema.additionalProperties === false;
+        for (const [key, member] of Object.entries(value)) {
+            const known = Object.hasOwn(props, key);
+            let matched = false;
+            if (known) {
+                const sub = props[key];
+                if (sub !== undefined && !checkSchema(sub, member)) {
+                    return false;
+                }
+            }
+            for (const { r, s } of patterns) {
+                if (r.test(key)) {
+                    matched = true;
+                    if (!checkSchema(s, member))
+                        return false;
+                }
+            }
+            if (!known && !matched && strict) {
+                return false;
+            }
+        }
+    }
+    return true;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { verifyAnchor } from "./anchor.js";
+import { verifyProof } from "./verify.js";
+const USAGE = "Usage: hcs-witness-verify <proof.json> --keys <keys.json> [--now <rfc3339>] [--json]";
+function parseArgs(args) {
+    let proof;
+    let keys;
+    let now;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args.at(i);
+        if (a === "--keys") {
+            keys = args.at(i + 1);
+            i += 1;
+        }
+        else if (a === "--now") {
+            const raw = args.at(i + 1) ?? "";
+            const t = Date.parse(raw);
+            if (Number.isNaN(t))
+                throw new Error("invalid --now value");
+            now = new Date(t);
+            i += 1;
+        }
+        else if (a === "--json") {
+            json = true;
+        }
+        else if (a?.startsWith("-")) {
+            throw new Error(`unknown option: ${a}`);
+        }
+        else if (proof === undefined) {
+            proof = a;
+        }
+        else {
+            throw new Error("unexpected extra argument");
+        }
+    }
+    if (proof === undefined || keys === undefined) {
+        throw new Error("missing arguments");
+    }
+    const out = {
+        proof,
+        keys,
+        json,
+    };
+    if (now !== undefined)
+        out.now = now;
+    return out;
+}
+function loadJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+try {
+    const opts = parseArgs(process.argv.slice(2));
+    const proof = loadJson(opts.proof);
+    const keys = loadJson(opts.keys);
+    const result = verifyProof(proof, keys, opts.now === undefined ? undefined : { now: opts.now });
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        const expired = result.errors.includes("PROOF_EXPIRED");
+        const authErrors = result.errors.filter((e) => e !== "PROOF_EXPIRED");
+        process.stdout.write(`proof_id: ${result.proof_id ?? "unknown"}\n`);
+        if (result.valid) {
+            process.stdout.write("status: VALID\n");
+        }
+        else {
+            process.stdout.write(`status: INVALID (${authErrors.join(", ") || "see errors"})\n`);
+        }
+        if (expired) {
+            process.stdout.write("note: proof is EXPIRED (signature authenticity intact)\n");
+        }
+        // Bloc presence (étape 5) : affiché pour information, JAMAIS
+        // utilisé pour la validité cryptographique.
+        const presence = proof.presence;
+        if (presence !== undefined && presence !== null) {
+            const p = presence;
+            const synced = (p.flags ?? []).includes("synced_passkey");
+            process.stdout.write(`presence: measured, not yet rated (challenge: ${p.challenge?.kind ?? "unknown"}${synced ? ", synced passkey" : ""})
+`);
+        }
+        const anchor = verifyAnchor(proof);
+        if (anchor.present) {
+            process.stdout.write(`anchor: merkle inclusion ${anchor.inclusion ? "OK" : "KO"}\n`);
+            if (anchor.otsMatchesRoot === false) {
+                process.stdout.write("anchor: ots file does NOT attest this root\n");
+            }
+            if (anchor.bitcoinBlockHeight !== undefined) {
+                process.stdout.write(`anchor: bitcoin block ${String(anchor.bitcoinBlockHeight)} (attested by the .ots file)\n`);
+            }
+            else if (anchor.pendingCalendars.length > 0) {
+                process.stdout.write(`anchor: pending (${anchor.pendingCalendars.join(", ")})\n`);
+            }
+            process.stdout.write("note: block confirmation is to be done with a node or an explorer\n");
+        }
+    }
+    process.exit(result.valid ? 0 : 1);
+}
+catch (error) {
+    process.stdout.write(`${error instanceof Error ? error.message : String(error)}\n${USAGE}\n`);
+    process.exit(2);
+}

package/dist/hash.d.ts

@@ -0,0 +1,3 @@
+/** SHA-256 via node:crypto — retourne un Uint8Array (Buffer). */
+export declare function sha256(data: Uint8Array): Uint8Array;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEnD"}

package/dist/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** SHA-256 via node:crypto — retourne un Uint8Array (Buffer). */
+export function sha256(data) {
+    return createHash("sha256").update(data).digest();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { canonicalBytes, NonJsonValueError } from "./jcs.js";
+export { bytesToB64url, b64urlToBytes } from "./base64.js";
+export { checkSchema, type JsonSchema } from "./check.js";
+export { keysetSchema, isKeyset, type Keyset, type KeysetKey, type Es256KeysetKey, type MlDsaKeysetKey, } from "./keyset.js";
+export { verifyProof, ML_DSA_CONTEXT, type VerifyResult, type VerifyErrorCode, type VerifyOptions, } from "./verify.js";
+export { proofSchema, unsignedProofSchema, isProof, isUnsignedProof, signedPayload, type Proof, type Presence, type PresenceChallenge, type ProofAnchor, type ProofSignature, type UnsignedProof, } from "./schema.js";
+export { checkActionBinding, type BindingCheck, type BindingErrorCode, type BindingResult, } from "./binding.js";
+export { merkleLeafHash, merkleNodeHash, merkleRoot, merklePath, verifyMerkleInclusion, } from "./merkle.js";
+export { OtsError, parseOtsFile, serializeOtsFile, serializeTimestamp, allAttestations, bitcoinBlockHeight, type OtsFile, type OtsOp, type OtsAttestation, type OtsTimestamp, } from "./ots.js";
+export { verifyAnchor, type AnchorResult } from "./anchor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,OAAO,EACP,eAAe,EACf,aAAa,EACb,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,cAAc,EACd,UAAU,EACV,UAAU,EACV,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { canonicalBytes, NonJsonValueError } from "./jcs.js";
+export { bytesToB64url, b64urlToBytes } from "./base64.js";
+export { checkSchema } from "./check.js";
+export { keysetSchema, isKeyset, } from "./keyset.js";
+export { verifyProof, ML_DSA_CONTEXT, } from "./verify.js";
+export { proofSchema, unsignedProofSchema, isProof, isUnsignedProof, signedPayload, } from "./schema.js";
+export { checkActionBinding, } from "./binding.js";
+export { merkleLeafHash, merkleNodeHash, merkleRoot, merklePath, verifyMerkleInclusion, } from "./merkle.js";
+export { OtsError, parseOtsFile, serializeOtsFile, serializeTimestamp, allAttestations, bitcoinBlockHeight, } from "./ots.js";
+export { verifyAnchor } from "./anchor.js";

package/dist/jcs.d.ts

@@ -0,0 +1,5 @@
+export declare class NonJsonValueError extends Error {
+    constructor(path: string, reason: string);
+}
+export declare function canonicalBytes(value: unknown): Uint8Array;
+//# sourceMappingURL=jcs.d.ts.map

package/dist/jcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jcs.d.ts","sourceRoot":"","sources":["../src/jcs.ts"],"names":[],"mappings":"AAEA,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIzC;AAmDD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAOzD"}

package/dist/jcs.js

@@ -0,0 +1,60 @@
+import canonicalize from "canonicalize";
+export class NonJsonValueError extends Error {
+    constructor(path, reason) {
+        super(`non-JSON value at ${path}: ${reason}`);
+        this.name = "NonJsonValueError";
+    }
+}
+function assertJsonValue(value, path, seen) {
+    if (value === undefined) {
+        throw new NonJsonValueError(path, "undefined");
+    }
+    if (value === null) {
+        return;
+    }
+    switch (typeof value) {
+        case "boolean":
+        case "string":
+            return;
+        case "number":
+            if (!Number.isFinite(value)) {
+                throw new NonJsonValueError(path, "non-finite number");
+            }
+            return;
+        case "object":
+            break;
+        default:
+            throw new NonJsonValueError(path, typeof value);
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        throw new NonJsonValueError(path, "cyclic reference");
+    }
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            obj.forEach((item, index) => {
+                assertJsonValue(item, `${path}[${String(index)}]`, seen);
+            });
+            return;
+        }
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new NonJsonValueError(path, "non-plain object");
+        }
+        for (const [key, member] of Object.entries(obj)) {
+            assertJsonValue(member, `${path}.${key}`, seen);
+        }
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+export function canonicalBytes(value) {
+    assertJsonValue(value, "$", new Set());
+    const out = canonicalize(value);
+    if (out === undefined) {
+        throw new NonJsonValueError("$", "canonicalize returned undefined");
+    }
+    return new TextEncoder().encode(out);
+}

package/dist/keyset.d.ts

@@ -0,0 +1,30 @@
+import { type JsonSchema } from "./check.js";
+/** Schéma JSON du jeu de clés publiques (/.well-known/hcs-keys.json). */
+export declare const keysetSchema: JsonSchema;
+interface KeysetKeyBase {
+    use: "sig";
+    kid: string;
+    status: "active" | "retired";
+    not_before: string;
+    not_after?: string;
+}
+export interface Es256KeysetKey extends KeysetKeyBase {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+    alg: "ES256";
+}
+export interface MlDsaKeysetKey extends KeysetKeyBase {
+    kty: "AKP";
+    alg: "ML-DSA-65";
+    pub: string;
+}
+export type KeysetKey = Es256KeysetKey | MlDsaKeysetKey;
+export interface Keyset {
+    _comment?: string;
+    keys: KeysetKey[];
+}
+export declare function isKeyset(value: unknown): value is Keyset;
+export {};
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset.d.ts","sourceRoot":"","sources":["../src/keyset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAuB1D,yEAAyE;AACzE,eAAO,MAAM,YAAY,EAAE,UAsC1B,CAAC;AAEF,UAAU,aAAa;IACrB,GAAG,EAAE,KAAK,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,EAAE,OAAO,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,GAAG,EAAE,KAAK,CAAC;IACX,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,cAAc,CAAC;AAExD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}

package/dist/keyset.js

@@ -0,0 +1,62 @@
+import { checkSchema } from "./check.js";
+const b64url = { type: "string", pattern: "^[A-Za-z0-9_-]+$" };
+const rfc3339Utc = {
+    type: "string",
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$",
+};
+const keyBase = {
+    use: { const: "sig", type: "string" },
+    kid: { type: "string", minLength: 1 },
+    status: {
+        anyOf: [
+            { const: "active", type: "string" },
+            { const: "retired", type: "string" },
+        ],
+    },
+    not_before: rfc3339Utc,
+    not_after: rfc3339Utc,
+};
+const keyBaseRequired = ["use", "kid", "status", "not_before"];
+/** Schéma JSON du jeu de clés publiques (/.well-known/hcs-keys.json). */
+export const keysetSchema = {
+    type: "object",
+    required: ["keys"],
+    additionalProperties: false,
+    properties: {
+        _comment: { type: "string" },
+        keys: {
+            type: "array",
+            items: {
+                anyOf: [
+                    {
+                        type: "object",
+                        required: ["kty", "crv", "x", "y", "alg", ...keyBaseRequired],
+                        additionalProperties: false,
+                        properties: {
+                            kty: { const: "EC", type: "string" },
+                            crv: { const: "P-256", type: "string" },
+                            x: b64url,
+                            y: b64url,
+                            alg: { const: "ES256", type: "string" },
+                            ...keyBase,
+                        },
+                    },
+                    {
+                        type: "object",
+                        required: ["kty", "alg", "pub", ...keyBaseRequired],
+                        additionalProperties: false,
+                        properties: {
+                            kty: { const: "AKP", type: "string" },
+                            alg: { const: "ML-DSA-65", type: "string" },
+                            pub: b64url,
+                            ...keyBase,
+                        },
+                    },
+                ],
+            },
+        },
+    },
+};
+export function isKeyset(value) {
+    return checkSchema(keysetSchema, value);
+}

package/dist/merkle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Arbre de Merkle de type RFC 6962 (Certificate Transparency) avec
+ * séparation de domaine :
+ *   feuille = SHA-256(0x00 ‖ SHA-256(signedPayload))
+ *   nœud    = SHA-256(0x01 ‖ gauche ‖ droite)
+ * Nombre impair de feuilles : la dernière est promue (règle DTR, le
+ * plus grand k = 2^m < n), jamais dupliquée.
+ */
+export declare function merkleLeafHash(signedPayload: Uint8Array): Uint8Array;
+export declare function merkleNodeHash(left: Uint8Array, right: Uint8Array): Uint8Array;
+/** Racine Merkle d'une liste de feuilles déjà hachées (merkleLeafHash). */
+export declare function merkleRoot(leaves: readonly Uint8Array[]): Uint8Array;
+/**
+ * Chemin d'inclusion (audit path) de la feuille `index`, dans l'ordre
+ * de remontée vers la racine : PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n])
+ * pour m < k (RFC 6962 §2.1.1).
+ */
+export declare function merklePath(leaves: readonly Uint8Array[], index: number): Uint8Array[];
+/**
+ * Vérification hors ligne : la feuille `leaf` (déjà hachée par
+ * merkleLeafHash) remonte-t-elle à `root` via `path` ? Miroir exact de
+ * merklePath : chaque entrée du chemin est consommée une fois, dans
+ * l'ordre.
+ */
+export declare function verifyMerkleInclusion(leaf: Uint8Array, index: number, leafCount: number, path: readonly Uint8Array[], root: Uint8Array): boolean;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAAC,aAAa,EAAE,UAAU,GAAG,UAAU,CAEpE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,UAAU,GAChB,UAAU,CAEZ;AAmCD,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CAqBd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,IAAI,EAAE,UAAU,GACf,OAAO,CAsCT"}

package/dist/merkle.js

@@ -0,0 +1,120 @@
+import { sha256 } from "./hash.js";
+/**
+ * Arbre de Merkle de type RFC 6962 (Certificate Transparency) avec
+ * séparation de domaine :
+ *   feuille = SHA-256(0x00 ‖ SHA-256(signedPayload))
+ *   nœud    = SHA-256(0x01 ‖ gauche ‖ droite)
+ * Nombre impair de feuilles : la dernière est promue (règle DTR, le
+ * plus grand k = 2^m < n), jamais dupliquée.
+ */
+export function merkleLeafHash(signedPayload) {
+    return sha256(Uint8Array.from([0x00, ...sha256(signedPayload)]));
+}
+export function merkleNodeHash(left, right) {
+    return sha256(Uint8Array.from([0x01, ...left, ...right]));
+}
+function bytesEq(a, b) {
+    return a.length === b.length && a.every((x, i) => x === b.at(i));
+}
+/** Plus grande puissance de 2 strictement inférieure à n (n > 1). */
+function splitK(n) {
+    let k = 1;
+    while (k * 2 < n) {
+        k *= 2;
+    }
+    return k;
+}
+/** Hash d'un sous-arbre DTR sur des feuilles déjà hachées. */
+function subtreeHash(leaves) {
+    const n = leaves.length;
+    if (n === 0) {
+        throw new Error("empty subtree");
+    }
+    if (n === 1) {
+        const leaf = leaves[0];
+        if (leaf === undefined) {
+            throw new Error("missing leaf");
+        }
+        return leaf;
+    }
+    const k = splitK(n);
+    return merkleNodeHash(subtreeHash(leaves.slice(0, k)), subtreeHash(leaves.slice(k)));
+}
+/** Racine Merkle d'une liste de feuilles déjà hachées (merkleLeafHash). */
+export function merkleRoot(leaves) {
+    return subtreeHash(leaves);
+}
+/**
+ * Chemin d'inclusion (audit path) de la feuille `index`, dans l'ordre
+ * de remontée vers la racine : PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n])
+ * pour m < k (RFC 6962 §2.1.1).
+ */
+export function merklePath(leaves, index) {
+    const n = leaves.length;
+    if (index < 0 || index >= n) {
+        throw new Error("leaf index out of range");
+    }
+    const path = [];
+    const walk = (lo, count, idx) => {
+        if (count === 1) {
+            return;
+        }
+        const k = splitK(count);
+        if (idx < k) {
+            walk(lo, k, idx);
+            path.push(subtreeHash(leaves.slice(lo + k, lo + count)));
+        }
+        else {
+            walk(lo + k, count - k, idx - k);
+            path.push(subtreeHash(leaves.slice(lo, lo + k)));
+        }
+    };
+    walk(0, n, index);
+    return path;
+}
+/**
+ * Vérification hors ligne : la feuille `leaf` (déjà hachée par
+ * merkleLeafHash) remonte-t-elle à `root` via `path` ? Miroir exact de
+ * merklePath : chaque entrée du chemin est consommée une fois, dans
+ * l'ordre.
+ */
+export function verifyMerkleInclusion(leaf, index, leafCount, path, root) {
+    if (leafCount < 1 || index < 0 || index >= leafCount) {
+        return false;
+    }
+    let consumed = 0;
+    const walk = (count, idx) => {
+        if (count === 1) {
+            return leaf;
+        }
+        const k = splitK(count);
+        // Miroir de merklePath : le sous-arbre porteur d'abord (il consomme
+        // les entrées profondes), puis le sibling de CE niveau.
+        let current;
+        let sibling;
+        if (idx < k) {
+            current = walk(k, idx);
+            sibling = path.at(consumed);
+            if (sibling === undefined) {
+                throw new Error("path too short");
+            }
+            consumed += 1;
+            return merkleNodeHash(current, sibling);
+        }
+        current = walk(count - k, idx - k);
+        sibling = path.at(consumed);
+        if (sibling === undefined) {
+            throw new Error("path too short");
+        }
+        consumed += 1;
+        return merkleNodeHash(sibling, current);
+    };
+    let computed;
+    try {
+        computed = walk(leafCount, index);
+    }
+    catch {
+        return false;
+    }
+    return consumed === path.length && bytesEq(computed, root);
+}

package/dist/ots.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Client OpenTimestamps minimal (ADR 0009) — format .ots uniquement.
+ * Périmètre strict : opérations sha256 / append / prepend,
+ * attestations pending et Bitcoin. Toute autre opération ou
+ * attestation est une erreur explicite, jamais ignorée. Aucun réseau.
+ *
+ * Référence du format : opentimestamps/python-opentimestamps,
+ * opentimestamps/core/{timestamp,op,notary,serialize}.py.
+ */
+export declare class OtsError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface OtsOp {
+    readonly kind: "sha256" | "append" | "prepend";
+    readonly arg?: Uint8Array;
+}
+export interface OtsAttestation {
+    readonly kind: "pending" | "bitcoin";
+    readonly uri?: string;
+    readonly height?: number;
+}
+export interface OtsTimestamp {
+    readonly msg: Uint8Array;
+    readonly attestations: OtsAttestation[];
+    readonly ops: {
+        op: OtsOp;
+        stamp: OtsTimestamp;
+    }[];
+}
+export interface OtsFile {
+    readonly fileDigest: Uint8Array;
+    readonly timestamp: OtsTimestamp;
+}
+/** Lit un fichier .ots complet. Jamais d'exception non gérée : OtsError. */
+export declare function parseOtsFile(input: Uint8Array): OtsFile;
+/** Sérialise un Timestamp (ordre canonique : attestations puis ops). */
+export declare function serializeTimestamp(stamp: OtsTimestamp): Uint8Array;
+/** Fabrique un fichier .ots : magic ‖ version ‖ sha256 ‖ digest ‖ timestamp. */
+export declare function serializeOtsFile(fileDigest: Uint8Array, timestampBytes: Uint8Array): Uint8Array;
+/** Toutes les attestations de l'arbre (avec le msg attesté). */
+export declare function allAttestations(stamp: OtsTimestamp): {
+    msg: Uint8Array;
+    attestation: OtsAttestation;
+}[];
+/** Plus petite hauteur de bloc Bitcoin attestée, si présente. */
+export declare function bitcoinBlockHeight(stamp: OtsTimestamp): number | undefined;
+//# sourceMappingURL=ots.d.ts.map

package/dist/ots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ots.d.ts","sourceRoot":"","sources":["../src/ots.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAmCD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,cAAc,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CAClC;AAwLD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CA4BvD;AAyFD,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAwClE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,UAAU,GACzB,UAAU,CAWZ;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG;IACpD,GAAG,EAAE,UAAU,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;CAC7B,EAAE,CASF;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAK1E"}