@tokono.ma/firkin 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# @tokono.ma/firkin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-first TypeScript SDK for the [Firkin](https://tangled.org/tokono.ma/firkin)
+API: content-addressed blobs (DASL CIDs), UCAN 1.0 authorization, and
+CAR Mirror batch sync — over plain `fetch`.
+
+```sh
+npm install @tokono.ma/firkin
+```
+
+Pure ESM, zero Node-only APIs: it runs in browsers through any bundler and
+in Node 22+ directly. Unreleased commits:
+`npm install git+https://tangled.org/tokono.ma/firkin`.
+
+## Quickstart
+
+```ts
+import { Signer, Firkin, signerToken } from "@tokono.ma/firkin";
+
+const signer = await Signer.generate(); // or Signer.fromSeedHex(hex)
+console.log(signer.did()); // did:key:z… — an admin must register it
+
+const rb = new Firkin("https://firkin.example.com", signerToken(signer));
+
+const { cid, deduplicated } = await rb.upload(new Blob(["hello"]));
+const bytes = await rb.get(cid); // same bytes = same CID, stored once
+```
+
+Every mutating call carries a single-use UCAN invocation minted by the
+`TokenSource`. `signerToken(signer)` is the simple case (the account key
+signs directly); delegates mint with [`invocation()`](#delegation--sessions).
+
+## Mental model
+
+- **Content addressing.** The CID is computed from the bytes *before*
+  upload (`cidForBytes`), and the server verifies the digest — never
+  trusts it. Identical bytes anywhere dedupe to one stored object, shared
+  by every claimant.
+- **Identity is a key pair.** Your seed is your account; its `did:key` is
+  registered by an admin. Passkey-native accounts use a P-256 credential
+  instead (see [Passkeys](#passkeys)).
+- **Authorization is per request.** Mutating commands are single-use
+  (replay-protected); read tokens are reusable. That is why the
+  `TokenSource` is a function, not a token.
+
+## API
+
+```ts
+// blobs — reads are authenticated automatically (for PUBLIC_READS=false)
+rb.upload(data, { codec?, hash?: "sha256" | "blake3" }) → { cid, deduplicated }
+rb.get(cid) → Uint8Array
+rb.getRange(cid, { start?, end?, suffix? }) → { data, start, end, total }
+
+// claims (multi-account sharing of one stored object)
+rb.claim(cid)          // attach an already-stored CID to your account
+rb.delete(cid)         // detach; bytes die with the last claimant
+
+// name registry — private name → CID pointers (names imply no claim)
+rb.registrySet(name, cid)
+rb.registryGet(name)   // null when unset
+rb.registryList()      // Record<name, cid>
+rb.registryDelete(name)
+
+// CAR Mirror (batch sync)
+rb.pushFile(chunks)           // ordered chunks → dag-cbor list root
+rb.pullFile(root)             // inverse of pushFile
+rb.dagPush(root, blocks)      // an existing DAG, as-is: [cid, bytes][] | Map
+rb.dagPull(root)              // Map<cid, bytes> — only the root is needed
+
+// account
+rb.revoke({ cids? , all? })   // kill delegations (account key only)
+rb.register(did, credential?) // admin: register a DID (+ passkey binding)
+rb.listAccounts()             // admin
+Firkin.whoami(base, assertion) // passkey re-attachment → account DID
+```
+
+`dagPull` follows dag-cbor **and dag-pb** links server-side, so a WNFS-shaped
+graph (dag-pb root tree, dag-cbor forest) comes back whole from its root.
+`dagPush` keeps every block under its real CID — nothing is re-hashed —
+which is what makes it composable with other IPLD tooling and with
+registry entries that point at the real root. `pushFile` is sugar over
+`dagPush` for plain chunk lists.
+
+Errors throw an `Error` with `status` (the HTTP code) and the server's
+message — branch on `status` (401 unauthorized, 403 forbidden/revoked,
+404 not found, 413 too large, 422 digest mismatch).
+
+## Delegation & sessions
+
+Delegate a narrow capability to a short-lived key, then mint invocations
+with that key:
+
+```ts
+import { delegationPayloadBytes, invocation, delegate } from "@tokono.ma/firkin";
+
+const { proof, cid } = await delegate(account, {
+  subject: account.did(),          // rights holder (the account)
+  audience: session.did(),         // recipient
+  command: "/firkin/blob/upload",  // narrow prefixes only ever narrow
+  expireIn: 8 * 3600,              // omit for an indefinite delegation
+});
+
+const rb = new Firkin(base, async (command) =>
+  invocation(session, { command, proofs: [proof], expireIn: 600 }),
+);
+
+// Revocation must be authorized by the account key — not the session:
+const accountClient = new Firkin(base, signerToken(account));
+await accountClient.revoke({ cids: [cid] }); // or { all: true }
+```
+
+The server enforces that the chain cannot widen rights and that revocations
+are signed by the account key (`revoke` from a plain delegated session is
+refused — a stolen session must not be able to revoke).
+
+## Passkeys
+
+`WebCryptoSigner` / `WebCryptoP256Signer` hold **non-extractable** keys
+(structured-cloneable into IndexedDB: scripts can sign, never read).
+Passkey-native accounts — the credential key *is* the account — sign
+delegations with a WebAuthn assertion:
+
+```ts
+import { assertionToProof, delegationPayloadBytes } from "@tokono.ma/firkin";
+
+const payload = delegationPayloadBytes({
+  issuerDid: passkeyDid, subject: passkeyDid, audience: session.did(),
+  command: "/firkin/blob", expireIn: 8 * 3600,
+});
+const assertion = await navigator.credentials.get({
+  publicKey: { challenge: base64url(payload), rpId, userVerification: "required" },
+});
+const proof = assertionToProof(payload, {
+  authData: /* bytes */, clientDataJSON: /* exact JSON text */, signature: /* bytes */,
+});
+```
+
+`Firkin.whoami` resolves a discoverable-credential assertion back to its
+account DID on a fresh browser. Working example:
+[`examples/passkey/`](https://tangled.org/tokono.ma/firkin/tree/main/examples/passkey).
+
+## Design notes
+
+**Minting is a shim, on purpose.** `ucan.ts` only assembles the wire format;
+the crypto and encoding are library code (`@noble/ed25519`,
+`@ipld/dag-cbor`, `multiformats`, `hash-wasm`). Correctness is pinned by
+golden tests: tokens minted here are accepted by the Rust server and decode
+byte-identically to the Rust reference client's fixtures.
+
+**[iso-ucan](https://github.com/hugomrdias/iso-repo/tree/main/packages/iso-ucan)**
+is the fuller TS UCAN library, but it mints final UCAN 1.0.0 (the server is
+pinned to rc.1 today). When the server moves to 1.0.0 final, the three
+mint functions can be swapped for iso-ucan behind the existing
+`TokenSource` interface — no other layer changes.
+
+## License
+
+Apache-2.0 OR MIT.

package/dist/bip39.d.ts

@@ -0,0 +1,4 @@
+/** Encode a 32-byte ed25519 seed as a 24-word BIP39 phrase. */
+export declare function seedToMnemonic(seed: Uint8Array): string;
+/** Decode a 24-word BIP39 phrase back into the 32-byte ed25519 seed. */
+export declare function mnemonicToSeedBytes(mnemonic: string): Uint8Array;

package/dist/bip39.js

@@ -0,0 +1,18 @@
+// BIP39 seed-phrase backup: a 24-word phrase encodes 256 bits of entropy
+// that IS the ed25519 seed (bijective: entropy ↔ mnemonic — no PBKDF2
+// stretching, so the phrase round-trips to the exact account key).
+import { entropyToMnemonic, mnemonicToEntropy } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+/** Encode a 32-byte ed25519 seed as a 24-word BIP39 phrase. */
+export function seedToMnemonic(seed) {
+    if (seed.length !== 32)
+        throw new Error("backup seed must be 32 bytes");
+    return entropyToMnemonic(seed, wordlist);
+}
+/** Decode a 24-word BIP39 phrase back into the 32-byte ed25519 seed. */
+export function mnemonicToSeedBytes(mnemonic) {
+    const seed = mnemonicToEntropy(mnemonic.trim().toLowerCase(), wordlist);
+    if (seed.length !== 32)
+        throw new Error("mnemonic does not encode a 32-byte seed");
+    return seed;
+}

package/dist/bloom.d.ts

@@ -0,0 +1,17 @@
+export declare class BloomFilter {
+    readonly bytes: Uint8Array;
+    readonly hashCount: number;
+    private constructor();
+    /** From a push response's `bb` (bytes) + `bk` (hash count). */
+    static fromWire(bytes: Uint8Array, hashCount: number): BloomFilter;
+    /** Fresh filter sized for `n` items at false-positive probability `fpp`
+     * (spec §3.4.2: k = m/n·ln2, m = -n·ln ε / ln²2). */
+    static build(n: number, fpp?: number): Promise<BloomFilter>;
+    get bitSize(): number;
+    /** Probabilistic membership: true = definitely or probably present. */
+    contains(item: Uint8Array): Promise<boolean>;
+    insert(item: Uint8Array): Promise<void>;
+    /** deterministic-bloom's HashIndexIterator: k accepted indexes, seeds
+     * counting up from 0 across hash rounds and rejection samples alike. */
+    private indices;
+}

package/dist/bloom.js

@@ -0,0 +1,82 @@
+// TS port of the Bloom filter used by car-mirror
+// (`deterministic-bloom`, runtime_size), so the client can BOTH interpret
+// the server's push-response filters AND build pull-request filters the
+// server will interpret identically:
+//
+// - items are hashed with XXH3-64, seed = a monotonic counter starting at 0
+//   that is shared across the k hash rounds AND rejection-sampling retries
+//   (the counter resets per insert/contains call)
+// - index = hash % 2^ceil(log2(bit_size)); non-power-of-two sizes rejection-
+//   sample (retry with the next seed when the value lands past the size)
+// - bits are LSB0 within the byte array
+// - an item is "contained" when all k of its bits are set (false positives
+//   possible, never false negatives)
+//
+// Items fed by the server are CID binary bytes (`cid.to_bytes()`), i.e. the
+// multiformats `CID.bytes`.
+//
+// NB: deterministic-bloom casts the u64 hash `as usize` — 32 bits on the
+// wasm32 worker. Both the read and write side mimic that truncation here
+// (revisit if the store is ever built natively, e.g. celld on x86_64, where
+// usize is 64 bits).
+import { xxhash3 } from "hash-wasm";
+export class BloomFilter {
+    bytes;
+    hashCount;
+    constructor(bytes, hashCount) {
+        this.bytes = bytes;
+        this.hashCount = hashCount;
+    }
+    /** From a push response's `bb` (bytes) + `bk` (hash count). */
+    static fromWire(bytes, hashCount) {
+        return new BloomFilter(bytes, hashCount);
+    }
+    /** Fresh filter sized for `n` items at false-positive probability `fpp`
+     * (spec §3.4.2: k = m/n·ln2, m = -n·ln ε / ln²2). */
+    static async build(n, fpp = Math.min(0.1, 1 / (10 * n))) {
+        if (n <= 0)
+            throw new Error("bloom needs at least one item");
+        const ln2 = Math.LN2;
+        const bits = Math.ceil((-n * Math.log(fpp)) / (ln2 * ln2));
+        const hashCount = Math.max(1, Math.round((bits / n) * ln2));
+        return new BloomFilter(new Uint8Array(Math.ceil(bits / 8)), hashCount);
+    }
+    get bitSize() {
+        return this.bytes.length * 8;
+    }
+    /** Probabilistic membership: true = definitely or probably present. */
+    async contains(item) {
+        for await (const index of this.indices(item)) {
+            const byte = this.bytes[index >> 3] ?? 0;
+            if ((byte & (1 << (index & 7))) === 0)
+                return false;
+        }
+        return true;
+    }
+    async insert(item) {
+        for await (const index of this.indices(item)) {
+            this.bytes[index >> 3] = (this.bytes[index >> 3] ?? 0) | (1 << (index & 7));
+        }
+    }
+    /** deterministic-bloom's HashIndexIterator: k accepted indexes, seeds
+     * counting up from 0 across hash rounds and rejection samples alike. */
+    async *indices(item) {
+        const size = this.bitSize;
+        if (size === 0 || this.hashCount === 0)
+            return;
+        const po2 = Math.pow(2, Math.ceil(Math.log2(size)));
+        let seed = 0;
+        for (let accepted = 0; accepted < this.hashCount; seed++) {
+            if (seed > 10_000_000)
+                throw new Error("bloom rejection sampling exhausted");
+            const hex = await xxhash3(item, seed, 0);
+            // NB: the `as usize` truncation described above.
+            const hash = BigInt("0x" + hex) & 0xffffffffn;
+            const value = Number(hash % BigInt(po2));
+            if (value < size) {
+                accepted++;
+                yield value;
+            }
+        }
+    }
+}

package/dist/cid.d.ts

@@ -0,0 +1,17 @@
+import { bytesToHex } from "./keys.ts";
+export declare const CODEC_RAW = 85;
+export declare const CODEC_DAG_PB = 112;
+export declare const CODEC_DAG_CBOR = 113;
+export declare const HASH_SHA256 = 18;
+export declare const HASH_BLAKE3 = 30;
+export type HashName = "sha256" | "blake3";
+/** The DASL/BDASL CID of the given bytes (canonical base32-lower text). */
+export declare function cidForBytes(data: Uint8Array, opts?: {
+    codec?: number;
+    hash?: HashName;
+}): string;
+/** CID text from a raw digest, codec and multihash code. */
+export declare function cidFromDigest(digest: Uint8Array, codec?: number, hashCode?: number): string;
+/** Convenience: hex digest + codec → CID (useful with external hashers). */
+export declare function cidFromDigestHex(hex: string, codec?: number): string;
+export { bytesToHex };

package/dist/cid.js

@@ -0,0 +1,69 @@
+// DASL/BDASL CID computation (CIDv1, base32-lower canonical form).
+//
+// Mirrors firkin-core's codec: version 0x01 + codec uvarint + multihash
+// (SHA-256 0x12 or BLAKE3 0x1e, 32-byte digest).
+import { sha256 } from "@noble/hashes/sha2";
+import { blake3 } from "@noble/hashes/blake3";
+import { bytesToHex } from "./keys.js";
+export const CODEC_RAW = 0x55;
+export const CODEC_DAG_PB = 0x70;
+export const CODEC_DAG_CBOR = 0x71;
+export const HASH_SHA256 = 0x12;
+export const HASH_BLAKE3 = 0x1e;
+const BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+function base32LowerNoPad(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const b of bytes) {
+        value = (value << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+    }
+    return out;
+}
+function pushUvarint(out, value, at) {
+    let v = value;
+    let i = at;
+    while (v >= 0x80) {
+        out[i++] = (v & 0x7f) | 0x80;
+        v >>>= 7;
+    }
+    out[i++] = v;
+    return i;
+}
+/** The DASL/BDASL CID of the given bytes (canonical base32-lower text). */
+export function cidForBytes(data, opts = {}) {
+    const codec = opts.codec ?? CODEC_RAW;
+    const hash = opts.hash ?? "sha256";
+    const hashCode = hash === "blake3" ? HASH_BLAKE3 : HASH_SHA256;
+    const digest = hash === "blake3" ? blake3(data) : sha256(data);
+    return cidFromDigest(digest, codec, hashCode);
+}
+/** CID text from a raw digest, codec and multihash code. */
+export function cidFromDigest(digest, codec = CODEC_RAW, hashCode = HASH_SHA256) {
+    if (digest.length !== 32)
+        throw new Error("expected a 32-byte digest");
+    const wire = new Uint8Array(4 + 32);
+    wire[0] = 0x01;
+    let i = pushUvarint(wire, codec, 1);
+    i = pushUvarint(wire, hashCode, i);
+    i = pushUvarint(wire, 32, i);
+    wire.set(digest, i);
+    return "b" + base32LowerNoPad(wire);
+}
+/** Convenience: hex digest + codec → CID (useful with external hashers). */
+export function cidFromDigestHex(hex, codec = CODEC_RAW) {
+    const digest = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        digest[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return cidFromDigest(digest, codec);
+}
+export { bytesToHex };

package/dist/client.d.ts

@@ -0,0 +1,187 @@
+import { CID } from "multiformats";
+import type { Signer } from "./keys.ts";
+/** Supplies a fresh bearer token for a command. Mutating commands are
+ * single-use server-side — implementations MUST mint a new token per call
+ * (the default signer source does). */
+export type TokenSource = (command: string) => Promise<Uint8Array>;
+/** Signer-backed source: mints a fresh direct invocation per request. */
+export declare function signerToken(signer: Signer, expireIn?: number): TokenSource;
+/** Fixed-token source: only appropriate for public/read-only usage. */
+export declare function staticToken(token: Uint8Array): TokenSource;
+export interface UploadResult {
+    cid: string;
+    /** True when the blob was already stored (dedup; claim joined). */
+    deduplicated: boolean;
+}
+export interface ByteRange {
+    /** Inclusive start (default 0). */
+    start?: number;
+    /** Inclusive end (default last byte). */
+    end?: number;
+    /** Last N bytes (alternative to start/end). */
+    suffix?: number;
+}
+export interface RangeResult {
+    data: Uint8Array;
+    /** Inclusive range within the full blob. */
+    start: number;
+    end: number;
+    total: number;
+}
+/** Local block store used for pull-side Bloom narrowing (spec §3.2.1): the
+ * cache's CIDs go into the pull request's filter, so the server skips
+ * blocks this client already has. */
+export interface BlockCache {
+    get(cid: string): Promise<Uint8Array | undefined> | Uint8Array | undefined;
+    set(cid: string, bytes: Uint8Array): Promise<void> | void;
+    keys(): Promise<string[]> | string[];
+}
+/** Simple in-memory cache (per Firkin instance). */
+export declare class MemoryBlockCache implements BlockCache {
+    private map;
+    get(cid: string): Uint8Array | undefined;
+    set(cid: string, bytes: Uint8Array): void;
+    keys(): string[];
+}
+export declare class Firkin {
+    private readonly base;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly blockCache;
+    constructor(base: string, token: TokenSource, fetchImpl?: typeof fetch, blockCache?: BlockCache);
+    /** Upload bytes; returns the CID and whether it was already stored. */
+    upload(data: Uint8Array | Blob, opts?: {
+        codec?: number;
+        hash?: "sha256" | "blake3";
+    }): Promise<UploadResult>;
+    /** Fetch a whole blob. Authenticated reads: the server's reads are public
+     * by default, but a `PUBLIC_READS=false` deployment requires the
+     * `/firkin/blob/read` capability — read tokens are reusable (reads are
+     * not replay-tracked), so sending one is always correct and cheap. */
+    get(cid: string): Promise<Uint8Array>;
+    /** Fetch a byte range (206 responses; server-trusted verification).
+     * Authenticated like [`get`](#get). */
+    getRange(cid: string, range?: ByteRange): Promise<RangeResult>;
+    /** Attach an already-stored CID to the signer's account. */
+    claim(cid: string): Promise<void>;
+    /** Detach the signer's claim; bytes die with the last claimant. */
+    delete(cid: string): Promise<void>;
+    /** Revoke delegated sessions: specific delegation CIDs, or every
+     * delegation minted before now (`all: true`). Must be authorized by the
+     * account key itself — a direct invocation (seed accounts) or a fresh
+     * passkey assertion delegating `/firkin/account/revoke` to the session key
+     * (passkey-native accounts; the server caps its lifetime at 10 minutes).
+     * A plain delegated session cannot revoke. */
+    revoke(opts: {
+        cids?: string[];
+        all?: boolean;
+    }): Promise<void>;
+    /** (Admin) register a DID as an account, optionally binding a WebAuthn
+     * credential (`id` = base64url rawId, `spki` = base64url of the browser's
+     * getPublicKey() DER). The binding is what lets a fresh browser re-attach
+     * the passkey later via `Firkin.whoami` — passkey-native accounts have no
+     * other record of the credential↔account link. */
+    register(did: string, credential?: {
+        id: string;
+        spki: string;
+    }): Promise<void>;
+    /** (Account key) attest a session delegation with the bound passkey. */
+    attest(body: {
+        credential_id: string;
+        auth_data: string;
+        client_data: string;
+        signature: string;
+        delegation_cid: string;
+    }): Promise<void>;
+    /** (Account key) bind a WebAuthn credential to this account. */
+    bindCredential(credential: {
+        id: string;
+        spki: string;
+    }): Promise<void>;
+    /** Resolve a passkey assertion to its account DID — the login primitive
+     * for passkey-native accounts on a fresh browser. The client performs a
+     * discoverable-credentials WebAuthn get (no `allowCredentials`); the
+     * server looks the credential up (bound at registration), verifies the
+     * ceremony + ES256 signature, and answers with the DID. Static because
+     * the endpoint is unauthenticated by design: the verified signature IS
+     * the authentication. */
+    static whoami(base: string, assertion: {
+        id: string;
+        authData: Uint8Array;
+        clientDataJSON: string;
+        signature: Uint8Array;
+    }, fetchImpl?: typeof fetch): Promise<string>;
+    /** (Admin) list registered accounts. */
+    listAccounts(): Promise<{
+        did: string;
+        registered_at: number;
+    }[]>;
+    /** Set `name` → `cid`. Overwrites silently (last-writer-wins). */
+    registrySet(name: string, cid: string): Promise<void>;
+    /** Resolve `name`; returns null when unset. */
+    registryGet(name: string): Promise<string | null>;
+    /** Unset `name` (idempotent). */
+    registryDelete(name: string): Promise<void>;
+    /** The account's whole registry: name → CID (sorted). */
+    registryList(): Promise<Record<string, string>>;
+    /**
+     * Push a flat file as an ordered list of chunks: each chunk is stored as
+     * a raw block, and a dag-cbor list of their CIDs becomes the root — the
+     * shape [`pullFile`](#pullfile) reassembles. The manifest is built here
+     * and pushed through [`dagPush`](#dagpush), so there is one
+     * push implementation. For an existing DAG (real CIDs and real root),
+     * use `dagPush` directly.
+     */
+    pushFile(chunks: Uint8Array[], opts?: {
+        roundBudgetBytes?: number;
+    }): Promise<string>;
+    /**
+     * Push an existing DAG as-is: `blocks` maps each block's REAL CID to its
+     * bytes, and `root` is the DAG's real root (one of the blocks). Same
+     * multi-round / Bloom-narrowed protocol as [`pushFile`](#pushfile), but
+     * nothing is re-hashed or wrapped in a manifest — the server stores the
+     * blocks under the given CIDs, so `dagPull(root)` works for other clients
+     * and a name-registry entry pointing at `root` resolves to the real DAG
+     * (e.g. a WNFS root tree: dag-pb root + dag-cbor/dag-pb descendants).
+     *
+     * Links are followed per the block's own codec (dag-cbor and dag-pb);
+     * blocks of other codecs are terminals.
+     */
+    dagPush(root: string | CID, blocks: Iterable<[string | CID, Uint8Array]>, opts?: {
+        roundBudgetBytes?: number;
+    }): Promise<string>;
+    /**
+     * The shared CAR Mirror push loop for a graph already in memory: BFS from
+     * the round's subgraph roots, Bloom-skip blocks the server has (never the
+     * subgraph roots themselves), budget-chunked; repeat while the server
+     * reports pending roots.
+     */
+    private pushGraph;
+    /** Pull a whole DAG knowing only its root; returns its blocks by CID.
+     *
+     * Spec §3.2: with a populated block cache, the pull request carries a
+     * Bloom filter over the cached CIDs, so the server skips blocks this
+     * client already has; the loop re-requests until the local graph below
+     * the root is complete (Bloom false positives can strand a block for one
+     * round — it's uncached, so the next filter omits it and the server
+     * sends it). With an empty cache this is a cold pull, exactly as before.
+     */
+    dagPull(root: string): Promise<Map<string, Uint8Array>>;
+    /**
+     * Pull + reassemble a file pushed via [`pushFile`](#pushfile): the root is
+     * a dag-cbor list of raw chunk CIDs in order — concatenates them back.
+     */
+    pullFile(root: string): Promise<Uint8Array>;
+}
+export declare function carFile(root: CID, entries: [CID, Uint8Array][]): Uint8Array;
+export declare function multihashSha256(data: Uint8Array): MultihashDigest;
+type MultihashDigest = {
+    code: number;
+    size: number;
+    digest: Uint8Array;
+    bytes: Uint8Array;
+};
+/** The CID links of a block, per its codec: dag-cbor (0x71) and dag-pb
+ * (0x70). Other codecs have no parseable links (raw blocks are terminals). */
+export declare function linksOf(code: number, bytes: Uint8Array): CID[];
+export {};