@tokono.ma/firkin 0.2.0 → 0.4.0

package/dist/client.js

@@ -4,15 +4,102 @@ import { CID } from "multiformats";
 import { sha256 } from "@noble/hashes/sha2";
 import { cidForBytes, CODEC_DAG_CBOR, CODEC_DAG_PB, CODEC_RAW } from "./cid.js";
 import { BloomFilter } from "./bloom.js";
+import { BAO_CHUNK_SIZE, decodeBaoRange } from "./bao.js";
+/** Wire version prefix for every API path (`/health` and `/.well-known/*`
+ * live outside it). */
+export const API_PREFIX = "/v1";
 import { CMD, mintInvocation } from "./ucan.js";
+import { assertionHeader, packageAssertion, } from "./webauthn.js";
 /** Signer-backed source: mints a fresh direct invocation per request. */
 export function signerToken(signer, expireIn = 600) {
     return async (command, options) => mintInvocation(signer, { command, expireIn: options?.expireIn ?? expireIn });
 }
+/**
+ * Source for an **attested session**: every invocation carries
+ * `meta["firkin/account"]`, the hint the server uses to resolve the
+ * session → account binding. The session key signs directly (no proofs); the
+ * binding, not the token, carries the account's authority.
+ *
+ * Obtain the binding with a passkey: `attestationChallenge(...)` →
+ * `credentials.get` → `Firkin.attest(...)`.
+ */
+export function sessionTokenSource(signer, opts) {
+    const expireIn = opts.expireIn ?? 600;
+    return async (command, options) => mintInvocation(signer, {
+        command,
+        expireIn: options?.expireIn ?? expireIn,
+        meta: { "firkin/account": opts.account },
+    });
+}
 /** Fixed-token source: only appropriate for public/read-only usage. */
 export function staticToken(token) {
     return async () => token;
 }
+/**
+ * Canonicalize an instance origin: scheme + host + optional port, lowercased,
+ * with no trailing slash, path, query, fragment or userinfo.
+ *
+ * This matters twice over. Firkin compares the `firkin` audience field of its
+ * own records to `ORIGIN` exactly, and the ATProto indexers that can discover
+ * appeals — Constellation backlinks and Spacedust links — match URLs
+ * byte-for-byte, so `https://Firkin.example/` and `https://firkin.example`
+ * would be two unrelated values to them.
+ *
+ * Throws on a string that is not an absolute URL (e.g. a bare host).
+ */
+export function normalizeOrigin(origin) {
+    const url = new URL(origin.trim());
+    return `${url.protocol}//${url.host}`;
+}
+/** NSID of the access appeal an operator's firehose consumer reads.
+ * See `lexicons/ma.tokono.firkin.appeal.json`. */
+export const APPEAL_COLLECTION = "ma.tokono.firkin.appeal";
+/**
+ * Build an access appeal to write into the requesting account's repo.
+ *
+ * Firkin's HTTP API is admin-gated; this record is how an account asks an
+ * operator to register it. An operator-side consumer tails the ATProto
+ * firehose, filters this collection, and applies its own policy. Nothing here
+ * grants service — the commit signature only proves who appealed.
+ *
+ * `firkin` is normalized with `normalizeOrigin`, because an operator-side
+ * consumer (and any indexer in front of it) matches the value against its own
+ * origin exactly.
+ *
+ * Use `appealRkey(firkin)` as the record key.
+ */
+export function appealRequest(opts) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    return {
+        $type: "ma.tokono.firkin.appeal",
+        firkin: normalizeOrigin(opts.firkin),
+        createdAt: new Date(now * 1000).toISOString(),
+        ...(opts.expireIn === undefined
+            ? {}
+            : { expiresAt: new Date((now + opts.expireIn) * 1000).toISOString() }),
+        ...(opts.nonce === undefined ? {} : { nonce: opts.nonce }),
+        ...(opts.note === undefined ? {} : { note: opts.note }),
+    };
+}
+/** The conventional record key for an appeal: the instance host
+ * (e.g. `firkin.example`), which is idempotent and a valid rkey. */
+export function appealRkey(firkin) {
+    return new URL(firkin.trim()).host;
+}
+/** The record a did:plc account writes into its repo to attest a session
+ * (MST key `ma.tokono.firkin.session/<session did>`). Write it once with your
+ * ATProto agent, then submit the commit + MST path via `Firkin.attestPlc`. */
+export function plcSessionRecord(opts) {
+    const nbf = opts.now ?? Math.floor(Date.now() / 1000);
+    return {
+        $type: "ma.tokono.firkin.session",
+        firkin: normalizeOrigin(opts.firkin),
+        session: opts.session,
+        commands: opts.commands,
+        nbf,
+        exp: nbf + (opts.expireIn ?? 30 * 24 * 60 * 60),
+    };
+}
 /** Simple in-memory cache (per Firkin instance). */
 export class MemoryBlockCache {
     map = new Map();
@@ -42,7 +129,10 @@ export class Firkin {
         this.blockCache = blockCache;
     }
     // --- blobs ---------------------------------------------------------------
-    /** Upload bytes; returns the CID and whether it was already stored. */
+    /** Upload bytes; returns the CID and whether it was already stored.
+     * `tags` is client-side sugar: after the bytes are stored (or deduped), the
+     * CID is added to each group with `tagAdd`. Tagging is a separate call, so
+     * if it fails the blob is already stored and `tagAdd` can be retried. */
     async upload(data, opts = {}) {
         let body;
         let cid;
@@ -54,7 +144,7 @@ export class Firkin {
             cid = cidForBytes(data, opts);
             body = new Blob([data]);
         }
-        const res = await this.fetchImpl(`${this.base}/blob/${cid}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}`, {
             method: "PUT",
             headers: {
                 Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobUpload))}`,
@@ -65,24 +155,81 @@ export class Firkin {
         if (!res.ok)
             throw await ApiError.of(res);
         const json = (await res.json());
+        await this.applyTags(cid, opts.tags);
         return { cid, deduplicated: json.status === "already_stored" };
     }
-    /** 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. */
+    /** Fetch a whole blob. Reads are authenticated: the server requires the
+     * `/firkin/blob/read` capability (an operator can opt into anonymous
+     * reads with `PUBLIC_READS=true`, in which case the header is ignored).
+     * Read tokens are reusable — reads are not replay-tracked. */
     async get(cid) {
-        const res = await this.fetchImpl(`${this.base}/blob/${cid}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}`, {
             headers: { Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobRead))}` },
         });
         if (!res.ok)
             throw await ApiError.of(res);
         return new Uint8Array(await res.arrayBuffer());
     }
+    /**
+     * Read a byte range of a **BDASL (BLAKE3)** blob with verified streaming:
+     * the server sends a bao proof and every chunk is checked against the CID
+     * before it is returned — the server is not trusted for integrity. Needs a
+     * BLAKE3 CID (`cidForBytes(data, { hash: "blake3" })`).
+     */
+    async verifiedRange(cid, range = {}) {
+        const headers = {
+            Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobRead))}`,
+        };
+        if (range.start !== undefined ||
+            range.end !== undefined ||
+            range.suffix !== undefined) {
+            headers.Range = rangeHeader(range);
+        }
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}?format=bao`, { headers });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        const total = Number(res.headers.get("X-Firkin-Data-Size") ?? "0");
+        const contentRange = res.headers.get("Content-Range") ?? "";
+        const parsedCid = CID.parse(cid);
+        const encoded = new Uint8Array(await res.arrayBuffer());
+        if (total === 0) {
+            decodeBaoRange({
+                encoded,
+                root: parsedCid.multihash.digest,
+                size: 0,
+                chunkStart: 0,
+                chunkEnd: 1,
+            });
+            return { data: new Uint8Array(0), start: 0, end: 0, total: 0 };
+        }
+        const last = total - 1;
+        const wantStart = range.suffix !== undefined
+            ? Math.max(0, total - range.suffix)
+            : Math.min(range.start ?? 0, last);
+        const wantEnd = range.suffix !== undefined
+            ? last
+            : Math.min(range.end ?? last, last);
+        const chunkStart = Math.floor(wantStart / BAO_CHUNK_SIZE);
+        const chunkEnd = Math.floor(wantEnd / BAO_CHUNK_SIZE) + 1;
+        const covered = /bytes (\d+)-(\d+)\/(\d+)/.exec(contentRange);
+        if (covered && Number(covered[1]) !== chunkStart * BAO_CHUNK_SIZE) {
+            throw new Error("verified streaming: the server covered an unexpected data range");
+        }
+        const data = decodeBaoRange({
+            encoded,
+            root: parsedCid.multihash.digest,
+            size: total,
+            chunkStart,
+            chunkEnd,
+        });
+        const from = wantStart - chunkStart * BAO_CHUNK_SIZE;
+        const to = wantEnd - chunkStart * BAO_CHUNK_SIZE + 1;
+        return { data: data.slice(from, to), start: wantStart, end: wantEnd, total };
+    }
     /** Fetch a byte range (206 responses; server-trusted verification).
      * Authenticated like [`get`](#get). */
     async getRange(cid, range = {}) {
-        const res = await this.fetchImpl(`${this.base}/blob/${cid}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}`, {
             headers: {
                 Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobRead))}`,
                 Range: rangeHeader(range),
@@ -109,7 +256,7 @@ export class Firkin {
      * caller's own chain is not stored yet. */
     async publishDelegation(minted, opts = {}) {
         const token = opts.token ?? (await this.token(CMD.blobUpload));
-        const res = await this.fetchImpl(`${this.base}/delegation/${minted.cid}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tokens/delegation/${minted.cid}`, {
             method: "PUT",
             headers: { Authorization: `Bearer ${toBase64Url(token)}` },
             body: new Blob([minted.proof]),
@@ -129,85 +276,99 @@ export class Firkin {
         const token = await this.token(`${CMD.blobRead}/${cid}`, {
             expireIn: opts.expireIn ?? 60,
         });
-        return `${this.base}/blob/${cid}?token=${toBase64Url(token)}`;
+        return `${this.base}${API_PREFIX}/blob/${cid}?token=${toBase64Url(token)}`;
     }
-    /** Attach an already-stored CID to the signer's account. */
-    async claim(cid) {
+    /** Attach an already-stored CID to the signer's account. `tags` is the
+     * same sugar as `upload`: the CID is added to each group afterwards. */
+    async claim(cid, opts = {}) {
         const token = await this.token(CMD.blobClaim);
-        const res = await this.fetchImpl(`${this.base}/blob/${cid}/claim`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}/claim`, {
             method: "POST",
             headers: { Authorization: `Bearer ${toBase64Url(token)}` },
         });
         if (!res.ok)
             throw await ApiError.of(res);
+        await this.applyTags(cid, opts.tags);
     }
     /** Detach the signer's claim; bytes die with the last claimant. */
     async delete(cid) {
-        const res = await this.fetchImpl(`${this.base}/blob/${cid}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}`, {
             method: "DELETE",
             headers: { Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobDelete))}` },
         });
         if (!res.ok)
             throw await ApiError.of(res);
     }
-    /** 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. */
-    async revoke(opts) {
-        const res = await this.fetchImpl(`${this.base}/account/revoke`, {
+    /** Revoke delegations/sessions: specific delegation or attestation CIDs,
+     * or every grant minted before now (`all: true`). Seed/did:key accounts
+     * authorize this with a direct invocation by the account key. An attested
+     * session must additionally pass a fresh passkey assertion (`stepUp`,
+     * built with `stepUpChallenge`) — a stolen session key must not be able to
+     * revoke. */
+    async revoke(opts, stepUp) {
+        const headers = {
+            Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountRevoke))}`,
+            "Content-Type": "application/json",
+        };
+        if (stepUp)
+            headers["X-Firkin-Assertion"] = assertionHeader(stepUp);
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/account/revoke`, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountRevoke))}`,
-                "Content-Type": "application/json",
-            },
+            headers,
             body: JSON.stringify({ cids: opts.cids ?? [], all: opts.all ?? false }),
         });
         if (!res.ok)
             throw await ApiError.of(res);
     }
-    /** (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. */
-    async register(did, credential) {
-        const token = await this.token(CMD.accountRegister);
-        const res = await this.fetchImpl(`${this.base}/accounts`, {
+    /** Attest a session for a `did:plc` account. `material` is what the client
+     * fetched from the account's repo and the PLC directory (base64url DAG-CBOR):
+     *
+     * - `ops`: the PLC operation log, genesis first;
+     * - `commit`: the signed repo commit containing the record;
+     * - `record`: the `plcSessionRecord(...)` value;
+     * - `proof`: the MST nodes proving the record is in that commit.
+     *
+     * The server verifies everything offline (no PLC/PDS call). */
+    static async attestPlc(base, material, fetchImpl = globalThis.fetch) {
+        const res = await fetchImpl(`${base}${API_PREFIX}/tokens/attestation`, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${toBase64Url(token)}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ did, ...(credential ? { credential } : {}) }),
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ plc: material }),
         });
         if (!res.ok)
             throw await ApiError.of(res);
+        return (await res.json());
     }
-    /** (Account key) attest a session delegation with the bound passkey. */
-    async attest(body) {
-        const res = await this.fetchImpl(`${this.base}/account/attest`, {
+    /** Enrol a passkey session. The assertion's challenge must be
+     * `attestationChallenge(...)`; the server verifies the ceremony, stores the
+     * session → account binding, and returns its attestation CID. After this,
+     * requests are signed by the session key (see `sessionTokenSource`).
+     * Static: the endpoint is unauthenticated by design — the assertion IS the
+     * authentication. */
+    static async attest(base, assertion, fetchImpl = globalThis.fetch) {
+        const res = await fetchImpl(`${base}${API_PREFIX}/tokens/attestation`, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountAttest))}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(body),
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ assertion: packageAssertion(assertion) }),
         });
         if (!res.ok)
             throw await ApiError.of(res);
+        return (await res.json());
     }
-    /** (Account key) bind a WebAuthn credential to this account. */
-    async bindCredential(credential) {
-        const res = await this.fetchImpl(`${this.base}/account/bind`, {
+    /** (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. */
+    async register(did, credential) {
+        const token = await this.token(CMD.accountRegister);
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/accounts`, {
             method: "POST",
             headers: {
-                Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountBind))}`,
+                Authorization: `Bearer ${toBase64Url(token)}`,
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({ credential }),
+            body: JSON.stringify({ did, ...(credential ? { credential } : {}) }),
         });
         if (!res.ok)
             throw await ApiError.of(res);
@@ -220,7 +381,7 @@ export class Firkin {
      * the endpoint is unauthenticated by design: the verified signature IS
      * the authentication. */
     static async whoami(base, assertion, fetchImpl = globalThis.fetch) {
-        const res = await fetchImpl(`${base}/account/whoami`, {
+        const res = await fetchImpl(`${base}${API_PREFIX}/account/whoami`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -237,7 +398,7 @@ export class Firkin {
     }
     /** (Admin) list registered accounts. */
     async listAccounts() {
-        const res = await this.fetchImpl(`${this.base}/accounts`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/accounts`, {
             headers: {
                 Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountList))}`,
             },
@@ -253,7 +414,7 @@ export class Firkin {
     // a resolved CID may be dangling (not yet uploaded or already GC'd).
     /** Set `name` → `cid`. Overwrites silently (last-writer-wins). */
     async registrySet(name, cid) {
-        const res = await this.fetchImpl(`${this.base}/registry/${encodeURIComponent(name)}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/registry/${encodeURIComponent(name)}`, {
             method: "PUT",
             headers: {
                 Authorization: `Bearer ${toBase64Url(await this.token(CMD.registryWrite))}`,
@@ -266,7 +427,7 @@ export class Firkin {
     }
     /** Resolve `name`; returns null when unset. */
     async registryGet(name) {
-        const res = await this.fetchImpl(`${this.base}/registry/${encodeURIComponent(name)}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/registry/${encodeURIComponent(name)}`, {
             headers: { Authorization: `Bearer ${toBase64Url(await this.token(CMD.registryRead))}` },
         });
         if (res.status === 404)
@@ -278,7 +439,7 @@ export class Firkin {
     }
     /** Unset `name` (idempotent). */
     async registryDelete(name) {
-        const res = await this.fetchImpl(`${this.base}/registry/${encodeURIComponent(name)}`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/registry/${encodeURIComponent(name)}`, {
             method: "DELETE",
             headers: { Authorization: `Bearer ${toBase64Url(await this.token(CMD.registryWrite))}` },
         });
@@ -287,7 +448,7 @@ export class Firkin {
     }
     /** The account's whole registry: name → CID (sorted). */
     async registryList() {
-        const res = await this.fetchImpl(`${this.base}/registry`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/registry`, {
             headers: { Authorization: `Bearer ${toBase64Url(await this.token(CMD.registryRead))}` },
         });
         if (!res.ok)
@@ -295,7 +456,136 @@ export class Firkin {
         const json = (await res.json());
         return json.names;
     }
+    // --- blob tags --------------------------------------------------------------
+    /** Tag blobs: add CIDs to a per-account label group (idempotent). */
+    async tagAdd(name, cids) {
+        const body = Array.isArray(cids) ? { cids } : { cid: cids };
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag/${encodeURIComponent(name)}`, {
+            method: "PUT",
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagWrite))}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
+    /** One page of a tag group (groups are paged; `next` walks them). */
+    async tagGet(name, opts = {}) {
+        const cursor = opts.cursor ?? 0;
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag/${encodeURIComponent(name)}?cursor=${cursor}`, {
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagRead))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
+    /** Every CID in a tag group (walks the pages). */
+    async tagAll(name) {
+        const all = [];
+        let cursor = 0;
+        while (cursor !== null) {
+            const page = await this.tagGet(name, { cursor });
+            all.push(...page.cids);
+            cursor = page.next;
+        }
+        return all;
+    }
+    /** The tag groups a CID belongs to (reverse lookup). Needs the full
+     * `/firkin/tag/read` command: a per-group proof cannot widen into it. */
+    async blobTags(cid) {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/blob/${cid}/tags`, {
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagRead))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        const json = (await res.json());
+        return json.tags;
+    }
+    /** Add a CID to each group in `tags` (sugar for `upload`/`claim`). */
+    async applyTags(cid, tags) {
+        if (tags === undefined)
+            return;
+        for (const name of Array.isArray(tags) ? tags : [tags]) {
+            await this.tagAdd(name, cid);
+        }
+    }
+    /** Every tag group with its CID count. */
+    async tagList() {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag`, {
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagRead))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        const json = (await res.json());
+        return json.tags;
+    }
+    /** Untag one blob from a group. */
+    async tagRemove(name, cid) {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag/${encodeURIComponent(name)}/${cid}`, {
+            method: "DELETE",
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagWrite))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
+    /** Drop a tag group; the blobs stay stored. */
+    async tagDelete(name) {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag/${encodeURIComponent(name)}`, {
+            method: "DELETE",
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagWrite))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
+    /** Drop a tag group **and detach every blob in it** (bytes die where this
+     * account is the last claimant). Needs `/firkin/tag/delete`. */
+    async tagDeleteBlobs(name) {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/tag/${encodeURIComponent(name)}/blobs`, {
+            method: "DELETE",
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.tagDelete))}`,
+            },
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
     // --- CAR Mirror batch sync ---------------------------------------------------
+    /**
+     * Ingest a rootless CARv1 — "upload a `.car` file". Every block is verified
+     * against its own CID, policy-checked and claimed by the account; there is
+     * no DAG traversal and no root requirement (unlike [`dagPush`](#dagpush),
+     * which syncs one DAG over multiple rounds). Partial success is normal:
+     * `failed` lists the rejected blocks (digest mismatch, policy, size).
+     */
+    async ingestCar(car) {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/car`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobUpload))}`,
+                "Content-Type": "application/vnd.ipld.car",
+            },
+            body: new Blob([car]),
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
     /**
      * 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
@@ -392,7 +682,7 @@ export class Firkin {
                 throw new Error("push round has no blocks");
             const first = send[0];
             const car = carFile(first === rootCid.toString() ? rootCid : CID.parse(first), send.map((c) => [CID.parse(c), all.get(c)]));
-            const res = await this.fetchImpl(`${this.base}/dag/push/${rootCid}`, {
+            const res = await this.fetchImpl(`${this.base}${API_PREFIX}/dag/push/${rootCid}`, {
                 method: "POST",
                 headers: {
                     Authorization: `Bearer ${toBase64Url(await this.token(CMD.blobUpload))}`,
@@ -447,7 +737,7 @@ export class Firkin {
             };
             if (body)
                 headers["Content-Type"] = "application/vnd.ipld.dag-cbor";
-            const res = await this.fetchImpl(`${this.base}/dag/pull/${root}`, {
+            const res = await this.fetchImpl(`${this.base}${API_PREFIX}/dag/pull/${root}`, {
                 method: "POST",
                 headers,
                 ...(body ? { body: new Blob([body]) } : {}),
@@ -522,10 +812,11 @@ function rangeHeader(range) {
 }
 // --- CARv1 framing -----------------------------------------------------------
 export function carFile(root, entries) {
-    // Header roots = the DAG root; entries = exactly the blocks being sent
-    // this round. Never repeat a block the server already has: the receiver
-    // interrupts the round at the first Have block.
-    const header = dagcbor.encode({ roots: [root], version: 1 });
+    // Header roots = the DAG root (`null` for a rootless bag — the DASL CAR
+    // format allows an empty roots array); entries = exactly the blocks being
+    // sent this round. Never repeat a block the server already has: the
+    // receiver interrupts the round at the first Have block.
+    const header = dagcbor.encode({ roots: root ? [root] : [], version: 1 });
     const parts = [uvarintFrame(header.length), header];
     for (const [cid, block] of entries) {
         const entry = new Uint8Array(cid.bytes.length + block.length);
@@ -535,7 +826,7 @@ export function carFile(root, entries) {
     }
     return concat(parts);
 }
-function parseCarBlocks(car) {
+export function parseCarBlocks(car) {
     let pos = 0;
     const readUvarint = () => {
         let result = 0;

package/dist/index.d.ts

@@ -4,5 +4,8 @@ export * from "./ucan.ts";
 export * from "./client.ts";
 export * from "./bloom.ts";
 export * from "./webauthn.ts";
+export * from "./plc.ts";
+export * from "./rasl.ts";
+export * from "./bao.ts";
 export * from "./bip39.ts";
 export * from "./bloom.ts";

package/dist/index.js

@@ -4,5 +4,8 @@ export * from "./ucan.js";
 export * from "./client.js";
 export * from "./bloom.js";
 export * from "./webauthn.js";
+export * from "./plc.js";
+export * from "./rasl.js";
+export * from "./bao.js";
 export * from "./bip39.js";
 export * from "./bloom.js";