@udibo/oauth2 0.1.0

package/esm/identity/service.js

@@ -0,0 +1,835 @@
+/**
+ * `IdentityService` — composable functions for an app that owns its login.
+ *
+ * Orchestrates the identity primitives ({@link PasswordIdentityService},
+ * {@link TokenFlowService}, delivery hooks, {@link RevocableSessionService})
+ * over an **app-owned** {@link IdentityUserStore} into the flows a single app
+ * needs: sign-up, sign-in, password reset, email verification, and passwordless
+ * sign-in (magic links + one-time codes). These are plain
+ * methods you call from your own routes/loaders/actions — there is no opinionated
+ * mounted framework here. A thin, optional Hono route factory lives in
+ * `@udibo/oauth2/hono/identity` for apps that want the endpoints mounted.
+ *
+ * Storage-agnostic by design: every flow addresses users by opaque id and the
+ * {@link IdentityUserStore} is yours — back it with whatever database, ORM, and
+ * schema your app already uses. The library composes the flows; it never owns
+ * your tables. It stays below the turnkey-identity-service line.
+ *
+ * @module
+ */
+import { delay } from "../deps/jsr.io/@std/async/1.5.0/delay.js";
+import { buildResetUrl, buildSignInUrl, buildUnlockUrl, buildVerificationUrl, } from "./delivery.js";
+import { PasswordIdentityService, } from "./password.js";
+import { TokenPurpose, } from "./token-flow.js";
+import { assertPasswordPolicy, } from "./password-policy.js";
+import { enforceRateLimit } from "./rate-limit.js";
+import { EmailOtpService, otpRateKey } from "./otp.js";
+import { dispatchIdentityEvent, } from "./events.js";
+import { findLegacyVerifier, } from "./migration.js";
+const DEFAULT_RESET_TTL = 60 * 60 * 1000;
+const DEFAULT_VERIFY_TTL = 24 * 60 * 60 * 1000;
+const DEFAULT_UNLOCK_TTL = 60 * 60 * 1000;
+const DEFAULT_SIGNIN_LINK_TTL = 15 * 60 * 1000;
+const DEFAULT_FAILED_SIGN_IN_FLOOR_MS = 250;
+function foldEmail(email) {
+    return email.trim().toLowerCase();
+}
+/**
+ * The rate-limit key for each throttled flow, one entry per
+ * {@link IdentityRateLimiters} key. Every check and every reset derives its key
+ * here, so the window a flow fills is always the window its reset clears.
+ *
+ * Case-folding is a decision per key type. Email-addressed keys fold, so casing
+ * variants of one mailbox share a window instead of each earning a fresh send
+ * budget (`signInCode` folds inside {@link otpRateKey}, so the window it fills
+ * is the one a standalone {@link EmailOtpService} would). Opaque user ids pass
+ * through untouched — only the app knows whether they are case-sensitive.
+ * `signin:` is trimmed but not folded: an identifier
+ * may be a username or phone whose equality only the app's `findByIdentifier`
+ * defines, and folding would merge two distinct accounts (`Bob`, `bob`) into
+ * one window, letting failures against either deny sign-in to the other.
+ */
+const RATE_KEYS = {
+    signIn: (identifier) => `signin:${identifier.trim()}`,
+    passwordReset: (email) => `pwreset:${foldEmail(email)}`,
+    emailVerification: (userId) => `verifyemail:${userId}`,
+    accountUnlock: (userId) => `unlock:${userId}`,
+    signInLink: (email) => `pwless:${foldEmail(email)}`,
+    signInCode: (email) => otpRateKey(TokenPurpose.SignIn, email),
+};
+/**
+ * Composable own-auth flows. Construct once with your dependencies and call the
+ * methods from your routes; the credential form, copy, and session creation stay
+ * in your app.
+ */
+export class IdentityService {
+    #users;
+    #tokens;
+    #passwords;
+    #sessions;
+    #delivery;
+    #baseUrl;
+    #ttl;
+    #passwordPolicy;
+    #rateLimiters;
+    #otp;
+    #lockout;
+    #enforce;
+    #onEvent;
+    #legacyVerifiers;
+    #failedSignInFloorMs;
+    /** Wires the user store and optional collaborators; applies the TTL and hasher defaults. */
+    constructor(options) {
+        this.#users = options.users;
+        this.#tokens = options.tokens;
+        this.#passwords = options.passwords ?? new PasswordIdentityService();
+        this.#sessions = options.sessions;
+        this.#delivery = options.delivery;
+        this.#baseUrl = options.baseUrl;
+        this.#ttl = {
+            passwordReset: options.ttl?.passwordReset ?? DEFAULT_RESET_TTL,
+            emailVerification: options.ttl?.emailVerification ?? DEFAULT_VERIFY_TTL,
+            accountUnlock: options.ttl?.accountUnlock ?? DEFAULT_UNLOCK_TTL,
+            signInLink: options.ttl?.signInLink ?? DEFAULT_SIGNIN_LINK_TTL,
+        };
+        this.#passwordPolicy = options.passwordPolicy;
+        this.#rateLimiters = {
+            signIn: options.rateLimiters?.signIn ?? options.rateLimiter,
+            passwordReset: options.rateLimiters?.passwordReset ?? options.rateLimiter,
+            emailVerification: options.rateLimiters?.emailVerification ??
+                options.rateLimiter,
+            accountUnlock: options.rateLimiters?.accountUnlock ?? options.rateLimiter,
+            signInLink: options.rateLimiters?.signInLink ?? options.rateLimiter,
+            signInCode: options.rateLimiters?.signInCode ?? options.rateLimiter,
+        };
+        this.#otp = options.otp
+            ? new EmailOtpService({
+                store: options.otp.store,
+                digits: options.otp.digits,
+                ttlMs: options.otp.ttlMs,
+                maxAttempts: options.otp.maxAttempts,
+            })
+            : undefined;
+        this.#lockout = options.lockout;
+        this.#enforce = (options.protectionMode ?? "enforce") === "enforce";
+        this.#onEvent = options.onEvent;
+        this.#legacyVerifiers = options.legacyVerifiers?.length
+            ? options.legacyVerifiers
+            : undefined;
+        const floor = options.failedSignInFloorMs ??
+            DEFAULT_FAILED_SIGN_IN_FLOOR_MS;
+        this.#failedSignInFloorMs = Number.isFinite(floor) && floor >= 0
+            ? floor
+            : DEFAULT_FAILED_SIGN_IN_FLOOR_MS;
+    }
+    /**
+     * Create a user with a hashed password. `profile` is your app's own fields.
+     *
+     * @throws {IdentityError} `weak_password` when `password` fails the password
+     * policy — including the 8–256 character defaults that apply when
+     * {@link IdentityServiceOptions.passwordPolicy} is omitted, and a non-string
+     * password (the hash would `String`-coerce it).
+     */
+    async signUp(input) {
+        await assertPasswordPolicy(input.password, this.#passwordPolicy);
+        const credential = await this.#passwords.hash(input.password);
+        const user = await this.#users.create(input.profile, credential);
+        await this.#emit({ type: "sign_up", userId: user.id });
+        return user;
+    }
+    /**
+     * Verify credentials; returns the user, or `null` for an unknown identifier or
+     * wrong password (don't reveal which). Establishing a session is your app's
+     * job — do it on a non-null result.
+     *
+     * The throttle window is keyed on the identifier as submitted (trimmed, not
+     * case-folded), so pass the same normalized form you resolve accounts by —
+     * otherwise casing variants of one account each get their own window, and
+     * the identifiers you later hand {@link IdentityService.resetSignInThrottle}
+     * won't match the ones that filled it.
+     *
+     * Every rejection is held to
+     * {@link IdentityServiceOptions.failedSignInFloorMs} (250 ms by default),
+     * measured from entry, so an unknown identifier, a locked account, a wrong
+     * native password, and a wrong password against an imported hash all take the
+     * same time — the branch that runs a foreign KDF is not visible from
+     * outside. A success returns as soon as it is done.
+     *
+     * @throws {IdentityError} `rate_limited` (with `retryAfterMs`) when a
+     * `rateLimiter` is configured, the identifier's limit is hit, and
+     * `protectionMode` is `"enforce"`. Rate-limit rejections throw before the
+     * account lookup and are not held to the floor.
+     */
+    async signIn(input) {
+        const startedAt = performance.now();
+        const identifier = input.identifier.trim();
+        // Throttle before lookup so 429s don't reveal whether the account exists.
+        await this.#throttle("signIn", identifier, "too many sign-in attempts", {
+            type: "sign_in.rate_limited",
+            identifier,
+        });
+        const user = await this.#users.findByIdentifier(identifier);
+        if (!user) {
+            await this.#equalizeTiming(input.password);
+            await this.#emit({
+                type: "sign_in.failed",
+                identifier,
+                reason: "unknown_identifier",
+            });
+            return await this.#rejectSignIn(startedAt);
+        }
+        if (await this.#isLockedOut(user.id, identifier)) {
+            await this.#equalizeTiming(input.password);
+            return await this.#rejectSignIn(startedAt);
+        }
+        const outcome = await this.#authenticate(user.id, input.password);
+        if (outcome !== "authenticated") {
+            await this.#emit({
+                type: "sign_in.failed",
+                identifier,
+                reason: outcome,
+                userId: user.id,
+            });
+            if (outcome === "wrong_password") {
+                await this.#recordSignInFailure(user.id, identifier);
+            }
+            return await this.#rejectSignIn(startedAt);
+        }
+        await this.#resetThrottle("signIn", identifier);
+        if (this.#lockout)
+            await this.#lockout.reset(user.id);
+        await this.#emit({
+            type: "sign_in.succeeded",
+            userId: user.id,
+            identifier,
+        });
+        return user;
+    }
+    /**
+     * Clear the sign-in rate-limit window for one identifier. Call it after a
+     * flow that proves account ownership (account unlock, password reset) with
+     * each identifier the user signs in with — otherwise the failed attempts
+     * that caused the lockout still fill the window and the user's next sign-in
+     * is rejected as rate-limited despite being unlocked. No-op without a
+     * `rateLimiter`.
+     */
+    async resetSignInThrottle(identifier) {
+        await this.#resetThrottle("signIn", identifier);
+    }
+    /**
+     * Enumeration-safe: always resolves or throws identically whether or not the
+     * email maps to a user. If it does, mints a single-use reset token and calls
+     * `delivery.sendPasswordReset`. With a `rateLimiter`, requests throttle per
+     * target email, case-folded so casing variants share one window — the check
+     * runs before the lookup, so a 429 reveals nothing —
+     * and throw {@link IdentityError} `rate_limited` when exceeded; catch it and
+     * return your uniform success response. Give it a tighter threshold than
+     * sign-in via `rateLimiters.passwordReset`.
+     */
+    async requestPasswordReset(email) {
+        const tokens = this.#requireTokens("requestPasswordReset");
+        const normalized = email.trim();
+        await this.#throttle("passwordReset", normalized, "too many password reset requests", { type: "password_reset.rate_limited", email: normalized });
+        const user = await this.#users.findByEmail(normalized);
+        if (!user) {
+            await this.#emit({
+                type: "password_reset.requested",
+                email: normalized,
+            });
+            return;
+        }
+        await this.#issueAndDeliver(tokens, {
+            hook: "sendPasswordReset",
+            to: normalized,
+            subject: user.id,
+            data: { email: normalized },
+            ttlMs: this.#ttl.passwordReset,
+            requested: {
+                type: "password_reset.requested",
+                email: normalized,
+                userId: user.id,
+            },
+        });
+    }
+    /**
+     * Consume a reset token, set the new password, and (if a `sessions` service
+     * was configured) revoke the user's other sessions. 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.
+     *
+     * 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
+     * (needs a token store with `deleteBySubject` — without it they stay
+     * redeemable until they expire) and, when an `otp` service is configured, the
+     * pending sign-in code. Neither can fail the reset: a store that throws is
+     * logged and the reset still completes, since the password has already
+     * changed by then.
+     *
+     * Sessions are revoked **after** the password is changed. If that revocation
+     * throws, the reset is reported failed — a `password_reset.failed`
+     * (`session_revocation_failed`) event fires, no `password_reset.completed`
+     * fires, and the error rethrows — rather than silently returning success with
+     * the user's old sessions still live. Retry the reset to clear them.
+     *
+     * @throws {IdentityError} `weak_password` when `password` fails the password
+     * policy — including the 8–256 character defaults that apply when
+     * {@link IdentityServiceOptions.passwordPolicy} is omitted. The token is left
+     * unconsumed, so the user's link still works.
+     */
+    async resetPassword(input) {
+        const tokens = this.#requireTokens("resetPassword");
+        // Check the policy before consuming the single-use token so a weak password
+        // doesn't burn the user's reset link.
+        await assertPasswordPolicy(input.password, this.#passwordPolicy);
+        const consumed = await this.#consumeToken({
+            tokens,
+            purpose: TokenPurpose.PasswordReset,
+            token: input.token,
+            failed: () => ({
+                type: "password_reset.failed",
+                reason: "invalid_token",
+            }),
+        });
+        if (consumed.status !== "success")
+            return null;
+        const { resolved } = consumed;
+        await this.#users.setCredential(resolved.subject, await this.#passwords.hash(input.password));
+        try {
+            await this.#users.clearLegacyCredential?.(resolved.subject);
+        }
+        catch (error) {
+            // A throwing hook must not skip session revocation after the password
+            // already changed.
+            console.error("[@udibo/oauth2] resetPassword legacy-credential clear failed:", error instanceof Error ? error.message : error);
+        }
+        await this.#voidPasswordlessCredentials(tokens, resolved.subject, emailFromData(resolved.data));
+        if (this.#sessions) {
+            try {
+                await this.#sessions.revokeAllByUser(resolved.subject);
+            }
+            catch (error) {
+                await this.#emit({
+                    type: "password_reset.failed",
+                    reason: "session_revocation_failed",
+                });
+                throw error;
+            }
+        }
+        await this.#lockout?.reset(resolved.subject);
+        await this.#emit({
+            type: "password_reset.completed",
+            userId: resolved.subject,
+        });
+        return { userId: resolved.subject };
+    }
+    /**
+     * Mint + deliver an email-verification link for a user. Typically called
+     * right after sign-up, or from an authenticated "resend" action — not exposed
+     * as an unauthenticated route (you'd be emailing arbitrary user ids). With a
+     * `rateLimiter` (or a tighter `rateLimiters.emailVerification`), requests
+     * throttle per user and throw {@link IdentityError} `rate_limited` when
+     * exceeded — surface it as a friendly cooldown.
+     */
+    async requestEmailVerification(input) {
+        const tokens = this.#requireTokens("requestEmailVerification");
+        await this.#throttle("emailVerification", input.userId, "too many verification email requests", {
+            type: "email_verification.rate_limited",
+            userId: input.userId,
+            email: input.email,
+        });
+        await this.#issueAndDeliver(tokens, {
+            hook: "sendEmailVerification",
+            to: input.email,
+            subject: input.userId,
+            ttlMs: this.#ttl.emailVerification,
+            data: { email: input.email },
+            requested: {
+                type: "email_verification.requested",
+                userId: input.userId,
+                email: input.email,
+            },
+        });
+    }
+    /**
+     * Consume a verification token and mark the user's email verified.
+     *
+     * Returns a discriminated {@link VerifyEmailResult} so the UI can tell an
+     * **expired** link (offer to resend) from a generically **invalid** one — the
+     * `inspect()` distinction, surfaced through the flow. A `valid` token is
+     * consumed; a lost race (consumed between inspect and consume) reports
+     * `invalid`.
+     *
+     * The email is marked verified **before** the token is consumed, so a throw
+     * from `markEmailVerified` leaves the single-use link unspent and the user
+     * can retry with the same link (`markEmailVerified` must be idempotent).
+     *
+     * The address the token was issued for is passed to
+     * {@link IdentityUserStore.markEmailVerified} alongside the user id, so a
+     * store that predicates on both never verifies an address the link was not
+     * minted for.
+     */
+    async verifyEmail(token) {
+        const tokens = this.#requireTokens("verifyEmail");
+        const result = await this.#consumeToken({
+            tokens,
+            purpose: TokenPurpose.EmailVerification,
+            token,
+            failed: (reason) => ({ type: "email_verification.failed", reason }),
+            beforeConsume: (subject, data) => this.#users.markEmailVerified?.(subject, emailFromData(data)),
+        });
+        if (result.status !== "success")
+            return result;
+        const userId = result.resolved.subject;
+        const email = emailFromData(result.resolved.data);
+        await this.#emit({
+            type: "email_verification.completed",
+            userId,
+            email,
+        });
+        return { status: "success", userId, email };
+    }
+    /**
+     * 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`
+     * (or a tighter `rateLimiters.accountUnlock`), requests throttle per user and
+     * throw {@link IdentityError} `rate_limited` when exceeded.
+     */
+    async requestAccountUnlock(input) {
+        const tokens = this.#requireTokens("requestAccountUnlock");
+        await this.#throttle("accountUnlock", input.userId, "too many account unlock requests", {
+            type: "account_unlock.rate_limited",
+            userId: input.userId,
+            email: input.email,
+        });
+        await this.#issueAndDeliver(tokens, {
+            hook: "sendAccountUnlock",
+            to: input.email,
+            subject: input.userId,
+            ttlMs: this.#ttl.accountUnlock,
+            requested: {
+                type: "account_unlock.requested",
+                userId: input.userId,
+                email: input.email,
+            },
+        });
+    }
+    /**
+     * Consume an unlock token and clear the account's lockout state (failures
+     * and lock). The self-service unlock path: the emailed link lands here.
+     */
+    async unlockAccount(token) {
+        const tokens = this.#requireTokens("unlockAccount");
+        const result = await this.#consumeToken({
+            tokens,
+            purpose: TokenPurpose.AccountUnlock,
+            token,
+            failed: (reason) => ({ type: "account_unlock.failed", reason }),
+        });
+        if (result.status !== "success")
+            return result;
+        const userId = result.resolved.subject;
+        await this.#lockout?.reset(userId);
+        await this.#emit({ type: "account_unlock.completed", userId });
+        return { status: "success", userId };
+    }
+    async #getLegacyCredential(userId) {
+        if (!this.#legacyVerifiers)
+            return null;
+        const get = this.#users.getLegacyCredential;
+        if (!get)
+            return null;
+        return (await get.call(this.#users, userId)) ?? null;
+    }
+    async #tryLegacy(verifier, password, phc) {
+        try {
+            return await verifier.verify(password, phc);
+        }
+        catch {
+            // Never log the error object: a BYO verifier may echo the hash or the
+            // submitted password in its message. Fail closed.
+            console.error(`[@udibo/oauth2] legacy password verifier ${verifier.id} threw`);
+            return false;
+        }
+    }
+    /**
+     * Passwordless request: always resolves with the same `void` result. If the
+     * email maps to a user, mints a single-use sign-in token (invalidating any
+     * outstanding one) and calls `delivery.sendSignInLink`; an unknown email does
+     * neither, so the **return value** never reveals whether an account exists.
+     * The synchronous path is not fully timing-uniform, though — only the
+     * known-email branch awaits token minting and delivery — so send email from a
+     * background queue and apply IP-level throttling at the route to close the
+     * residual latency/side-channel oracle. Throttled per email (case-folded,
+     * key `pwless:<email>`) when a `rateLimiter` — or a tighter
+     * `rateLimiters.signInLink` — is configured; throws {@link IdentityError}
+     * `rate_limited` in enforce mode. Default link lifetime is 15 minutes.
+     */
+    async requestSignInLink(email, options) {
+        const tokens = this.#requireTokens("requestSignInLink");
+        const normalized = email.trim();
+        await this.#throttle("signInLink", normalized, "too many sign-in link requests", { type: "signin_link.rate_limited", email: normalized });
+        const user = await this.#users.findByEmail(normalized);
+        if (!user) {
+            await this.#emit({ type: "signin_link.requested", email: normalized });
+            return;
+        }
+        await this.#issueAndDeliver(tokens, {
+            hook: "sendSignInLink",
+            to: normalized,
+            subject: user.id,
+            ttlMs: options?.ttlMs ?? this.#ttl.signInLink,
+            requested: {
+                type: "signin_link.requested",
+                email: normalized,
+                userId: user.id,
+            },
+        });
+    }
+    /**
+     * Consume a sign-in link token (single-use). `success` carries the `userId`
+     * to sign in; establishing the session — and running your MFA gate first —
+     * 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.
+     */
+    async consumeSignInLink(token) {
+        const tokens = this.#requireTokens("consumeSignInLink");
+        const result = await this.#consumeToken({
+            tokens,
+            purpose: TokenPurpose.SignIn,
+            token,
+            failed: (reason) => ({ type: "signin_link.failed", reason }),
+        });
+        if (result.status !== "success")
+            return result;
+        const userId = result.resolved.subject;
+        await this.#emit({ type: "signin_link.consumed", userId });
+        return { status: "success", userId };
+    }
+    /**
+     * Passwordless request: always resolves with the same `void` result. If the
+     * email maps to a user, mints a one-time numeric code (invalidating any
+     * outstanding one) and calls `delivery.sendSignInCode`; an unknown email does
+     * neither, so the **return value** never reveals whether an account exists.
+     * As with {@link IdentityService.requestSignInLink}, only the known-email
+     * branch awaits code minting and delivery, so send from a background queue
+     * and throttle by IP at the route to close the residual timing oracle.
+     * Requires the `otp` option. Throttled per email (case-folded, key
+     * `otp:signin:<email>`, shared with {@link IdentityService.verifySignInCode})
+     * when a `rateLimiter` — or a tighter `rateLimiters.signInCode` — is
+     * configured; throws {@link IdentityError} `rate_limited` in enforce mode.
+     * That is the flow's only throttle, and it runs before the lookup, so a
+     * known email can never be rate-limited on a request an unknown one survives.
+     * A throwing `sendSignInCode` is trapped like the link hooks (see
+     * {@link DeliveryHooks}): that exact code is invalidated — never a newer one a
+     * retry may have delivered meanwhile — a `delivery.failed` event is emitted,
+     * and the call still resolves `void`, so a mailer outage is not an enumeration
+     * oracle either.
+     */
+    async requestSignInCode(email) {
+        const otp = this.#requireOtp("requestSignInCode");
+        const normalized = email.trim();
+        await this.#throttle("signInCode", normalized, "too many sign-in code requests", { type: "signin_code.rate_limited", email: normalized });
+        const user = await this.#users.findByEmail(normalized);
+        if (!user) {
+            await this.#emit({ type: "signin_code.requested", email: normalized });
+            return;
+        }
+        await otp.request({
+            email: normalized,
+            purpose: TokenPurpose.SignIn,
+            onDeliver: (code, expiresAt, codeId) => this.#deliverCode(normalized, code, user.id, expiresAt, codeId),
+        });
+        await this.#emit({
+            type: "signin_code.requested",
+            email: normalized,
+            userId: user.id,
+        });
+    }
+    /**
+     * Verify a one-time sign-in code. An unknown email performs the same hash
+     * work as a known one and reports plain `invalid` — the result is not an
+     * enumeration oracle. Wrong tries spend the code's attempt budget (`locked`
+     * once it runs out); success consumes the code (single-use), resets the
+     * flow's throttle window, and carries the `userId` to sign in — session
+     * creation and your MFA gate stay your app's job, as does treating a
+     * since-deleted/disabled user as a failed sign-in.
+     */
+    async verifySignInCode(input) {
+        const otp = this.#requireOtp("verifySignInCode");
+        const email = input.email.trim();
+        await this.#throttle("signInCode", email, "too many sign-in code attempts", { type: "signin_code.rate_limited", email });
+        const user = await this.#users.findByEmail(email);
+        const result = await otp.verify({
+            email,
+            purpose: TokenPurpose.SignIn,
+            code: input.code,
+        });
+        if (!user) {
+            await this.#emit({
+                type: "signin_code.failed",
+                email,
+                reason: "unknown_email",
+            });
+            return { status: "invalid" };
+        }
+        if (result.status !== "success") {
+            await this.#emit({
+                type: "signin_code.failed",
+                email,
+                reason: result.status,
+            });
+            return { status: "invalid" };
+        }
+        await this.#resetThrottle("signInCode", email);
+        await this.#emit({ type: "signin_code.verified", userId: user.id });
+        return { status: "success", userId: user.id };
+    }
+    #throttle(purpose, value, message, event) {
+        return enforceRateLimit({
+            rateLimiter: this.#rateLimiters[purpose],
+            key: RATE_KEYS[purpose](value),
+            message,
+            enforce: this.#enforce,
+            event,
+            emit: (e) => this.#emit(e),
+        });
+    }
+    async #resetThrottle(purpose, value) {
+        await this.#rateLimiters[purpose]?.reset(RATE_KEYS[purpose](value));
+    }
+    async #equalizeTiming(password) {
+        await this.#passwords.hash(password);
+    }
+    async #rejectSignIn(startedAt) {
+        const remaining = this.#failedSignInFloorMs -
+            (performance.now() - startedAt);
+        if (remaining > 0)
+            await delay(remaining);
+        return null;
+    }
+    async #isLockedOut(userId, identifier) {
+        if (!this.#lockout)
+            return false;
+        const status = await this.#lockout.status(userId);
+        if (!status.locked)
+            return false;
+        await this.#emit({
+            type: "sign_in.locked",
+            userId,
+            identifier,
+            enforced: this.#enforce,
+        });
+        return this.#enforce;
+    }
+    async #authenticate(userId, password) {
+        const credential = await this.#users.getCredential(userId);
+        // Native credential is authoritative: only try an imported hash when there
+        // is none, so a wrong password can't resurrect a stale one (no downgrade).
+        const legacyHash = credential ? null : await this.#getLegacyCredential(userId);
+        if (!credential && !legacyHash) {
+            await this.#equalizeTiming(password);
+            return "no_password";
+        }
+        if (credential && await this.#passwords.verify(password, credential)) {
+            return await this.#rehashCredential(userId, password, credential)
+                ? "authenticated"
+                : "wrong_password";
+        }
+        if (!legacyHash)
+            return "wrong_password";
+        const verifier = findLegacyVerifier(this.#legacyVerifiers, legacyHash);
+        if (!verifier || !await this.#tryLegacy(verifier, password, legacyHash)) {
+            await this.#equalizeTiming(password);
+            return "wrong_password";
+        }
+        return await this.#upgradeCredential(userId, password, verifier.id)
+            ? "authenticated"
+            : "wrong_password";
+    }
+    async #rehashCredential(userId, password, credential) {
+        if (!this.#users.replaceCredential ||
+            !this.#passwords.needsRehash?.(credential))
+            return true;
+        let replaced;
+        try {
+            replaced = await this.#users.replaceCredential(userId, credential, await this.#passwords.hash(password));
+        }
+        catch (error) {
+            this.#logPersistFailure("password rehash", error);
+            return true;
+        }
+        return replaced || await this.#verifyCurrentCredential(userId, password);
+    }
+    async #upgradeCredential(userId, password, verifierId) {
+        if (!this.#users.replaceCredential)
+            return true;
+        let upgraded;
+        try {
+            upgraded = await this.#users.replaceCredential(userId, undefined, await this.#passwords.hash(password));
+        }
+        catch (error) {
+            this.#logPersistFailure("upgrade-on-login", error);
+            return true;
+        }
+        if (!upgraded)
+            return await this.#verifyCurrentCredential(userId, password);
+        try {
+            await this.#users.clearLegacyCredential?.(userId);
+        }
+        catch (error) {
+            this.#logPersistFailure("upgrade-on-login", error);
+        }
+        await this.#emit({ type: "password.upgraded", userId, verifierId });
+        return true;
+    }
+    async #verifyCurrentCredential(userId, password) {
+        const current = await this.#users.getCredential(userId);
+        return current !== undefined &&
+            await this.#passwords.verify(password, current);
+    }
+    #logPersistFailure(operation, error) {
+        console.error(`[@udibo/oauth2] ${operation} persist failed:`, error instanceof Error ? error.message : error);
+    }
+    async #recordSignInFailure(userId, identifier) {
+        if (!this.#lockout)
+            return;
+        const result = await this.#lockout.recordFailure(userId);
+        if (!result.justLocked)
+            return;
+        await this.#emit({
+            type: "lockout",
+            userId,
+            identifier,
+            failures: result.failures,
+            lockedUntil: result.lockedUntil,
+            enforced: this.#enforce,
+        });
+    }
+    async #voidPasswordlessCredentials(tokens, subject, email) {
+        try {
+            await tokens.invalidate(TokenPurpose.SignIn, subject);
+            if (email)
+                await this.#otp?.invalidate(email, TokenPurpose.SignIn);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] resetPassword could not void the outstanding " +
+                "passwordless credentials; they stay usable until they expire:", error instanceof Error ? error.message : error);
+        }
+    }
+    async #issueAndDeliver(tokens, request) {
+        const { token, expiresAt } = await tokens.create({
+            purpose: DELIVERY_PURPOSES[request.hook],
+            subject: request.subject,
+            data: request.data,
+            ttlMs: request.ttlMs,
+            invalidateExisting: true,
+        });
+        await this.#deliver(request.hook, request.to, token, request.subject, expiresAt);
+        await this.#emit(request.requested);
+    }
+    async #consumeToken(input) {
+        const { tokens, purpose, token } = input;
+        const status = await tokens.inspect(purpose, token);
+        if (status.status === "expired") {
+            await this.#emit(input.failed("expired"));
+            return { status: "expired" };
+        }
+        if (status.status !== "valid") {
+            await this.#emit(input.failed("invalid"));
+            return { status: "invalid" };
+        }
+        await input.beforeConsume?.(status.subject, status.data);
+        const resolved = await tokens.consume(purpose, token);
+        if (!resolved) {
+            await this.#emit(input.failed("invalid"));
+            return { status: "invalid" };
+        }
+        return { status: "success", resolved };
+    }
+    #emit(event) {
+        return dispatchIdentityEvent(this.#onEvent, "identity", event);
+    }
+    #requireTokens(method) {
+        if (!this.#tokens) {
+            throw new Error(`IdentityService.${method}() requires a \`tokens\` option`);
+        }
+        return this.#tokens;
+    }
+    #requireOtp(method) {
+        if (!this.#otp) {
+            throw new Error(`IdentityService.${method}() requires an \`otp\` option`);
+        }
+        return this.#otp;
+    }
+    async #deliver(hook, to, token, subject, expiresAt) {
+        const delivery = this.#delivery;
+        const send = delivery?.[hook];
+        if (!send)
+            return;
+        const url = this.#baseUrl
+            ? URL_BUILDERS[hook](this.#baseUrl, token)
+            : undefined;
+        await this.#trapDeliveryFailure(hook, () => send.call(delivery, { to, url, token, subject, expiresAt }), async () => {
+            await this.#tokens?.consume(DELIVERY_PURPOSES[hook], token);
+        });
+    }
+    async #deliverCode(to, code, subject, expiresAt, codeId) {
+        const delivery = this.#delivery;
+        const send = delivery?.sendSignInCode;
+        if (!send)
+            return;
+        await this.#trapDeliveryFailure("sendSignInCode", () => send.call(delivery, { to, code, subject, expiresAt }), async () => {
+            await this.#otp?.invalidateCode(codeId);
+        });
+    }
+    async #trapDeliveryFailure(hook, send, invalidate) {
+        try {
+            await send();
+            return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const invalidated = await this.#invalidateAfterFailedDelivery(hook, invalidate, message);
+            await this.#emit({
+                type: "delivery.failed",
+                hook,
+                invalidated,
+                error: message,
+            });
+        }
+    }
+    async #invalidateAfterFailedDelivery(hook, invalidate, message) {
+        try {
+            await invalidate();
+            console.error(`[@udibo/oauth2] delivery hook ${hook} failed; minted credential invalidated:`, message);
+            return true;
+        }
+        catch (error) {
+            console.error(`[@udibo/oauth2] delivery hook ${hook} failed AND the minted ` +
+                `credential could not be invalidated — it stays live until it ` +
+                `expires. Send failure:`, message, "Invalidation failure:", error instanceof Error ? error.message : error);
+            return false;
+        }
+    }
+}
+const URL_BUILDERS = {
+    sendPasswordReset: buildResetUrl,
+    sendAccountUnlock: buildUnlockUrl,
+    sendEmailVerification: buildVerificationUrl,
+    sendSignInLink: buildSignInUrl,
+};
+const DELIVERY_PURPOSES = {
+    sendPasswordReset: TokenPurpose.PasswordReset,
+    sendAccountUnlock: TokenPurpose.AccountUnlock,
+    sendEmailVerification: TokenPurpose.EmailVerification,
+    sendSignInLink: TokenPurpose.SignIn,
+};
+function emailFromData(data) {
+    const email = data?.email;
+    return typeof email === "string" ? email : undefined;
+}