@mikeargento/bitgraph 1.10.0 → 1.11.0

package/dist/recovery.d.ts

@@ -0,0 +1,490 @@
+/**
+ * Recovering a BitGraph from the file: bitgraph-recovery/1 (2026-10-03).
+ *
+ * THE RULE (Mike): anyone holding a file can always get its proof back, and
+ * export it again, if the export was lost.
+ *
+ * RECOVERY IS NOT VERIFICATION. Verification needs nothing of ours: an export
+ * and the file check themselves (packages/verify, export.ts). Recovery uses
+ * our bucket, and only to answer one question for whoever holds the bytes:
+ * which BitGraphs hold these bytes, and where is each one's proof? Each entry
+ * hands back exactly what a member's export carries (the root document and
+ * the member's evidence) plus a locator for the proof itself, which is then
+ * fetched from the public proof routes and verifies with nothing of ours.
+ *
+ * WHAT IS WRITTEN. For every member of a tree, up to two sealed entries: one
+ * under the file's origin digest (the file as dropped) and one under its
+ * artifact digest (the committed bytes), so either file in hand finds it. An
+ * as-is leaf (placement 0x00) has one digest and earns one entry.
+ *
+ * FORMATS. Hex is lowercase. digest32 is the RAW 32-byte SHA-256, never its
+ * text; proofHash32 is the raw 32 bytes of computeProofHash(proof) (the
+ * ledger identity, base64 in the verify package).
+ *
+ *   address   = hex SHA-256( UTF-8 "bitgraph-lookup"       || digest32 )
+ *   entryId   = hex SHA-256( UTF-8 "bitgraph-lookup-entry" || digest32 || proofHash32 || leafIndex u32 big-endian )
+ *   saltedId  = hex SHA-256( UTF-8 "bitgraph-lookup-entry/salted" || digest32 || proofHash32 || leafIndex u32 big-endian || salt32 )
+ *               the fallback name when the deterministic key is held by another entry (squatting, below);
+ *               the salt (32 random bytes) is sealed in the plaintext, so a reader checks the name either way
+ *   key       =     SHA-256( UTF-8 "bitgraph-lookup-key"   || digest32 )          the AES-256-GCM key
+ *   objectKey = "recovery/v1/" + address + "/" + entryId
+ *   envelope  = 0x01 || nonce (12 random bytes, fresh per entry) || ciphertext || tag (16)
+ *               AAD = objectKey as UTF-8
+ *   plaintext = UTF-8 JSON, written in this key order:
+ *               { "format": "bitgraph-recovery/1",
+ *                 "proofHash": base64 (44),
+ *                 "leafIndex": n,
+ *                 "rootDocument": hex (168),
+ *                 "member": { "index", "count", "leaf", "path" }       TreeMemberEvidence
+ *                 "proof": { "epochId", "counter", "artifactDigestB64" } a locator
+ *                 "salt"?: base64 (44),                                 present exactly when the entry is salted
+ *                 "name"?: string }                                     advisory, at most 512 UTF-8 bytes
+ *
+ * The four labels differ and every input after a label is fixed length, so
+ * the four preimages (47, 51, 89 and 128 bytes) can never be confused with
+ * one another. The address is public (it is in the object key); the key is
+ * not derivable from it without the digest.
+ *
+ * SQUATTING, AND THE SALTED FALLBACK. Keys are deterministic and writes are
+ * create-only, so whoever knows a file's digest and its proof hash can occupy
+ * a member's deterministic key first. They cannot make a wrong proof come
+ * back (a reader binds every entry to its proof and verifies the member), but
+ * they could deny that one entry. So a writer that finds another member's
+ * envelope at its deterministic key writes the same plaintext, plus a fresh
+ * 32-byte salt, under the salted name instead; a reader accepts either name
+ * when the plaintext derives it, and lists one member once however many
+ * names it has. The salt is kept by the writer before the salted write, so a
+ * retry lands on the same key. Listing spam under an address stays a
+ * rate-limit matter.
+ *
+ * LOOKING UP MANY FILES AT ONCE. recoverFromDigests asks one request for the
+ * first page of many addresses. That tells the server which addresses were
+ * asked together, a linkage one-by-one requests only hint at by timing; the
+ * route logs counts, never addresses, and the SPEC says so.
+ *
+ * WHY THE ENTRY ID IS A HASH. The first draft keyed entries
+ * "<address>/<proofHash>/<leafIndex>", which let anyone listing the bucket
+ * group every entry of one drop by the shared proofHash. The entryId is still
+ * deterministic (a rewrite after a crash lands on the same key, so writes stay
+ * idempotent) and two members of one tree never collide (the leaf index is in
+ * it), but it says nothing about which tree it belongs to without the digest.
+ *
+ * PRIVACY, AND ITS LIMIT. The server sees object keys and opaque envelopes,
+ * never a digest, a proof hash, a leaf or a name. But anyone who KNOWS a
+ * file's digest (holding the file, a published digest, or guessing among a
+ * few candidate files) can derive the address and key and test whether it was
+ * recorded; that is the same ability recovery needs. The promise covers these
+ * sealed entries only, not older plain-digest indexes, logs or metadata. (One
+ * piece of metadata worth naming: the entries of one drop are written in the
+ * same requests and land with near-identical write times, so whoever can list
+ * the bucket can group them by time. Today that is only BitGraph.)
+ *
+ * WHAT A STORED ENTRY IS WORTH. Whoever holds the file can write an entry for
+ * it; that is the rule working, not a hole. So an entry is never trusted for
+ * holding the right key: it is opened (AES-GCM, AAD the object key), parsed
+ * strictly, its entryId recomputed, its leaf checked to name the looked-up
+ * digest, its path checked to reach the root inside its own root document,
+ * and that document checked to hash to the locator's digest. Then the proof is
+ * fetched and bound by proofHash and verifyTreeMember (fetchRecoveredProof).
+ * A writer who knows the digest can occupy a key; they cannot make a wrong
+ * proof come back as this file's. (The queue reports a member whose key was
+ * occupied first as "blocked", and keeps writing its other entry.)
+ *
+ * CREATE-ONLY. Entries are written with If-None-Match: * and never replaced;
+ * see recovery-store-s3.ts for the bucket policy that keeps a delete marker
+ * from ever letting a second version in under the same key.
+ *
+ * SHA-256 here is @noble/hashes (as in packages/verify), AES-GCM is WebCrypto.
+ * Both run unchanged in the browser and in node 20+. The hashes are noble's
+ * rather than crypto.subtle.digest's because a tree of 100,000 files needs
+ * 600,000 small hashes: measured on node 24, 300,000 cost 275 ms through
+ * noble and 2,368 ms through subtle (one promise and thread hop each). The
+ * bytes are identical; the test suite derives every format again with
+ * node:crypto to prove it.
+ */
+import { MerkleTree, type BitGraphProof, type TreeLeaf, type TreeMemberEvidence, type TreeVerifyResult, type ByteSource } from "@mikeargento/bitgraph-verify";
+export declare const RECOVERY_FORMAT: "bitgraph-recovery/1";
+export declare const RECOVERY_PREFIX: "recovery/v1/";
+export declare const ENVELOPE_VERSION = 1;
+export declare const NONCE_BYTES = 12;
+export declare const TAG_BYTES = 16;
+/** Version byte, nonce and tag: 29 bytes around the ciphertext. */
+export declare const ENVELOPE_OVERHEAD: number;
+/**
+ * The largest envelope anyone may store. Sized from the response, not the
+ * entry: a batch of MAX_BATCH_ENTRIES whose keys all exist comes back with
+ * every stored envelope in it, and a Vercel function answers at most 4.5 MB.
+ * 500 x 4,096 bytes is 2.7 MB as base64, in both directions. The largest
+ * honest plaintext (a 1,000,000-leaf tree's 20-node path, the longest
+ * locator, a 512-byte name) is about 3.1 KB; the suite pins that it fits.
+ */
+export declare const MAX_ENVELOPE_BYTES = 4096;
+export declare const MIN_ENVELOPE_BYTES: number;
+export declare const MAX_PLAINTEXT_BYTES: number;
+/** A name longer than this keeps its last 509 bytes behind "…" (a path's tail is the file's own name). */
+export declare const MAX_NAME_BYTES = 512;
+/** Entries per POST. */
+export declare const MAX_BATCH_ENTRIES = 500;
+/** A POST body above this is refused before it is parsed. A full batch of the largest envelopes is about 2.8 MB. */
+export declare const MAX_BODY_BYTES = 4000000;
+/** Entries per page of GET /api/recovery/<address>. */
+export declare const MAX_LIST_LIMIT = 100;
+export declare const ADDRESS_PATTERN: RegExp;
+export declare const ENTRY_ID_PATTERN: RegExp;
+export declare const OBJECT_KEY_PATTERN: RegExp;
+/** "recovery/v1/" + 64 + "/" + 64. */
+export declare const OBJECT_KEY_LENGTH: number;
+/** A salted entry's salt: 32 random bytes, sealed in its plaintext. */
+export declare const SALT_BYTES = 32;
+/** Addresses one lookup request may ask for (POST /api/recovery/lookup). */
+export declare const MAX_LOOKUP_ADDRESSES = 1000;
+/** The most a lookup answer carries (under the hosting platform's 4.5 MB response limit); addresses past it come back `truncated` and are listed one by one. */
+export declare const MAX_LOOKUP_RESPONSE_BYTES = 3500000;
+/** The default time one recovery read may take. */
+export declare const LOOKUP_TIMEOUT_MS = 30000;
+/** The most a lookup request's body may be (1,000 addresses are 70 KB). */
+export declare const MAX_LOOKUP_BODY_BYTES = 131072;
+/** More distinct members than this listed under one address, and the lookup is unknown: each would cost a proof fetch, and nothing honest records one file this often. */
+export declare const MAX_RECOVERED_PER_DIGEST = 200;
+/** A caller handed the queue or the sealer something that must never be written. */
+export declare class RecoveryInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * The recovery entries could not be READ. Never an answer about whether the
+ * file was recorded: "we could not check" and "nothing is kept for these
+ * bytes" are different claims, and only the second is a finding.
+ */
+export declare class RecoveryUnavailableError extends Error {
+    constructor(where: string, cause?: unknown);
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** hex SHA-256("bitgraph-lookup" || digest32): the public folder a file's entries live in. */
+export declare function recoveryAddress(digest32: Uint8Array): string;
+/** SHA-256("bitgraph-lookup-key" || digest32): the AES-256-GCM key every entry under this digest is sealed with. */
+export declare function recoveryKeyBytes(digest32: Uint8Array): Uint8Array;
+/** hex SHA-256("bitgraph-lookup-entry" || digest32 || proofHash32 || leafIndex u32 BE): one entry's name inside the address. */
+export declare function recoveryEntryId(digest32: Uint8Array, proofHash32: Uint8Array, leafIndex: number): string;
+/** hex SHA-256("bitgraph-lookup-entry/salted" || digest32 || proofHash32 || leafIndex u32 BE || salt32): the entry's fallback name when its deterministic one is held. */
+export declare function recoverySaltedEntryId(digest32: Uint8Array, proofHash32: Uint8Array, leafIndex: number, salt32: Uint8Array): string;
+/** A fresh salt for a salted entry. */
+export declare function newRecoverySalt(): Uint8Array;
+export declare function recoveryObjectKey(address: string, entryId: string): string;
+/** The address and entry id of a well-formed object key; null for anything else. */
+export declare function parseRecoveryObjectKey(key: unknown): {
+    address: string;
+    entryId: string;
+} | null;
+/**
+ * Seal one entry: 0x01 || nonce || AES-256-GCM(plaintext) || tag, with the
+ * object key as associated data, so an envelope opens only at the key it was
+ * written for. The nonce is 12 random bytes per call. A key encrypts one
+ * entry per recording of one file, so random nonces are nowhere near their
+ * limit.
+ */
+export declare function sealRecoveryEnvelope(keyBytes: Uint8Array, objectKey: string, plaintext: Uint8Array): Promise<Uint8Array>;
+/** The plaintext, or null when the envelope is not version 1 or does not authenticate under this key at this object key. */
+export declare function openRecoveryEnvelope(keyBytes: Uint8Array, objectKey: string, envelope: Uint8Array): Promise<Uint8Array | null>;
+/** Where the proof is: its position, and the digest the public proof routes find it under. */
+export interface RecoveryLocator {
+    epochId: string;
+    counter: string;
+    /** Standard base64 SHA-256 of the root document: the proof's signed artifact digest. */
+    artifactDigestB64: string;
+}
+export interface RecoveryPlaintext {
+    format: typeof RECOVERY_FORMAT;
+    /** base64 computeProofHash(proof). */
+    proofHash: string;
+    leafIndex: number;
+    /** The 84-byte root document, lowercase hex. */
+    rootDocument: string;
+    member: TreeMemberEvidence;
+    proof: RecoveryLocator;
+    /** Present exactly when the entry sits under its salted name: the 32-byte salt, base64. */
+    salt?: string;
+    /** Advisory, unsigned, like an export's names. */
+    name?: string;
+}
+/** The canonical bytes: keys in the documented order, compact JSON, UTF-8. */
+export declare function encodeRecoveryPlaintext(p: RecoveryPlaintext): Uint8Array;
+/**
+ * Strict read, and every check that needs nothing but the plaintext: exactly
+ * the documented keys, the format, a 32-byte proof hash, a root document that
+ * parses, member evidence that parses (verify's own strict reader), the leaf
+ * index and the tree size agreeing everywhere, the member's path reaching the
+ * root inside this root document, and the locator naming this document's
+ * hash. Null on any deviation. It does not say the proof exists or binds
+ * this document; fetchRecoveredProof does.
+ */
+export declare function parseRecoveryPlaintext(bytes: Uint8Array): RecoveryPlaintext | null;
+/** The entry id a plaintext derives for digest `d`: the salted name when it carries a salt, else the deterministic one. */
+export declare function recoveryEntryIdOf(digest32: Uint8Array, p: RecoveryPlaintext): string;
+/**
+ * The same member of the same recording, field by field: proof hash, leaf
+ * index, root document, the whole evidence (leaf and every path node) and the
+ * locator. The design's first test was proof hash and leaf index only, and
+ * that is not enough: anyone who knows the digest can seal an envelope that
+ * carries the right two numbers around a wrong path or a wrong locator, and a
+ * client that accepted it would mark the file recoverable while its only
+ * entry is useless. The name is left out on purpose: it is advisory and
+ * unsigned, and nothing recovered rests on it; so is the salt, which names
+ * the entry and says nothing about the member.
+ */
+export declare function sameRecoveryMember(a: RecoveryPlaintext, b: RecoveryPlaintext): boolean;
+/** Keep a long name's tail (a path's tail is the file's own name) inside MAX_NAME_BYTES; undefined for no name. */
+export declare function clampRecoveryName(name: string | null | undefined): string | undefined;
+export interface RecoveryTreeParts {
+    /** base64 computeProofHash(proof). */
+    proofHash: string;
+    locator: RecoveryLocator;
+    /** The 84-byte root document. */
+    rootDocument: Uint8Array;
+    /** The owner's list: every leaf in tree order (count x 65 bytes). */
+    leaves: Uint8Array;
+}
+export interface RecoveryTree {
+    proofHash: string;
+    proofHash32: Uint8Array;
+    locator: RecoveryLocator;
+    rootDocument: Uint8Array;
+    rootDocumentHex: string;
+    count: number;
+    /** count x 65 bytes, tree order; a private copy. */
+    leaves: Uint8Array;
+    /** Over the leaf hashes, for every member's path. */
+    tree: MerkleTree;
+}
+/**
+ * Everything is checked before anything is sealed, because what is sealed is
+ * written create-only under keys nobody can ever reuse: an entry built from a
+ * list that does not rebuild the committed root would hold its member's key
+ * for ten years and help nobody. The checks are verifyTreeLeaves' own (count,
+ * every leaf valid, strictly ascending artifact digests, the rebuilt root
+ * equal to the document's; the suite pins the two agreeing), done here so
+ * the tree that proves the list is the tree that makes the paths.
+ */
+export declare function recoveryTreeFromParts(parts: RecoveryTreeParts): RecoveryTree;
+/** The proof's own parts: its proof hash, its position and its signed artifact digest. Throws for anything that is not a tree/1 proof with a position. */
+export declare function recoveryProofParts(proof: BitGraphProof): {
+    proofHash: string;
+    locator: RecoveryLocator;
+};
+export interface RecoveryTreeInput {
+    proof: BitGraphProof;
+    /** The 84-byte root document; read from proof.metadata when omitted. */
+    rootDocument?: Uint8Array | null;
+    /** Every leaf in tree order: the 65-byte encodings concatenated, or the leaves themselves. */
+    leaves?: Uint8Array | readonly TreeLeaf[];
+    /** The same list already encoded (fuse-tree-make's MadeTree carries both); preferred when present. */
+    leavesBytes?: Uint8Array;
+}
+/** A tree/1 proof and its owner's list, checked and ready to seal. */
+export declare function recoveryTreeFrom(input: RecoveryTreeInput): RecoveryTree;
+/** The owner's list as bytes, from whichever form the caller holds. */
+export declare function leavesBytesOf(input: {
+    leaves?: Uint8Array | readonly TreeLeaf[];
+    leavesBytes?: Uint8Array;
+}): Uint8Array;
+/** Leaf `index` of the list, raw. */
+export declare function leafBytesAt(tree: {
+    leaves: Uint8Array;
+}, index: number): Uint8Array;
+/**
+ * Member `index`'s plaintext and its bytes. A name that would push the
+ * plaintext past MAX_PLAINTEXT_BYTES (only possible with hundreds of escaped
+ * control characters) is dropped, never the entry.
+ */
+export declare function recoveryPlaintextFor(tree: RecoveryTree, index: number, name?: string | null, salt?: Uint8Array | null): {
+    plaintext: RecoveryPlaintext;
+    bytes: Uint8Array;
+};
+/** Which of a leaf's digests an entry is filed under. An as-is leaf has one digest and one entry. */
+export type RecoverySide = "origin" | "artifact" | "as-is";
+export interface RecoveryWrite {
+    side: RecoverySide;
+    /** The digest the entry is sealed under (a private copy). */
+    digest: Uint8Array;
+    objectKey: string;
+    envelope: Uint8Array;
+    /** The entry's deterministic key: its own key, or the held key a salted entry stands in for. */
+    deterministicKey: string;
+    /** True when the entry sits under its salted name. */
+    salted: boolean;
+    /** The plaintext sealed into this envelope (the salt is in it when salted). */
+    plaintext: RecoveryPlaintext;
+}
+/** The sides member `index` is filed under: ["as-is"] for placement 0x00, else ["origin", "artifact"]. */
+export declare function recoverySidesOf(tree: {
+    leaves: Uint8Array;
+}, index: number): RecoverySide[];
+/** The digest one side of member `index` is filed under. */
+export declare function recoveryDigestOf(tree: {
+    leaves: Uint8Array;
+}, index: number, side: RecoverySide): Uint8Array;
+/** Bit 0 origin kept, bit 1 committed bytes kept, bit 2 origin blocked, bit 3 committed bytes blocked. An as-is member sets both bits of a kind at once. */
+export declare const ORIGIN_KEPT = 1;
+export declare const ARTIFACT_KEPT = 2;
+export declare const ORIGIN_BLOCKED = 4;
+export declare const ARTIFACT_BLOCKED = 8;
+export declare const RECOVERY_SIDE_BITS: Record<RecoverySide, {
+    kept: number;
+    blocked: number;
+}>;
+export type RecoveryMemberStatus = "pending" | "recoverable" | "blocked";
+export type RecoverySideState = "kept" | "pending" | "blocked";
+/** A member's status from its progress byte alone (so a finished job, whose list is gone, still answers). */
+export declare function recoveryMemberStatus(b: number): RecoveryMemberStatus;
+export declare function recoverySideState(b: number, side: RecoverySide): RecoverySideState;
+export declare const recoverySideResolved: (b: number, side: RecoverySide) => boolean;
+/** The key a member's side has in a writer's salt table: "<leafIndex>:<side>". */
+export declare const recoverySaltKey: (index: number, side: RecoverySide) => string;
+/** A writer's salt table (base64 salts by recoverySaltKey) as the `salts` sealRecoveryMember takes for member `index`; null when it holds none for that member. */
+export declare function recoverySaltsFor(salts: Readonly<Record<string, string>> | null | undefined, index: number): Partial<Record<RecoverySide, Uint8Array>> | null;
+/** The object key one side of member `index` is filed under: deterministic, or salted when a salt is given. */
+export declare function recoveryObjectKeyFor(tree: RecoveryTree, index: number, side: RecoverySide, salt?: Uint8Array | null): string;
+/**
+ * Seal member `index`: one envelope per side (or only the sides asked for),
+ * each under its own key, nonce and AAD. A side named in `salts` is sealed
+ * under its salted name, with the salt in its plaintext; `plaintext` is the
+ * unsalted one, the member all of them describe.
+ */
+export declare function sealRecoveryMember(tree: RecoveryTree, index: number, name?: string | null, only?: readonly RecoverySide[], salts?: Partial<Record<RecoverySide, Uint8Array>> | null): Promise<{
+    plaintext: RecoveryPlaintext;
+    writes: RecoveryWrite[];
+}>;
+/**
+ * The 412 path's test: the envelope already stored at `objectKey` holds THIS
+ * member (sameRecoveryMember), opened with the digest's key at that key. A
+ * stored envelope that does not open, does not parse, or holds anything else
+ * is somebody else's entry, and the write is not a success.
+ */
+export declare function existingEntryHoldsMember(digest32: Uint8Array, objectKey: string, envelope: Uint8Array, expected: RecoveryPlaintext): Promise<boolean>;
+/**
+ * This member's own entry under its address, if one is already there under
+ * any name: the deterministic one, or a salted one from an earlier run whose
+ * salt was lost (a job finished and removed, a browser tab's save that
+ * failed). Returns the entry's key and, for a salted one, its salt, so the
+ * writer counts it kept and reuses the salt instead of leaving a second copy.
+ * Null when none is there; raises RecoveryUnavailableError when the address
+ * cannot be read (then the writer must not guess).
+ */
+export declare function findOwnRecoveryEntry(digest32: Uint8Array, expected: RecoveryPlaintext, fetchFn?: FetchLike, opts?: RecoveryLookupOptions): Promise<{
+    objectKey: string;
+    salt: Uint8Array | null;
+} | null>;
+export interface RecoveredEntry {
+    objectKey: string;
+    entryId: string;
+    /** True when the entry sits under its salted name (its deterministic one was held by another entry). */
+    salted: boolean;
+    /** The salted entry's salt, base64; null under the deterministic name. */
+    salt: string | null;
+    /** Which of the leaf's digests the looked-up digest is: "as-is" when the leaf has one. */
+    matched: RecoverySide;
+    /** base64 computeProofHash(proof) of the recording. */
+    proofHash: string;
+    leafIndex: number;
+    /** Hex, 84 bytes: an export's tree.rootDocument. */
+    rootDocument: string;
+    /** An export's tree.member. */
+    member: TreeMemberEvidence;
+    proof: RecoveryLocator;
+    name: string | null;
+}
+export interface RecoveryLookupOptions {
+    /** Origin of the site's routes; "" (same origin) in the browser. */
+    baseUrl?: string;
+    /** A guard against a server whose pages never end. Default 1,000 (100,000 entries). */
+    maxPages?: number;
+    /** The most one read may take; a read that outlasts it is a failed read. Default LOOKUP_TIMEOUT_MS. */
+    timeoutMs?: number;
+}
+/**
+ * Every recording of the file whose SHA-256 is `digest32`, from the sealed
+ * entries under its address: one entry per member per recording, so the same
+ * file recorded twice comes back twice (and the same member under two names
+ * once). An entry that does not authenticate, does not parse, sits under an
+ * entry id its own contents do not derive, or names a leaf that is not this
+ * digest is skipped: it is not ours to show. The list is in the server's
+ * listing order; order the recordings by their proofs' own times once
+ * fetched.
+ *
+ * Raises RecoveryUnavailableError when the entries cannot be read, a route
+ * that answers 404 included. An empty array is an answer (nothing is kept
+ * for these bytes); a failure never is.
+ */
+export declare function recoverFromDigest(digest32: Uint8Array, fetchFn?: FetchLike, opts?: RecoveryLookupOptions): Promise<RecoveredEntry[]>;
+/** One digest's lookup in a batch: every page read and every entry opened, or why it could not be. A failure is never a verdict. */
+export type RecoveryLookupAnswer = {
+    ok: true;
+    entries: RecoveredEntry[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * recoverFromDigest for many files at once: the first page of every address
+ * in one request (POST /api/recovery/lookup, at most MAX_LOOKUP_ADDRESSES per
+ * request), then the rest of any longer listing page by page. One answer per
+ * digest, in order; a digest whose entries could not all be read answers
+ * { ok: false }, never an empty list. A site without the route (404) is asked
+ * one address at a time instead.
+ *
+ * Asking many addresses in one request tells the server which files were
+ * dropped together, which one-by-one requests only hint at by timing. The
+ * route logs counts, never addresses (SPEC section 13).
+ */
+export declare function recoverFromDigests(digests: readonly Uint8Array[], fetchFn?: FetchLike, opts?: RecoveryLookupOptions): Promise<RecoveryLookupAnswer[]>;
+/**
+ * The measurement policy a recovery reader judges proofs by (SPEC section
+ * 5.6): "published", BitGraph's published images (the default); a list of
+ * PCR0 hex strings, the reader's own; "none", the signature and tree alone
+ * (tests with the published TEST key). An empty list judges nothing: every
+ * candidate is then unresolved, never a negative (see proofTrusted).
+ */
+export type RecoveryTrust = "published" | "none" | readonly string[];
+/**
+ * Whether the proof's attestation verified in full (AWS signature, chain,
+ * root, validity, PCR0 as the proof names it, bound to this proof's signed
+ * body) and attests an image the policy accepts. "undetermined" when the
+ * policy is empty: nothing was judged, and a reader must leave the candidate
+ * unresolved rather than call it negative.
+ */
+export declare function proofTrusted(proof: BitGraphProof, policy?: RecoveryTrust): "trusted" | "rejected" | "undetermined";
+export interface RecoveredProof {
+    proof: BitGraphProof;
+    /**
+     * verifyTreeMember on the fetched proof with this entry's root document and
+     * evidence (and the file, when given): TREE_PATH_VALID, or one of the
+     * TREE_MEMBER categories with the file, is a recovered BitGraph. Anything
+     * else is a reason, never a verdict about the file.
+     */
+    check: TreeVerifyResult;
+}
+/**
+ * The proof a recovered entry points at, from the public proof routes by its
+ * artifact digest, bound by proof hash (a proof whose computeProofHash is not
+ * the entry's is not this recording) and checked with verifyTreeMember.
+ * Null when no proof under that digest has this proof hash. Raises
+ * RecoveryUnavailableError when the route cannot be read.
+ *
+ * With the proof and the entry in hand an export is the existing machinery:
+ * fuse-tree's buildTreeExport(proof, memberTree(rootDocument, member),
+ * await fetchTreeEvidence(proof)).
+ *
+ * ⚠️ THIS READ NEEDS THE LEDGER'S BY-DIGEST INDEX for the tree's artifact
+ * digest, which exists while per-proof writes are on (LEDGER_WRITES). If they
+ * are ever switched off, the entry still names the proof exactly: the
+ * parent's own key is proofs/<url-safe epochId>/<counter, 12 digits>-<url-safe
+ * proofHash>.json, and a read-only route serving that key is all this needs.
+ */
+export declare function fetchRecoveredProof(entry: Pick<RecoveredEntry, "proofHash" | "rootDocument" | "member" | "proof">, fetchFn?: FetchLike, opts?: {
+    baseUrl?: string;
+    bytes?: Uint8Array;
+    source?: ByteSource;
+    extraSpecHashes?: readonly string[];
+    timeoutMs?: number;
+    trust?: RecoveryTrust;
+}): Promise<RecoveredProof | null>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"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"}