@tokono.ma/firkin 0.1.0 → 0.2.0

package/README.md

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

package/dist/client.d.ts

@@ -1,9 +1,15 @@
 import { CID } from "multiformats";
 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. */
@@ -62,6 +68,28 @@ export declare class Firkin {
     /** 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. */

package/dist/client.js

@@ -7,7 +7,7 @@ import { BloomFilter } from "./bloom.js";
 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) {
@@ -102,6 +102,35 @@ 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}/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}/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);

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";
@@ -41,23 +42,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 +102,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

@@ -85,33 +85,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 +124,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.0",
+  "version": "0.2.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": {