@tokono.ma/firkin 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @tokono.ma/firkin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-first TypeScript SDK for the Firkin API.
+
+```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:
+`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.

package/dist/bip39.d.ts

@@ -0,0 +1,4 @@
+/** Encode a 32-byte ed25519 seed as a 24-word BIP39 phrase. */
+export declare function seedToMnemonic(seed: Uint8Array): string;
+/** Decode a 24-word BIP39 phrase back into the 32-byte ed25519 seed. */
+export declare function mnemonicToSeedBytes(mnemonic: string): Uint8Array;

package/dist/bip39.js

@@ -0,0 +1,18 @@
+// BIP39 seed-phrase backup: a 24-word phrase encodes 256 bits of entropy
+// that IS the ed25519 seed (bijective: entropy ↔ mnemonic — no PBKDF2
+// stretching, so the phrase round-trips to the exact account key).
+import { entropyToMnemonic, mnemonicToEntropy } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+/** Encode a 32-byte ed25519 seed as a 24-word BIP39 phrase. */
+export function seedToMnemonic(seed) {
+    if (seed.length !== 32)
+        throw new Error("backup seed must be 32 bytes");
+    return entropyToMnemonic(seed, wordlist);
+}
+/** Decode a 24-word BIP39 phrase back into the 32-byte ed25519 seed. */
+export function mnemonicToSeedBytes(mnemonic) {
+    const seed = mnemonicToEntropy(mnemonic.trim().toLowerCase(), wordlist);
+    if (seed.length !== 32)
+        throw new Error("mnemonic does not encode a 32-byte seed");
+    return seed;
+}

package/dist/bloom.d.ts

@@ -0,0 +1,17 @@
+export declare class BloomFilter {
+    readonly bytes: Uint8Array;
+    readonly hashCount: number;
+    private constructor();
+    /** From a push response's `bb` (bytes) + `bk` (hash count). */
+    static fromWire(bytes: Uint8Array, hashCount: number): BloomFilter;
+    /** Fresh filter sized for `n` items at false-positive probability `fpp`
+     * (spec §3.4.2: k = m/n·ln2, m = -n·ln ε / ln²2). */
+    static build(n: number, fpp?: number): Promise<BloomFilter>;
+    get bitSize(): number;
+    /** Probabilistic membership: true = definitely or probably present. */
+    contains(item: Uint8Array): Promise<boolean>;
+    insert(item: Uint8Array): Promise<void>;
+    /** deterministic-bloom's HashIndexIterator: k accepted indexes, seeds
+     * counting up from 0 across hash rounds and rejection samples alike. */
+    private indices;
+}

package/dist/bloom.js

@@ -0,0 +1,82 @@
+// TS port of the Bloom filter used by car-mirror
+// (`deterministic-bloom`, runtime_size), so the client can BOTH interpret
+// the server's push-response filters AND build pull-request filters the
+// server will interpret identically:
+//
+// - items are hashed with XXH3-64, seed = a monotonic counter starting at 0
+//   that is shared across the k hash rounds AND rejection-sampling retries
+//   (the counter resets per insert/contains call)
+// - index = hash % 2^ceil(log2(bit_size)); non-power-of-two sizes rejection-
+//   sample (retry with the next seed when the value lands past the size)
+// - bits are LSB0 within the byte array
+// - an item is "contained" when all k of its bits are set (false positives
+//   possible, never false negatives)
+//
+// Items fed by the server are CID binary bytes (`cid.to_bytes()`), i.e. the
+// multiformats `CID.bytes`.
+//
+// NB: deterministic-bloom casts the u64 hash `as usize` — 32 bits on the
+// wasm32 worker. Both the read and write side mimic that truncation here
+// (revisit if the store is ever built natively, e.g. celld on x86_64, where
+// usize is 64 bits).
+import { xxhash3 } from "hash-wasm";
+export class BloomFilter {
+    bytes;
+    hashCount;
+    constructor(bytes, hashCount) {
+        this.bytes = bytes;
+        this.hashCount = hashCount;
+    }
+    /** From a push response's `bb` (bytes) + `bk` (hash count). */
+    static fromWire(bytes, hashCount) {
+        return new BloomFilter(bytes, hashCount);
+    }
+    /** Fresh filter sized for `n` items at false-positive probability `fpp`
+     * (spec §3.4.2: k = m/n·ln2, m = -n·ln ε / ln²2). */
+    static async build(n, fpp = Math.min(0.1, 1 / (10 * n))) {
+        if (n <= 0)
+            throw new Error("bloom needs at least one item");
+        const ln2 = Math.LN2;
+        const bits = Math.ceil((-n * Math.log(fpp)) / (ln2 * ln2));
+        const hashCount = Math.max(1, Math.round((bits / n) * ln2));
+        return new BloomFilter(new Uint8Array(Math.ceil(bits / 8)), hashCount);
+    }
+    get bitSize() {
+        return this.bytes.length * 8;
+    }
+    /** Probabilistic membership: true = definitely or probably present. */
+    async contains(item) {
+        for await (const index of this.indices(item)) {
+            const byte = this.bytes[index >> 3] ?? 0;
+            if ((byte & (1 << (index & 7))) === 0)
+                return false;
+        }
+        return true;
+    }
+    async insert(item) {
+        for await (const index of this.indices(item)) {
+            this.bytes[index >> 3] = (this.bytes[index >> 3] ?? 0) | (1 << (index & 7));
+        }
+    }
+    /** deterministic-bloom's HashIndexIterator: k accepted indexes, seeds
+     * counting up from 0 across hash rounds and rejection samples alike. */
+    async *indices(item) {
+        const size = this.bitSize;
+        if (size === 0 || this.hashCount === 0)
+            return;
+        const po2 = Math.pow(2, Math.ceil(Math.log2(size)));
+        let seed = 0;
+        for (let accepted = 0; accepted < this.hashCount; seed++) {
+            if (seed > 10_000_000)
+                throw new Error("bloom rejection sampling exhausted");
+            const hex = await xxhash3(item, seed, 0);
+            // NB: the `as usize` truncation described above.
+            const hash = BigInt("0x" + hex) & 0xffffffffn;
+            const value = Number(hash % BigInt(po2));
+            if (value < size) {
+                accepted++;
+                yield value;
+            }
+        }
+    }
+}

package/dist/cid.d.ts

@@ -0,0 +1,17 @@
+import { bytesToHex } from "./keys.ts";
+export declare const CODEC_RAW = 85;
+export declare const CODEC_DAG_PB = 112;
+export declare const CODEC_DAG_CBOR = 113;
+export declare const HASH_SHA256 = 18;
+export declare const HASH_BLAKE3 = 30;
+export type HashName = "sha256" | "blake3";
+/** The DASL/BDASL CID of the given bytes (canonical base32-lower text). */
+export declare function cidForBytes(data: Uint8Array, opts?: {
+    codec?: number;
+    hash?: HashName;
+}): string;
+/** CID text from a raw digest, codec and multihash code. */
+export declare function cidFromDigest(digest: Uint8Array, codec?: number, hashCode?: number): string;
+/** Convenience: hex digest + codec → CID (useful with external hashers). */
+export declare function cidFromDigestHex(hex: string, codec?: number): string;
+export { bytesToHex };

package/dist/cid.js

@@ -0,0 +1,69 @@
+// DASL/BDASL CID computation (CIDv1, base32-lower canonical form).
+//
+// Mirrors firkin-core's codec: version 0x01 + codec uvarint + multihash
+// (SHA-256 0x12 or BLAKE3 0x1e, 32-byte digest).
+import { sha256 } from "@noble/hashes/sha2";
+import { blake3 } from "@noble/hashes/blake3";
+import { bytesToHex } from "./keys.js";
+export const CODEC_RAW = 0x55;
+export const CODEC_DAG_PB = 0x70;
+export const CODEC_DAG_CBOR = 0x71;
+export const HASH_SHA256 = 0x12;
+export const HASH_BLAKE3 = 0x1e;
+const BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+function base32LowerNoPad(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const b of bytes) {
+        value = (value << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+    }
+    return out;
+}
+function pushUvarint(out, value, at) {
+    let v = value;
+    let i = at;
+    while (v >= 0x80) {
+        out[i++] = (v & 0x7f) | 0x80;
+        v >>>= 7;
+    }
+    out[i++] = v;
+    return i;
+}
+/** The DASL/BDASL CID of the given bytes (canonical base32-lower text). */
+export function cidForBytes(data, opts = {}) {
+    const codec = opts.codec ?? CODEC_RAW;
+    const hash = opts.hash ?? "sha256";
+    const hashCode = hash === "blake3" ? HASH_BLAKE3 : HASH_SHA256;
+    const digest = hash === "blake3" ? blake3(data) : sha256(data);
+    return cidFromDigest(digest, codec, hashCode);
+}
+/** CID text from a raw digest, codec and multihash code. */
+export function cidFromDigest(digest, codec = CODEC_RAW, hashCode = HASH_SHA256) {
+    if (digest.length !== 32)
+        throw new Error("expected a 32-byte digest");
+    const wire = new Uint8Array(4 + 32);
+    wire[0] = 0x01;
+    let i = pushUvarint(wire, codec, 1);
+    i = pushUvarint(wire, hashCode, i);
+    i = pushUvarint(wire, 32, i);
+    wire.set(digest, i);
+    return "b" + base32LowerNoPad(wire);
+}
+/** Convenience: hex digest + codec → CID (useful with external hashers). */
+export function cidFromDigestHex(hex, codec = CODEC_RAW) {
+    const digest = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        digest[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return cidFromDigest(digest, codec);
+}
+export { bytesToHex };

package/dist/client.d.ts

@@ -0,0 +1,187 @@
+import { CID } from "multiformats";
+import type { Signer } from "./keys.ts";
+/** 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>;
+/** 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 UploadResult {
+    cid: string;
+    /** True when the blob was already stored (dedup; claim joined). */
+    deduplicated: boolean;
+}
+export interface ByteRange {
+    /** Inclusive start (default 0). */
+    start?: number;
+    /** Inclusive end (default last byte). */
+    end?: number;
+    /** Last N bytes (alternative to start/end). */
+    suffix?: number;
+}
+export interface RangeResult {
+    data: Uint8Array;
+    /** Inclusive range within the full blob. */
+    start: number;
+    end: number;
+    total: number;
+}
+/** Local block store used for pull-side Bloom narrowing (spec §3.2.1): the
+ * cache's CIDs go into the pull request's filter, so the server skips
+ * blocks this client already has. */
+export interface BlockCache {
+    get(cid: string): Promise<Uint8Array | undefined> | Uint8Array | undefined;
+    set(cid: string, bytes: Uint8Array): Promise<void> | void;
+    keys(): Promise<string[]> | string[];
+}
+/** Simple in-memory cache (per Firkin instance). */
+export declare class MemoryBlockCache implements BlockCache {
+    private map;
+    get(cid: string): Uint8Array | undefined;
+    set(cid: string, bytes: Uint8Array): void;
+    keys(): string[];
+}
+export declare class Firkin {
+    private readonly base;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly blockCache;
+    constructor(base: string, token: TokenSource, fetchImpl?: typeof fetch, blockCache?: BlockCache);
+    /** Upload bytes; returns the CID and whether it was already stored. */
+    upload(data: Uint8Array | Blob, opts?: {
+        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. */
+    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>;
+    /** 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. */
+    delete(cid: string): Promise<void>;
+    /** Revoke delegated sessions: specific delegation CIDs, or every
+     * delegation minted before now (`all: true`). Must be authorized by the
+     * account key itself — a direct invocation (seed accounts) or a fresh
+     * passkey assertion delegating `/firkin/account/revoke` to the session key
+     * (passkey-native accounts; the server caps its lifetime at 10 minutes).
+     * A plain delegated session cannot revoke. */
+    revoke(opts: {
+        cids?: string[];
+        all?: boolean;
+    }): Promise<void>;
+    /** (Admin) register a DID as an account, optionally binding a WebAuthn
+     * credential (`id` = base64url rawId, `spki` = base64url of the browser's
+     * getPublicKey() DER). The binding is what lets a fresh browser re-attach
+     * the passkey later via `Firkin.whoami` — passkey-native accounts have no
+     * other record of the credential↔account link. */
+    register(did: string, credential?: {
+        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
+     * server looks the credential up (bound at registration), verifies the
+     * ceremony + ES256 signature, and answers with the DID. Static because
+     * the endpoint is unauthenticated by design: the verified signature IS
+     * the authentication. */
+    static whoami(base: string, assertion: {
+        id: string;
+        authData: Uint8Array;
+        clientDataJSON: string;
+        signature: Uint8Array;
+    }, fetchImpl?: typeof fetch): Promise<string>;
+    /** (Admin) list registered accounts. */
+    listAccounts(): Promise<{
+        did: string;
+        registered_at: number;
+    }[]>;
+    /** Set `name` → `cid`. Overwrites silently (last-writer-wins). */
+    registrySet(name: string, cid: string): Promise<void>;
+    /** Resolve `name`; returns null when unset. */
+    registryGet(name: string): Promise<string | null>;
+    /** Unset `name` (idempotent). */
+    registryDelete(name: string): Promise<void>;
+    /** The account's whole registry: name → CID (sorted). */
+    registryList(): Promise<Record<string, string>>;
+    /**
+     * 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
+     * shape [`pullFile`](#pullfile) reassembles. The manifest is built here
+     * and pushed through [`dagPush`](#dagpush), so there is one
+     * push implementation. For an existing DAG (real CIDs and real root),
+     * use `dagPush` directly.
+     */
+    pushFile(chunks: Uint8Array[], opts?: {
+        roundBudgetBytes?: number;
+    }): Promise<string>;
+    /**
+     * Push an existing DAG as-is: `blocks` maps each block's REAL CID to its
+     * bytes, and `root` is the DAG's real root (one of the blocks). Same
+     * multi-round / Bloom-narrowed protocol as [`pushFile`](#pushfile), but
+     * nothing is re-hashed or wrapped in a manifest — the server stores the
+     * blocks under the given CIDs, so `dagPull(root)` works for other clients
+     * and a name-registry entry pointing at `root` resolves to the real DAG
+     * (e.g. a WNFS root tree: dag-pb root + dag-cbor/dag-pb descendants).
+     *
+     * Links are followed per the block's own codec (dag-cbor and dag-pb);
+     * blocks of other codecs are terminals.
+     */
+    dagPush(root: string | CID, blocks: Iterable<[string | CID, Uint8Array]>, opts?: {
+        roundBudgetBytes?: number;
+    }): Promise<string>;
+    /**
+     * The shared CAR Mirror push loop for a graph already in memory: BFS from
+     * the round's subgraph roots, Bloom-skip blocks the server has (never the
+     * subgraph roots themselves), budget-chunked; repeat while the server
+     * reports pending roots.
+     */
+    private pushGraph;
+    /** Pull a whole DAG knowing only its root; returns its blocks by CID.
+     *
+     * Spec §3.2: with a populated block cache, the pull request carries a
+     * Bloom filter over the cached CIDs, so the server skips blocks this
+     * client already has; the loop re-requests until the local graph below
+     * the root is complete (Bloom false positives can strand a block for one
+     * round — it's uncached, so the next filter omits it and the server
+     * sends it). With an empty cache this is a cold pull, exactly as before.
+     */
+    dagPull(root: string): Promise<Map<string, Uint8Array>>;
+    /**
+     * Pull + reassemble a file pushed via [`pushFile`](#pushfile): the root is
+     * a dag-cbor list of raw chunk CIDs in order — concatenates them back.
+     */
+    pullFile(root: string): Promise<Uint8Array>;
+}
+export declare function carFile(root: CID, entries: [CID, Uint8Array][]): Uint8Array;
+export declare function multihashSha256(data: Uint8Array): MultihashDigest;
+type MultihashDigest = {
+    code: number;
+    size: number;
+    digest: Uint8Array;
+    bytes: Uint8Array;
+};
+/** The CID links of a block, per its codec: dag-cbor (0x71) and dag-pb
+ * (0x70). Other codecs have no parseable links (raw blocks are terminals). */
+export declare function linksOf(code: number, bytes: Uint8Array): CID[];
+export {};