@tokono.ma/firkin 0.1.0 → 0.1.1

package/README.md

@@ -1,45 +1,158 @@
 # @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.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 { proof, cid } = 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
+});
+
+const rb = new Firkin(base, async (command) =>
+  invocation(session, { command, proofs: [proof], 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokono.ma/firkin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {