@tokono.ma/firkin 0.2.0 → 0.4.0

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/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

@@ -21,10 +21,11 @@ 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";
+    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 {
@@ -32,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

@@ -46,10 +46,11 @@ 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",
+    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;
@@ -74,7 +75,7 @@ function invocationPayload(signer, opts) {
         cause: null,
         iat: null,
         exp: expFromNow(opts.expireIn),
-        meta: {},
+        meta: opts.meta ?? {},
         nonce: nonce(),
     };
 }

package/dist/webauthn.d.ts

@@ -6,15 +6,62 @@ export interface WebAuthnAssertion {
     /** The authenticator's signature over authData || SHA-256(clientDataJSON). */
     signature: Uint8Array;
 }
+/** Default session lease: 30 days (the server caps it). */
+export declare const ATTESTATION_DEFAULT_TTL: number;
 /**
- * Package an assertion (whose challenge was the bare delegation payload)
- * into a proof: dag-cbor `{ad, cd, sg}`. Also returns the proof's CID —
- * computed over the envelope the server synthesizes
- * (`[signature, {h, "ucan/dlg@…": payload}]`, with the varsig header of the
- * payload issuer's key type — ed25519 or P-256), which is what the
- * invocation's `prf` must reference.
+ * The challenge for a passkey session attestation: DAG-CBOR naming the
+ * account, the session key and the granted commands. Every field is inside
+ * `clientDataJSON.challenge`, hence covered by the authenticator's signature.
+ *
+ * Pass it to `navigator.credentials.get` as `publicKey.challenge`, then send
+ * the resulting assertion to `Firkin.attest()`.
  */
-export declare function assertionToProof(challengePayload: Uint8Array, assertion: WebAuthnAssertion): {
-    proof: Uint8Array;
-    cid: string;
+export declare function attestationChallenge(opts: {
+    /** The API origin (`https://firkin.example`) — must match server config. */
+    firkin: string;
+    /** The passkey account DID. */
+    account: string;
+    /** The `did:key` session that will sign API calls. */
+    session: string;
+    /** Capability prefixes the session may exercise. */
+    commands: string[];
+    /** Lease in seconds (default 30 days, server-capped). */
+    expireIn?: number;
+    /** Override the start time (unix seconds) — tests only. */
+    now?: number;
+}): Uint8Array;
+/**
+ * The challenge for a step-up action (revocation): bound to one account and
+ * one command, short-lived and single-use. Sent in the `X-Firkin-Assertion`
+ * header alongside an ordinary session invocation.
+ */
+export declare function stepUpChallenge(opts: {
+    firkin: string;
+    account: string;
+    /** The capability the action requires, e.g. "/firkin/account/revoke". */
+    action: string;
+    /** Seconds until expiry (default 120; server caps at 300). */
+    expireIn?: number;
+    /** Override the start time (unix seconds) — tests only. */
+    now?: number;
+}): Uint8Array;
+/**
+ * The challenge for a recovery grant: authorizes `recovery` (a did:key) to
+ * call `POST /v1/account/recover` for this account. Omit `expireIn` for an
+ * indefinite grant (revoke it by its attestation CID).
+ */
+export declare function recoveryChallenge(opts: {
+    firkin: string;
+    account: string;
+    recovery: string;
+    expireIn?: number;
+    now?: number;
+}): Uint8Array;
+/** The JSON body expected by `POST /v1/tokens/attestation`. */
+export declare function packageAssertion(assertion: WebAuthnAssertion): {
+    ad: string;
+    cd: string;
+    sg: string;
 };
+/** The `X-Firkin-Assertion` header value (base64url DAG-CBOR). */
+export declare function assertionHeader(assertion: WebAuthnAssertion): string;

package/dist/webauthn.js

@@ -1,29 +1,90 @@
-// Assertion-wrapped UCAN delegations: a WebAuthn assertion whose challenge
-// is the bare dag-cbor delegation payload. The authenticator signs
-// `authData || SHA-256(clientDataJSON)` — the server verifies that against
-// the payload's issuer DID and reconstructs the delegation.
+// Passkey attestations: a WebAuthn assertion whose challenge is a Firkin
+// attestation (`firkin/attestation/passkey`) or step-up (`firkin/step-up`)
+// payload.
+//
+// An assertion is NOT a UCAN proof. The account key lives in the
+// authenticator and only signs `authData || SHA-256(clientDataJSON)`, so the
+// assertion enrols a `did:key` session (or authorizes one account-level
+// action) and is verified once by the server. Tokens are then ordinary
+// self-issued invocations by the session key.
 import * as dagcbor from "@ipld/dag-cbor";
-import { cidForBytes } from "./cid.js";
-import { DLG_TAG, headerForDid } from "./ucan.js";
+import { randomBytes } from "@noble/hashes/utils";
+/** Default session lease: 30 days (the server caps it). */
+export const ATTESTATION_DEFAULT_TTL = 30 * 24 * 60 * 60;
 /**
- * Package an assertion (whose challenge was the bare delegation payload)
- * into a proof: dag-cbor `{ad, cd, sg}`. Also returns the proof's CID —
- * computed over the envelope the server synthesizes
- * (`[signature, {h, "ucan/dlg@…": payload}]`, with the varsig header of the
- * payload issuer's key type — ed25519 or P-256), which is what the
- * invocation's `prf` must reference.
+ * The challenge for a passkey session attestation: DAG-CBOR naming the
+ * account, the session key and the granted commands. Every field is inside
+ * `clientDataJSON.challenge`, hence covered by the authenticator's signature.
+ *
+ * Pass it to `navigator.credentials.get` as `publicKey.challenge`, then send
+ * the resulting assertion to `Firkin.attest()`.
  */
-export function assertionToProof(challengePayload, assertion) {
-    const proof = dagcbor.encode({
+export function attestationChallenge(opts) {
+    const nbf = opts.now ?? Math.floor(Date.now() / 1000);
+    const exp = nbf + (opts.expireIn ?? ATTESTATION_DEFAULT_TTL);
+    return dagcbor.encode({
+        $type: "firkin/attestation/passkey",
+        firkin: opts.firkin,
+        account: opts.account,
+        session: opts.session,
+        commands: opts.commands,
+        nbf,
+        exp,
+        nonce: randomBytes(16),
+    });
+}
+/**
+ * The challenge for a step-up action (revocation): bound to one account and
+ * one command, short-lived and single-use. Sent in the `X-Firkin-Assertion`
+ * header alongside an ordinary session invocation.
+ */
+export function stepUpChallenge(opts) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    return dagcbor.encode({
+        $type: "firkin/step-up",
+        firkin: opts.firkin,
+        account: opts.account,
+        action: opts.action,
+        exp: now + (opts.expireIn ?? 120),
+        nonce: randomBytes(16),
+    });
+}
+/**
+ * The challenge for a recovery grant: authorizes `recovery` (a did:key) to
+ * call `POST /v1/account/recover` for this account. Omit `expireIn` for an
+ * indefinite grant (revoke it by its attestation CID).
+ */
+export function recoveryChallenge(opts) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    return dagcbor.encode({
+        $type: "firkin/recovery/passkey",
+        firkin: opts.firkin,
+        account: opts.account,
+        recovery: opts.recovery,
+        exp: opts.expireIn === undefined ? null : now + opts.expireIn,
+        nonce: randomBytes(16),
+    });
+}
+/** The JSON body expected by `POST /v1/tokens/attestation`. */
+export function packageAssertion(assertion) {
+    return {
+        ad: b64url(assertion.authData),
+        // The EXACT clientDataJSON text — the server hashes those bytes.
+        cd: b64url(new TextEncoder().encode(assertion.clientDataJSON)),
+        sg: b64url(assertion.signature),
+    };
+}
+/** The `X-Firkin-Assertion` header value (base64url DAG-CBOR). */
+export function assertionHeader(assertion) {
+    return b64url(dagcbor.encode({
         ad: assertion.authData,
         cd: assertion.clientDataJSON,
         sg: assertion.signature,
-    });
-    const payload = dagcbor.decode(challengePayload);
-    const h = headerForDid(payload.iss);
-    const envelope = dagcbor.encode([
-        assertion.signature,
-        { h, [DLG_TAG]: payload },
-    ]);
-    return { proof, cid: cidForBytes(envelope, { codec: 0x71 }) };
+    }));
+}
+function b64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokono.ma/firkin",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -42,13 +42,14 @@
     "@ipld/dag-cbor": "^9.2.0",
     "@noble/ed25519": "^1.7.3",
     "@noble/hashes": "^1.5.0",
+    "@scure/bip39": "^1.5.0",
     "bs58": "^6.0.0",
-    "multiformats": "^13.0.0",
     "hash-wasm": "^4.12.0",
-    "@scure/bip39": "^1.5.0"
+    "multiformats": "^13.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "blake3-bao": "1.3.4"
   },
   "engines": {
     "node": ">=22"