@udibo/oauth2 0.42.0 → 0.44.0

package/dist/identity/passkeys/service.js

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

package/dist/identity/service.d.ts

@@ -45,7 +45,14 @@ export interface IdentityUserStore<User extends IdentityUser> {
     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). */
+    /**
+     * Find a user by email (password-reset / sign-in-link requests).
+     *
+     * Also called when a mailed reset, sign-in or account-unlock link is
+     * redeemed: the link works only while this still resolves the address it
+     * was sent to to the same user. Normalize as at write time; a lookup that
+     * case-folds lets a link requested with different casing still redeem.
+     */
     findByEmail(email: string): Promise<User | undefined>;
     /**
      * The user's stored password credential, or `undefined`.
@@ -482,7 +489,10 @@ export declare class IdentityService<User extends IdentityUser> {
      * 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
@@ -558,7 +568,10 @@ export declare class IdentityService<User extends IdentityUser> {
      * 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.
      */
@@ -568,7 +581,9 @@ export declare class IdentityService<User extends IdentityUser> {
     }): 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.
+     * 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.
      */
     unlockAccount(token: string): Promise<UnlockAccountResult>;
     /**
@@ -598,7 +613,9 @@ export declare class IdentityService<User extends IdentityUser> {
      * 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.
      */
     consumeSignInLink(token: string): Promise<ConsumeSignInLinkResult>;
     /**