@tokono.ma/firkin 0.1.1 → 0.3.0

package/README.md

@@ -46,12 +46,13 @@ signs directly); delegates mint with [`invocation()`](#delegation--sessions).
 ## API
 
 ```ts
-// blobs — reads are authenticated automatically (for PUBLIC_READS=false)
+// blobs — reads are authenticated automatically (read tokens)
 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.publishDelegation(d)    // store a delegation so tokens can reference it by CID
 rb.claim(cid)          // attach an already-stored CID to your account
 rb.delete(cid)         // detach; bytes die with the last claimant
 
@@ -66,6 +67,7 @@ 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
+rb.ingestCar(carBytes)        // rootless CARv1: verify + claim each block (no DAG)
 
 // account
 rb.revoke({ cids? , all? })   // kill delegations (account key only)
@@ -93,15 +95,17 @@ with that key:
 ```ts
 import { delegationPayloadBytes, invocation, delegate } from "@tokono.ma/firkin";
 
-const { proof, cid } = await delegate(account, {
+const delegation = 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
 });
+await accountClient.publishDelegation(delegation); // once — idempotent
 
+// Tokens reference the proof by CID: no proof bytes on the wire.
 const rb = new Firkin(base, async (command) =>
-  invocation(session, { command, proofs: [proof], expireIn: 600 }),
+  invocation(session, { command, proofs: [delegation.cid], subject: account.did(), expireIn: 600 }),
 );
 
 // Revocation must be authorized by the account key — not the session:

package/dist/client.d.ts

@@ -1,13 +1,36 @@
 import { CID } from "multiformats";
+/** Wire version prefix for every API path (`/health` and `/.well-known/*`
+ * live outside it). */
+export declare const API_PREFIX = "/v1";
 import type { Signer } from "./keys.ts";
+/** Per-call options a TokenSource may honor. */
+export interface TokenOptions {
+    /** Override the token's expiry (seconds from now). */
+    expireIn?: number;
+}
 /** 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>;
+ * (the default signer source does). `options.expireIn` is a hint used by
+ * `readUrl` to mint short-lived links; sources may ignore it. */
+export type TokenSource = (command: string, options?: TokenOptions) => 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 CarIngestResult {
+    /** Blocks found in the CAR. */
+    blocks: number;
+    /** Blocks written by this call. */
+    stored: number;
+    /** Blocks that were already stored (claim joined). */
+    already: number;
+    /** Total rejected blocks (the `failed` list may be capped). */
+    failed_total: number;
+    failed: {
+        cid: string;
+        error: string;
+    }[];
+}
 export interface UploadResult {
     cid: string;
     /** True when the blob was already stored (dedup; claim joined). */
@@ -54,14 +77,36 @@ export declare class Firkin {
         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. */
+    /** 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. */
     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>;
+    /** Publish a delegation to the server's delegation store so invocations
+     * can reference it by CID — the default token shape. Idempotent: the store
+     * dedups by CID, so publishing at session start is always safe. `token`
+     * bootstraps with an inline-proof token (`inlineInvocation`) when the
+     * caller's own chain is not stored yet. */
+    publishDelegation(minted: {
+        proof: Uint8Array;
+        cid: string;
+    }, opts?: {
+        token?: Uint8Array;
+    }): Promise<{
+        cid: string;
+    }>;
+    /** A short-lived, CID-scoped read URL — the presigned-URL equivalent for
+     * media elements (`<audio src>`, `<video src>`), which cannot set an
+     * Authorization header. The URL carries a `/firkin/blob/read/<cid>`
+     * invocation; the server accepts `?token=` on GET/HEAD only and, with
+     * `PUBLIC_READS=false`, enforces the CID narrowing — a leaked URL exposes
+     * just that blob until the token expires. Keep `expireIn` short (60s). */
+    readUrl(cid: string, opts?: {
+        expireIn?: number;
+    }): Promise<string>;
     /** 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. */
@@ -85,19 +130,6 @@ export declare class Firkin {
         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
@@ -124,6 +156,14 @@ export declare class Firkin {
     registryDelete(name: string): Promise<void>;
     /** The account's whole registry: name → CID (sorted). */
     registryList(): Promise<Record<string, string>>;
+    /**
+     * 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).
+     */
+    ingestCar(car: Uint8Array): Promise<CarIngestResult>;
     /**
      * 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
@@ -173,7 +213,7 @@ export declare class Firkin {
      */
     pullFile(root: string): Promise<Uint8Array>;
 }
-export declare function carFile(root: CID, entries: [CID, Uint8Array][]): Uint8Array;
+export declare function carFile(root: CID | null, entries: [CID, Uint8Array][]): Uint8Array;
 export declare function multihashSha256(data: Uint8Array): MultihashDigest;
 type MultihashDigest = {
     code: number;

package/dist/client.js

@@ -4,10 +4,13 @@ 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";
+/** 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";
 /** Signer-backed source: mints a fresh direct invocation per request. */
 export function signerToken(signer, expireIn = 600) {
-    return async (command) => mintInvocation(signer, { command, expireIn });
+    return async (command, options) => mintInvocation(signer, { command, expireIn: options?.expireIn ?? expireIn });
 }
 /** Fixed-token source: only appropriate for public/read-only usage. */
 export function staticToken(token) {
@@ -54,7 +57,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))}`,
@@ -67,12 +70,12 @@ export class Firkin {
         const json = (await res.json());
         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)
@@ -82,7 +85,7 @@ export class Firkin {
     /** 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),
@@ -102,10 +105,39 @@ export class Firkin {
         };
     }
     // --- claims & deletion ------------------------------------------------------
+    /** Publish a delegation to the server's delegation store so invocations
+     * can reference it by CID — the default token shape. Idempotent: the store
+     * dedups by CID, so publishing at session start is always safe. `token`
+     * bootstraps with an inline-proof token (`inlineInvocation`) when the
+     * 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}`, {
+            method: "PUT",
+            headers: { Authorization: `Bearer ${toBase64Url(token)}` },
+            body: new Blob([minted.proof]),
+        });
+        if (!res.ok)
+            throw await ApiError.of(res);
+        const json = (await res.json());
+        return json;
+    }
+    /** A short-lived, CID-scoped read URL — the presigned-URL equivalent for
+     * media elements (`<audio src>`, `<video src>`), which cannot set an
+     * Authorization header. The URL carries a `/firkin/blob/read/<cid>`
+     * invocation; the server accepts `?token=` on GET/HEAD only and, with
+     * `PUBLIC_READS=false`, enforces the CID narrowing — a leaked URL exposes
+     * just that blob until the token expires. Keep `expireIn` short (60s). */
+    async readUrl(cid, opts = {}) {
+        const token = await this.token(`${CMD.blobRead}/${cid}`, {
+            expireIn: opts.expireIn ?? 60,
+        });
+        return `${this.base}${API_PREFIX}/blob/${cid}?token=${toBase64Url(token)}`;
+    }
     /** Attach an already-stored CID to the signer's account. */
     async claim(cid) {
         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)}` },
         });
@@ -114,7 +146,7 @@ export class Firkin {
     }
     /** 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))}` },
         });
@@ -128,7 +160,7 @@ export class Firkin {
      * (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`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/account/revoke`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountRevoke))}`,
@@ -146,7 +178,7 @@ export class Firkin {
      * 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`, {
+        const res = await this.fetchImpl(`${this.base}${API_PREFIX}/accounts`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${toBase64Url(token)}`,
@@ -157,32 +189,6 @@ export class Firkin {
         if (!res.ok)
             throw await ApiError.of(res);
     }
-    /** (Account key) attest a session delegation with the bound passkey. */
-    async attest(body) {
-        const res = await this.fetchImpl(`${this.base}/account/attest`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountAttest))}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(body),
-        });
-        if (!res.ok)
-            throw await ApiError.of(res);
-    }
-    /** (Account key) bind a WebAuthn credential to this account. */
-    async bindCredential(credential) {
-        const res = await this.fetchImpl(`${this.base}/account/bind`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${toBase64Url(await this.token(CMD.accountBind))}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ credential }),
-        });
-        if (!res.ok)
-            throw await ApiError.of(res);
-    }
     /** 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
@@ -191,7 +197,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({
@@ -208,7 +214,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))}`,
             },
@@ -224,7 +230,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))}`,
@@ -237,7 +243,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)
@@ -249,7 +255,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))}` },
         });
@@ -258,7 +264,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)
@@ -267,6 +273,26 @@ export class Firkin {
         return json.names;
     }
     // --- 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
@@ -363,7 +389,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))}`,
@@ -418,7 +444,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]) } : {}),
@@ -493,10 +519,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);

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/rasl.d.ts

@@ -0,0 +1,30 @@
+export interface RaslUrl {
+    /** The DASL/BDASL CID (the URL's authority). */
+    cid: string;
+    /** Hosts that may serve it (`?hint=` values, invalid ones dropped). */
+    hints: string[];
+}
+/** Build a `rasl://` URL for a CID and optional hint hosts. */
+export declare function raslUrl(cid: string, hints?: string[]): string;
+/** Parse a `rasl://` URL per the spec: the host is the CID, `hint` entries
+ * are the (valid) hint hosts; everything else, including the path, is
+ * ignored. */
+export declare function parseRasl(url: string): RaslUrl;
+/** Check that `bytes` hash to `cid` (SHA-256 and BLAKE3 multihashes).
+ * Compares the digest, so CIDv0/CIDv1 spelling doesn't matter. */
+export declare function verifyCid(cid: string, bytes: Uint8Array): boolean;
+export interface ResolveOptions {
+    fetchImpl?: typeof fetch;
+    /** Cancels the whole resolution (including in-flight hint requests). */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a `rasl://` URL: request every hint's
+ * `https://<hint>/.well-known/rasl/<cid>` in parallel (statelessly), take the
+ * first response whose bytes hash to the CID. Failing or mismatching hints
+ * are skipped; if none verify, it throws.
+ */
+export declare function resolveRasl(url: string, opts?: ResolveOptions): Promise<{
+    cid: string;
+    bytes: Uint8Array;
+}>;

package/dist/rasl.js

@@ -0,0 +1,107 @@
+// RASL (Retrieval of Arbitrary Structures & Links) — https://dasl.ing/rasl.html
+//
+// A `rasl://<cid>/?hint=<host>&hint=<host>` URL names a CID plus optional
+// places to fetch it. Retrieval is stateless (no cookies, no credentials —
+// the hash is the authority) and self-verifying: whatever comes back must
+// hash to the CID.
+import { sha256 } from "@noble/hashes/sha2";
+import { blake3 } from "@noble/hashes/blake3";
+import { CID } from "multiformats";
+import { HASH_BLAKE3, HASH_SHA256 } from "./cid.js";
+/** A valid `https` host: DNS labels + optional port (IPv6 literals too). */
+const HOST_RE = /^(\[[0-9a-fA-F:]+\]|[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*)(:\d{1,5})?$/;
+/** Build a `rasl://` URL for a CID and optional hint hosts. */
+export function raslUrl(cid, hints = []) {
+    const query = hints.map((hint) => `hint=${encodeURIComponent(hint)}`).join("&");
+    return `rasl://${cid}/${query ? `?${query}` : ""}`;
+}
+/** Parse a `rasl://` URL per the spec: the host is the CID, `hint` entries
+ * are the (valid) hint hosts; everything else, including the path, is
+ * ignored. */
+export function parseRasl(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "rasl:") {
+        throw new Error(`not a rasl:// URL: ${url}`);
+    }
+    const cid = parsed.host;
+    if (!cid)
+        throw new Error(`rasl:// URL lacks a CID: ${url}`);
+    CID.parse(cid); // must be a well-formed CID
+    const hints = parsed.searchParams
+        .getAll("hint")
+        .map((hint) => hint.trim())
+        .filter((hint) => HOST_RE.test(hint));
+    return { cid, hints };
+}
+/** Check that `bytes` hash to `cid` (SHA-256 and BLAKE3 multihashes).
+ * Compares the digest, so CIDv0/CIDv1 spelling doesn't matter. */
+export function verifyCid(cid, bytes) {
+    const parsed = CID.parse(cid);
+    const digest = parsed.multihash.code === HASH_SHA256
+        ? sha256(bytes)
+        : parsed.multihash.code === HASH_BLAKE3
+            ? blake3(bytes)
+            : undefined;
+    if (!digest || digest.length !== parsed.multihash.size)
+        return false;
+    return parsed.multihash.digest.every((byte, i) => byte === digest[i]);
+}
+/**
+ * Resolve a `rasl://` URL: request every hint's
+ * `https://<hint>/.well-known/rasl/<cid>` in parallel (statelessly), take the
+ * first response whose bytes hash to the CID. Failing or mismatching hints
+ * are skipped; if none verify, it throws.
+ */
+export async function resolveRasl(url, opts = {}) {
+    const { cid, hints } = parseRasl(url);
+    if (hints.length === 0) {
+        throw new Error("rasl:// URL has no usable hints");
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const signals = [controller.signal];
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            throw new Error("rasl resolution aborted");
+        opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+        signals.push(opts.signal);
+    }
+    const attempts = hints.map(async (hint) => {
+        const res = await fetchImpl(`https://${hint}/.well-known/rasl/${cid}`, {
+            method: "GET",
+            // RASL is stateless: no cookies, no credentials, no content negotiation.
+            credentials: "omit",
+            headers: { Accept: "*/*" },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            throw new Error(`${hint}: HTTP ${res.status}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (!verifyCid(cid, bytes))
+            throw new Error(`${hint}: bytes do not hash to ${cid}`);
+        return { cid, bytes };
+    });
+    try {
+        return await firstSuccess(attempts);
+    }
+    finally {
+        controller.abort(); // stop the losers
+    }
+}
+/** The first fulfilled promise; rejects when all fail. */
+async function firstSuccess(promises) {
+    return new Promise((resolve, reject) => {
+        let pending = promises.length;
+        const errors = [];
+        for (const promise of promises) {
+            promise.then(resolve, (error) => {
+                errors.push(error);
+                if (--pending === 0) {
+                    reject(new Error(`RASL retrieval failed for all hints: ${errors
+                        .map((e) => (e instanceof Error ? e.message : String(e)))
+                        .join("; ")}`));
+                }
+            });
+        }
+    });
+}

package/dist/ucan.d.ts

@@ -1,3 +1,4 @@
+import { CID } from "multiformats";
 import type { UcanSigner } from "./keys.ts";
 export declare const INV_TAG = "ucan/inv@1.0.0-rc.1";
 export declare const DLG_TAG = "ucan/dlg@1.0.0-rc.1";
@@ -20,8 +21,6 @@ export declare const CMD: {
     readonly accountList: "/firkin/account/list";
     readonly accountRevoke: "/firkin/account/revoke";
     readonly accountRecover: "/firkin/account/recover";
-    readonly accountAttest: "/firkin/account/attest";
-    readonly accountBind: "/firkin/account/bind";
     readonly registryRead: "/firkin/registry/read";
     readonly registryWrite: "/firkin/registry/write";
 };
@@ -41,23 +40,34 @@ export interface DelegationOptions extends MintOptions {
 /** Mint a direct invocation token (issuer == subject == the signer's DID). */
 export declare function mintInvocation(signer: UcanSigner, opts: MintOptions): Promise<Uint8Array>;
 /**
- * Mint a delegated invocation token: `proofs` are bare delegation envelope
- * containers (root-first) minted by the account holder. Each proof's CID is
- * written into the invocation payload's `prf` — the server checks that the
- * payload's proof CIDs match the envelopes carried in the container.
+ * Mint a delegated invocation token whose proofs travel **by reference**:
+ * the container carries only the invocation, and its `prf` names the CIDs of
+ * delegations previously published to the server's delegation store
+ * (`Firkin.publishDelegation`). This keeps tokens small regardless of chain
+ * depth or assertion size — a passkey session's read URL is ~700 B instead of
+ * ~1.7 kB.
  *
- * A proof is either the bare envelope bytes, or `{proof, cid}` /`{bytes,
- * cid}` — the shape `delegate`/`assertionToProof` return. The explicit `cid`
- * is required for assertion proofs: their CID is over the envelope the
- * SERVER synthesizes, not over the proof bytes.
+ * A proof input may carry its own bytes (`delegate`/`assertionToProof` return
+ * `{proof, cid}`), which are used locally only — to discover the chain
+ * subject and to narrow the command — and are never put on the wire. With a
+ * bare CID, pass `subject` (the account DID) yourself.
  */
-type ProofInput = Uint8Array | {
+export type ProofInput = string | CID | {
     bytes?: Uint8Array;
     proof?: Uint8Array;
     cid: string;
 };
 export declare function invocation(signer: UcanSigner, opts: MintOptions & {
     proofs: ProofInput[];
+    subject?: string;
+}): Promise<Uint8Array>;
+/**
+ * Mint an invocation **with its proofs inline** — bootstrap only: the
+ * delegation store's publish call is authorized by a chain that is not stored
+ * yet. Everything else should use [`invocation`](#invocation).
+ */
+export declare function inlineInvocation(signer: UcanSigner, opts: MintOptions & {
+    proofs: ProofInput[];
 }): Promise<Uint8Array>;
 export interface MintedDelegation {
     /** The proof container (DAG-CBOR bytes) the delegate attaches to invocations. */
@@ -90,4 +100,3 @@ export declare function delegate(signer: UcanSigner, opts: DelegationOptions): P
 export declare function parseContainer(container: Uint8Array): unknown[];
 /** Decode a container's invocation payload (diagnostics / verification). */
 export declare function decodeInvocation(container: Uint8Array): Record<string, unknown>;
-export {};

package/dist/ucan.js

@@ -46,8 +46,6 @@ export const CMD = {
     accountList: "/firkin/account/list",
     accountRevoke: "/firkin/account/revoke",
     accountRecover: "/firkin/account/recover",
-    accountAttest: "/firkin/account/attest",
-    accountBind: "/firkin/account/bind",
     registryRead: "/firkin/registry/read",
     registryWrite: "/firkin/registry/write",
 };
@@ -85,33 +83,37 @@ export async function mintInvocation(signer, opts) {
     return dagcbor.encode([invocation]);
 }
 export async function invocation(signer, opts) {
-    // Decode each proof: either a standard varsig dlg envelope
-    // `[sig, {h, "ucan/dlg@…": payload}]` or a WebAuthn assertion proof
-    // `{ad, cd, sg}` whose clientDataJSON.challenge carries the dlg payload.
-    const decoded = opts.proofs.map((p) => {
-        const bytes = p instanceof Uint8Array ? p : (p.bytes ?? p.proof);
+    if (opts.proofs.length === 0) {
+        throw new Error("delegated invocation needs at least one proof");
+    }
+    const decoded = opts.proofs.map((input) => {
+        const cid = proofInputCid(input);
+        const bytes = proofInputBytes(input);
         if (!bytes)
-            throw new Error("proof input lacks bytes");
+            return { cid, payload: undefined };
         const d = dagcbor.decode(bytes);
         if (Array.isArray(d) &&
             d.length === 2 &&
             d[1] instanceof Object &&
             Object.keys(d[1]).some((k) => k.startsWith("ucan/dlg@"))) {
             const payload = d[1][Object.keys(d[1]).find((k) => k.startsWith("ucan/dlg@"))];
-            return { bytes, decoded: d, payload };
+            return { cid, payload };
         }
         if (d instanceof Object && "ad" in d && "cd" in d && "sg" in d) {
             // Assertion proof: the dlg payload rides in the challenge.
             const cd = JSON.parse(d.cd);
             const payload = dagcbor.decode(base64UrlDecode(cd.challenge));
-            return { bytes, decoded: d, payload };
+            return { cid, payload };
         }
         throw new Error("unrecognized proof format");
     });
     const first = decoded[0];
     if (!first)
         throw new Error("delegated invocation needs at least one proof");
-    const subject = first.payload.sub;
+    const subject = first.payload?.sub ?? opts.subject;
+    if (!subject) {
+        throw new Error("unknown chain subject: pass `subject` (the account DID) when proofs are referenced by CID only");
+    }
     const payload = invocationPayload(signer, opts);
     payload.aud = subject;
     payload.sub = subject;
@@ -120,19 +122,80 @@ export async function invocation(signer, opts) {
     // so `/firkin/blob/delete/<cid>` proofs can't be invoked with the bare
     // `/firkin/blob/delete`. Narrow down to the proof's own command when it
     // extends (never broadens) the requested one.
-    const dlgCmd = first.payload.cmd;
-    if (dlgCmd !== opts.command && dlgCmd.startsWith(opts.command)) {
+    const dlgCmd = first.payload?.cmd;
+    if (dlgCmd && dlgCmd !== opts.command && dlgCmd.startsWith(opts.command)) {
         payload.cmd = dlgCmd;
     }
-    payload.prf = decoded.map((p, i) => {
-        // Assertion proofs carry their CID (over the envelope the SERVER
-        // synthesizes); envelope proofs' CID is over their own bytes.
-        const input = opts.proofs[i];
-        const cid = input instanceof Uint8Array ? cidForBytes(dagcbor.encode(p.decoded), { codec: 0x71 }) : input.cid;
-        return CID.parse(cid);
+    payload.prf = decoded.map((p) => p.cid);
+    const inv = await envelope(signer, INV_TAG, payload);
+    // By reference: no proof envelopes ride along.
+    return dagcbor.encode([inv]);
+}
+/**
+ * Mint an invocation **with its proofs inline** — bootstrap only: the
+ * delegation store's publish call is authorized by a chain that is not stored
+ * yet. Everything else should use [`invocation`](#invocation).
+ */
+export async function inlineInvocation(signer, opts) {
+    const decoded = opts.proofs.map((input) => {
+        const bytes = proofInputBytes(input);
+        if (!bytes)
+            throw new Error("inline proofs need their bytes");
+        const d = dagcbor.decode(bytes);
+        if (Array.isArray(d) &&
+            d.length === 2 &&
+            d[1] instanceof Object &&
+            Object.keys(d[1]).some((k) => k.startsWith("ucan/dlg@"))) {
+            return d;
+        }
+        if (d instanceof Object && "ad" in d && "cd" in d && "sg" in d) {
+            return d;
+        }
+        throw new Error("unrecognized proof format");
     });
-    const invocation = await envelope(signer, INV_TAG, payload);
-    return dagcbor.encode([invocation, ...decoded.map((p) => p.decoded)]);
+    // The chain subject comes from the proof (`sub`), not from the signer.
+    const firstPayload = (() => {
+        const d = decoded[0];
+        if (Array.isArray(d) && d[1] instanceof Object) {
+            const tag = Object.keys(d[1]).find((key) => key.startsWith("ucan/dlg@"));
+            if (tag)
+                return d[1][tag];
+        }
+        if (d instanceof Object && "ad" in d && "cd" in d) {
+            const cd = JSON.parse(d.cd);
+            return dagcbor.decode(base64UrlDecode(cd.challenge));
+        }
+        return undefined;
+    })();
+    const subject = firstPayload?.sub;
+    const payload = invocationPayload(signer, opts);
+    if (subject) {
+        payload.aud = subject;
+        payload.sub = subject;
+    }
+    // Assertion proofs carry their synthesized-envelope CID from the caller —
+    // hashing the `{ad, cd, sg}` bytes would name the wrong envelope.
+    payload.prf = opts.proofs.map((input) => proofInputCid(input));
+    const inv = await envelope(signer, INV_TAG, payload);
+    return dagcbor.encode([inv, ...decoded]);
+}
+function proofInputCid(input) {
+    if (typeof input === "string")
+        return CID.parse(input);
+    const direct = CID.asCID(input);
+    if (direct)
+        return direct;
+    if (input instanceof Object && "cid" in input)
+        return CID.parse(input.cid);
+    throw new Error("proof input lacks a CID");
+}
+function proofInputBytes(input) {
+    if (input instanceof Uint8Array)
+        return input;
+    if (typeof input === "string" || !(input instanceof Object))
+        return undefined;
+    const holder = input;
+    return holder.bytes ?? holder.proof;
 }
 function base64UrlDecode(text) {
     const padded = text.replace(/-/g, "+").replace(/_/g, "/");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokono.ma/firkin",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Browser-first TypeScript client SDK for the Firkin API (UCAN 1.0, DASL CIDs, CAR Mirror sync)",
   "license": "Apache-2.0 OR MIT",
   "repository": {