@udibo/oauth2 0.42.0 → 0.43.0

package/dist/react/components/sign-in-form.d.ts

@@ -2,14 +2,14 @@
  * {@link SignInForm} — a default, accessible, unstyled sign-in form built on
  * {@link useAuthForm}. Collects an identifier and password (optionally a
  * "remember me" checkbox), renders "Continue with …" social buttons when
- * providers are supplied, and reports the outcome through the injected
- * `onSubmit`.
+ * providers are supplied and a passkey button when `passkey` is, and reports
+ * the outcome through the injected `onSubmit`.
  *
  * @module
  */
 import type { ReactNode } from "react";
 import type { AuthFormState } from "./use-auth-form.ts";
-import type { BaseAuthFormProps, SocialProvidersProps } from "./types.ts";
+import type { BaseAuthFormProps, PasskeyOption, SocialProvidersProps } from "./types.ts";
 /** Values collected by {@link SignInForm}. */
 export type SignInValues = {
     /** Email address or username. */
@@ -42,6 +42,14 @@ export interface SignInFormProps extends BaseAuthFormProps<SignInValues>, Social
     forgotPasswordHref?: string;
     /** Text overrides. */
     labels?: SignInLabels;
+    /**
+     * Offer passkey sign-in: renders a "Sign in with a passkey" button and marks
+     * the identifier field `autocomplete="username webauthn"`, so a browser
+     * running a conditional-mediation request (`mediation: "conditional"`)
+     * offers saved passkeys in the field's autofill. Start that request
+     * yourself on mount; the form only provides the field.
+     */
+    passkey?: PasskeyOption;
     /**
      * Render-prop escape hatch. When provided, you own the markup and receive
      * the live {@link AuthFormState}; the component still owns state and submit.

package/dist/react/components/sign-in-form.js

@@ -1,6 +1,6 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useAuthForm } from "./use-auth-form.js";
-import { AuthFormShell, SocialButtons, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
+import { AuthFormShell, PasskeyButton, SocialButtons, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
 import { useAuthFormClassNames } from "./class-names.js";
 /**
  * A ready-to-use sign-in form. Wire `onSubmit` to your auth endpoint; pass
@@ -26,7 +26,7 @@ import { useAuthFormClassNames } from "./class-names.js";
  * ```
  */
 export function SignInForm(props) {
-    const { onSubmit, className, socialProviders, onSocialSelect, socialHref, showRemember = false, forgotPasswordHref, labels, children, } = props;
+    const { onSubmit, className, socialProviders, onSocialSelect, socialHref, showRemember = false, forgotPasswordHref, labels, passkey, children, } = props;
     const form = useAuthForm({
         initialValues: { identifier: "", password: "", remember: false },
         onSubmit,
@@ -35,5 +35,5 @@ export function SignInForm(props) {
     useFocusFirstError(form);
     const classNames = useAuthFormClassNames(props.classNames);
     const rememberField = form.getFieldProps("remember");
-    return (_jsxs(AuthFormShell, { name: "sign-in", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, aboveForm: _jsx(SocialButtons, { socialProviders: socialProviders, onSocialSelect: onSocialSelect, socialHref: socialHref }), children: [_jsx(TextField, { fieldProps: form.getFieldProps("identifier"), label: labels?.identifier ?? "Email or username", autoComplete: "username", required: true, error: form.errors.identifier }), _jsx(TextField, { fieldProps: form.getFieldProps("password"), label: labels?.password ?? "Password", type: "password", autoComplete: "current-password", required: true, error: form.errors.password, children: forgotPasswordHref ? (_jsx("a", { href: forgotPasswordHref, "data-oauth2-forgot-password": "", className: classNames.hint, children: labels?.forgotPassword ?? "Forgot password?" })) : null }), showRemember ? (_jsx("div", { "data-oauth2-field": "remember", className: classNames.field, children: _jsxs("label", { htmlFor: rememberField.id, "data-oauth2-label": "", className: classNames.label, children: [_jsx("input", { ...rememberField, type: "checkbox", "data-oauth2-input": "", className: classNames.input }), labels?.remember ?? "Remember me"] }) })) : null, _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Sign in", submittingLabel: labels?.submitting ?? "Signing in…" })] }));
+    return (_jsxs(AuthFormShell, { name: "sign-in", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, aboveForm: _jsxs(_Fragment, { children: [_jsx(PasskeyButton, { option: passkey, defaultLabel: "Sign in with a passkey" }), _jsx(SocialButtons, { socialProviders: socialProviders, onSocialSelect: onSocialSelect, socialHref: socialHref })] }), children: [_jsx(TextField, { fieldProps: form.getFieldProps("identifier"), label: labels?.identifier ?? "Email or username", autoComplete: passkey ? "username webauthn" : "username", required: true, error: form.errors.identifier }), _jsx(TextField, { fieldProps: form.getFieldProps("password"), label: labels?.password ?? "Password", type: "password", autoComplete: "current-password", required: true, error: form.errors.password, children: forgotPasswordHref ? (_jsx("a", { href: forgotPasswordHref, "data-oauth2-forgot-password": "", className: classNames.hint, children: labels?.forgotPassword ?? "Forgot password?" })) : null }), showRemember ? (_jsx("div", { "data-oauth2-field": "remember", className: classNames.field, children: _jsxs("label", { htmlFor: rememberField.id, "data-oauth2-label": "", className: classNames.label, children: [_jsx("input", { ...rememberField, type: "checkbox", "data-oauth2-input": "", className: classNames.input }), labels?.remember ?? "Remember me"] }) })) : null, _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Sign in", submittingLabel: labels?.submitting ?? "Signing in…" })] }));
 }

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

@@ -70,6 +70,18 @@ export interface SocialProvidersProps {
     /** Builds the href for a provider; renders anchors instead of buttons. */
     socialHref?: (provider: SocialProvider) => string;
 }
+/**
+ * A passkey button for a sign-in or challenge form. The component never runs
+ * the WebAuthn ceremony itself: `onSelect` fetches options from your server,
+ * calls `navigator.credentials.get()` (or `startAuthentication` from
+ * `@simplewebauthn/browser`), and posts the result back.
+ */
+export interface PasskeyOption {
+    /** Runs the passkey ceremony when the button is pressed. */
+    onSelect: () => void | Promise<void>;
+    /** Button text. Defaults to the form's own wording. */
+    label?: string;
+}
 /**
  * The class hook every prebuilt component shares. Component-specific class-name
  * maps ({@link AuthFormClassNames}, `UserMenuClassNames`) extend this, so `root`

package/dist/testing/contract/mod.d.ts

@@ -10,11 +10,12 @@
  * fixtures and shipped token readers internally, so consumers and the
  * library are tested by the exact same checks.
  *
- * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
- * `OtpStore`, `RateLimitStore`, `LockoutStore` — and the client's
+ * The identity layer's storage seams — `MfaStore`, `PasskeyStore`,
+ * `PasskeyChallengeStore`, `TokenFlowStore`, `OtpStore`, `RateLimitStore`,
+ * `LockoutStore` — and the client's
  * `AuthRequestStorage` have runners of their own. Those interfaces document
  * methods that **must be atomic** (single-use recovery codes, single-use
- * links, the TOTP replay guard, the guess and failure budgets, the
+ * links and passkey challenges, the passkey cap and sign count, the TOTP replay guard, the guess and failure budgets, the
  * single-use claim of a login's `state`), and each suite checks that claim
  * with overlapping calls: a read-modify-write implementation passes every
  * sequential case and fails the concurrent one, which is the whole
@@ -50,6 +51,7 @@ export { runTokenReaderContractTests, type TokenReaderContractFixture, type Toke
 export { type AuthorizationCodeServiceContractOptions, runAuthorizationCodeServiceContractTests, } from "./authorization-code.ts";
 export { type DeviceAuthorizationServiceContractOptions, runDeviceAuthorizationServiceContractTests, } from "./device-authorization.ts";
 export { type MfaStoreContractOptions, runMfaStoreContractTests, } from "./mfa-store.ts";
+export { type PasskeyChallengeStoreContractOptions, type PasskeyStoreContractOptions, runPasskeyChallengeStoreContractTests, runPasskeyStoreContractTests, } from "./passkey-store.ts";
 export { runTokenFlowStoreContractTests, type TokenFlowStoreContractOptions, } from "./token-flow-store.ts";
 export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-store.ts";
 export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.ts";

package/dist/testing/contract/mod.js

@@ -10,11 +10,12 @@
  * fixtures and shipped token readers internally, so consumers and the
  * library are tested by the exact same checks.
  *
- * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
- * `OtpStore`, `RateLimitStore`, `LockoutStore` — and the client's
+ * The identity layer's storage seams — `MfaStore`, `PasskeyStore`,
+ * `PasskeyChallengeStore`, `TokenFlowStore`, `OtpStore`, `RateLimitStore`,
+ * `LockoutStore` — and the client's
  * `AuthRequestStorage` have runners of their own. Those interfaces document
  * methods that **must be atomic** (single-use recovery codes, single-use
- * links, the TOTP replay guard, the guess and failure budgets, the
+ * links and passkey challenges, the passkey cap and sign count, the TOTP replay guard, the guess and failure budgets, the
  * single-use claim of a login's `state`), and each suite checks that claim
  * with overlapping calls: a read-modify-write implementation passes every
  * sequential case and fails the concurrent one, which is the whole
@@ -50,6 +51,7 @@ export { runTokenReaderContractTests, } from "./token-reader.js";
 export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
 export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";
 export { runMfaStoreContractTests, } from "./mfa-store.js";
+export { runPasskeyChallengeStoreContractTests, runPasskeyStoreContractTests, } from "./passkey-store.js";
 export { runTokenFlowStoreContractTests, } from "./token-flow-store.js";
 export { runOtpStoreContractTests, } from "./otp-store.js";
 export { runRateLimitStoreContractTests, } from "./rate-limit-store.js";

package/dist/testing/contract/passkey-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Contract test suites for {@link PasskeyStore} and
+ * {@link PasskeyChallengeStore} implementations.
+ *
+ * `PasskeyService` relies on three atomic operations: `addPasskey` (credential
+ * uniqueness and the per-user cap in one step), `recordUse` (compare-and-set
+ * on the sign count), and the challenge store's `take` (read-and-delete, which
+ * makes a challenge single-use). These suites check each with concurrent
+ * calls.
+ *
+ * @example Verify database-backed stores
+ * ```ts
+ * import {
+ *   runPasskeyChallengeStoreContractTests,
+ *   runPasskeyStoreContractTests,
+ * } from "@udibo/oauth2/testing/contract";
+ * import type {
+ *   PasskeyChallengeStore,
+ *   PasskeyStore,
+ * } from "@udibo/oauth2/identity/passkeys";
+ *
+ * declare function freshPasskeyStore(): Promise<PasskeyStore>;
+ * declare function freshChallengeStore(): Promise<PasskeyChallengeStore>;
+ *
+ * runPasskeyStoreContractTests({ makeStore: freshPasskeyStore });
+ * runPasskeyChallengeStoreContractTests({ makeStore: freshChallengeStore });
+ * ```
+ *
+ * @module
+ */
+import type { PasskeyChallengeStore, PasskeyStore } from "../../identity/passkeys/service.ts";
+/** Options for {@link runPasskeyStoreContractTests}. */
+export interface PasskeyStoreContractOptions {
+    /** Returns a fresh, empty store for each test. */
+    makeStore(): Promise<PasskeyStore> | PasskeyStore;
+    /**
+     * The user the cases act on, in your application's id format; it must name
+     * a user that exists when your rows reference a users table. Defaults to
+     * `"user-1"`.
+     */
+    userId?: string;
+    /** A second, distinct user. Defaults to `"user-2"`. */
+    otherUserId?: string;
+    /** Overrides the outer `describe` name. Defaults to `"PasskeyStore contract"`. */
+    describeName?: string;
+}
+/** Options for {@link runPasskeyChallengeStoreContractTests}. */
+export interface PasskeyChallengeStoreContractOptions {
+    /** Returns a fresh, empty store for each test. */
+    makeStore(): Promise<PasskeyChallengeStore> | PasskeyChallengeStore;
+    /**
+     * Overrides the outer `describe` name. Defaults to
+     * `"PasskeyChallengeStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link PasskeyStore} contract suite. Call it from your own test
+ * file; it registers `describe` / `it` blocks.
+ */
+export declare function runPasskeyStoreContractTests(options: PasskeyStoreContractOptions): void;
+/**
+ * Runs the {@link PasskeyChallengeStore} contract suite. Call it from your own
+ * test file; it registers `describe` / `it` blocks.
+ */
+export declare function runPasskeyChallengeStoreContractTests(options: PasskeyChallengeStoreContractOptions): void;

package/dist/testing/contract/passkey-store.js

@@ -0,0 +1,196 @@
+/**
+ * Contract test suites for {@link PasskeyStore} and
+ * {@link PasskeyChallengeStore} implementations.
+ *
+ * `PasskeyService` relies on three atomic operations: `addPasskey` (credential
+ * uniqueness and the per-user cap in one step), `recordUse` (compare-and-set
+ * on the sign count), and the challenge store's `take` (read-and-delete, which
+ * makes a challenge single-use). These suites check each with concurrent
+ * calls.
+ *
+ * @example Verify database-backed stores
+ * ```ts
+ * import {
+ *   runPasskeyChallengeStoreContractTests,
+ *   runPasskeyStoreContractTests,
+ * } from "@udibo/oauth2/testing/contract";
+ * import type {
+ *   PasskeyChallengeStore,
+ *   PasskeyStore,
+ * } from "@udibo/oauth2/identity/passkeys";
+ *
+ * declare function freshPasskeyStore(): Promise<PasskeyStore>;
+ * declare function freshChallengeStore(): Promise<PasskeyChallengeStore>;
+ *
+ * runPasskeyStoreContractTests({ makeStore: freshPasskeyStore });
+ * runPasskeyChallengeStoreContractTests({ makeStore: freshChallengeStore });
+ * ```
+ *
+ * @module
+ */
+import { beforeEach, describe, expect, it } from "vitest";
+import { CONCURRENT_CALLERS, race } from "./_race.js";
+function passkey(userId, credentialId, rpId = "login.example.com") {
+    return {
+        credentialId,
+        userId,
+        rpId,
+        publicKey: new Uint8Array([1, 2, 3, 4]),
+        signCount: 0,
+        transports: ["internal", "hybrid"],
+        aaguid: "00000000-0000-0000-0000-000000000000",
+        multiDevice: true,
+        backedUp: true,
+        name: "Laptop",
+        createdAt: new Date("2026-01-01T00:00:00.000Z"),
+        lastUsedAt: null,
+    };
+}
+/**
+ * Runs the {@link PasskeyStore} contract suite. Call it from your own test
+ * file; it registers `describe` / `it` blocks.
+ */
+export function runPasskeyStoreContractTests(options) {
+    const USER = options.userId ?? "user-1";
+    const OTHER_USER = options.otherUserId ?? "user-2";
+    describe(options.describeName ?? "PasskeyStore contract", () => {
+        let store;
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        it("stores and returns a passkey with its fields intact", async () => {
+            expect(await store.addPasskey(passkey(USER, "cred-a"), 25)).toBe("added");
+            const found = await store.findPasskey("cred-a");
+            expect(found).toStrictEqual(passkey(USER, "cred-a"));
+        });
+        it("lists a user's passkeys oldest first, filtered by RP ID", async () => {
+            await store.addPasskey({
+                ...passkey(USER, "cred-a"),
+                createdAt: new Date("2026-01-01T00:00:00.000Z"),
+            }, 25);
+            await store.addPasskey({
+                ...passkey(USER, "cred-b", "other.example.com"),
+                createdAt: new Date("2026-01-02T00:00:00.000Z"),
+            }, 25);
+            await store.addPasskey(passkey(OTHER_USER, "cred-c"), 25);
+            const all = await store.listPasskeys(USER);
+            expect(all.map((stored) => stored.credentialId)).toStrictEqual([
+                "cred-a",
+                "cred-b",
+            ]);
+            const scoped = await store.listPasskeys(USER, "login.example.com");
+            expect(scoped.map((stored) => stored.credentialId)).toStrictEqual([
+                "cred-a",
+            ]);
+        });
+        it("refuses a credential id that is already registered", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 25);
+            expect(await store.addPasskey(passkey(OTHER_USER, "cred-a"), 25)).toBe("duplicate");
+            expect((await store.findPasskey("cred-a"))?.userId).toBe(USER);
+        });
+        it("treats a credential id as unique across relying parties", async () => {
+            await store.addPasskey(passkey(USER, "cred-a", "login.example.com"), 25);
+            expect(await store.addPasskey(passkey(OTHER_USER, "cred-a", "other.example.com"), 25)).toBe("duplicate");
+            expect((await store.findPasskey("cred-a"))?.rpId).toBe("login.example.com");
+        });
+        it("refuses to record a use of a removed passkey", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 25);
+            await store.removePasskey(USER, "cred-a");
+            expect(await store.recordUse("cred-a", {
+                previousSignCount: 0,
+                signCount: 1,
+                backedUp: true,
+                usedAt: new Date(),
+            })).toBe(false);
+        });
+        it("refuses a passkey over the per-user limit", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 2);
+            await store.addPasskey(passkey(USER, "cred-b"), 2);
+            expect(await store.addPasskey(passkey(USER, "cred-c"), 2)).toBe("limit_reached");
+            expect(await store.addPasskey(passkey(OTHER_USER, "cred-d"), 2)).toBe("added");
+        });
+        it("holds the per-user limit under concurrent registration", async () => {
+            const results = await race((caller) => store.addPasskey(passkey(USER, `cred-${caller}`), 3));
+            expect(results.filter((result) => result === "added")).toHaveLength(3);
+            expect(await store.listPasskeys(USER)).toHaveLength(3);
+        });
+        it("adds one passkey when the same credential races itself", async () => {
+            const results = await race(() => store.addPasskey(passkey(USER, "cred-a"), 25));
+            expect(results.filter((result) => result === "added")).toHaveLength(1);
+            expect(results.filter((result) => result === "duplicate")).toHaveLength(CONCURRENT_CALLERS - 1);
+        });
+        it("records a use only while the sign count still matches", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 25);
+            const usedAt = new Date("2026-02-01T00:00:00.000Z");
+            expect(await store.recordUse("cred-a", {
+                previousSignCount: 0,
+                signCount: 5,
+                backedUp: false,
+                usedAt,
+            })).toBe(true);
+            const stored = await store.findPasskey("cred-a");
+            expect(stored?.signCount).toBe(5);
+            expect(stored?.backedUp).toBe(false);
+            expect(stored?.lastUsedAt).toStrictEqual(usedAt);
+            expect(await store.recordUse("cred-a", {
+                previousSignCount: 0,
+                signCount: 6,
+                backedUp: false,
+                usedAt,
+            })).toBe(false);
+            expect((await store.findPasskey("cred-a"))?.signCount).toBe(5);
+        });
+        it("lets one of several concurrent uses with the same counter win", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 25);
+            const results = await race((caller) => store.recordUse("cred-a", {
+                previousSignCount: 0,
+                signCount: caller + 1,
+                backedUp: true,
+                usedAt: new Date(),
+            }));
+            expect(results.filter(Boolean)).toHaveLength(1);
+        });
+        it("renames and removes only the owner's passkey", async () => {
+            await store.addPasskey(passkey(USER, "cred-a"), 25);
+            expect(await store.renamePasskey(OTHER_USER, "cred-a", "Mine")).toBe(false);
+            expect(await store.removePasskey(OTHER_USER, "cred-a")).toBe(false);
+            expect(await store.renamePasskey(USER, "cred-a", "Phone")).toBe(true);
+            expect((await store.findPasskey("cred-a"))?.name).toBe("Phone");
+            expect(await store.removePasskey(USER, "cred-a")).toBe(true);
+            expect(await store.findPasskey("cred-a")).toBe(undefined);
+            expect(await store.removePasskey(USER, "cred-a")).toBe(false);
+        });
+    });
+}
+/**
+ * Runs the {@link PasskeyChallengeStore} contract suite. Call it from your own
+ * test file; it registers `describe` / `it` blocks.
+ */
+export function runPasskeyChallengeStoreContractTests(options) {
+    describe(options.describeName ?? "PasskeyChallengeStore contract", () => {
+        let store;
+        const challenge = {
+            challenge: "c2lnbi1tZQ",
+            ceremony: "authentication",
+            rpId: "login.example.com",
+            userId: "user-1",
+            expiresAt: Date.now() + 60_000,
+        };
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        it("returns a stored challenge once", async () => {
+            await store.put("ceremony-1", challenge);
+            expect(await store.take("ceremony-1")).toStrictEqual(challenge);
+            expect(await store.take("ceremony-1")).toBe(undefined);
+        });
+        it("returns undefined for an unknown ceremony", async () => {
+            expect(await store.take("missing")).toBe(undefined);
+        });
+        it("hands a challenge to exactly one of several concurrent takers", async () => {
+            await store.put("ceremony-1", challenge);
+            const results = await race(() => store.take("ceremony-1"));
+            expect(results.filter((result) => result !== undefined)).toHaveLength(1);
+        });
+    });
+}

package/dist/testing/mod.d.ts

@@ -35,6 +35,10 @@
  *   Identity tenant can test its own routes without running the identity
  *   service.
  *
+ * - **A software passkey authenticator.** {@link TestPasskeyAuthenticator}
+ *   answers `PasskeyService` options with real signed WebAuthn responses, so
+ *   passkey registration and sign-in can be tested without a browser.
+ *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.
  *
@@ -43,3 +47,4 @@
 export { MemoryAuthorizationCodeService, type MemoryAuthorizationCodeServiceOptions, MemoryClientService, MemoryDeviceAuthorizationService, type MemoryDeviceAuthorizationServiceOptions, MemoryTokenService, type MemoryTokenServiceOptions, MemoryUserService, type MemoryUserServiceOptions, type MemoryUserShape, } from "./services.ts";
 export { createMemoryAuthorizationServer, type CreateMemoryAuthorizationServerOptions, type MemoryAuthorizationServerClientSeed, type MemoryAuthorizationServerGrants, type MemoryAuthorizationServerHarness, type MemoryAuthorizationServerUserSeed, } from "./server.ts";
 export { createFakeTenant, type FakeTenant, type FakeTenantClient, type FakeTenantGrant, type FakeTenantLinkedAccount, type FakeTenantMachinePermission, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantOrganizationRole, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.ts";
+export { type TestPasskeyAuthenticateOptions, TestPasskeyAuthenticator, type TestPasskeyAuthenticatorOptions, type TestPasskeyCredential, } from "./passkey-authenticator.ts";

package/dist/testing/mod.js

@@ -35,6 +35,10 @@
  *   Identity tenant can test its own routes without running the identity
  *   service.
  *
+ * - **A software passkey authenticator.** {@link TestPasskeyAuthenticator}
+ *   answers `PasskeyService` options with real signed WebAuthn responses, so
+ *   passkey registration and sign-in can be tested without a browser.
+ *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.
  *
@@ -43,3 +47,4 @@
 export { MemoryAuthorizationCodeService, MemoryClientService, MemoryDeviceAuthorizationService, MemoryTokenService, MemoryUserService, } from "./services.js";
 export { createMemoryAuthorizationServer, } from "./server.js";
 export { createFakeTenant, } from "./tenant.js";
+export { TestPasskeyAuthenticator, } from "./passkey-authenticator.js";

package/dist/testing/passkey-authenticator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A software WebAuthn authenticator for tests: it answers registration and
+ * authentication options with real, signed ES256 responses, the way a browser
+ * and a platform authenticator would.
+ *
+ * @module
+ */
+import type { PasskeyAuthenticationOptions, PasskeyAuthenticationResponse, PasskeyRegistrationOptions, PasskeyRegistrationResponse } from "../identity/passkeys/service.ts";
+/** Options for {@link TestPasskeyAuthenticator}. */
+export interface TestPasskeyAuthenticatorOptions {
+    /** The origin the simulated browser reports, such as `https://login.example.com`. */
+    origin: string;
+    /** Whether the authenticator verifies the person (the UV flag). Defaults to `true`. */
+    userVerified?: boolean;
+    /**
+     * Whether passkeys are synced (backup-eligible and backed up), like a
+     * password manager's. Defaults to `true`. `false` behaves like a security key.
+     */
+    synced?: boolean;
+    /**
+     * Whether the signature counter increases on each use, like a security key.
+     * Defaults to `false`: synced passkeys report `0`.
+     */
+    countSignatures?: boolean;
+}
+/** Per-call overrides for {@link TestPasskeyAuthenticator.authenticate}. */
+export interface TestPasskeyAuthenticateOptions {
+    /** Use this credential instead of the first one the options allow. */
+    credentialId?: string;
+    /** Report this origin instead of the authenticator's, as a phishing page would. */
+    origin?: string;
+    /** Override the UV flag for this assertion. */
+    userVerified?: boolean;
+    /** Report this sign count instead of the next one. */
+    signCount?: number;
+}
+/** A credential the {@link TestPasskeyAuthenticator} holds. */
+export interface TestPasskeyCredential {
+    /** The credential id, base64url. */
+    credentialId: string;
+    /** The RP ID it was created for. */
+    rpId: string;
+    /** The user handle, base64url. */
+    userHandle: string;
+    /** The current signature counter. */
+    signCount: number;
+}
+/**
+ * A software authenticator for tests. {@link register} answers
+ * `PasskeyService.startRegistration` options and {@link authenticate} answers
+ * `startAuthentication` options with responses `PasskeyService` verifies like
+ * a browser's. Keys are P-256 (ES256) and the attestation format is `none`.
+ *
+ * @example
+ * ```ts
+ * import { TestPasskeyAuthenticator } from "@udibo/oauth2/testing";
+ * import type { PasskeyRegistrationOptions } from "@udibo/oauth2/identity/passkeys";
+ *
+ * declare const options: PasskeyRegistrationOptions;
+ * const authenticator = new TestPasskeyAuthenticator({
+ *   origin: "https://login.example.com",
+ * });
+ * const response = await authenticator.register(options);
+ * ```
+ */
+export declare class TestPasskeyAuthenticator {
+    #private;
+    /** Creates an authenticator with no credentials. */
+    constructor(options: TestPasskeyAuthenticatorOptions);
+    /** The credentials created so far. */
+    get credentials(): TestPasskeyCredential[];
+    /**
+     * Create a credential for the options' RP ID and user, and return the
+     * response `navigator.credentials.create()` would.
+     */
+    register(options: PasskeyRegistrationOptions, overrides?: {
+        origin?: string;
+    }): Promise<PasskeyRegistrationResponse>;
+    /**
+     * Sign the options' challenge with a held credential and return the
+     * response `navigator.credentials.get()` would.
+     *
+     * @throws {Error} when no held credential matches the options.
+     */
+    authenticate(options: PasskeyAuthenticationOptions, overrides?: TestPasskeyAuthenticateOptions): Promise<PasskeyAuthenticationResponse>;
+}