@tokono.ma/firkin 0.3.0 → 0.4.0

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.3.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"