@udibo/oauth2 0.41.0 → 0.43.0

package/dist/identity/passkeys/service.js

@@ -0,0 +1,558 @@
+/**
+ * The passkey orchestrator: WebAuthn registration and authentication
+ * ceremonies over an app-owned {@link PasskeyStore} and
+ * {@link PasskeyChallengeStore}. Cryptographic verification is delegated to
+ * `@simplewebauthn/server`; this layer owns the policy around it — no
+ * attestation, discoverable credentials, single-use challenges, a per-user
+ * cap, sign-count clone detection, and the usual identity seams.
+ *
+ * @module
+ */
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse, } from "@simplewebauthn/server";
+import { base64urlEncode, randomToken } from "../../utils/crypto.js";
+import { IdentityError } from "../errors.js";
+import { dispatchIdentityEvent, } from "../events.js";
+import { enforceRateLimit } from "../rate-limit.js";
+/**
+ * The RFC 8176 / OpenID EAP `amr` value for a passkey: proof of possession of
+ * a key. `hwk` and `swk` would claim to know where the key lives, which an
+ * unattested passkey cannot show.
+ */
+export const PASSKEY_AMR = "pop";
+const DEFAULT_MAX_PASSKEYS = 25;
+const DEFAULT_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+const MAX_NAME_LENGTH = 64;
+const MAX_USER_HANDLE_BYTES = 64;
+const SUPPORTED_ALGORITHMS = [-8, -7, -257];
+/**
+ * Orchestrates passkey registration, sign-in, and management over app-owned
+ * stores. Every passkey is discoverable, attestation is never requested, and
+ * user verification is preferred and reported rather than required, so
+ * security keys without a PIN still work as a second factor. Deciding what a
+ * verified passkey is worth — a first factor, a second factor, whether it
+ * satisfies your MFA policy — and minting the session are the app's job.
+ *
+ * @example Register, then sign in
+ * ```ts
+ * import {
+ *   MemoryPasskeyChallengeStore,
+ *   MemoryPasskeyStore,
+ *   PasskeyService,
+ * } from "@udibo/oauth2/identity/passkeys";
+ *
+ * const passkeys = new PasskeyService({
+ *   store: new MemoryPasskeyStore(),
+ *   challenges: new MemoryPasskeyChallengeStore(),
+ * });
+ * const relyingParty = {
+ *   id: "login.example.com",
+ *   name: "Example",
+ *   origins: ["https://login.example.com"],
+ * };
+ * const user = { id: "user-1", name: "ada@example.com" };
+ *
+ * const registration = await passkeys.startRegistration({ relyingParty, user });
+ * // keep registration.ceremonyId in an HttpOnly cookie; the browser runs
+ * // navigator.credentials.create() with registration.options and posts back:
+ * declare const createResponse: import("@udibo/oauth2/identity/passkeys").PasskeyRegistrationResponse;
+ * await passkeys.finishRegistration({
+ *   relyingParty,
+ *   ceremonyId: registration.ceremonyId,
+ *   userId: user.id,
+ *   response: createResponse,
+ * });
+ *
+ * const signIn = await passkeys.startAuthentication({ relyingParty });
+ * declare const getResponse: import("@udibo/oauth2/identity/passkeys").PasskeyAuthenticationResponse;
+ * const result = await passkeys.finishAuthentication({
+ *   relyingParty,
+ *   ceremonyId: signIn.ceremonyId,
+ *   response: getResponse,
+ * });
+ * if (result.valid) {
+ *   // run your MFA policy for result.userId, then start a session
+ * }
+ * ```
+ */
+export class PasskeyService {
+    #store;
+    #challenges;
+    #maxPasskeys;
+    #challengeTtlMs;
+    #rateLimiter;
+    #enforce;
+    #onEvent;
+    /**
+     * Builds the service around app-owned stores.
+     *
+     * @throws {TypeError} when `maxPasskeysPerUser` or `challengeTtlMs` is not a
+     * positive integer, so a miswired deploy fails at startup.
+     */
+    constructor(options) {
+        const max = options.maxPasskeysPerUser ?? DEFAULT_MAX_PASSKEYS;
+        const ttl = options.challengeTtlMs ?? DEFAULT_CHALLENGE_TTL_MS;
+        if (!Number.isInteger(max) || max <= 0) {
+            throw new TypeError("maxPasskeysPerUser must be a positive integer");
+        }
+        if (!Number.isInteger(ttl) || ttl <= 0) {
+            throw new TypeError("challengeTtlMs must be a positive integer");
+        }
+        this.#store = options.store;
+        this.#challenges = options.challenges;
+        this.#maxPasskeys = max;
+        this.#challengeTtlMs = ttl;
+        this.#rateLimiter = options.rateLimiter;
+        this.#enforce = (options.protectionMode ?? "enforce") === "enforce";
+        this.#onEvent = options.onEvent;
+    }
+    /** The most passkeys one user may register. */
+    get maxPasskeysPerUser() {
+        return this.#maxPasskeys;
+    }
+    /**
+     * Begin adding a passkey to a signed-in account. The user's existing
+     * passkeys under this relying party are excluded so an authenticator is not
+     * registered twice. Call it only after confirming it is really the account
+     * holder — a stolen session must not be able to add its own passkey.
+     *
+     * @throws {IdentityError} `passkey_limit_reached` when the user already
+     * holds the maximum number of passkeys.
+     * @throws {TypeError} when the user id is longer than 64 UTF-8 bytes or the
+     * relying party lists no origins.
+     */
+    async startRegistration(options) {
+        const { relyingParty, user } = options;
+        assertRelyingParty(relyingParty);
+        const userHandle = new TextEncoder().encode(user.id);
+        if (userHandle.byteLength === 0 ||
+            userHandle.byteLength > MAX_USER_HANDLE_BYTES) {
+            throw new TypeError("user.id must be 1 to 64 UTF-8 bytes");
+        }
+        const existing = await this.#store.listPasskeys(user.id);
+        if (existing.length >= this.#maxPasskeys) {
+            throw new IdentityError("passkey_limit_reached", `a user may register at most ${this.#maxPasskeys} passkeys`);
+        }
+        const passkeyOptions = await generateRegistrationOptions({
+            rpID: relyingParty.id,
+            rpName: relyingParty.name,
+            userID: userHandle,
+            userName: user.name,
+            userDisplayName: user.displayName ?? user.name,
+            challenge: crypto.getRandomValues(new Uint8Array(32)),
+            timeout: this.#challengeTtlMs,
+            attestationType: "none",
+            excludeCredentials: existing
+                .filter((passkey) => passkey.rpId === relyingParty.id)
+                .map((passkey) => ({
+                id: passkey.credentialId,
+                transports: passkey.transports,
+            })),
+            authenticatorSelection: {
+                residentKey: "required",
+                requireResidentKey: true,
+                userVerification: "preferred",
+            },
+            supportedAlgorithmIDs: SUPPORTED_ALGORITHMS,
+        });
+        const ceremonyId = await this.#putChallenge({
+            challenge: passkeyOptions.challenge,
+            ceremony: "registration",
+            rpId: relyingParty.id,
+            userId: user.id,
+        });
+        return { ceremonyId, options: passkeyOptions };
+    }
+    /**
+     * Verify the browser's response and store the new passkey. The challenge
+     * is spent whatever the outcome. Attestation is never relied on: a
+     * statement the authenticator volunteers must still be well-formed, but the
+     * passkey is stored as unattested and no authenticator is preferred.
+     */
+    async finishRegistration(options) {
+        const { relyingParty, userId } = options;
+        const challenge = await this.#takeChallenge(options.ceremonyId);
+        if (!challenge) {
+            return await this.#registrationFailed(userId, "expired_challenge");
+        }
+        if (challenge.ceremony !== "registration" ||
+            challenge.rpId !== relyingParty.id ||
+            challenge.userId !== userId) {
+            return await this.#registrationFailed(userId, "invalid");
+        }
+        let verified;
+        try {
+            verified = await verifyRegistrationResponse({
+                response: options.response,
+                expectedChallenge: challenge.challenge,
+                expectedOrigin: [...relyingParty.origins],
+                expectedRPID: relyingParty.id,
+                requireUserPresence: true,
+                requireUserVerification: false,
+                supportedAlgorithmIDs: SUPPORTED_ALGORITHMS,
+            });
+        }
+        catch {
+            return await this.#registrationFailed(userId, "invalid");
+        }
+        if (!verified.verified) {
+            return await this.#registrationFailed(userId, "invalid");
+        }
+        const info = verified.registrationInfo;
+        const passkey = {
+            credentialId: info.credential.id,
+            userId,
+            rpId: relyingParty.id,
+            publicKey: new Uint8Array(info.credential.publicKey),
+            signCount: info.credential.counter,
+            transports: [...(info.credential.transports ?? [])],
+            aaguid: info.aaguid,
+            multiDevice: info.credentialDeviceType === "multiDevice",
+            backedUp: info.credentialBackedUp,
+            name: normalizeName(options.name),
+            createdAt: new Date(),
+            lastUsedAt: null,
+        };
+        const added = await this.#store.addPasskey(passkey, this.#maxPasskeys);
+        if (added !== "added") {
+            return await this.#registrationFailed(userId, added);
+        }
+        await this.#emit({
+            type: "passkey.registered",
+            userId,
+            credentialId: passkey.credentialId,
+            multiDevice: passkey.multiDevice,
+        });
+        return { registered: true, passkey, userVerified: info.userVerified };
+    }
+    /**
+     * Begin a passkey sign-in. Without `userId` the browser offers every
+     * passkey it holds for this relying party (the account is learned from the
+     * response); with it, only that user's passkeys are allowed.
+     *
+     * @throws {IdentityError} `passkey_not_registered` when `userId` is given
+     * and the user has no passkey under this relying party.
+     */
+    async startAuthentication(options) {
+        const { relyingParty, userId } = options;
+        assertRelyingParty(relyingParty);
+        let allowCredentials;
+        if (userId !== undefined) {
+            const passkeys = await this.#store.listPasskeys(userId, relyingParty.id);
+            if (passkeys.length === 0) {
+                throw new IdentityError("passkey_not_registered", "the user has no passkey for this relying party");
+            }
+            allowCredentials = passkeys.map((passkey) => ({
+                id: passkey.credentialId,
+                transports: passkey.transports,
+            }));
+        }
+        const passkeyOptions = await generateAuthenticationOptions({
+            rpID: relyingParty.id,
+            challenge: crypto.getRandomValues(new Uint8Array(32)),
+            timeout: this.#challengeTtlMs,
+            userVerification: "preferred",
+            ...(allowCredentials ? { allowCredentials } : {}),
+        });
+        const ceremonyId = await this.#putChallenge({
+            challenge: passkeyOptions.challenge,
+            ceremony: "authentication",
+            rpId: relyingParty.id,
+            ...(userId !== undefined ? { userId } : {}),
+        });
+        return { ceremonyId, options: passkeyOptions };
+    }
+    /**
+     * Verify a sign-in response. The challenge is spent whatever the outcome;
+     * on success the passkey's sign count and last-used time are recorded and
+     * the rate-limit window resets. This never starts a session — apply your
+     * account checks and MFA policy to `userId` first.
+     *
+     * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
+     * `protectionMode` is `"enforce"`, and the limit is hit.
+     */
+    async finishAuthentication(options) {
+        const { relyingParty, response } = options;
+        const challenge = await this.#takeChallenge(options.ceremonyId);
+        const credentialId = credentialIdOf(response);
+        const expectedUserId = options.userId;
+        const boundUserId = challenge?.userId;
+        const throttledUserId = expectedUserId ?? boundUserId;
+        const rateKey = throttledUserId !== undefined
+            ? `passkey:verify:${throttledUserId}`
+            : options.rateLimitKey !== undefined
+                ? `passkey:verify:anonymous:${options.rateLimitKey}`
+                : undefined;
+        if (rateKey !== undefined) {
+            await this.#throttle(rateKey, throttledUserId, credentialId);
+        }
+        if (!challenge) {
+            return await this.#verifyFailed("expired_challenge", credentialId, expectedUserId);
+        }
+        if (challenge.ceremony !== "authentication" ||
+            challenge.rpId !== relyingParty.id ||
+            (expectedUserId !== undefined && boundUserId !== expectedUserId)) {
+            return await this.#verifyFailed("invalid", credentialId, throttledUserId);
+        }
+        const passkey = credentialId
+            ? await this.#store.findPasskey(credentialId)
+            : undefined;
+        if (!passkey || passkey.rpId !== relyingParty.id) {
+            return await this.#verifyFailed("unknown_passkey", credentialId, boundUserId);
+        }
+        if ((boundUserId !== undefined && passkey.userId !== boundUserId) ||
+            !userHandleMatches(response.response?.userHandle, passkey.userId)) {
+            return await this.#verifyFailed("invalid", credentialId, boundUserId ?? passkey.userId);
+        }
+        let verified;
+        try {
+            verified = await verifyAuthenticationResponse({
+                response,
+                expectedChallenge: challenge.challenge,
+                expectedOrigin: [...relyingParty.origins],
+                expectedRPID: relyingParty.id,
+                credential: {
+                    id: passkey.credentialId,
+                    publicKey: new Uint8Array(passkey.publicKey),
+                    counter: 0,
+                    transports: passkey.transports,
+                },
+                requireUserVerification: false,
+            });
+        }
+        catch {
+            return await this.#verifyFailed("invalid", credentialId, passkey.userId);
+        }
+        if (!verified.verified) {
+            return await this.#verifyFailed("invalid", credentialId, passkey.userId);
+        }
+        const info = verified.authenticationInfo;
+        if ((info.newCounter > 0 || passkey.signCount > 0) &&
+            info.newCounter <= passkey.signCount) {
+            return await this.#verifyFailed("sign_count", credentialId, passkey.userId);
+        }
+        const usedAt = new Date();
+        const recorded = await this.#store.recordUse(credentialId, {
+            previousSignCount: passkey.signCount,
+            signCount: info.newCounter,
+            backedUp: info.credentialBackedUp,
+            usedAt,
+        });
+        if (!recorded) {
+            return await this.#verifyFailed("replayed", credentialId, passkey.userId);
+        }
+        if (rateKey !== undefined)
+            await this.#resetThrottle(rateKey);
+        await this.#emit({
+            type: "passkey.verify.succeeded",
+            userId: passkey.userId,
+            credentialId,
+            userVerified: info.userVerified,
+        });
+        return {
+            valid: true,
+            userId: passkey.userId,
+            userVerified: info.userVerified,
+            passkey: {
+                ...passkey,
+                signCount: info.newCounter,
+                backedUp: info.credentialBackedUp,
+                lastUsedAt: usedAt,
+            },
+        };
+    }
+    /** The user's passkeys, oldest first; only those under `rpId` when given. */
+    listPasskeys(userId, rpId) {
+        return this.#store.listPasskeys(userId, rpId);
+    }
+    /**
+     * Rename one of the user's passkeys. The name is trimmed and capped at 64
+     * characters; an empty name becomes `"Passkey"`. Returns `false` when the
+     * passkey is not the user's.
+     */
+    async renamePasskey(userId, credentialId, name) {
+        const renamed = await this.#store.renamePasskey(userId, credentialId, normalizeName(name));
+        if (renamed) {
+            await this.#emit({ type: "passkey.renamed", userId, credentialId });
+        }
+        return renamed;
+    }
+    /**
+     * Remove one of the user's passkeys. Returns `false` when it is not theirs.
+     * Gate the route behind a fresh confirmation, and refuse it yourself when it
+     * would leave the account with no way to sign in — only the app knows
+     * which other methods are usable.
+     */
+    async removePasskey(userId, credentialId) {
+        const removed = await this.#store.removePasskey(userId, credentialId);
+        if (removed) {
+            await this.#emit({ type: "passkey.removed", userId, credentialId });
+        }
+        return removed;
+    }
+    async #putChallenge(challenge) {
+        const ceremonyId = randomToken(32);
+        await this.#challenges.put(ceremonyId, {
+            ...challenge,
+            expiresAt: Date.now() + this.#challengeTtlMs,
+        });
+        return ceremonyId;
+    }
+    async #takeChallenge(ceremonyId) {
+        if (typeof ceremonyId !== "string" || ceremonyId === "")
+            return undefined;
+        const challenge = await this.#challenges.take(ceremonyId);
+        if (!challenge || challenge.expiresAt <= Date.now())
+            return undefined;
+        return challenge;
+    }
+    async #registrationFailed(userId, reason) {
+        await this.#emit({ type: "passkey.registration.failed", userId, reason });
+        return { registered: false, reason };
+    }
+    async #verifyFailed(reason, credentialId, userId) {
+        await this.#emit({
+            type: "passkey.verify.failed",
+            reason,
+            ...(credentialId ? { credentialId } : {}),
+            ...(userId !== undefined ? { userId } : {}),
+        });
+        return { valid: false, reason };
+    }
+    #throttle(key, userId, credentialId) {
+        return enforceRateLimit({
+            rateLimiter: this.#rateLimiter,
+            key,
+            message: "too many passkey attempts",
+            enforce: this.#enforce,
+            event: {
+                type: "passkey.verify.rate_limited",
+                ...(userId !== undefined ? { userId } : {}),
+                ...(credentialId ? { credentialId } : {}),
+            },
+            emit: (event) => this.#emit(event),
+        });
+    }
+    async #resetThrottle(key) {
+        try {
+            await this.#rateLimiter?.reset(key);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] passkey rate-limit reset failed; the window stays " +
+                "filled until it lapses:", error instanceof Error ? error.message : error);
+        }
+    }
+    #emit(event) {
+        return dispatchIdentityEvent(this.#onEvent, "passkeys", event);
+    }
+}
+function assertRelyingParty(relyingParty) {
+    if (!relyingParty.id || relyingParty.origins.length === 0) {
+        throw new TypeError("relyingParty needs an id and at least one origin");
+    }
+}
+function normalizeName(name) {
+    const trimmed = (name ?? "").trim().slice(0, MAX_NAME_LENGTH);
+    return trimmed === "" ? "Passkey" : trimmed;
+}
+const MAX_CREDENTIAL_ID_LENGTH = 1366;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+function credentialIdOf(response) {
+    const id = response?.id;
+    return typeof id === "string" &&
+        id.length <= MAX_CREDENTIAL_ID_LENGTH &&
+        BASE64URL.test(id)
+        ? id
+        : "";
+}
+function userHandleMatches(userHandle, userId) {
+    if (userHandle === undefined || userHandle === "")
+        return true;
+    return userHandle === base64urlEncode(new TextEncoder().encode(userId));
+}
+/**
+ * In-memory {@link PasskeyStore} for development and tests. State is lost on
+ * restart.
+ */
+export class MemoryPasskeyStore {
+    #passkeys = new Map();
+    /** The user's passkeys, oldest first. */
+    listPasskeys(userId, rpId) {
+        return Promise.resolve([...this.#passkeys.values()]
+            .filter((passkey) => passkey.userId === userId &&
+            (rpId === undefined || passkey.rpId === rpId))
+            .map(copyPasskey));
+    }
+    /** The passkey with this credential id, or `undefined`. */
+    findPasskey(credentialId) {
+        const passkey = this.#passkeys.get(credentialId);
+        return Promise.resolve(passkey ? copyPasskey(passkey) : undefined);
+    }
+    /** Insert unless duplicate or over the per-user limit. */
+    addPasskey(passkey, limit) {
+        if (this.#passkeys.has(passkey.credentialId)) {
+            return Promise.resolve("duplicate");
+        }
+        const held = [...this.#passkeys.values()].filter((existing) => existing.userId === passkey.userId).length;
+        if (held >= limit)
+            return Promise.resolve("limit_reached");
+        this.#passkeys.set(passkey.credentialId, copyPasskey(passkey));
+        return Promise.resolve("added");
+    }
+    /** Record a use while the sign count still matches. */
+    recordUse(credentialId, use) {
+        const passkey = this.#passkeys.get(credentialId);
+        if (!passkey || passkey.signCount !== use.previousSignCount) {
+            return Promise.resolve(false);
+        }
+        passkey.signCount = use.signCount;
+        passkey.backedUp = use.backedUp;
+        passkey.lastUsedAt = use.usedAt;
+        return Promise.resolve(true);
+    }
+    /** Rename one of the user's passkeys. */
+    renamePasskey(userId, credentialId, name) {
+        const passkey = this.#passkeys.get(credentialId);
+        if (passkey?.userId !== userId)
+            return Promise.resolve(false);
+        passkey.name = name;
+        return Promise.resolve(true);
+    }
+    /** Delete one of the user's passkeys. */
+    removePasskey(userId, credentialId) {
+        if (this.#passkeys.get(credentialId)?.userId !== userId) {
+            return Promise.resolve(false);
+        }
+        this.#passkeys.delete(credentialId);
+        return Promise.resolve(true);
+    }
+}
+/**
+ * In-memory {@link PasskeyChallengeStore} for development and tests. Expired
+ * entries are dropped as new ones arrive.
+ */
+export class MemoryPasskeyChallengeStore {
+    #challenges = new Map();
+    /** Store a challenge. */
+    put(ceremonyId, challenge) {
+        const now = Date.now();
+        for (const [id, stored] of this.#challenges) {
+            if (stored.expiresAt <= now)
+                this.#challenges.delete(id);
+        }
+        this.#challenges.set(ceremonyId, { ...challenge });
+        return Promise.resolve();
+    }
+    /** Remove and return a challenge. */
+    take(ceremonyId) {
+        const challenge = this.#challenges.get(ceremonyId);
+        this.#challenges.delete(ceremonyId);
+        return Promise.resolve(challenge);
+    }
+}
+function copyPasskey(passkey) {
+    return {
+        ...passkey,
+        publicKey: new Uint8Array(passkey.publicKey),
+        transports: [...passkey.transports],
+    };
+}

package/dist/models/token.d.ts

@@ -18,6 +18,13 @@ export interface Token<Client extends ClientInterface, User, Scope extends Abstr
     client: Client;
     /** The user this token was issued for (if applicable). */
     user?: User;
+    /**
+     * Exact resource URI accepted by an opted-in client-credentials policy
+     * (RFC 8707). Persist and restore it on every token read; never derive it
+     * from a later request or the client's current configuration. Absent for
+     * legacy issuance. Resource authority still belongs to the application.
+     */
+    resource?: string;
     /** The scope granted to this token. */
     scope?: Scope | null;
     /**

package/dist/react/components/internal.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode, type Ref } from "react";
 import type { AuthFieldProps, AuthFormState } from "./use-auth-form.ts";
-import type { AuthFormClassNames, AuthFormValues, SocialProvidersProps } from "./types.ts";
+import type { PasskeyOption, AuthFormClassNames, AuthFormValues, SocialProvidersProps } from "./types.ts";
 /**
  * What every default form component returns: the shared root, `<form>` and
  * error summary, or the caller's `render` output instead, with the resolved
@@ -47,5 +47,9 @@ export declare function ErrorSummary(props: {
  */
 export declare function useFocusFirstError<V extends AuthFormValues>(form: AuthFormState<V>): void;
 export declare function SocialButtons(props: SocialProvidersProps): ReactNode;
+export declare function PasskeyButton(props: {
+    option: PasskeyOption | undefined;
+    defaultLabel: string;
+}): ReactNode;
 export declare function combineClassNames(className: string | undefined, slot: string | undefined): string | undefined;
 export declare function displayName(user: Record<string, unknown>): string;

package/dist/react/components/internal.js

@@ -69,6 +69,15 @@ export function SocialButtons(props) {
     const label = (provider) => (_jsxs(_Fragment, { children: [provider.iconSlot ? (_jsx("span", { "data-oauth2-social-icon": "", children: provider.iconSlot })) : null, _jsxs("span", { "data-oauth2-social-label": "", children: ["Continue with ", provider.name] })] }));
     return (_jsxs(_Fragment, { children: [_jsx("div", { "data-oauth2-social": "", className: classNames.socialSection, children: socialProviders.map((provider) => socialHref ? (_jsx("a", { href: socialHref(provider), "data-oauth2-social-button": provider.id, className: classNames.socialButton, children: label(provider) }, provider.id)) : (_jsx("button", { type: "button", onClick: () => onSocialSelect?.(provider), "data-oauth2-social-button": provider.id, className: classNames.socialButton, children: label(provider) }, provider.id))) }), _jsx("div", { "data-oauth2-social-divider": "", "aria-hidden": "true", className: classNames.socialDivider })] }));
 }
+export function PasskeyButton(props) {
+    const classNames = useAuthFormClassNames();
+    const { option } = props;
+    if (!option)
+        return null;
+    return (_jsx("button", { type: "button", onClick: () => {
+            void option.onSelect();
+        }, "data-oauth2-passkey-button": "", className: classNames.socialButton, children: option.label ?? props.defaultLabel }));
+}
 export function combineClassNames(className, slot) {
     return [className, slot].filter(Boolean).join(" ") || undefined;
 }

package/dist/react/components/mfa-challenge-form.d.ts

@@ -1,14 +1,15 @@
 /**
  * {@link MfaChallengeForm} — a default, accessible, unstyled second-factor
  * challenge form built on {@link useAuthForm}. Collects a one-time code and,
- * when allowed, toggles to accepting a recovery code instead. The active
- * method is forwarded to `onSubmit` so your endpoint knows how to verify it.
+ * when allowed, toggles to accepting a recovery code instead, and offers a
+ * passkey when `passkey` is supplied. The active method is forwarded to
+ * `onSubmit` so your endpoint knows how to verify it.
  *
  * @module
  */
 import type { ReactNode } from "react";
 import type { AuthFormState } from "./use-auth-form.ts";
-import type { BaseAuthFormProps } from "./types.ts";
+import type { BaseAuthFormProps, PasskeyOption } from "./types.ts";
 /** Which credential the user is submitting. */
 export type MfaChallengeMethod = "totp" | "recovery";
 /** Values collected by {@link MfaChallengeForm}. */
@@ -39,6 +40,11 @@ export interface MfaChallengeFormProps extends BaseAuthFormProps<MfaChallengeVal
     allowRecoveryCode?: boolean;
     /** Text overrides. */
     labels?: MfaChallengeLabels;
+    /**
+     * Offer a passkey as the second factor: renders a "Use a passkey" button
+     * whose `onSelect` runs the ceremony against the already-identified user.
+     */
+    passkey?: PasskeyOption;
     /**
      * Render-prop escape hatch. When provided, you own the markup and receive
      * the live {@link AuthFormState}. Toggle `method` with `setValue`.

package/dist/react/components/mfa-challenge-form.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useAuthForm } from "./use-auth-form.js";
-import { AuthFormShell, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
+import { AuthFormShell, PasskeyButton, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
 import { useAuthFormClassNames } from "./class-names.js";
 /**
  * A ready-to-use MFA challenge form. Wire `onSubmit` to your verification
@@ -21,7 +21,7 @@ import { useAuthFormClassNames } from "./class-names.js";
  * ```
  */
 export function MfaChallengeForm(props) {
-    const { onSubmit, className, allowRecoveryCode = true, labels, children, } = props;
+    const { onSubmit, className, allowRecoveryCode = true, labels, passkey, children, } = props;
     const form = useAuthForm({
         initialValues: { code: "", method: "totp" },
         onSubmit,
@@ -36,7 +36,7 @@ export function MfaChallengeForm(props) {
             code: "",
         });
     };
-    return (_jsxs(AuthFormShell, { name: "mfa-challenge", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, rootProps: { "data-oauth2-method": form.values.method }, children: [_jsx(TextField, { fieldProps: form.getFieldProps("code"), label: isRecovery
+    return (_jsxs(AuthFormShell, { name: "mfa-challenge", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, rootProps: { "data-oauth2-method": form.values.method }, aboveForm: _jsx(PasskeyButton, { option: passkey, defaultLabel: "Use a passkey" }), children: [_jsx(TextField, { fieldProps: form.getFieldProps("code"), label: isRecovery
                     ? (labels?.recoveryCode ?? "Recovery code")
                     : (labels?.code ?? "Authentication code"), autoComplete: isRecovery ? "off" : "one-time-code", required: true, error: form.errors.code }), _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Verify", submittingLabel: labels?.submitting ?? "Verifying…" }), allowRecoveryCode ? (_jsx("button", { type: "button", onClick: toggleMethod, "data-oauth2-secondary": "", "data-oauth2-toggle-recovery": "", className: classNames.secondary, children: isRecovery
                     ? (labels?.useAuthenticator ?? "Use your authenticator app")

package/dist/react/components/mod.d.ts

@@ -85,7 +85,7 @@
  */
 export { useAuthForm } from "./use-auth-form.ts";
 export type { AuthFieldProps, AuthFormState, AuthFormStatus, UseAuthFormOptions, } from "./use-auth-form.ts";
-export type { AuthFormClassNames, AuthFormErrors, AuthFormResult, AuthFormValues, AuthSubmitHandler, BaseAuthFormProps, BaseClassNames, SocialProvider, SocialProvidersProps, } from "./types.ts";
+export type { AuthFormClassNames, AuthFormErrors, AuthFormResult, AuthFormValues, AuthSubmitHandler, BaseAuthFormProps, BaseClassNames, PasskeyOption, SocialProvider, SocialProvidersProps, } from "./types.ts";
 export { AuthFormClassNamesProvider, useAuthFormClassNames, } from "./class-names.tsx";
 export type { AuthFormClassNamesProviderProps } from "./class-names.tsx";
 export { SignInForm } from "./sign-in-form.tsx";