@o3co/auth-provider-passkey 0.0.0 → 0.18.0-rc.1

package/webauthn/src/records.js

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { Unavailable } from "@o3co/auth-provider-foundation/kernel";
+import { z } from "zod";
+/** Whether `text` is unpadded base64url of 1 to `max` bytes: the one spelling of those bytes. */
+export function isCanonical(text, max) {
+    if (typeof text !== "string" || !/^[A-Za-z0-9_-]+$/.test(text))
+        return false;
+    const bytes = Buffer.from(text, "base64url");
+    return bytes.length >= 1 && bytes.length <= max && bytes.toString("base64url") === text;
+}
+export const handleBytes = 64;
+export const idBytes = 1023;
+const hashOf = (value) => createHash("sha256").update(value).digest("base64url");
+const subjectKey = (subject) => `s-${hashOf(subject)}`;
+const credentialKey = (id) => `c-${hashOf(id)}`;
+const broken = () => new Unavailable("webauthn");
+const canonical = (max) => z.string().refine((text) => isCanonical(text, max));
+const holderShape = z.object({
+    v: z.literal(1),
+    handle: canonical(handleBytes),
+    credentials: z.array(z.string()),
+});
+const passkeyShape = z.object({
+    v: z.literal(1),
+    subject: z.string(),
+    publicKey: canonical(4096),
+    signCount: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    backupEligible: z.boolean(),
+    backedUp: z.boolean(),
+    transports: z.array(z.string()).optional(),
+});
+const credentialShape = passkeyShape
+    .omit({ v: true, subject: true })
+    .extend({ id: canonical(idBytes), userHandle: canonical(handleBytes) });
+/** A credential in the shape webauthn writes, with its fields alone; none for any other value. */
+export function credentialOf(value) {
+    const parsed = credentialShape.safeParse(value);
+    if (!parsed.success)
+        return undefined;
+    const { transports, ...rest } = parsed.data;
+    return { ...rest, ...(transports ? { transports } : {}) };
+}
+/** A new subject's user handle: 32 random bytes, unpadded base64url. */
+export const freshHandle = (random) => Buffer.from(random(32)).toString("base64url");
+/** A kept holder in the one shape written, or unavailable: a broken record decides nothing. */
+function holderOf(record) {
+    const parsed = holderShape.safeParse(record);
+    if (!parsed.success)
+        throw broken();
+    return { handle: parsed.data.handle, credentials: parsed.data.credentials };
+}
+function passkeyOf(id, record) {
+    const parsed = passkeyShape.safeParse(record);
+    if (!parsed.success)
+        throw broken();
+    const { subject, transports, publicKey, signCount, backupEligible, backedUp } = parsed.data;
+    return {
+        subject,
+        credential: {
+            id,
+            publicKey,
+            signCount,
+            backupEligible,
+            backedUp,
+            ...(transports ? { transports } : {}),
+        },
+    };
+}
+const stored = (value) => value;
+/** Passkeys and their holders, written only in canonical form and read only in the shape written. */
+export function keptPasskeys(store) {
+    const holder = async (subject) => {
+        const record = await store.subjects.read(subjectKey(subject));
+        return record && holderOf(record);
+    };
+    /** Takes over a credential no holder lists (a failed registration's, or one between its writes), while it holds what was read. */
+    const takeUnlisted = async (id, record) => {
+        const key = credentialKey(id);
+        const seen = await store.credentials.read(key);
+        if (!seen)
+            throw broken();
+        const owner = await holder(passkeyOf(id, seen).subject);
+        if (owner?.credentials.includes(id))
+            return false;
+        const same = (r) => JSON.stringify(r) === JSON.stringify(seen);
+        const taken = await store.credentials.update(key, (current) => same(current) ? { value: record } : undefined);
+        return taken !== undefined && same(taken.before);
+    };
+    return {
+        holder,
+        /** The subject's handle; `fresh` becomes it when the subject has none yet. */
+        handleFor: async (subject, fresh) => {
+            if (!isCanonical(fresh, handleBytes))
+                throw new Error("a handle must be canonical");
+            const first = stored({ v: 1, handle: fresh, credentials: [] });
+            await store.subjects.save(subjectKey(subject), first);
+            const kept = await holder(subject);
+            if (!kept)
+                throw broken();
+            return kept.handle;
+        },
+        passkey: async (id) => {
+            if (!isCanonical(id, idBytes))
+                return undefined;
+            const record = await store.credentials.read(credentialKey(id));
+            return record && passkeyOf(id, record);
+        },
+        /** Keeps a new passkey for the subject, whose handle it was made for; an id its holder lists is a conflict. */
+        register: async (subject, credential, max, nickname) => {
+            // Only what reads back: a record no read can take would make every later use unavailable.
+            if (!credentialOf(credential))
+                return "malformed";
+            const { id, userHandle, ...rest } = credential;
+            const kept = await holder(subject);
+            if (kept?.handle !== userHandle)
+                return "malformed";
+            if (kept.credentials.length >= max)
+                return "full";
+            const record = stored({ v: 1, subject, ...rest, ...(nickname ? { nickname } : {}) });
+            const key = credentialKey(id);
+            if ((await store.credentials.save(key, record)) === "exists") {
+                if (!(await takeUnlisted(id, record)))
+                    return "conflict";
+            }
+            const listed = await store.subjects.update(subjectKey(subject), (current) => {
+                const { credentials } = holderOf(current);
+                if (credentials.includes(id) || credentials.length >= max)
+                    return undefined;
+                return { value: stored({ ...current, credentials: [...credentials, id] }) };
+            });
+            if (!listed)
+                throw broken();
+            return holderOf(listed.after).credentials.includes(id) ? "registered" : "full";
+        },
+        /** Moves the count on from the one judged; another change first is a lost race. */
+        count: async (judged, next) => {
+            const changed = await store.credentials.update(credentialKey(judged.id), (current) => {
+                if (passkeyOf(judged.id, current).credential.signCount !== judged.signCount)
+                    return undefined;
+                return {
+                    value: stored({ ...current, signCount: next.signCount, backedUp: next.backedUp }),
+                };
+            });
+            // Written only over the count judged, so the count before tells whether this one wrote.
+            const before = changed && passkeyOf(judged.id, changed.before).credential.signCount;
+            return before === judged.signCount ? "counted" : "raced";
+        },
+    };
+}
+const storedChallenge = (value) => value;
+const taken = storedChallenge({ v: 1, taken: true });
+const openedShape = z.discriminatedUnion("kind", [
+    z.object({
+        v: z.literal(1),
+        kind: z.literal("assertion"),
+        requester: z.string(),
+        at: z.number(),
+    }),
+    z.object({
+        v: z.literal(1),
+        kind: z.literal("registration"),
+        subject: z.string(),
+        at: z.number(),
+    }),
+]);
+const isChallenge = (text) => isCanonical(text, 32) && Buffer.from(text, "base64url").length === 32;
+/** Challenges of 32 bytes, each taken once, with when they were made. */
+export function keptChallenges(store, now, lifetimeMs) {
+    return {
+        open: async (challenge, purpose) => {
+            const record = storedChallenge({ v: 1, ...purpose, at: now() });
+            // 32 random bytes meeting another challenge cannot be told from a broken place.
+            if ((await store.open(challenge, record, lifetimeMs)) === "exists")
+                throw broken();
+        },
+        /** The purpose and time of a challenge made and not yet taken; none for any other. */
+        take: async (challenge) => {
+            if (!isChallenge(challenge))
+                return undefined;
+            const parsed = openedShape.safeParse((await store.take(challenge, taken))?.before);
+            // Ended on kernel's clock, as a late write gives it the store's full lifetime again.
+            if (!parsed.success || now() - parsed.data.at >= lifetimeMs)
+                return undefined;
+            const { v: _version, ...opened } = parsed.data;
+            return opened;
+        },
+    };
+}

package/webauthn/src/registration/README.md

@@ -0,0 +1,19 @@
+# registration
+
+Internal module of `webauthn`: registering passkeys.
+
+## Responsibilities
+- Registers passkeys for a subject: options, then the verified response.
+
+## Not here
+- The ceremonies (`ceremony`). How records are written (the package's records). Who the subject is (the caller).
+
+## Offers
+- `registrationsOver` (ceremonies, records, challenges, user verification, the limit, a fresh handle) → the package's `Registrations`.
+
+## Invariants
+- A challenge counts only for the subject it was made for, once. Client data that does not read takes no challenge.
+- A subject's handle is made on its first options, and kept.
+
+## Depends on
+- `ceremony`; the package's contract and records

package/webauthn/src/registration/registrations.d.ts

@@ -0,0 +1,14 @@
+import type { Ceremonies, Registrations, Verification } from "../contract.js";
+import type { KeptChallenges, KeptPasskeys } from "../records.js";
+export interface RegistrationParts {
+    readonly ceremonies: Ceremonies;
+    readonly records: KeptPasskeys;
+    readonly challenges: KeptChallenges;
+    readonly verification: Verification;
+    /** The passkeys a subject may hold. */
+    readonly max: number;
+    /** A new subject's handle: 32 random bytes, unpadded base64url. */
+    freshHandle(): string;
+}
+/** Registrations of passkeys, each answering a challenge made for its subject. */
+export declare function registrationsOver(p: RegistrationParts): Registrations;

package/webauthn/src/registration/registrations.js

@@ -0,0 +1,31 @@
+import { challengeOf } from "../ceremony/ceremony.js";
+const refused = (reason) => ({ kind: "refused", reason });
+/** Registrations of passkeys, each answering a challenge made for its subject. */
+export function registrationsOver(p) {
+    return {
+        creation: async (subject) => {
+            const handle = await p.records.handleFor(subject, p.freshHandle());
+            const held = (await p.records.holder(subject))?.credentials ?? [];
+            const made = p.ceremonies.creation({ handle, name: subject }, held, p.verification);
+            await p.challenges.open(made.challenge, { kind: "registration", subject });
+            return { options: made.options };
+        },
+        register: async (subject, response, nickname) => {
+            const challenge = challengeOf(response);
+            if (challenge === undefined)
+                return refused("unreadable");
+            const opened = await p.challenges.take(challenge);
+            const holder = await p.records.holder(subject);
+            if (opened?.kind !== "registration" || opened.subject !== subject || !holder) {
+                return refused("no-challenge");
+            }
+            const attested = await p.ceremonies.attest(response, challenge, holder.handle, p.verification);
+            if (attested.kind === "refused")
+                return attested;
+            const kept = await p.records.register(subject, attested.credential, p.max, nickname);
+            return kept === "registered"
+                ? { kind: "registered", credential: attested.credential }
+                : refused(kept);
+        },
+    };
+}

package/webauthn/src/section.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const section: z.ZodObject<{
+    "rp-id": z.ZodString;
+    "rp-name": z.ZodString;
+    origins: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
+    "top-origins": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    "challenge-seconds": z.ZodDefault<z.ZodNumber>;
+    "user-verification": z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        preferred: "preferred";
+        discouraged: "discouraged";
+    }>>;
+    "max-credentials": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type Settings = z.output<typeof section>;

package/webauthn/src/section.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/** An origin as a browser serializes it: https, or http on localhost; a domain, never an IP literal. */
+const origin = z.string().refine((entry) => {
+    const url = URL.parse(entry);
+    if (!url || url.origin !== entry)
+        return false;
+    if (url.hostname.startsWith("[") || /^[\d.]+$/.test(url.hostname))
+        return false;
+    return url.protocol === "https:" || (url.protocol === "http:" && url.hostname === "localhost");
+}, "a serialized https origin (http only on localhost), on a domain");
+/** An Android app origin: the unpadded base64url SHA-256 of its signing certificate; no host. */
+const app = /^android:apk-key-hash:[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+/** Whether a browser takes `rpId` on `host`: the host, or a domain above it but no single label. */
+const servesHost = (rpId, host) => host === rpId || (host.endsWith(`.${rpId}`) && rpId.includes("."));
+export const section = z
+    .strictObject({
+    "rp-id": z.string().min(1),
+    "rp-name": z.string().min(1),
+    /** The origins ceremonies may come from, matched exactly. */
+    origins: z
+        .array(z.union([z.string().regex(app, "an Android app origin of this form"), origin]))
+        .min(1),
+    /** The pages that may frame a ceremony; none by default, so any ceremony in a frame is refused. */
+    "top-origins": z.array(origin).default([]),
+    "challenge-seconds": z.number().int().min(10).max(600).default(120),
+    "user-verification": z.enum(["required", "preferred", "discouraged"]).default("preferred"),
+    "max-credentials": z.number().int().min(1).max(100).default(10),
+})
+    .refine((s) => s.origins.every((entry) => app.test(entry) || servesHost(s["rp-id"], new URL(entry).hostname)), {
+    path: ["rp-id"],
+    message: "the host of each web origin, or a domain each one lies under",
+});

package/webauthn/src/store.d.ts

@@ -0,0 +1,55 @@
+declare const storedPasskey: unique symbol;
+/** A passkey record as the store keeps it: the store never reads it, and only webauthn opens it. */
+export type StoredPasskey = {
+    readonly [storedPasskey]: true;
+};
+declare const storedChallenge: unique symbol;
+/** A challenge's record as the store keeps it: only webauthn opens it. */
+export type StoredChallenge = {
+    readonly [storedChallenge]: true;
+};
+/** Records by a key webauthn makes, each changed only from what it holds, kept without end. */
+export interface PasskeyRecords {
+    /** Keeps a key's first record, unless the key holds one. */
+    save(key: string, record: StoredPasskey): Promise<"created" | "exists">;
+    read(key: string): Promise<StoredPasskey | undefined>;
+    /** Changes the record from what it holds; `change` runs again on a race, so it is pure; none leaves it. Nothing when gone. */
+    update(key: string, change: (record: StoredPasskey) => {
+        readonly value: StoredPasskey;
+    } | undefined): Promise<{
+        readonly before: StoredPasskey;
+        readonly after: StoredPasskey;
+    } | undefined>;
+}
+/** Passkeys by credential, and each subject's handle and credentials, apart. Every call throws Unavailable when the place cannot tell. */
+export interface PasskeyStore {
+    readonly credentials: PasskeyRecords;
+    readonly subjects: PasskeyRecords;
+}
+export declare const passkeyStore: import("@o3co/auth-provider-foundation/kernel").Contract<PasskeyStore>;
+/** A passkey lost or come back would let a removed key in, or keep its owner out; a login reads one another request wrote. */
+export declare const passkeyStoreNeeds: {
+    readonly neverEvicted: true;
+    readonly survivesCrash: true;
+    readonly survivesFailover: true;
+    readonly confirmedReads: true;
+};
+/** Challenges by the challenge, never kept in clear, each kept for its lifetime. Every call throws Unavailable when the place cannot tell. */
+export interface ChallengeStore {
+    /** Keeps a new challenge's record for its lifetime, unless the challenge holds one. */
+    open(challenge: string, record: StoredChallenge, lifetimeMs: number): Promise<"created" | "exists">;
+    /** Puts `mark` in place of what the challenge holds, for the rest of its lifetime, and answers both. Nothing when gone. */
+    take(challenge: string, mark: StoredChallenge): Promise<{
+        readonly before: StoredChallenge;
+        readonly after: StoredChallenge;
+    } | undefined>;
+}
+export declare const challengeStore: import("@o3co/auth-provider-foundation/kernel").Contract<ChallengeStore>;
+/** A challenge taken that came back could be answered twice; one lost to memory only fails its ceremony. */
+export declare const challengeStoreNeeds: {
+    readonly survivesCrash: true;
+    readonly survivesFailover: true;
+    /** Names derive from the challenge, so the place never keeps it in clear. */
+    readonly namesFromSecret: true;
+};
+export {};

package/webauthn/src/store.js

@@ -0,0 +1,17 @@
+import { contract } from "@o3co/auth-provider-foundation/kernel";
+export const passkeyStore = contract("webauthn.passkey-store");
+/** A passkey lost or come back would let a removed key in, or keep its owner out; a login reads one another request wrote. */
+export const passkeyStoreNeeds = {
+    neverEvicted: true,
+    survivesCrash: true,
+    survivesFailover: true,
+    confirmedReads: true,
+};
+export const challengeStore = contract("webauthn.challenge-store");
+/** A challenge taken that came back could be answered twice; one lost to memory only fails its ceremony. */
+export const challengeStoreNeeds = {
+    survivesCrash: true,
+    survivesFailover: true,
+    /** Names derive from the challenge, so the place never keeps it in clear. */
+    namesFromSecret: true,
+};

package/webauthn/src/testing.d.ts

@@ -0,0 +1,147 @@
+import type { z } from "zod";
+import type { section } from "./section.js";
+import type { ChallengeStore, PasskeyStore, StoredPasskey } from "./store.js";
+export type WebauthnSettings = z.input<typeof section>;
+export declare const testOrigin = "https://rp.example";
+/** The webauthn part of a test's configuration: a relying party at `rp.example`. */
+export declare function webauthnConfig(settings?: Partial<WebauthnSettings>): {
+    webauthn: {
+        "rp-id": string;
+        "rp-name": string;
+        origins: string[];
+        "top-origins"?: string[] | undefined;
+        "challenge-seconds"?: number | undefined;
+        "user-verification"?: "required" | "preferred" | "discouraged" | undefined;
+        "max-credentials"?: number | undefined;
+    };
+};
+/** Where a ceremony runs, as the browser reports it in the client data. */
+export interface Client {
+    readonly origin: string;
+    readonly crossOrigin?: boolean;
+    readonly topOrigin?: string;
+}
+/** What an authenticator may be told to do otherwise, for a test of a refusal. */
+export interface Twist {
+    /** The relying party the authenticator data names, instead of the one the options name. */
+    readonly rpId?: string;
+    /** The user handle an assertion carries; null carries none. */
+    readonly userHandle?: string | null;
+    /** The count an assertion carries. */
+    readonly counter?: number;
+    /** The id a new credential takes, instead of 16 random bytes. */
+    readonly credentialId?: string;
+    /** The client data, encoded as given instead of as JSON in base64url. */
+    readonly clientDataJSON?: (json: string) => string;
+    /** Answers what a browser would refuse: the options' rules and its own limits are not checked. */
+    readonly overlook?: boolean;
+}
+/** Credential creation options, as a relying party sends them in JSON. */
+export interface CreationOptions {
+    readonly rp: {
+        readonly id?: string;
+    };
+    readonly user: {
+        readonly id: string;
+    };
+    readonly challenge: string;
+    readonly pubKeyCredParams: readonly {
+        readonly alg: number;
+        readonly type: string;
+    }[];
+    readonly excludeCredentials?: readonly {
+        readonly id: string;
+        readonly type: string;
+    }[];
+    readonly authenticatorSelection?: {
+        readonly residentKey?: string;
+        readonly requireResidentKey?: boolean;
+        readonly userVerification?: string;
+    };
+}
+/** Credential request options, as a relying party sends them in JSON. */
+export interface RequestOptions {
+    readonly challenge: string;
+    readonly rpId?: string;
+    readonly allowCredentials?: readonly {
+        readonly id: string;
+        readonly type: string;
+    }[];
+    readonly userVerification?: string;
+}
+/**
+ * A software WebAuthn authenticator behind a browser: it makes ES256 (or ES384) credentials,
+ * attests with `none`, asserts with a count that goes up unless it keeps none, and checks the
+ * options as a browser does unless a twist says to overlook them.
+ */
+export declare function softwareAuthenticator(settings?: {
+    /** Whether it can verify the user; it can unless told otherwise. */
+    readonly userVerified?: boolean;
+    readonly backupEligible?: boolean;
+    readonly countless?: boolean;
+    readonly algorithm?: "ES256" | "ES384";
+    /** Whether it can keep a discoverable credential; it can unless told otherwise. */
+    readonly discoverable?: boolean;
+}): {
+    /** Answers creation options as `navigator.credentials.create` does. */
+    create: (options: CreationOptions, client: Client, twist?: Twist) => {
+        id: string;
+        rawId: string;
+        type: string;
+        response: {
+            clientDataJSON: string;
+            attestationObject: string;
+            transports: string[];
+        };
+        clientExtensionResults: {};
+    };
+    /** Answers request options as `navigator.credentials.get` does, with `pick` if the user picks one. */
+    get: (options: RequestOptions, client: Client, twist?: Twist, pick?: string) => {
+        id: string;
+        rawId: string;
+        type: string;
+        response: {
+            userHandle?: string;
+            clientDataJSON: string;
+            authenticatorData: string;
+            signature: string;
+        };
+        clientExtensionResults: {};
+    };
+};
+/** A place that keeps webauthn's passkeys, as one implementation of its store interface offers it. */
+export interface PasskeyPlace {
+    readonly passkeys: PasskeyStore;
+    /** Moves the place's clock on. */
+    advance(ms: number): void;
+    /** Before the next update of a subject's `key` writes, another writer changes its record as given. */
+    raceNextUpdate(key: string, change: (record: StoredPasskey) => StoredPasskey): void;
+    /** Where answers can be lost: the next write takes effect, but its answer is lost. */
+    readonly loseNextAnswer?: () => void;
+    /** Where the place replicates: a replica takes over, keeping only what was confirmed. */
+    readonly failover?: () => Promise<void>;
+    /** Where the place can restart: it does, keeping only what it holds durably. */
+    readonly restart?: () => Promise<void>;
+    /** Where memory can run short: it does, keeping only what is kept from eviction. */
+    readonly pressMemory?: () => Promise<void>;
+    /** Where reads can meet unconfirmed writes: runs `during` as the next save takes effect, unconfirmed. */
+    readonly duringNextSave?: (during: () => Promise<void>) => void;
+}
+/** What webauthn needs from any implementation: records kept whole and apart, without end, written by webauthn in one shape. */
+export declare function passkeyStoreContract(name: string, open: () => Promise<PasskeyPlace>): void;
+/** A place that keeps webauthn's challenges, as one implementation of its store interface offers it. */
+export interface ChallengePlace {
+    readonly challenges: ChallengeStore;
+    /** Moves the place's clock on, so lifetimes run out. */
+    advance(ms: number): void;
+    /** Where answers can be lost: the next write takes effect, but its answer is lost. */
+    readonly loseNextAnswer?: () => void;
+    /** Where the place replicates: a replica takes over, keeping only what was confirmed. */
+    readonly failover?: () => Promise<void>;
+    /** Where the place can restart: it does, keeping only what it holds durably. */
+    readonly restart?: () => Promise<void>;
+    /** Where what the place was given can be searched: whether any of it carried `text`. */
+    readonly holds?: (text: string) => boolean;
+}
+/** What webauthn needs from any implementation: a challenge kept once for its lifetime, taken once, never in clear. */
+export declare function challengeStoreContract(name: string, open: () => Promise<ChallengePlace>): void;