@udibo/oauth2 0.1.0

package/esm/identity/service.d.ts

@@ -0,0 +1,579 @@
+/**
+ * `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 { type DeliveryHooks } from "./delivery.js";
+import type { AccountLockoutLike } from "./lockout.js";
+import { type PasswordCredential, type PasswordHasherLike } from "./password.js";
+import { type TokenFlowService } from "./token-flow.js";
+import type { RevocableSessionService } from "./session.js";
+import { type PasswordPolicy } from "./password-policy.js";
+import { type RateLimiterLike } from "./rate-limit.js";
+import { type OtpStore } from "./otp.js";
+import { type IdentityEventHook } from "./events.js";
+import { type LegacyPasswordVerifier } from "./migration.js";
+/** The minimum the identity flows require of your user record. */
+export interface IdentityUser {
+    /** Opaque user id the flows address users by; never interpreted by the library. */
+    id: string;
+}
+/**
+ * App-owned user storage the identity flows orchestrate. You implement it over
+ * your own database/ORM; the flows only ever address users by opaque id, so the
+ * backing store stays entirely yours.
+ */
+export interface IdentityUserStore<User extends IdentityUser> {
+    /**
+     * Create a user from a sign-up `profile` (your app's fields — validate them)
+     * plus the hashed password credential.
+     */
+    create(profile: Record<string, unknown>, credential: PasswordCredential): Promise<User>;
+    /** Find a user by a sign-in identifier (email/username/phone). */
+    findByIdentifier(identifier: string): Promise<User | undefined>;
+    /** Find a user by email (password-reset / re-verification requests). */
+    findByEmail(email: string): Promise<User | undefined>;
+    /**
+     * The user's stored password credential, or `undefined`.
+     *
+     * Must reflect every write committed before a
+     * {@link IdentityUserStore.replaceCredential} call returned `false` — read
+     * the primary, never a cache, a lagging replica, or a snapshot shared with
+     * the compare-and-set. The service re-reads through this to decide a sign-in
+     * that lost the compare-and-set, so a stale read lets a password retired by
+     * the winning write still sign in.
+     */
+    getCredential(userId: string): Promise<PasswordCredential | undefined>;
+    /** Replace the user's password credential (reset / change). */
+    setCredential(userId: string, credential: PasswordCredential): Promise<void>;
+    /**
+     * Atomically replace the credential only if it still equals `expected`.
+     * `undefined` expects no native credential, for an imported-password upgrade.
+     * Return `false` without writing if anything changed. Compare all stored
+     * credential fields in the same database operation as the write, never read
+     * then write. On `false` the service re-reads the credential and re-verifies
+     * the password against it, so a concurrent sign-in that rehashed first still
+     * lets this one in while a reset or change to a different password rejects
+     * it. Without this capability, sign-in succeeds but automatic rehash and
+     * imported credential upgrades are skipped; explicit password resets still
+     * work.
+     */
+    replaceCredential?(userId: string, expected: PasswordCredential | undefined, credential: PasswordCredential): Promise<boolean>;
+    /**
+     * Mark the user's email verified. Omit if you don't verify email.
+     *
+     * `email` is the address the verification token was **issued for**, when the
+     * token carried one. Your implementation must only flip the flag when the
+     * user's current email still equals it (`WHERE id = $userId AND email =
+     * $email`) — otherwise a link minted for one address verifies whatever
+     * address the account holds when the link is clicked, letting an attacker
+     * mark a victim's address verified by changing the account email after
+     * requesting the link.
+     *
+     * Must be idempotent: it runs before the single-use token is consumed, so a
+     * retried link calls it again.
+     */
+    markEmailVerified?(userId: string, email?: string): Promise<void>;
+    /**
+     * The user's imported foreign password hash (bcrypt/argon2/PBKDF2/… PHC
+     * string), or `null` once migrated or never imported. Implement it — alongside
+     * a `legacyCredential` column and {@link IdentityUserStore.clearLegacyCredential}
+     * — to enable upgrade-on-login: {@link IdentityService.signIn} verifies this
+     * hash with the configured `legacyVerifiers` only while the user has no
+     * native credential (the native credential, once set, is authoritative —
+     * a wrong password never falls back to the imported hash). Only consulted
+     * when `legacyVerifiers` is set.
+     */
+    getLegacyCredential?(userId: string): Promise<string | null>;
+    /**
+     * Drop the user's imported foreign hash once it is superseded — after a
+     * successful upgrade-on-login and after {@link IdentityService.resetPassword}.
+     * **Implement this whenever you implement {@link getLegacyCredential}:** a
+     * lingering foreign hash keeps the old imported password alive as a
+     * fallback — ignored while a native credential exists, but it would come
+     * back to life if the native credential is ever removed. Called at most
+     * once per user per supersession.
+     */
+    clearLegacyCredential?(userId: string): Promise<void>;
+}
+/**
+ * Per-flow limiter overrides for {@link IdentityServiceOptions.rateLimiters}.
+ * One key per throttled flow, each falling back to
+ * {@link IdentityServiceOptions.rateLimiter} when unset. `signInCode` covers
+ * both requesting and verifying a code — they share the `otp:signin:` key.
+ */
+export interface IdentityRateLimiters {
+    /** `signin:<identifier>` — {@link IdentityService.signIn}. */
+    signIn?: RateLimiterLike;
+    /** `pwreset:<email>` — {@link IdentityService.requestPasswordReset}. */
+    passwordReset?: RateLimiterLike;
+    /** `verifyemail:<userId>` — {@link IdentityService.requestEmailVerification}. */
+    emailVerification?: RateLimiterLike;
+    /** `unlock:<userId>` — {@link IdentityService.requestAccountUnlock}. */
+    accountUnlock?: RateLimiterLike;
+    /** `pwless:<email>` — {@link IdentityService.requestSignInLink}. */
+    signInLink?: RateLimiterLike;
+    /** `otp:signin:<email>` — request and verify of a sign-in code. */
+    signInCode?: RateLimiterLike;
+}
+/** Options for {@link IdentityService}. */
+export interface IdentityServiceOptions<User extends IdentityUser> {
+    /** App-owned user storage. */
+    users: IdentityUserStore<User>;
+    /** Token flow for verify/reset links. Required for those flows. */
+    tokens?: TokenFlowService;
+    /**
+     * Password hasher. Defaults to a new {@link PasswordIdentityService}
+     * (PBKDF2-SHA-256). Any {@link PasswordHasherLike} works, so argon2 or scrypt
+     * plug in with your own dependency. When the hasher implements
+     * `needsRehash`, {@link IdentityService.signIn} transparently re-hashes and
+     * stores a credential whose work factor has fallen behind, when the user
+     * store implements `replaceCredential`.
+     */
+    passwords?: PasswordHasherLike;
+    /**
+     * Foreign password-hash verifiers for **upgrade-on-login**, tried in order.
+     * When set, {@link IdentityService.signIn} — for a user with no native
+     * credential yet — reads the imported hash via
+     * {@link IdentityUserStore.getLegacyCredential} and verifies it with the first
+     * verifier whose `canVerify` accepts it. On a match it rehashes the password
+     * into the native format ({@link IdentityUserStore.replaceCredential}), clears the
+     * imported hash ({@link IdentityUserStore.clearLegacyCredential}), emits a
+     * `password.upgraded` event, and signs the user in. The package ships
+     * {@link pbkdf2Verifier} built-in; bcrypt/argon2/scrypt are bring-your-own via
+     * the {@link LegacyPasswordVerifier} seam (no dep-free implementation exists).
+     */
+    legacyVerifiers?: LegacyPasswordVerifier[];
+    /**
+     * Minimum wall-clock duration of a **failed** {@link IdentityService.signIn},
+     * in ms. Defaults to `250`. Every rejection — unknown identifier, locked
+     * account, no password set, wrong native password, wrong imported password —
+     * is held to the same deadline measured from the call's first statement, so
+     * the response time reveals nothing about which branch ran.
+     *
+     * Set it above the cost of your slowest configured
+     * {@link IdentityServiceOptions.legacyVerifiers} plus one password hash —
+     * that is the expensive branch (a foreign KDF the native branch never runs),
+     * and without a floor above it an unauthenticated caller can separate the
+     * accounts still carrying an imported hash from the migrated ones by response
+     * time alone. A branch that outruns the floor returns as soon as its own work
+     * finishes: whatever it spends *above* the floor stays visible, so raising a
+     * work factor means re-checking this number.
+     *
+     * `0` disables the floor entirely, which restores that signal in full — the
+     * one value that turns it off. Anything else out of range (negative, `NaN`,
+     * `Infinity`) falls back to the default rather than to no floor.
+     * Successful sign-ins are never delayed.
+     */
+    failedSignInFloorMs?: number;
+    /** Session revocation, called on a successful password reset. Optional. */
+    sessions?: RevocableSessionService;
+    /** Delivery transports for verify/reset links. Optional. */
+    delivery?: DeliveryHooks;
+    /**
+     * Base URL (origin, or origin + prefix) used to build the action links
+     * passed to delivery hooks. When omitted, hooks receive only the raw `token`.
+     */
+    baseUrl?: string;
+    /**
+     * Token lifetimes in ms. Defaults: password reset 1h, email verification 24h,
+     * account unlock 1h, sign-in link 15m. A per-call `ttlMs` — currently only
+     * {@link IdentityService.requestSignInLink} takes one — overrides the
+     * configured default for that request. One-time sign-in **codes** are not
+     * tokens; their lifetime is {@link IdentityServiceOptions.otp}'s `ttlMs`.
+     */
+    ttl?: {
+        passwordReset?: number;
+        emailVerification?: number;
+        accountUnlock?: number;
+        signInLink?: number;
+    };
+    /**
+     * One-time sign-in codes ("email me a code"). When set,
+     * {@link IdentityService.requestSignInCode} and
+     * {@link IdentityService.verifySignInCode} run an {@link EmailOtpService}
+     * over the app-owned store. Storage and code shape only — the code flow's
+     * single throttle is `rateLimiters.signInCode` (falling back to
+     * {@link rateLimiter}) under the key `otp:signin:<email>`, so a request for
+     * a known email is throttled exactly like one for an unknown email.
+     */
+    otp?: {
+        /** App-owned code storage. */
+        store: OtpStore;
+        /** Code length in digits. Defaults to `6`. */
+        digits?: number;
+        /** Code lifetime in ms. Defaults to 10 minutes. */
+        ttlMs?: number;
+        /** Wrong-attempt budget before the code locks. Defaults to `5`. */
+        maxAttempts?: number;
+    };
+    /**
+     * Password policy enforced by {@link IdentityService.signUp} and
+     * {@link IdentityService.resetPassword} before hashing — always, not only
+     * when you configure one. Omitting it leaves the
+     * {@link PasswordPolicy} defaults in force: 8–256 characters, no composition
+     * rules, no extra validators. The maximum is a DoS guard on the hash input
+     * (the hasher itself has none), so every password the app can **store** is
+     * bounded in every configuration. {@link IdentityService.signIn} is outside
+     * the policy by design — it hashes whatever the request carries, because the
+     * equal-work path that hides an unknown identifier has to run on the
+     * submitted password as-is. A violation — including a non-string password,
+     * which the hasher would otherwise `String`-coerce — throws
+     * {@link IdentityError} `weak_password`.
+     */
+    passwordPolicy?: PasswordPolicy;
+    /**
+     * Auth-flow rate limiter. When set, {@link IdentityService.signIn} throttles
+     * by identifier — an unknown and a known identifier throttle identically, so
+     * the limit can't be used to enumerate accounts — throws
+     * {@link IdentityError} `rate_limited` (with `retryAfterMs`) when exceeded,
+     * and resets the counter on a successful sign-in. Every other flow throttles
+     * on the same limiter with its own key: the email-sending requests
+     * ({@link IdentityService.requestPasswordReset} per case-folded email,
+     * {@link IdentityService.requestEmailVerification} and
+     * {@link IdentityService.requestAccountUnlock} per user) and the passwordless
+     * flows (`pwless:<email>` for sign-in links, `otp:signin:<email>` for sign-in
+     * codes — request and verify share the key; a successful verify resets it),
+     * so none of them can drive unbounded sends. IP-based limiting stays a
+     * route-layer concern: the service has no request context, which is the
+     * correct seam.
+     *
+     * This is the **default** for every flow; {@link rateLimiters} overrides it
+     * per flow when one threshold cannot serve them all.
+     */
+    rateLimiter?: RateLimiterLike;
+    /**
+     * Per-flow limiter overrides. Set one when a single threshold cannot serve
+     * every flow — a limit tuned as a sign-in floor is usually far too permissive
+     * for the four flows that make the server **send an email to a
+     * caller-supplied address** (`passwordReset`, `emailVerification`,
+     * `accountUnlock`, `signInLink`, plus `signInCode`), which typically want a
+     * handful of requests per hour rather than per 15 minutes.
+     *
+     * Each entry is a whole {@link RateLimiterLike} — build one
+     * {@link RateLimiter} per flow (they can share a {@link RateLimitStore}; the
+     * key prefixes already keep their counters disjoint) or bring your own.
+     * Entries left unset fall back to {@link rateLimiter}, so adding this option
+     * never changes an existing caller's behavior.
+     *
+     * @example Throttle the email-sending flows harder than sign-in
+     * ```ts
+     * const emailFlow = new RateLimiter({
+     *   store: sharedStore,
+     *   limit: 3,
+     *   windowMs: 60 * 60_000,
+     * });
+     * const identity = new IdentityService<AppUser>({
+     *   users: userStore,
+     *   rateLimiter: new RateLimiter({ store: sharedStore }),
+     *   rateLimiters: {
+     *     passwordReset: emailFlow,
+     *     emailVerification: emailFlow,
+     *     accountUnlock: emailFlow,
+     *     signInLink: emailFlow,
+     *     signInCode: emailFlow,
+     *   },
+     * });
+     * ```
+     */
+    rateLimiters?: IdentityRateLimiters;
+    /**
+     * Failed-attempt account lockout. When set, {@link IdentityService.signIn}
+     * records consecutive wrong-password failures per account and — once the
+     * threshold locks the account — rejects further attempts with the same
+     * uniform, timing-equalized `null` an unknown identifier gets (no lockout
+     * oracle). A successful sign-in resets the count;
+     * {@link IdentityService.unlockAccount} clears a lock via an emailed
+     * single-use token.
+     */
+    lockout?: AccountLockoutLike;
+    /**
+     * How the attack protections respond when tripped. `"enforce"` (the safe
+     * default) blocks: rate limiting throws and a locked account can't sign in.
+     * `"log-only"` never blocks — events still fire (with `enforced: false`) so
+     * adopters can observe thresholds before turning enforcement on.
+     */
+    protectionMode?: "enforce" | "log-only";
+    /**
+     * Called with an {@link IdentityEvent} after each flow outcome — the seam for
+     * audit capture. Awaited, but isolated: a rejection is logged and swallowed
+     * so observability can never break the auth flow. Optional; no-op when
+     * absent.
+     */
+    onEvent?: IdentityEventHook;
+}
+/**
+ * Outcome of {@link IdentityService.verifyEmail}. `success` carries the verified
+ * user; `expired` and `invalid` are distinguished so the UI can offer to resend
+ * an expired link rather than showing one generic error.
+ */
+export type VerifyEmailResult = {
+    status: "success";
+    userId: string;
+    email?: string;
+} | {
+    status: "expired";
+} | {
+    status: "invalid";
+};
+/**
+ * Outcome of {@link IdentityService.consumeSignInLink}. `expired` and
+ * `invalid` are distinguished so the UI can offer a fresh link for an expired
+ * one. No session is created — do that in your app on `success`.
+ */
+export type ConsumeSignInLinkResult = {
+    status: "success";
+    userId: string;
+} | {
+    status: "expired";
+} | {
+    status: "invalid";
+};
+/**
+ * Outcome of {@link IdentityService.verifySignInCode}. Deliberately only
+ * `success` vs `invalid`: a known email whose code expired or hit its attempt
+ * cap collapses to `invalid`, identical to an unknown email, so the caller-
+ * facing result is not an account-enumeration oracle. The precise reason
+ * (`expired`/`locked`/`unknown_email`) is available server-side via the
+ * `signin_code.failed` event.
+ */
+export type VerifySignInCodeResult = {
+    status: "success";
+    userId: string;
+} | {
+    status: "invalid";
+};
+/**
+ * Outcome of {@link IdentityService.unlockAccount}. `expired` and `invalid`
+ * are distinguished so the UI can offer a fresh link for an expired one.
+ */
+export type UnlockAccountResult = {
+    status: "success";
+    userId: string;
+} | {
+    status: "expired";
+} | {
+    status: "invalid";
+};
+/**
+ * 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 declare class IdentityService<User extends IdentityUser> {
+    #private;
+    /** Wires the user store and optional collaborators; applies the TTL and hasher defaults. */
+    constructor(options: IdentityServiceOptions<User>);
+    /**
+     * 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).
+     */
+    signUp(input: {
+        password: string;
+        profile: Record<string, unknown>;
+    }): Promise<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.
+     */
+    signIn(input: {
+        identifier: string;
+        password: string;
+    }): Promise<User | null>;
+    /**
+     * 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`.
+     */
+    resetSignInThrottle(identifier: string): Promise<void>;
+    /**
+     * 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`.
+     */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * 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.
+     */
+    resetPassword(input: {
+        token: string;
+        password: string;
+    }): Promise<{
+        userId: string;
+    } | null>;
+    /**
+     * 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.
+     */
+    requestEmailVerification(input: {
+        userId: string;
+        email: string;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    verifyEmail(token: string): Promise<VerifyEmailResult>;
+    /**
+     * 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.
+     */
+    requestAccountUnlock(input: {
+        userId: string;
+        email: string;
+    }): Promise<void>;
+    /**
+     * Consume an unlock token and clear the account's lockout state (failures
+     * and lock). The self-service unlock path: the emailed link lands here.
+     */
+    unlockAccount(token: string): Promise<UnlockAccountResult>;
+    /**
+     * 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.
+     */
+    requestSignInLink(email: string, options?: {
+        ttlMs?: number;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    consumeSignInLink(token: string): Promise<ConsumeSignInLinkResult>;
+    /**
+     * 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.
+     */
+    requestSignInCode(email: string): Promise<void>;
+    /**
+     * 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.
+     */
+    verifySignInCode(input: {
+        email: string;
+        code: string;
+    }): Promise<VerifySignInCodeResult>;
+}