@udibo/oauth2 0.42.0 → 0.44.0

package/dist/identity/service.js

@@ -236,7 +236,6 @@ export class IdentityService {
             hook: "sendPasswordReset",
             to: normalized,
             subject: user.id,
-            data: { email: normalized },
             ttlMs: this.#ttl.passwordReset,
             requested: {
                 type: "password_reset.requested",
@@ -250,7 +249,10 @@ export class IdentityService {
      * was configured) revoke **all** of the user's sessions via
      * `revokeAllByUser`. Clears any failed-attempt lockout — the emailed token
      * proves the same account ownership the unlock flow does. Returns
-     * `{ userId }`, or `null` for an invalid/expired/used token.
+     * `{ userId }`, or `null` for an invalid/expired/used token — including one
+     * whose address no longer finds this user through
+     * {@link IdentityUserStore.findByEmail}, because the account's email moved
+     * after the link was mailed. That refusal leaves the token unspent.
      *
      * A reset is the user's "lock everyone else out" action, so the outstanding
      * passwordless credentials for the same account are voided too: sign-in links
@@ -298,6 +300,7 @@ export class IdentityService {
                 type: "password_reset.failed",
                 reason: "invalid_token",
             }),
+            addressBound: true,
         });
         if (consumed.status !== "success")
             return null;
@@ -371,7 +374,6 @@ export class IdentityService {
             to: input.email,
             subject: input.userId,
             ttlMs: this.#ttl.emailVerification,
-            data: { email: input.email },
             requested: {
                 type: "email_verification.requested",
                 userId: input.userId,
@@ -421,7 +423,10 @@ export class IdentityService {
      * Mint + deliver a single-use account-unlock link after a lockout. Call it
      * with the locked account's email (typically from your `lockout` event
      * handler — the service only knows opaque user ids). Requires `tokens` and
-     * a `delivery.sendAccountUnlock` hook to actually send. With a `rateLimiter`
+     * a `delivery.sendAccountUnlock` hook to actually send. `email` must be an
+     * address {@link IdentityUserStore.findByEmail} resolves to `userId`:
+     * {@link IdentityService.unlockAccount} refuses the link once it does not.
+     * With a `rateLimiter`
      * (or a tighter `rateLimiters.accountUnlock`), requests throttle per user and
      * throw {@link IdentityError} `rate_limited` when exceeded.
      */
@@ -446,7 +451,9 @@ export class IdentityService {
     }
     /**
      * Consume an unlock token and clear the account's lockout state (failures
-     * and lock). The self-service unlock path: the emailed link lands here.
+     * and lock). The self-service unlock path: the emailed link lands here. A
+     * link whose address no longer finds this user through
+     * {@link IdentityUserStore.findByEmail} reports `invalid` and stays unspent.
      */
     async unlockAccount(token) {
         const tokens = this.#requireTokens("unlockAccount");
@@ -455,6 +462,7 @@ export class IdentityService {
             purpose: TokenPurpose.AccountUnlock,
             token,
             failed: (reason) => ({ type: "account_unlock.failed", reason }),
+            addressBound: true,
         });
         if (result.status !== "success")
             return result;
@@ -527,7 +535,9 @@ export class IdentityService {
      * stays your app's job. So does re-resolving the user: a user deleted or
      * disabled since the link was minted must be treated as `invalid` by your
      * user store, not signed in. `expired` and `invalid` are distinguished so
-     * the UI can offer a fresh link.
+     * the UI can offer a fresh link. A link whose address no longer finds this
+     * user through {@link IdentityUserStore.findByEmail} — the account's email
+     * moved after it was mailed — reports `invalid` and stays unspent.
      */
     async consumeSignInLink(token) {
         const tokens = this.#requireTokens("consumeSignInLink");
@@ -536,6 +546,7 @@ export class IdentityService {
             purpose: TokenPurpose.SignIn,
             token,
             failed: (reason) => ({ type: "signin_link.failed", reason }),
+            addressBound: true,
         });
         if (result.status !== "success")
             return result;
@@ -783,7 +794,7 @@ export class IdentityService {
         const { token, expiresAt } = await tokens.create({
             purpose: DELIVERY_PURPOSES[request.hook],
             subject: request.subject,
-            data: request.data,
+            data: { email: request.to },
             ttlMs: request.ttlMs,
             invalidateExisting: true,
         });
@@ -797,7 +808,9 @@ export class IdentityService {
             await this.#emit(input.failed("expired"));
             return { status: "expired" };
         }
-        if (status.status !== "valid") {
+        if (status.status !== "valid" ||
+            (input.addressBound &&
+                !(await this.#stillAddressedTo(status.subject, status.data)))) {
             await this.#emit(input.failed("invalid"));
             return { status: "invalid" };
         }
@@ -809,6 +822,12 @@ export class IdentityService {
         }
         return { status: "success", resolved };
     }
+    async #stillAddressedTo(subject, data) {
+        const email = emailFromData(data);
+        if (email === undefined)
+            return true;
+        return (await this.#users.findByEmail(email))?.id === subject;
+    }
     #emit(event) {
         return dispatchIdentityEvent(this.#onEvent, "identity", event);
     }

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";

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";