@tokono.ma/firkin 0.2.0 → 0.4.0

package/dist/client.d.ts

@@ -1,5 +1,10 @@
 import { CID } from "multiformats";
+/** Wire version prefix for every API path (`/health` and `/.well-known/*`
+ * live outside it). */
+export declare const API_PREFIX = "/v1";
 import type { Signer } from "./keys.ts";
+import { type WebAuthnAssertion } from "./webauthn.ts";
+import type { PlcAttestationMaterial } from "./plc.ts";
 /** Per-call options a TokenSource may honor. */
 export interface TokenOptions {
     /** Override the token's expiry (seconds from now). */
@@ -12,8 +17,150 @@ export interface TokenOptions {
 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;
+/**
+ * Source for an **attested session**: every invocation carries
+ * `meta["firkin/account"]`, the hint the server uses to resolve the
+ * session → account binding. The session key signs directly (no proofs); the
+ * binding, not the token, carries the account's authority.
+ *
+ * Obtain the binding with a passkey: `attestationChallenge(...)` →
+ * `credentials.get` → `Firkin.attest(...)`.
+ */
+export declare function sessionTokenSource(signer: Signer, opts: {
+    account: string;
+    expireIn?: number;
+}): TokenSource;
 /** Fixed-token source: only appropriate for public/read-only usage. */
 export declare function staticToken(token: Uint8Array): TokenSource;
+export interface CarIngestResult {
+    /** Blocks found in the CAR. */
+    blocks: number;
+    /** Blocks written by this call. */
+    stored: number;
+    /** Blocks that were already stored (claim joined). */
+    already: number;
+    /** Total rejected blocks (the `failed` list may be capped). */
+    failed_total: number;
+    failed: {
+        cid: string;
+        error: string;
+    }[];
+}
+/** One page of a tag group. */
+export interface TagPage {
+    name: string;
+    cids: string[];
+    count: number;
+    cursor: number;
+    /** Next page cursor, or null when this was the last page. */
+    next: number | null;
+}
+/** Result of `POST /v1/tokens/attestation`. */
+export type AttestationResult = SessionAttestation | RecoveryAttestation;
+/** A session binding (passkey or `did:plc`). */
+export interface SessionAttestation {
+    kind: "session";
+    /** Content-addressed attestation id — revoke it with `revoke({cids})`. */
+    cid: string;
+    account: string;
+    /** The bound `did:key` that signs API calls. */
+    session: string;
+    commands: string[];
+    nbf: number;
+    exp: number;
+}
+/** A recovery grant: `recovery` may call `POST /v1/account/recover`. */
+export interface RecoveryAttestation {
+    kind: "recovery";
+    cid: string;
+    account: string;
+    /** The DID authorised to recover the account. */
+    recovery: string;
+    /** Unix seconds; null for an indefinite grant. */
+    exp: number | null;
+}
+/**
+ * Canonicalize an instance origin: scheme + host + optional port, lowercased,
+ * with no trailing slash, path, query, fragment or userinfo.
+ *
+ * This matters twice over. Firkin compares the `firkin` audience field of its
+ * own records to `ORIGIN` exactly, and the ATProto indexers that can discover
+ * appeals — Constellation backlinks and Spacedust links — match URLs
+ * byte-for-byte, so `https://Firkin.example/` and `https://firkin.example`
+ * would be two unrelated values to them.
+ *
+ * Throws on a string that is not an absolute URL (e.g. a bare host).
+ */
+export declare function normalizeOrigin(origin: string): string;
+/** NSID of the access appeal an operator's firehose consumer reads.
+ * See `lexicons/ma.tokono.firkin.appeal.json`. */
+export declare const APPEAL_COLLECTION = "ma.tokono.firkin.appeal";
+/** An appeal to be registered on one Firkin instance. */
+export interface AppealRequest {
+    $type: "ma.tokono.firkin.appeal";
+    /** The target instance's canonical origin, e.g. `https://firkin.example`
+     * (see `normalizeOrigin`). */
+    firkin: string;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** Optional ISO 8601 timestamp after which the appeal is void. */
+    expiresAt?: string;
+    /** Optional opaque correlation value. */
+    nonce?: string;
+    /** Optional message for the operator. PUBLIC — never put secrets here. */
+    note?: string;
+}
+/**
+ * Build an access appeal to write into the requesting account's repo.
+ *
+ * Firkin's HTTP API is admin-gated; this record is how an account asks an
+ * operator to register it. An operator-side consumer tails the ATProto
+ * firehose, filters this collection, and applies its own policy. Nothing here
+ * grants service — the commit signature only proves who appealed.
+ *
+ * `firkin` is normalized with `normalizeOrigin`, because an operator-side
+ * consumer (and any indexer in front of it) matches the value against its own
+ * origin exactly.
+ *
+ * Use `appealRkey(firkin)` as the record key.
+ */
+export declare function appealRequest(opts: {
+    firkin: string;
+    /** Seconds until `expiresAt` (omit for no expiry). */
+    expireIn?: number;
+    nonce?: string;
+    note?: string;
+    /** Override the creation time (unix seconds) — tests only. */
+    now?: number;
+}): AppealRequest;
+/** The conventional record key for an appeal: the instance host
+ * (e.g. `firkin.example`), which is idempotent and a valid rkey. */
+export declare function appealRkey(firkin: string): string;
+/** A did:plc session record (the value written into the account's repo). */
+export interface PlcSessionRecord {
+    $type: "ma.tokono.firkin.session";
+    /** The API origin, matching server config (see `normalizeOrigin`). */
+    firkin: string;
+    /** The `did:key` session that will sign API calls. */
+    session: string;
+    /** Capability prefixes the session may exercise. */
+    commands: string[];
+    /** Unix seconds. */
+    nbf: number;
+    /** Unix seconds; the server caps `exp - nbf`. */
+    exp: number;
+}
+/** The record a did:plc account writes into its repo to attest a session
+ * (MST key `ma.tokono.firkin.session/<session did>`). Write it once with your
+ * ATProto agent, then submit the commit + MST path via `Firkin.attestPlc`. */
+export declare function plcSessionRecord(opts: {
+    /** The API origin, matching server config (normalized). */
+    firkin: string;
+    session: string;
+    commands: string[];
+    expireIn?: number;
+    now?: number;
+}): PlcSessionRecord;
 export interface UploadResult {
     cid: string;
     /** True when the blob was already stored (dedup; claim joined). */
@@ -55,16 +202,27 @@ export declare class Firkin {
     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 bytes; returns the CID and whether it was already stored.
+     * `tags` is client-side sugar: after the bytes are stored (or deduped), the
+     * CID is added to each group with `tagAdd`. Tagging is a separate call, so
+     * if it fails the blob is already stored and `tagAdd` can be retried. */
     upload(data: Uint8Array | Blob, opts?: {
         codec?: number;
         hash?: "sha256" | "blake3";
+        tags?: string | string[];
     }): 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. */
+    /** Fetch a whole blob. Reads are authenticated: the server requires the
+     * `/firkin/blob/read` capability (an operator can opt into anonymous
+     * reads with `PUBLIC_READS=true`, in which case the header is ignored).
+     * Read tokens are reusable — reads are not replay-tracked. */
     get(cid: string): Promise<Uint8Array>;
+    /**
+     * Read a byte range of a **BDASL (BLAKE3)** blob with verified streaming:
+     * the server sends a bao proof and every chunk is checked against the CID
+     * before it is returned — the server is not trusted for integrity. Needs a
+     * BLAKE3 CID (`cidForBytes(data, { hash: "blake3" })`).
+     */
+    verifiedRange(cid: string, range?: ByteRange): Promise<RangeResult>;
     /** Fetch a byte range (206 responses; server-trusted verification).
      * Authenticated like [`get`](#get). */
     getRange(cid: string, range?: ByteRange): Promise<RangeResult>;
@@ -90,20 +248,40 @@ export declare class Firkin {
     readUrl(cid: string, opts?: {
         expireIn?: number;
     }): Promise<string>;
-    /** Attach an already-stored CID to the signer's account. */
-    claim(cid: string): Promise<void>;
+    /** Attach an already-stored CID to the signer's account. `tags` is the
+     * same sugar as `upload`: the CID is added to each group afterwards. */
+    claim(cid: string, opts?: {
+        tags?: string | 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 delegations/sessions: specific delegation or attestation CIDs,
+     * or every grant minted before now (`all: true`). Seed/did:key accounts
+     * authorize this with a direct invocation by the account key. An attested
+     * session must additionally pass a fresh passkey assertion (`stepUp`,
+     * built with `stepUpChallenge`) — a stolen session key must not be able to
+     * revoke. */
     revoke(opts: {
         cids?: string[];
         all?: boolean;
-    }): Promise<void>;
+    }, stepUp?: WebAuthnAssertion): Promise<void>;
+    /** Attest a session for a `did:plc` account. `material` is what the client
+     * fetched from the account's repo and the PLC directory (base64url DAG-CBOR):
+     *
+     * - `ops`: the PLC operation log, genesis first;
+     * - `commit`: the signed repo commit containing the record;
+     * - `record`: the `plcSessionRecord(...)` value;
+     * - `proof`: the MST nodes proving the record is in that commit.
+     *
+     * The server verifies everything offline (no PLC/PDS call). */
+    static attestPlc(base: string, material: PlcAttestationMaterial, fetchImpl?: typeof fetch): Promise<AttestationResult>;
+    /** Enrol a passkey session. The assertion's challenge must be
+     * `attestationChallenge(...)`; the server verifies the ceremony, stores the
+     * session → account binding, and returns its attestation CID. After this,
+     * requests are signed by the session key (see `sessionTokenSource`).
+     * Static: the endpoint is unauthenticated by design — the assertion IS the
+     * authentication. */
+    static attest(base: string, assertion: WebAuthnAssertion, fetchImpl?: typeof fetch): Promise<AttestationResult>;
     /** (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
@@ -113,19 +291,6 @@ export declare class Firkin {
         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
@@ -152,6 +317,52 @@ export declare class Firkin {
     registryDelete(name: string): Promise<void>;
     /** The account's whole registry: name → CID (sorted). */
     registryList(): Promise<Record<string, string>>;
+    /** Tag blobs: add CIDs to a per-account label group (idempotent). */
+    tagAdd(name: string, cids: string | string[]): Promise<{
+        name: string;
+        count: number;
+    }>;
+    /** One page of a tag group (groups are paged; `next` walks them). */
+    tagGet(name: string, opts?: {
+        cursor?: number;
+    }): Promise<TagPage>;
+    /** Every CID in a tag group (walks the pages). */
+    tagAll(name: string): Promise<string[]>;
+    /** The tag groups a CID belongs to (reverse lookup). Needs the full
+     * `/firkin/tag/read` command: a per-group proof cannot widen into it. */
+    blobTags(cid: string): Promise<string[]>;
+    /** Add a CID to each group in `tags` (sugar for `upload`/`claim`). */
+    private applyTags;
+    /** Every tag group with its CID count. */
+    tagList(): Promise<{
+        name: string;
+        count: number;
+    }[]>;
+    /** Untag one blob from a group. */
+    tagRemove(name: string, cid: string): Promise<{
+        name: string;
+        count: number;
+    }>;
+    /** Drop a tag group; the blobs stay stored. */
+    tagDelete(name: string): Promise<{
+        name: string;
+        cids: number;
+    }>;
+    /** Drop a tag group **and detach every blob in it** (bytes die where this
+     * account is the last claimant). Needs `/firkin/tag/delete`. */
+    tagDeleteBlobs(name: string): Promise<{
+        name: string;
+        blobs: number;
+        deleted: number;
+    }>;
+    /**
+     * Ingest a rootless CARv1 — "upload a `.car` file". Every block is verified
+     * against its own CID, policy-checked and claimed by the account; there is
+     * no DAG traversal and no root requirement (unlike [`dagPush`](#dagpush),
+     * which syncs one DAG over multiple rounds). Partial success is normal:
+     * `failed` lists the rejected blocks (digest mismatch, policy, size).
+     */
+    ingestCar(car: Uint8Array): Promise<CarIngestResult>;
     /**
      * 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
@@ -201,7 +412,8 @@ export declare class Firkin {
      */
     pullFile(root: string): Promise<Uint8Array>;
 }
-export declare function carFile(root: CID, entries: [CID, Uint8Array][]): Uint8Array;
+export declare function carFile(root: CID | null, entries: [CID, Uint8Array][]): Uint8Array;
+export declare function parseCarBlocks(car: Uint8Array): Map<string, Uint8Array>;
 export declare function multihashSha256(data: Uint8Array): MultihashDigest;
 type MultihashDigest = {
     code: number;