@tokono.ma/firkin 0.3.0 → 0.4.0

package/dist/client.js

@@ -4,18 +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();
@@ -45,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;
@@ -68,6 +155,7 @@ 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. Reads are authenticated: the server requires the
@@ -82,6 +170,62 @@ export class Firkin {
             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 = {}) {
@@ -112,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}${API_PREFIX}/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]),
@@ -134,8 +278,9 @@ export class Firkin {
         });
         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}${API_PREFIX}/blob/${cid}/claim`, {
             method: "POST",
@@ -143,6 +288,7 @@ export class Firkin {
         });
         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) {
@@ -153,24 +299,62 @@ export class Firkin {
         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) {
+    /** 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);
     }
+    /** 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: { "Content-Type": "application/json" },
+            body: JSON.stringify({ plc: material }),
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
+    /** 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: { "Content-Type": "application/json" },
+            body: JSON.stringify({ assertion: packageAssertion(assertion) }),
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        return (await res.json());
+    }
     /** (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
@@ -272,6 +456,115 @@ 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
@@ -533,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,6 +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,6 +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";

package/dist/plc.d.ts

@@ -0,0 +1,87 @@
+import type { PlcSessionRecord } from "./client.ts";
+/** The record collection Firkin verifies (`ma.tokono.firkin.session`). */
+export declare const PLC_SESSION_COLLECTION = "ma.tokono.firkin.session";
+/** What `Firkin.attestPlc` takes. */
+export interface PlcAttestationMaterial {
+    did: string;
+    /** PLC operations, genesis first (base64url DAG-CBOR). */
+    ops: string[];
+    /** The signed repo commit block. */
+    commit: string;
+    /** The session record. */
+    record: string;
+    /** MST node blocks proving the record's inclusion. */
+    proof: string[];
+}
+/**
+ * The subset of an ATProto agent this needs. `@atproto/api`'s `Agent` (or an
+ * OAuth session's agent) satisfies it structurally.
+ */
+export interface PlcAgentLike {
+    com: {
+        atproto: {
+            repo: {
+                putRecord(input: {
+                    repo: string;
+                    collection: string;
+                    rkey: string;
+                    record: unknown;
+                    validate?: boolean;
+                }): Promise<{
+                    data: {
+                        commit?: {
+                            cid?: string;
+                        };
+                    };
+                }>;
+            };
+            sync: {
+                getLatestCommit(input: {
+                    did: string;
+                }): Promise<{
+                    data: {
+                        cid: string;
+                    };
+                }>;
+                getBlocks(input: {
+                    did: string;
+                    cids: string[];
+                }): Promise<{
+                    data: Uint8Array;
+                }>;
+                getRecord(input: {
+                    did: string;
+                    collection: string;
+                    rkey: string;
+                }): Promise<{
+                    data: {
+                        cid: string;
+                        value: unknown;
+                        proof?: Uint8Array[];
+                    };
+                }>;
+            };
+        };
+    };
+}
+/**
+ * Write `record` into the account's repo and collect the attestation material.
+ *
+ * `record` is what `plcSessionRecord(...)` returns; its `session` field is used
+ * as the record key, which is why the service can find it deterministically.
+ *
+ * The commit and the MST proof must describe the *same* revision; a concurrent
+ * write between the two fetches is detected (the proof must contain the
+ * commit's `data` root) and retried.
+ */
+export declare function collectPlcAttestation(opts: {
+    agent: PlcAgentLike;
+    did: string;
+    record: PlcSessionRecord;
+    collection?: string;
+    /** Defaults to `https://plc.directory`. */
+    plcDirectory?: string;
+    fetchImpl?: typeof fetch;
+    /** Fetch retries when the repo advances mid-collection (default 5). */
+    attempts?: number;
+}): Promise<PlcAttestationMaterial>;

package/dist/plc.js

@@ -0,0 +1,97 @@
+// `did:plc` attestation material: write the session record into the account's
+// repo with an ATProto agent, then collect everything Firkin verifies.
+//
+// Firkin never talks to a PDS or a PLC directory. The client gathers:
+// - the PLC operation log (`plc.directory/<did>/log`),
+// - the signed repo commit containing the record,
+// - the record itself,
+// - the MST nodes proving the record is in that commit.
+// Everything is sent as base64url DAG-CBOR; `Firkin.attestPlc` posts it.
+import * as dagcbor from "@ipld/dag-cbor";
+import { cidForBytes, CODEC_DAG_CBOR } from "./cid.js";
+import { parseCarBlocks } from "./client.js";
+/** The record collection Firkin verifies (`ma.tokono.firkin.session`). */
+export const PLC_SESSION_COLLECTION = "ma.tokono.firkin.session";
+/**
+ * Write `record` into the account's repo and collect the attestation material.
+ *
+ * `record` is what `plcSessionRecord(...)` returns; its `session` field is used
+ * as the record key, which is why the service can find it deterministically.
+ *
+ * The commit and the MST proof must describe the *same* revision; a concurrent
+ * write between the two fetches is detected (the proof must contain the
+ * commit's `data` root) and retried.
+ */
+export async function collectPlcAttestation(opts) {
+    const collection = opts.collection ?? PLC_SESSION_COLLECTION;
+    // The PLC endpoint takes the DID verbatim (`/did:plc:…/log`); validate the
+    // syntax rather than escaping it into a path.
+    if (!/^did:plc:[a-z2-7]{24}$/.test(opts.did)) {
+        throw new Error(`not a did:plc: ${opts.did}`);
+    }
+    const session = opts.record.session;
+    if (typeof session !== "string" || session.length === 0) {
+        throw new Error("record.session (the did:key) is required");
+    }
+    const rkey = session;
+    await opts.agent.com.atproto.repo.putRecord({
+        repo: opts.did,
+        collection,
+        rkey,
+        record: opts.record,
+    });
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const directory = opts.plcDirectory ?? "https://plc.directory";
+    const logRes = await fetchImpl(`${directory}/${opts.did}/log`);
+    if (!logRes.ok) {
+        throw new Error(`PLC log for ${opts.did}: ${logRes.status}`);
+    }
+    const log = (await logRes.json());
+    if (!Array.isArray(log) || log.length === 0) {
+        throw new Error(`PLC log for ${opts.did} is empty`);
+    }
+    const ops = log.map((op) => base64url(dagcbor.encode(op)));
+    for (let attempt = 0; attempt < (opts.attempts ?? 5); attempt++) {
+        // Everything below is public; the agent's auth is simply unused.
+        const latest = await opts.agent.com.atproto.sync.getLatestCommit({
+            did: opts.did,
+        });
+        const car = await opts.agent.com.atproto.sync.getBlocks({
+            did: opts.did,
+            cids: [latest.data.cid],
+        });
+        const commitBytes = parseCarBlocks(new Uint8Array(car.data)).get(latest.data.cid);
+        if (!commitBytes)
+            continue;
+        const commit = dagcbor.decode(commitBytes);
+        const rec = await opts.agent.com.atproto.sync.getRecord({
+            did: opts.did,
+            collection,
+            rkey,
+        });
+        const proof = rec.data.proof ?? [];
+        if (!commit.data || proof.length === 0)
+            continue;
+        // The proof must belong to this commit's tree. The node order is not
+        // specified, so look for the declared root anywhere in the set. (`proof`
+        // entries are raw DAG-CBOR blocks, hashed as-is.)
+        const root = commit.data.toString();
+        const roots = proof.map((node) => cidForBytes(node, { codec: CODEC_DAG_CBOR }));
+        if (!roots.includes(root))
+            continue;
+        return {
+            did: opts.did,
+            ops,
+            commit: base64url(commitBytes),
+            record: base64url(dagcbor.encode(rec.data.value)),
+            proof: proof.map((node) => base64url(node)),
+        };
+    }
+    throw new Error("the repo kept advancing while collecting the attestation; retry");
+}
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/dist/ucan.d.ts

@@ -23,6 +23,9 @@ export declare const CMD: {
     readonly accountRecover: "/firkin/account/recover";
     readonly registryRead: "/firkin/registry/read";
     readonly registryWrite: "/firkin/registry/write";
+    readonly tagRead: "/firkin/tag/read";
+    readonly tagWrite: "/firkin/tag/write";
+    readonly tagDelete: "/firkin/tag/delete";
 };
 export type UcanCommand = (typeof CMD)[keyof typeof CMD] | (string & {});
 export interface MintOptions {
@@ -30,6 +33,10 @@ export interface MintOptions {
     command: UcanCommand;
     /** Seconds until expiry (default 600). */
     expireIn?: number;
+    /** Free-form signed metadata. Attested sessions set
+     * `{ "firkin/account": "<account did>" }` so the server can resolve the
+     * session binding (the value is a hint; the DO enforces it). */
+    meta?: Record<string, unknown>;
 }
 export interface DelegationOptions extends MintOptions {
     /** The rights holder (account DID) — the chain root. */

package/dist/ucan.js

@@ -48,6 +48,9 @@ export const CMD = {
     accountRecover: "/firkin/account/recover",
     registryRead: "/firkin/registry/read",
     registryWrite: "/firkin/registry/write",
+    tagRead: "/firkin/tag/read",
+    tagWrite: "/firkin/tag/write",
+    tagDelete: "/firkin/tag/delete",
 };
 function expFromNow(expireIn) {
     return expireIn === undefined ? null : Math.floor(Date.now() / 1000) + expireIn;
@@ -72,7 +75,7 @@ function invocationPayload(signer, opts) {
         cause: null,
         iat: null,
         exp: expFromNow(opts.expireIn),
-        meta: {},
+        meta: opts.meta ?? {},
         nonce: nonce(),
     };
 }