@tokono.ma/firkin 0.1.1 → 0.2.0

package/README.md

@@ -52,6 +52,7 @@ 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
 
@@ -93,15 +94,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,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.1",
+  "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": {