@tokono.ma/firkin 0.3.0 → 0.4.0

package/README.md

@@ -47,13 +47,13 @@ signs directly); delegates mint with [`invocation()`](#delegation--sessions).
 
 ```ts
 // blobs — reads are authenticated automatically (read tokens)
-rb.upload(data, { codec?, hash?: "sha256" | "blake3" }) → { cid, deduplicated }
+rb.upload(data, { codec?, hash?: "sha256" | "blake3", tags? }) → { 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.claim(cid, { tags? })   // 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)
@@ -62,18 +62,40 @@ rb.registryGet(name)   // null when unset
 rb.registryList()      // Record<name, cid>
 rb.registryDelete(name)
 
+// tags — per-account label groups over blobs (paged)
+rb.tagAdd("photos", [cidA, cidB])
+rb.tagGet("photos")           // one page: { name, cids, count, cursor, next }
+rb.tagAll("photos")           // every CID in the group (walks the pages)
+rb.blobTags(cidA)             // ["photos"] — reverse lookup
+rb.tagList()                  // [{ name, count }]
+rb.tagRemove("photos", cidA)
+rb.tagDelete("photos")        // drop the group
+rb.tagDeleteBlobs("photos")   // drop the group AND detach its blobs
+
 // 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
 rb.ingestCar(carBytes)        // rootless CARv1: verify + claim each block (no DAG)
+rb.verifiedRange(cid, { start, end }) // BDASL: bao proof verified against the CID
 
 // account
-rb.revoke({ cids? , all? })   // kill delegations (account key only)
+rb.revoke({ cids?, all? }, stepUpAssertion?) // kill grants (attested sessions need a fresh touch)
 rb.register(did, credential?) // admin: register a DID (+ passkey binding)
 rb.listAccounts()             // admin
+Firkin.attest(base, assertion) // passkey attestation → session binding / recovery grant
+Firkin.attestPlc(base, { did, ops, commit, record, proof }) // did:plc enrolment
+plcSessionRecord({ firkin, session, commands, expireIn? })  // the repo record to write
+collectPlcAttestation({ agent, did, record })               // write + gather + encode
+appealRequest({ firkin, expireIn?, nonce?, note? })         // ask to be registered (repo record)
+appealRkey(firkin)                                          // the instance host, used as rkey
+normalizeOrigin(origin)                                     // canonical origin for the audience field
 Firkin.whoami(base, assertion) // passkey re-attachment → account DID
+sessionTokenSource(session, { account }) // attested-session token source
+attestationChallenge({ firkin, account, session, commands, expireIn? })
+stepUpChallenge({ firkin, account, action, expireIn? })
+recoveryChallenge({ firkin, account, recovery, expireIn? })
 ```
 
 `dagPull` follows dag-cbor **and dag-pb** links server-side, so a WNFS-shaped
@@ -83,6 +105,12 @@ 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.
 
+`appealRequest` and `plcSessionRecord` normalize their `firkin` audience with
+`normalizeOrigin` (lowercase scheme + host + non-default port, no trailing
+slash or path). Firkin compares that field to `ORIGIN` exactly, and so do the
+ATProto indexers that can discover appeals — use the same helper when you
+compare an incoming record against your own origin.
+
 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).
@@ -114,35 +142,77 @@ 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).
+are authorized by the account itself: the account key signs directly, while an
+attested session must present a fresh passkey step-up assertion — a stolen
+session key must not be able to revoke.
 
 ## Passkeys
 
+All four identity models — seed keys, regular passkeys, PRF passkeys and
+`did:plc` — are compared, with code for each, in
+[`docs/ACCOUNTS.md`](https://tangled.org/tokono.ma/firkin/blob/main/docs/ACCOUNTS.md).
+The short version follows.
+
 `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:
+Passkey-native accounts — the credential key *is* the account — authorise a
+session with a WebAuthn **attestation**, verified once by the server. The
+assertion is never a UCAN proof: requests are ordinary self-issued
+invocations by the session key, carrying `meta["firkin/account"]`.
 
 ```ts
-import { assertionToProof, delegationPayloadBytes } from "@tokono.ma/firkin";
-
-const payload = delegationPayloadBytes({
-  issuerDid: passkeyDid, subject: passkeyDid, audience: session.did(),
-  command: "/firkin/blob", expireIn: 8 * 3600,
+import { attestationChallenge, sessionTokenSource, Firkin } from "@tokono.ma/firkin";
+
+const challenge = attestationChallenge({
+  firkin: "http://localhost:8787",   // the API origin
+  account: passkeyDid,
+  session: session.did(),
+  commands: ["/firkin/blob"],
+  expireIn: 8 * 3600,
 });
 const assertion = await navigator.credentials.get({
-  publicKey: { challenge: base64url(payload), rpId, userVerification: "required" },
+  publicKey: { challenge, rpId, userVerification: "required" },
 });
-const proof = assertionToProof(payload, {
+
+const attestation = await Firkin.attest("http://localhost:8787", {
   authData: /* bytes */, clientDataJSON: /* exact JSON text */, signature: /* bytes */,
 });
+
+// From here on the session signs directly. It can be revoked by CID.
+const rb = new Firkin(base, sessionTokenSource(session, { account: passkeyDid }));
 ```
 
+Revocation and recovery need a fresh touch: `stepUpChallenge(...)` beside an
+ordinary session invocation (`rb.revoke(body, assertion)`), and
+`recoveryChallenge(...)` to install a backup identity.
 `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).
 
+`did:plc` accounts use the same session model with a repo record as the proof.
+One call does the write and the gather:
+
+```ts
+import { collectPlcAttestation, plcSessionRecord } from "@tokono.ma/firkin";
+
+const material = await collectPlcAttestation({
+  agent,                                   // an @atproto/api Agent
+  did: account,                            // did:plc:…
+  record: plcSessionRecord({
+    firkin: origin, session: session.did(),
+    commands: ["/firkin/blob", "/firkin/account/revoke"],
+    expireIn: 30 * 24 * 3600,
+  }),
+});
+await Firkin.attestPlc(origin, material);
+// then: new Firkin(origin, sessionTokenSource(session, { account }))
+```
+
+`collectPlcAttestation` writes the record via your ATProto agent, reads the PLC
+log, fetches the signed commit and the MST proof, and retries if the repo
+advanced between fetches. Everything it produces is exactly what
+`Firkin.attestPlc` posts; you can also assemble that material yourself.
+
 ## Design notes
 
 **Minting is a shim, on purpose.** `ucan.ts` only assembles the wire format;

package/dist/bao.d.ts

@@ -0,0 +1,25 @@
+/** BDASL verifies in 1 KiB chunks ("rounds to the nearest kilobyte"). */
+export declare const BAO_CHUNK_SIZE = 1024;
+/** Number of 1 KiB chunks (an empty blob still has one chunk). */
+export declare function baoChunkCount(size: number): number;
+/** The BLAKE3 root of arbitrary data, computed with the verified-streaming
+ * tree (exposed for tests; equals `blake3(data)`). */
+export declare function blake3TreeRoot(data: Uint8Array): Uint8Array;
+export interface BaoRangeInput {
+    /** The bao-encoded proof + chunk bytes. */
+    encoded: Uint8Array;
+    /** The CID's 32-byte digest — the BLAKE3 root to verify against. */
+    root: Uint8Array;
+    /** Total blob size in bytes (from the server, but bound by the proof). */
+    size: number;
+    /** First chunk to read (inclusive). */
+    chunkStart: number;
+    /** One past the last chunk to read (exclusive). */
+    chunkEnd: number;
+}
+/**
+ * Decode and verify a bao proof for a chunk range. Throws on any proof
+ * mismatch, truncation, or when the root does not match. Returns the
+ * chunk-aligned data starting at `chunkStart * 1024`.
+ */
+export declare function decodeBaoRange(input: BaoRangeInput): Uint8Array;

package/dist/bao.js

@@ -0,0 +1,225 @@
+// BDASL verified streaming (bao): verify a BLAKE3 hash-tree proof so a byte
+// range can be trusted without trusting the server.
+//
+// Wire format (as produced by `bao-tree` / iroh, block size 1 KiB, pre-order):
+// - an internal node intersecting the requested range contributes 64 bytes:
+//   `left_cv ‖ right_cv` (the two child chaining values),
+// - a requested leaf chunk contributes its raw bytes (≤ 1024, the last chunk
+//   may be shorter).
+// The verifier recomputes chunk CVs, folds them up, and checks that the
+// ROOT-flagged root equals the CID's digest (which *is* the BLAKE3 root).
+/** BDASL verifies in 1 KiB chunks ("rounds to the nearest kilobyte"). */
+export const BAO_CHUNK_SIZE = 1024;
+const IV = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+    0x1f83d9ab, 0x5be0cd19,
+]);
+const MSG_PERMUTATION = [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8];
+const CHUNK_START = 1;
+const CHUNK_END = 2;
+const PARENT = 4;
+const ROOT = 8;
+function rotr(value, bits) {
+    return ((value >>> bits) | (value << (32 - bits))) >>> 0;
+}
+function g(v, a, b, c, d, mx, my) {
+    v[a] = (v[a] + v[b] + mx) >>> 0;
+    v[d] = rotr(v[d] ^ v[a], 16);
+    v[c] = (v[c] + v[d]) >>> 0;
+    v[b] = rotr(v[b] ^ v[c], 12);
+    v[a] = (v[a] + v[b] + my) >>> 0;
+    v[d] = rotr(v[d] ^ v[a], 8);
+    v[c] = (v[c] + v[d]) >>> 0;
+    v[b] = rotr(v[b] ^ v[c], 7);
+}
+function round(v, m) {
+    g(v, 0, 4, 8, 12, m[0], m[1]);
+    g(v, 1, 5, 9, 13, m[2], m[3]);
+    g(v, 2, 6, 10, 14, m[4], m[5]);
+    g(v, 3, 7, 11, 15, m[6], m[7]);
+    g(v, 0, 5, 10, 15, m[8], m[9]);
+    g(v, 1, 6, 11, 12, m[10], m[11]);
+    g(v, 2, 7, 8, 13, m[12], m[13]);
+    g(v, 3, 4, 9, 14, m[14], m[15]);
+}
+/** BLAKE3 compression; returns the 8-word chaining value (32 bytes). */
+function compress(cv, block, counter, blockLen, flags) {
+    const v = new Uint32Array(16);
+    v.set(cv.subarray(0, 8), 0);
+    v[8] = IV[0];
+    v[9] = IV[1];
+    v[10] = IV[2];
+    v[11] = IV[3];
+    v[12] = counter >>> 0;
+    v[13] = Math.floor(counter / 0x1_0000_0000) >>> 0;
+    v[14] = blockLen;
+    v[15] = flags;
+    const m = Uint32Array.from(block);
+    for (let r = 0; r < 7; r++) {
+        round(v, m);
+        if (r < 6) {
+            const permuted = new Uint32Array(16);
+            for (let i = 0; i < 16; i++)
+                permuted[i] = m[MSG_PERMUTATION[i]];
+            m.set(permuted);
+        }
+    }
+    const out = new Uint32Array(8);
+    for (let i = 0; i < 8; i++)
+        out[i] = (v[i] ^ v[i + 8]) >>> 0;
+    return out;
+}
+function wordsToBytes(words) {
+    const out = new Uint8Array(words.length * 4);
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        out[i * 4] = word & 0xff;
+        out[i * 4 + 1] = (word >>> 8) & 0xff;
+        out[i * 4 + 2] = (word >>> 16) & 0xff;
+        out[i * 4 + 3] = (word >>> 24) & 0xff;
+    }
+    return out;
+}
+function bytesToWords(bytes) {
+    const words = new Uint32Array(bytes.length / 4);
+    for (let i = 0; i < words.length; i++) {
+        words[i] =
+            (bytes[i * 4] |
+                (bytes[i * 4 + 1] << 8) |
+                (bytes[i * 4 + 2] << 16) |
+                (bytes[i * 4 + 3] << 24)) >>>
+                0;
+    }
+    return words;
+}
+/** The chaining value of one chunk (chunk counter = its index). */
+function chunkCv(chunk, counter, root) {
+    let cv = Uint32Array.from(IV);
+    const blocks = Math.max(1, Math.ceil(chunk.length / 64));
+    for (let b = 0; b < blocks; b++) {
+        const start = b * 64;
+        const len = Math.min(64, chunk.length - start);
+        const block = new Uint32Array(16);
+        for (let i = 0; i < len; i++) {
+            block[i >> 2] = block[i >> 2] | (chunk[start + i] << ((i & 3) * 8));
+        }
+        let flags = 0;
+        if (b === 0)
+            flags |= CHUNK_START;
+        if (b === blocks - 1) {
+            flags |= CHUNK_END;
+            if (root)
+                flags |= ROOT;
+        }
+        cv = compress(cv, block, counter, len, flags);
+    }
+    return wordsToBytes(cv);
+}
+function parentCv(left, right, root) {
+    const block = new Uint32Array(16);
+    block.set(bytesToWords(left), 0);
+    block.set(bytesToWords(right), 8);
+    return wordsToBytes(compress(Uint32Array.from(IV), block, 0, 64, PARENT | (root ? ROOT : 0)));
+}
+/** Number of 1 KiB chunks (an empty blob still has one chunk). */
+export function baoChunkCount(size) {
+    return Math.max(1, Math.ceil(size / BAO_CHUNK_SIZE));
+}
+/** Largest power of two strictly smaller than `n` (the BLAKE3 split rule). */
+function splitLeft(n) {
+    let p = 1;
+    while (p * 2 < n)
+        p *= 2;
+    return p;
+}
+function chunkLen(size, chunk) {
+    return Math.min(BAO_CHUNK_SIZE, size - chunk * BAO_CHUNK_SIZE);
+}
+/** The BLAKE3 root of arbitrary data, computed with the verified-streaming
+ * tree (exposed for tests; equals `blake3(data)`). */
+export function blake3TreeRoot(data) {
+    const size = data.length;
+    const visit = (start, len, root) => {
+        if (len === 1) {
+            const offset = start * BAO_CHUNK_SIZE;
+            return chunkCv(data.subarray(offset, offset + chunkLen(size, start)), start, root);
+        }
+        const left = splitLeft(len);
+        return parentCv(visit(start, left, false), visit(start + left, len - left, false), root);
+    };
+    return visit(0, baoChunkCount(size), true);
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Decode and verify a bao proof for a chunk range. Throws on any proof
+ * mismatch, truncation, or when the root does not match. Returns the
+ * chunk-aligned data starting at `chunkStart * 1024`.
+ */
+export function decodeBaoRange(input) {
+    const { encoded, root, size } = input;
+    const total = baoChunkCount(size);
+    const chunkStart = Math.max(0, Math.min(input.chunkStart, total - 1));
+    const chunkEnd = Math.max(chunkStart + 1, Math.min(input.chunkEnd, total));
+    if (root.length !== 32)
+        throw new Error("bao: root must be 32 bytes");
+    let pos = 0;
+    const read = (n) => {
+        if (pos + n > encoded.length)
+            throw new Error("bao: truncated proof");
+        const slice = encoded.subarray(pos, pos + n);
+        pos += n;
+        return slice;
+    };
+    const chunks = [];
+    const intersects = (start, len) => start < chunkEnd && start + len > chunkStart;
+    const visit = (start, len, isRoot) => {
+        if (len === 1) {
+            const data = read(chunkLen(size, start));
+            chunks.push(data);
+            return chunkCv(data, start, isRoot);
+        }
+        const pair = read(64);
+        const leftHash = pair.subarray(0, 32);
+        const rightHash = pair.subarray(32, 64);
+        const leftLen = splitLeft(len);
+        const leftSelected = intersects(start, leftLen);
+        const rightSelected = intersects(start + leftLen, len - leftLen);
+        let leftCv;
+        if (leftSelected) {
+            leftCv = visit(start, leftLen, false);
+            if (!equalBytes(leftCv, leftHash))
+                throw new Error("bao: left subtree mismatch");
+        }
+        else {
+            leftCv = leftHash;
+        }
+        let rightCv;
+        if (rightSelected) {
+            rightCv = visit(start + leftLen, len - leftLen, false);
+            if (!equalBytes(rightCv, rightHash))
+                throw new Error("bao: right subtree mismatch");
+        }
+        else {
+            rightCv = rightHash;
+        }
+        return parentCv(leftCv, rightCv, isRoot);
+    };
+    const computed = visit(0, total, true);
+    if (!equalBytes(computed, root)) {
+        throw new Error("bao: proof does not match the CID (root mismatch)");
+    }
+    const assembled = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let at = 0;
+    for (const chunk of chunks) {
+        assembled.set(chunk, at);
+        at += chunk.length;
+    }
+    return assembled;
+}