@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/core/auth/api.js

@@ -1,4 +1,15 @@
+import { checkPermission } from "./authorize.js";
+import { generateToken, hashPassword, verifyPassword } from "./passwords.js";
+import { createMemoryRateLimit } from "./throttle.js";
+import { authFailureMessage } from "./tokens.js";
+import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpUri, verifyTotp } from "./totp.js";
+import { createHash } from "node:crypto";
 //#region src/core/auth/api.ts
+/** The user agent, off whatever carried the request. Nothing else here reads headers, so it is done once. */
+var clientOf = (carrier) => {
+	const userAgent = carrier?.headers["user-agent"];
+	return typeof userAgent === "string" && userAgent ? { userAgent } : void 0;
+};
 var refuse = (status, error, reason) => ({
 	ok: false,
 	status,
@@ -19,6 +30,56 @@ var asText = (value) => {
 };
 var asString = (value) => asText(value).trim();
 /**
+* The destination a caller named, for a mail to carry — or nothing at all.
+*
+* Carried, not judged: the kernel has no redirect policy, and the link it ends up in is composed by the deployment,
+* which vets it there (`createRedirectPolicy`). Absent rather than empty when there is none, so a mail template never
+* has to know that `''` means "nowhere".
+*/
+var destinationOf = (value) => {
+	const redirect = asString(value);
+	return redirect ? { redirect } : {};
+};
+var now = () => Math.floor(Date.now() / 1e3);
+var HOUR = 3600;
+/**
+* How long the things this server mails or hands out stay good for. Constants rather than configuration: each is a
+* security answer with one sensible value, and an option here is a question every deployment has to work out an
+* answer to before it can start.
+*/
+var LIFETIME = {
+	/** A code from an email. Long enough to go and find it, short enough that a stolen one is worthless. */
+	signInCode: 600,
+	/** A reset link IS a password, and it sits in an inbox, a mail archive, a forwarded ticket. */
+	resetLink: HOUR,
+	/** Confirming an address is not a credential in the same way, and people read their mail tomorrow. */
+	confirmLink: 24 * HOUR,
+	/** A borrowed session — see `admin.impersonate`. Short, and it cannot renew. */
+	impersonation: 900
+};
+var STATUSES = [
+	"active",
+	"inactive",
+	"blocked"
+];
+/**
+* Why an account may not hold a session, when it may not.
+*
+* `active` answers whether it may sign in at all; `verified` answers whether its owner can do anything about that.
+* A deployment where confirming an address is what makes an account active — Plitzi is one — refuses both through
+* the same flag, so a screen told only `inactive` has to tell somebody whose address has simply never answered that
+* their password was wrong. It was, in fact, right.
+*/
+var deniedReason = (account) => account && !account.verified ? "unverified" : "inactive";
+/** An account as it may be shown. Never the password hash, and never the credentials — not even to an admin. */
+var profileOf = (account) => ({
+	id: account.id,
+	username: account.username,
+	email: account.email,
+	active: account.active,
+	verified: account.verified
+});
+/**
 * The HTTP surface of authentication, as functions rather than routes.
 *
 * Nothing here knows about Express, or about this server's own pipeline: a handler is given what the request
@@ -27,7 +88,87 @@ var asString = (value) => asText(value).trim();
 * form without either owning it.
 */
 var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
-	const { verifyPassword, hashPassword, generateToken, verifyOnSignup = false } = config;
+	const { verifyPassword: verifyPassword$1 = verifyPassword, hashPassword: hashPassword$1 = hashPassword, generateToken: generateToken$1 = generateToken, verifyOnSignup = false, adminPermission = "userManage", impersonationPermission, password: policy = {}, rateLimit = createMemoryRateLimit(), onMailError, onEvent, mfaIssuer, csrf } = config;
+	/** Never awaited, never able to throw: a logging outage must not become an authentication outage. */
+	const record = (event) => {
+		if (!onEvent) return;
+		try {
+			onEvent({
+				...event,
+				at: Math.floor(Date.now() / 1e3)
+			});
+		} catch (error) {
+			console.error("[auth] security event handler threw:", error);
+		}
+	};
+	/**
+	* A single-use link token that stops working.
+	*
+	* The deadline is carried **inside the token**, after a `~`, and that is what makes this cost nothing: no column,
+	* no adapter argument, and nothing a deployment with its own store has to remember to enforce — which is the
+	* failure mode of putting the check in the adapters, where forgetting it is silent and looks like everything
+	* working. It is not a secret and does not need to be: the token is compared against the stored copy, so editing
+	* the deadline just produces a string that matches no row.
+	*
+	* A token issued before this existed has no `~`, reads as no deadline, and keeps working — the links already in
+	* people's inboxes when a deployment upgrades.
+	*/
+	const mintLink = (random, lifetime) => `${random}~${now() + lifetime}`;
+	const linkExpired = (token) => {
+		const deadline = Number(token.slice(token.lastIndexOf("~") + 1));
+		return Number.isFinite(deadline) && token.includes("~") && deadline < now();
+	};
+	/** Recovery codes are high-entropy, so a fast digest is right — scrypt ten times per sign-in would not be. */
+	const digestRecoveryCode = (code) => createHash("sha256").update(normalizeRecoveryCode(code)).digest("hex");
+	/**
+	* Sends, and never fails the flow if it cannot.
+	*
+	* Every one of these goes out AFTER something has already been committed — an account created, an address
+	* changed, a reset token stored. Letting the mail provider decide whether that request succeeded turns an
+	* outage at Brevo into a 500 on a change that did happen, which is the worst of both: the caller is told it
+	* failed and retries against the new state. Reported instead, and the person can ask for another.
+	*/
+	const deliver = async (message) => {
+		try {
+			await adapters.sendMail?.(message);
+		} catch (error) {
+			(onMailError ?? ((cause) => console.error("[auth] could not send mail:", cause)))(error, {
+				to: message.to,
+				template: message.template
+			});
+		}
+	};
+	/**
+	* Checked before the password is, so a throttled attempt costs no hash — which is the difference between a rate
+	* limit and a slightly slower way to be brute-forced.
+	*/
+	/** Whatever was counted against this key is forgiven: the attempt it was guarding against succeeded. */
+	const throttleSucceeded = (attempt) => {
+		Promise.resolve(rateLimit({
+			...attempt,
+			succeeded: true
+		})).catch(() => void 0);
+	};
+	const throttled = async (attempt) => {
+		const verdict = await rateLimit(attempt);
+		if (typeof verdict === "boolean" ? verdict : verdict.allowed) return;
+		const retryAfter = typeof verdict === "boolean" ? void 0 : verdict.retryAfter;
+		return {
+			ok: false,
+			status: 429,
+			body: {
+				error: "Too many attempts",
+				...retryAfter !== void 0 ? { retryAfter } : {}
+			}
+		};
+	};
+	/** The one place a new password is judged, so signing up, resetting and changing cannot disagree about it. */
+	const rejectPassword = async (value, context = {}) => {
+		const minLength = policy.minLength ?? 8;
+		if (value.length < minLength) return refuse(400, `The password must be at least ${minLength} characters`);
+		const reason = await policy.validate?.(value, context);
+		return reason ? refuse(400, reason) : void 0;
+	};
 	/**
 	* What this deployment offers, decided by what it supplied and nothing else.
 	*
@@ -37,30 +178,64 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 	* that answers 404 for no reason anyone can see. Declining a flow is now one act: do not implement it.
 	*/
 	const capabilities = {
-		passwordLogin: !!adapters.findByUsername && !!verifyPassword,
+		passwordLogin: !!adapters.findByUsername,
 		refresh: !!adapters.findByRefreshToken,
-		signup: !!adapters.createAccount && !!hashPassword,
-		passwordReset: !!adapters.findByEmail && !!adapters.setResetToken && !!hashPassword,
-		emailVerification: !!adapters.findByValidationToken && !!adapters.markVerified,
-		exchange: !!adapters.exchangeCredential
+		signup: !!adapters.createAccount,
+		passwordReset: !!adapters.findByEmail && !!adapters.setResetToken,
+		emailVerification: !!adapters.findByValidationToken && !!adapters.setVerified,
+		exchange: !!adapters.exchangeCredential,
+		mfa: !!adapters.loadMfa && !!adapters.saveMfa,
+		passwordless: !!adapters.saveOtp && !!adapters.findOtp && !!adapters.findByEmail && !!adapters.sendMail,
+		profile: !!adapters.updateAccount,
+		passwordChange: !!adapters.findById && !!adapters.setPassword,
+		accountDeletion: !!adapters.deleteAccount,
+		sessionList: !!adapters.listSessions,
+		administration: !!adapters.listAccounts && !!adapters.findById,
+		/** Changing an address by confirming it, rather than on the spot. Needs somewhere to park it and a way to write. */
+		emailChange: !!adapters.setPendingEmail && !!adapters.findByPendingEmail && !!adapters.clearPendingEmail && !!adapters.updateAccount && !!adapters.sendMail,
+		/** Off unless the deployment named the capability it takes — see `impersonationPermission`. */
+		impersonation: !!impersonationPermission && !!adapters.findById
+	};
+	/**
+	* An administrator acting on somebody else.
+	*
+	* `subject` refuses the case where that somebody is themselves. Banning or deleting your own account through the
+	* admin surface is how a deployment loses its last administrator, and it is never what was meant: closing your
+	* own account is the self-service flow, which asks for a password precisely because it is irreversible.
+	*/
+	const requireAdmin = (actor, subject) => {
+		const check = checkPermission(actor, adminPermission);
+		if (!check.ok) return refuse(check.status, check.error, check.status === 401 ? "missing" : void 0);
+		if (subject !== void 0 && subject === actor?.id) return refuse(400, "Use the self-service route to act on your own account");
 	};
-	const issue = async (userId) => {
+	/**
+	* A session for this account. `options` is only for the one that is not an ordinary sign-in: a borrowed session
+	* carries who borrowed it and cannot renew itself, so it dies at its deadline instead of quietly living for a
+	* month behind a refresh token.
+	*/
+	const issue = async (userId, context, options = {}) => {
+		const { actingAs, ttlSeconds, renewable = true } = options;
 		const now = Math.floor(Date.now() / 1e3);
 		const session = {
-			token: tokens.generateUserToken(userId),
-			expiresAt: now + tokens.lifetimes.access,
-			refreshToken: tokens.generateRefreshToken(userId),
-			refreshExpiresAt: now + tokens.lifetimes.refresh
+			token: tokens.generateUserToken(userId, {
+				actingAs,
+				ttlSeconds
+			}),
+			expiresAt: now + (ttlSeconds ?? tokens.lifetimes.access),
+			...renewable ? {
+				refreshToken: tokens.generateRefreshToken(userId),
+				refreshExpiresAt: now + tokens.lifetimes.refresh
+			} : {}
 		};
-		await adapters.saveSession(userId, session);
+		await adapters.saveSession(userId, session, context);
 		return session;
 	};
 	/**
 	* The body a grant answers with. `details` is the same object the session endpoint returns, deliberately: it makes
 	* a grant an identity, so a client that has just signed in or renewed knows who it is without a second request.
 	*/
-	const grantBody = async (account, session) => {
-		const access = await adapters.loadAccess(account.id);
+	const grantBody = async (account, session, loaded) => {
+		const access = loaded ?? await adapters.loadAccess(account.id);
 		const now = Math.floor(Date.now() / 1e3);
 		return {
 			success: true,
@@ -80,6 +255,57 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			refresh_expire_at: session.refreshExpiresAt
 		};
 	};
+	/**
+	* Turning a credential from an external identity provider into a session here, answered in accounts.
+	*
+	* `offered` separates "this deployment does not do exchanges" from "that credential was refused" — a 404 and a
+	* 401 respectively, and a caller that cannot tell them apart reports a misconfiguration as a bad password.
+	*/
+	const exchangeAccount = async (provider, token, carrier) => {
+		if (!capabilities.exchange) return {
+			ok: false,
+			offered: false,
+			status: 404,
+			error: "Not found"
+		};
+		if (!provider || !token) return {
+			ok: false,
+			offered: true,
+			status: 400,
+			error: "A provider and a token are required"
+		};
+		if (await throttled({
+			action: "exchange",
+			key: provider,
+			carrier
+		})) return {
+			ok: false,
+			offered: true,
+			status: 429,
+			error: "Too many attempts"
+		};
+		const result = await adapters.exchangeCredential?.(provider, token, carrier);
+		if (!result) return {
+			ok: false,
+			offered: true,
+			status: 401,
+			error: "Token Invalid",
+			reason: "revoked"
+		};
+		if ("error" in result) return {
+			ok: false,
+			offered: true,
+			status: result.status ?? 400,
+			error: result.error,
+			reason: "revoked"
+		};
+		return {
+			ok: true,
+			account: result,
+			access: await adapters.loadAccess(result.id),
+			session: await issue(result.id, { client: clientOf(carrier) })
+		};
+	};
 	return {
 		capabilities,
 		/** What a client reads to know which of the flows below actually exist here. */
@@ -105,7 +331,8 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 						email: actor.email,
 						verified: actor.verified,
 						roles: actor.roles,
-						permissions: actor.permissions
+						permissions: actor.permissions,
+						...actor.impersonatedBy === void 0 ? {} : { impersonatedBy: actor.impersonatedBy }
 					},
 					access_token: actor.token,
 					expire_in: Math.max(0, actor.expiresAt - now),
@@ -113,29 +340,373 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				}
 			};
 		},
-		login: async (credentials) => {
+		login: async (credentials, carrier) => {
 			if (!capabilities.passwordLogin) return NOT_OFFERED;
 			const username = asString(credentials.username);
 			const password = asText(credentials.password);
 			if (!username || !password) return refuse(400, "A username and a password are required");
-			const account = await adapters.findByUsername?.(username);
+			const limited = await throttled({
+				action: "login",
+				key: username,
+				carrier
+			});
+			if (limited) return limited;
+			/**
+			* The username, or the email — in that order.
+			*
+			* Every sign-in screen worth using offers both, because the one thing a person reliably remembers about an
+			* account is the address it was created with. Username first so an account whose name happens to be somebody
+			* else's address cannot shadow the owner of that address; the email lookup only runs when the first misses,
+			* so this costs a second query on a failed sign-in and nothing on a successful one.
+			*
+			* `findByEmail` is optional like everything else here: a deployment that supplies no email store keeps exactly
+			* the behaviour it had.
+			*/
+			const account = await adapters.findByUsername?.(username) ?? (username.includes("@") ? await adapters.findByEmail?.(username) : void 0);
 			if (!account) return refuse(401, "Invalid credentials");
-			if (!account.active) return refuse(401, "Account is not active");
-			if (!account.passwordHash || !await verifyPassword?.(password, account.passwordHash)) return refuse(401, "Invalid credentials");
-			const session = await issue(account.id);
+			if (!account.passwordHash || !await verifyPassword$1(password, account.passwordHash)) {
+				record({
+					type: "login.failed",
+					userId: account.id,
+					carrier,
+					detail: { username }
+				});
+				return refuse(401, "Invalid credentials");
+			}
+			/**
+			* Whether this account may hold a session — asked AFTER the password, and that order is the point.
+			*
+			* Anything said about an account before its password is checked is said to anybody who types an address. The
+			* other way round, "that address has not been confirmed" once cost nothing to establish: two attempts with a
+			* made-up password told a stranger which of a list of addresses have accounts here and which do not. It is
+			* only a refusal somebody has earned the right to understand once they have proved the account is theirs.
+			*/
+			if (!account.active) {
+				const reason = deniedReason(account);
+				return refuse(401, authFailureMessage[reason], reason);
+			}
+			if ((capabilities.mfa ? await adapters.loadMfa?.(account.id) : void 0)?.confirmedAt) {
+				record({
+					type: "login.mfa-required",
+					userId: account.id,
+					carrier
+				});
+				return {
+					ok: true,
+					body: {
+						success: false,
+						mfaRequired: true,
+						mfaToken: tokens.generateMfaChallenge(account.id)
+					}
+				};
+			}
+			const session = await issue(account.id, { client: clientOf(carrier) });
+			throttleSucceeded({
+				action: "login",
+				key: username,
+				carrier
+			});
+			record({
+				type: "login",
+				userId: account.id,
+				carrier
+			});
 			return {
 				ok: true,
 				body: await grantBody(account, session),
 				session
 			};
 		},
-		refresh: async (refreshToken) => {
+		/**
+		* The second half of a sign-in that owed a factor.
+		*
+		* Takes a TOTP code or a recovery code. A recovery code is SPENT — removed from the stored list — because one
+		* that survives being used is a password with extra steps.
+		*/
+		completeMfa: async (mfaToken, code, carrier) => {
+			if (!capabilities.mfa) return NOT_OFFERED;
+			const verified = tokens.verifyMfaChallenge(mfaToken);
+			if (!verified.ok) return refuse(401, authFailureMessage[verified.reason], verified.reason);
+			const userId = Number(verified.payload.sub);
+			const limited = await throttled({
+				action: "mfa",
+				key: String(userId),
+				carrier
+			});
+			if (limited) return limited;
+			const account = await adapters.findById?.(userId);
+			const mfa = await adapters.loadMfa?.(userId);
+			if (!account || !mfa?.confirmedAt) return refuse(401, "Invalid credentials");
+			if (!account.active) {
+				const reason = deniedReason(account);
+				return refuse(401, authFailureMessage[reason], reason);
+			}
+			const stored = mfa.recoveryCodes ?? [];
+			const supplied = digestRecoveryCode(code);
+			const usedRecovery = stored.includes(supplied);
+			if (!usedRecovery && !verifyTotp(mfa.secret, code)) {
+				record({
+					type: "mfa.failed",
+					userId,
+					carrier
+				});
+				return refuse(401, "Invalid code");
+			}
+			if (usedRecovery) await adapters.saveMfa?.(userId, {
+				...mfa,
+				recoveryCodes: stored.filter((entry) => entry !== supplied)
+			});
+			const session = await issue(userId, { client: clientOf(carrier) });
+			throttleSucceeded({
+				action: "mfa",
+				key: String(userId),
+				carrier
+			});
+			record({
+				type: "login",
+				userId,
+				carrier,
+				detail: { recoveryCode: usedRecovery }
+			});
+			return {
+				ok: true,
+				body: {
+					...await grantBody(account, session),
+					...usedRecovery ? { recoveryCodeUsed: true } : {}
+				},
+				session
+			};
+		},
+		/**
+		* Signing in with a code sent to an email address, and no password at all.
+		*
+		* Two decisions worth stating. **The request answers the same whether the address exists or not** — anything
+		* else turns this endpoint into a way to ask which addresses have accounts. And **it never creates an
+		* account**: a sign-in flow that silently registers whoever asks is a different feature, and one a deployment
+		* should choose deliberately rather than inherit.
+		*/
+		passwordless: {
+			request: async (email, carrier) => {
+				if (!capabilities.passwordless) return NOT_OFFERED;
+				const address = asString(email).toLowerCase();
+				if (!address) return refuse(400, "An email is required");
+				const limited = await throttled({
+					action: "passwordless",
+					key: address,
+					carrier
+				});
+				if (limited) return limited;
+				const account = await adapters.findByEmail?.(address);
+				if (account?.active) {
+					/**
+					* Six characters somebody reads out of an email and types, not a link token — `generateToken` mints 128
+					* random bits, which is right for something clicked and hostile for something retyped. Two different jobs
+					* that were sharing one function, and the deployment that fixed the code for typing quietly weakened
+					* every reset link it mailed.
+					*/
+					const code = randomCode(6);
+					await adapters.saveOtp?.({
+						purpose: "signin",
+						identifier: address,
+						codeHash: digestRecoveryCode(code),
+						expiresAt: now() + LIFETIME.signInCode,
+						userId: account.id
+					});
+					await deliver({
+						to: account.email,
+						template: "signin-code",
+						data: {
+							username: account.username,
+							code
+						}
+					});
+				}
+				return {
+					ok: true,
+					body: { message: "If that address has an account, a sign-in link is on its way" }
+				};
+			},
+			complete: async (email, code, carrier) => {
+				if (!capabilities.passwordless) return NOT_OFFERED;
+				const address = asString(email).toLowerCase();
+				if (!address || !code) return refuse(400, "An email and a code are required");
+				const limited = await throttled({
+					action: "passwordless",
+					key: address,
+					carrier
+				});
+				if (limited) return limited;
+				const stored = await adapters.findOtp?.("signin", address);
+				if (!stored || stored.expiresAt < now() || stored.codeHash !== digestRecoveryCode(code)) {
+					record({
+						type: "login.failed",
+						carrier,
+						detail: {
+							method: "passwordless",
+							email: address
+						}
+					});
+					return refuse(401, "Invalid or expired code");
+				}
+				await adapters.consumeOtp?.(stored.id);
+				const account = stored.userId === void 0 ? void 0 : await adapters.findById?.(stored.userId);
+				if (!account?.active) {
+					const reason = deniedReason(account);
+					return refuse(401, authFailureMessage[reason], reason);
+				}
+				if ((capabilities.mfa ? await adapters.loadMfa?.(account.id) : void 0)?.confirmedAt) {
+					record({
+						type: "login.mfa-required",
+						userId: account.id,
+						carrier
+					});
+					return {
+						ok: true,
+						body: {
+							success: false,
+							mfaRequired: true,
+							mfaToken: tokens.generateMfaChallenge(account.id)
+						}
+					};
+				}
+				const session = await issue(account.id, { client: clientOf(carrier) });
+				throttleSucceeded({
+					action: "passwordless",
+					key: address,
+					carrier
+				});
+				record({
+					type: "login",
+					userId: account.id,
+					carrier,
+					detail: { method: "passwordless" }
+				});
+				return {
+					ok: true,
+					body: await grantBody(account, session),
+					session
+				};
+			}
+		},
+		/**
+		* Everything about this account's second factor. `begin` hands back a secret and the URI an app scans; nothing
+		* is in force until `confirm` proves a code from it.
+		*/
+		mfa: {
+			status: async (actor) => {
+				if (!capabilities.mfa) return NOT_OFFERED;
+				if (!actor) return refuse(401, "Not authenticated", "missing");
+				const mfa = await adapters.loadMfa?.(actor.id);
+				return {
+					ok: true,
+					body: {
+						enabled: Boolean(mfa?.confirmedAt),
+						pending: Boolean(mfa && !mfa.confirmedAt),
+						recoveryCodesRemaining: mfa?.recoveryCodes?.length ?? 0
+					}
+				};
+			},
+			begin: async (actor) => {
+				if (!capabilities.mfa) return NOT_OFFERED;
+				if (!actor) return refuse(401, "Not authenticated", "missing");
+				if ((await adapters.loadMfa?.(actor.id))?.confirmedAt) return refuse(409, "A second factor is already set up. Remove it before enrolling another.");
+				const secret = generateTotpSecret();
+				await adapters.saveMfa?.(actor.id, { secret });
+				return {
+					ok: true,
+					body: {
+						secret,
+						uri: totpUri({
+							secret,
+							account: actor.email || actor.username,
+							issuer: mfaIssuer ?? tokens.issuer
+						})
+					}
+				};
+			},
+			/** Proves the app was actually set up, and only then does the factor start being required. */
+			confirm: async (actor, code) => {
+				if (!capabilities.mfa) return NOT_OFFERED;
+				if (!actor) return refuse(401, "Not authenticated", "missing");
+				const mfa = await adapters.loadMfa?.(actor.id);
+				if (!mfa) return refuse(400, "Start the enrolment first");
+				if (mfa.confirmedAt) return refuse(409, "A second factor is already set up");
+				if (!verifyTotp(mfa.secret, code)) {
+					record({
+						type: "mfa.failed",
+						userId: actor.id
+					});
+					return refuse(401, "Invalid code");
+				}
+				const plain = generateRecoveryCodes();
+				await adapters.saveMfa?.(actor.id, {
+					...mfa,
+					confirmedAt: Math.floor(Date.now() / 1e3),
+					recoveryCodes: plain.map(digestRecoveryCode)
+				});
+				record({
+					type: "mfa.enabled",
+					userId: actor.id
+				});
+				return {
+					ok: true,
+					body: {
+						success: true,
+						recoveryCodes: plain
+					}
+				};
+			},
+			/** Removing a factor is a security downgrade, so it asks for the password the way deleting an account does. */
+			disable: async (actor, password) => {
+				if (!capabilities.mfa || !adapters.deleteMfa) return NOT_OFFERED;
+				if (!actor) return refuse(401, "Not authenticated", "missing");
+				const account = await adapters.findById?.(actor.id);
+				if (account?.passwordHash) {
+					if (!password || !await verifyPassword$1(password, account.passwordHash)) return refuse(401, "Invalid credentials");
+				}
+				await adapters.deleteMfa(actor.id);
+				record({
+					type: "mfa.disabled",
+					userId: actor.id
+				});
+				return {
+					ok: true,
+					body: { success: true }
+				};
+			}
+		},
+		refresh: async (refreshToken, carrier) => {
 			if (!capabilities.refresh) return NOT_OFFERED;
 			if (!refreshToken) return refuse(400, "Refresh token is required");
+			/**
+			* Every refusal below ends the session in this browser, because each of them means the credential it just
+			* presented can never work again: no such row, past its deadline, or an account that may not hold one. What
+			* is being cleared is not authority — the row is already gone — it is the browser's reason to keep asking.
+			*/
 			const account = await adapters.findByRefreshToken?.(refreshToken);
-			if (!account || !account.refreshExpiresAt || account.refreshExpiresAt < Math.floor(Date.now() / 1e3)) return refuse(401, "Invalid or expired refresh token", "expired");
-			if (!account.active) return refuse(401, "Account is not active", "inactive");
-			const session = await issue(account.id);
+			if (!account || !account.refreshExpiresAt || account.refreshExpiresAt < Math.floor(Date.now() / 1e3)) return {
+				...refuse(401, "Invalid or expired refresh token", "expired"),
+				endSession: true
+			};
+			if (!account.active) {
+				const reason = deniedReason(account);
+				return {
+					...refuse(401, authFailureMessage[reason], reason),
+					endSession: true
+				};
+			}
+			const cap = tokens.lifetimes.session;
+			if (cap > 0 && account.sessionStartedAt !== void 0 && account.sessionStartedAt + cap < now()) {
+				await adapters.clearSession({ refreshToken });
+				return {
+					...refuse(401, "This session has reached its maximum lifetime", "expired"),
+					endSession: true
+				};
+			}
+			const session = await issue(account.id, {
+				replaces: { refreshToken },
+				client: clientOf(carrier)
+			});
 			return {
 				ok: true,
 				body: await grantBody(account, session),
@@ -166,43 +737,63 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			};
 		},
 		exchange: async (provider, token, carrier) => {
-			if (!capabilities.exchange) return NOT_OFFERED;
-			if (!provider || !token) return refuse(400, "A provider and a token are required");
-			const result = await adapters.exchangeCredential?.(provider, token, carrier);
-			if (!result) return refuse(401, "Token Invalid", "revoked");
-			if ("error" in result) return refuse(result.status ?? 400, result.error, "revoked");
-			const session = await issue(result.id);
+			const result = await exchangeAccount(provider, token, carrier);
+			if (!result.ok) return result.offered ? refuse(result.status, result.error, result.reason) : NOT_OFFERED;
+			const { account, access, session } = result;
 			return {
 				ok: true,
-				body: await grantBody(result, session),
+				body: await grantBody(account, session, access),
 				session
 			};
 		},
+		/**
+		* The same exchange, answering in accounts rather than in HTTP.
+		*
+		* A page server needs who came back and the session they got; the flow above needs a body and a status. They
+		* are the same act, and the translation between them has one correct answer — so it is made once, here, rather
+		* than by every deployment that wires an external identity provider into a rendered page.
+		*/
+		exchangeAccount,
 		signup: async (fields) => {
 			if (!capabilities.signup) return NOT_OFFERED;
 			const username = asString(fields.username);
 			const email = asString(fields.email);
 			const password = asText(fields.password);
 			if (!username || !email || !password) return refuse(400, "A username, an email and a password are required");
+			const weak = await rejectPassword(password, {
+				username,
+				email
+			});
+			if (weak) return weak;
+			const limited = await throttled({
+				action: "signup",
+				key: email
+			});
+			if (limited) return limited;
 			if (await adapters.findByUsername?.(username) ?? await adapters.findByEmail?.(email)) return refuse(400, "User already exists");
-			if (!adapters.createAccount || !hashPassword) return NOT_OFFERED;
+			if (!adapters.createAccount) return NOT_OFFERED;
 			const account = await adapters.createAccount({
 				username,
 				email,
-				passwordHash: await hashPassword(password)
+				passwordHash: await hashPassword$1(password)
 			});
-			if (!verifyOnSignup && capabilities.emailVerification && generateToken && adapters.setValidationToken) {
-				const validationToken = generateToken();
+			if (!verifyOnSignup && capabilities.emailVerification && adapters.setValidationToken) {
+				const validationToken = mintLink(generateToken$1(), LIFETIME.confirmLink);
 				await adapters.setValidationToken(account.id, validationToken);
-				await adapters.sendMail?.({
+				await deliver({
 					to: email,
 					template: "validation",
 					data: {
 						username,
-						validationToken
+						validationToken,
+						...destinationOf(fields.redirect)
 					}
 				});
 			}
+			record({
+				type: "signup",
+				userId: account.id
+			});
 			return {
 				ok: true,
 				status: 201,
@@ -214,12 +805,17 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 		},
 		/** Answers the same either way: whether an address has an account here is not something a stranger may probe. */
 		forgotPassword: async (email) => {
-			if (!capabilities.passwordReset || !generateToken) return NOT_OFFERED;
+			if (!capabilities.passwordReset) return NOT_OFFERED;
+			const limited = await throttled({
+				action: "forgotPassword",
+				key: asString(email)
+			});
+			if (limited) return limited;
 			const account = await adapters.findByEmail?.(asString(email));
 			if (account) {
-				const resetToken = generateToken();
+				const resetToken = mintLink(generateToken$1(), LIFETIME.resetLink);
 				await adapters.setResetToken?.(account.id, resetToken);
-				await adapters.sendMail?.({
+				await deliver({
 					to: account.email,
 					template: "password-reset",
 					data: {
@@ -234,13 +830,27 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			};
 		},
 		resetPassword: async (token, password) => {
-			if (!capabilities.passwordReset || !hashPassword) return NOT_OFFERED;
+			if (!capabilities.passwordReset) return NOT_OFFERED;
 			if (!token || !password) return refuse(400, "A token and a password are required");
-			const account = await adapters.findByResetToken?.(token);
+			const limited = await throttled({
+				action: "resetPassword",
+				key: token
+			});
+			if (limited) return limited;
+			const account = linkExpired(token) ? void 0 : await adapters.findByResetToken?.(token);
 			if (!account) return refuse(400, "Invalid or expired token");
-			await adapters.setPassword?.(account.id, await hashPassword(password));
+			const weak = await rejectPassword(password, {
+				username: account.username,
+				email: account.email
+			});
+			if (weak) return weak;
+			await adapters.setPassword?.(account.id, await hashPassword$1(password));
 			await adapters.setResetToken?.(account.id, "");
 			await adapters.clearSession({ userId: account.id });
+			record({
+				type: "password.reset",
+				userId: account.id
+			});
 			return {
 				ok: true,
 				body: { message: "Password reset successfully" },
@@ -249,26 +859,27 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 		},
 		validateAccount: async (token) => {
 			if (!capabilities.emailVerification) return NOT_OFFERED;
-			const account = await adapters.findByValidationToken?.(token);
+			const account = linkExpired(token) ? void 0 : await adapters.findByValidationToken?.(token);
 			if (!account) return refuse(400, "Invalid or expired token");
-			await adapters.markVerified?.(account.id);
+			await adapters.setVerified?.(account.id, true);
 			return {
 				ok: true,
 				body: { message: "Account validated successfully" }
 			};
 		},
-		resendVerification: async (email) => {
-			if (!capabilities.emailVerification || !generateToken) return NOT_OFFERED;
+		resendVerification: async (email, redirect) => {
+			if (!capabilities.emailVerification) return NOT_OFFERED;
 			const account = await adapters.findByEmail?.(asString(email));
 			if (account && !account.verified) {
-				const validationToken = generateToken();
+				const validationToken = mintLink(generateToken$1(), LIFETIME.confirmLink);
 				await adapters.setValidationToken?.(account.id, validationToken);
-				await adapters.sendMail?.({
+				await deliver({
 					to: account.email,
 					template: "validation",
 					data: {
 						username: account.username,
-						validationToken
+						validationToken,
+						...destinationOf(redirect)
 					}
 				});
 			}
@@ -277,6 +888,389 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				body: { message: "Verification email resent" }
 			};
 		},
+		/**
+		* Change what an account says about itself.
+		*
+		* Both fields are sign-in identifiers, so both are checked for collision first — a store that only has a unique
+		* index reports the clash as a driver error five hundred lines away.
+		*/
+		updateProfile: async (actor, fields) => {
+			if (!capabilities.profile || !adapters.updateAccount) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			const username = asString(fields.username);
+			const email = asString(fields.email);
+			if (!username && !email) return refuse(400, "Nothing to change");
+			if (username && username !== actor.username) {
+				const taken = await adapters.findByUsername?.(username);
+				if (taken && taken.id !== actor.id) return refuse(409, "That username is taken");
+			}
+			if (email && email !== actor.email) {
+				const taken = await adapters.findByEmail?.(email);
+				if (taken && taken.id !== actor.id) return refuse(409, "That email is taken");
+			}
+			const changingEmail = Boolean(email) && email !== actor.email;
+			/**
+			* A new address is PARKED, not applied: the account keeps the one it has until the new one answers a
+			* confirmation. That is what makes a typo survivable — `n@exmaple.com` costs a resend, not the account.
+			*
+			* The alternative, applying it and taking `verified` away, was tried and reverted: `verified` in this server
+			* gates ACCESS (`createAuthorizer` refuses to present an unverified account as an actor at all), so it locked
+			* people out of the account they were sitting in. And the attack it guarded against needs a live session,
+			* from which the same person could simply change the password.
+			*
+			* A deployment that supplies nowhere to park it changes the address on the spot, as it always did.
+			*/
+			const parking = changingEmail && capabilities.emailChange;
+			const account = await adapters.updateAccount(actor.id, {
+				...username ? { username } : {},
+				...email && !parking ? { email } : {}
+			});
+			if (parking && adapters.setPendingEmail) {
+				const confirmationToken = mintLink(generateToken$1(), LIFETIME.confirmLink);
+				await adapters.setPendingEmail(actor.id, email, confirmationToken);
+				await deliver({
+					to: email,
+					template: "email-change",
+					data: {
+						username: account.username,
+						email,
+						confirmationToken
+					}
+				});
+				return {
+					ok: true,
+					body: {
+						success: true,
+						details: profileOf(account),
+						pendingEmail: email,
+						message: "A confirmation was sent to the new address. It takes effect once confirmed."
+					}
+				};
+			}
+			if (changingEmail && capabilities.emailVerification && adapters.setValidationToken) {
+				const validationToken = mintLink(generateToken$1(), LIFETIME.confirmLink);
+				await adapters.setValidationToken(actor.id, validationToken);
+				await deliver({
+					to: account.email,
+					template: "validation",
+					data: {
+						username: account.username,
+						validationToken
+					}
+				});
+				return {
+					ok: true,
+					body: {
+						success: true,
+						details: profileOf(account),
+						message: "A confirmation was sent to the new address"
+					}
+				};
+			}
+			return {
+				ok: true,
+				body: {
+					success: true,
+					details: profileOf(account)
+				}
+			};
+		},
+		/**
+		* Takes the parked address, having proved somebody reads it.
+		*
+		* Public, and it has to be: the link is opened from a mail client, in whatever browser that happens to be, with
+		* no session. The token is the whole credential — which is why it is single-use and why confirming also marks
+		* the account verified: an address that answered a link is an address that was proven.
+		*/
+		confirmEmailChange: async (token) => {
+			if (!capabilities.emailChange || !adapters.findByPendingEmail || !adapters.clearPendingEmail) return NOT_OFFERED;
+			const confirmation = asString(token);
+			const pending = linkExpired(confirmation) ? void 0 : await adapters.findByPendingEmail(confirmation);
+			if (!pending) return refuse(400, "Invalid or expired token");
+			const taken = await adapters.findByEmail?.(pending.email);
+			if (taken && taken.id !== pending.account.id) {
+				await adapters.clearPendingEmail(pending.account.id);
+				return refuse(409, "That email is taken");
+			}
+			const account = await adapters.updateAccount?.(pending.account.id, { email: pending.email });
+			await adapters.clearPendingEmail(pending.account.id);
+			if (adapters.setVerified) await adapters.setVerified(pending.account.id, true);
+			record({
+				type: "email.changed",
+				userId: pending.account.id,
+				detail: { email: pending.email }
+			});
+			const confirmed = {
+				...account ?? pending.account,
+				email: pending.email
+			};
+			return {
+				ok: true,
+				body: {
+					success: true,
+					details: profileOf(adapters.setVerified ? {
+						...confirmed,
+						verified: true
+					} : confirmed)
+				}
+			};
+		},
+		/**
+		* Change a password, having proved you know the current one.
+		*
+		* Then **every other session ends**. Changing a password is what somebody does when they think a credential
+		* escaped, and one that leaves the other sessions signed in has not done the thing they asked for. The session
+		* making the change survives, or the act of securing the account would sign them out of it.
+		*/
+		changePassword: async (actor, currentPassword, newPassword) => {
+			if (!capabilities.passwordChange || !adapters.findById) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			if (!currentPassword || !newPassword) return refuse(400, "The current and the new password are required");
+			const weak = await rejectPassword(newPassword, {
+				username: actor.username,
+				email: actor.email
+			});
+			if (weak) return weak;
+			const limited = await throttled({
+				action: "changePassword",
+				key: String(actor.id)
+			});
+			if (limited) return limited;
+			const account = await adapters.findById(actor.id);
+			if (!account?.passwordHash || !await verifyPassword$1(currentPassword, account.passwordHash)) return refuse(401, "Invalid credentials");
+			await adapters.setPassword?.(actor.id, await hashPassword$1(newPassword));
+			await adapters.revokeOtherSessions?.(actor.id, actor.token);
+			throttleSucceeded({
+				action: "changePassword",
+				key: String(actor.id)
+			});
+			record({
+				type: "password.changed",
+				userId: actor.id
+			});
+			return {
+				ok: true,
+				body: {
+					success: true,
+					message: "Password changed. Other sessions were signed out."
+				}
+			};
+		},
+		/**
+		* Close the account.
+		*
+		* Confirmed with the password when there is one — this is irreversible, and a borrowed session should not be
+		* able to do it. An account with no password (one that signs in through a provider) cannot be asked, so the
+		* session alone has to be enough.
+		*/
+		deleteSelf: async (actor, password) => {
+			if (!capabilities.accountDeletion || !adapters.deleteAccount) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			const account = await adapters.findById?.(actor.id);
+			if (account?.passwordHash) {
+				if (!password || !await verifyPassword$1(password, account.passwordHash)) return refuse(401, "Invalid credentials");
+			}
+			await adapters.deleteAccount(actor.id);
+			record({
+				type: "account.deleted",
+				userId: actor.id
+			});
+			return {
+				ok: true,
+				body: {
+					success: true,
+					message: "Account deleted"
+				},
+				endSession: true
+			};
+		},
+		/** The devices this account is signed in on, with the one asking marked. */
+		listSessions: async (actor) => {
+			if (!capabilities.sessionList || !adapters.listSessions) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			return {
+				ok: true,
+				body: { sessions: await adapters.listSessions(actor.id, actor.token) }
+			};
+		},
+		/** End one of them. Scoped to the caller's own account, or a session id would be an IDOR. */
+		revokeSession: async (actor, sessionId) => {
+			if (!adapters.revokeSession) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			if (!Number.isInteger(sessionId)) return refuse(400, "A session id is required");
+			return await adapters.revokeSession(actor.id, sessionId) ? {
+				ok: true,
+				body: { success: true }
+			} : refuse(404, "No such session");
+		},
+		/** "Sign out everywhere else" — the thing to do from a device you still hold after losing one you do not. */
+		revokeOtherSessions: async (actor) => {
+			if (!adapters.revokeOtherSessions) return NOT_OFFERED;
+			if (!actor) return refuse(401, "Not authenticated", "missing");
+			return {
+				ok: true,
+				body: {
+					success: true,
+					revoked: await adapters.revokeOtherSessions(actor.id, actor.token)
+				}
+			};
+		},
+		admin: {
+			list: async (actor, query) => {
+				const denial = requireAdmin(actor);
+				if (denial) return denial;
+				if (!adapters.listAccounts) return NOT_OFFERED;
+				const { accounts, total } = await adapters.listAccounts(query);
+				return {
+					ok: true,
+					body: {
+						accounts: accounts.map(profileOf),
+						total
+					}
+				};
+			},
+			get: async (actor, userId) => {
+				const denial = requireAdmin(actor);
+				if (denial) return denial;
+				const account = await adapters.findById?.(userId);
+				if (!account) return refuse(404, "No such account");
+				return {
+					ok: true,
+					body: {
+						account: profileOf(account),
+						access: await adapters.loadAccess(userId)
+					}
+				};
+			},
+			/**
+			* Suspend, block or restore an account — and **end its sessions when it stops being active**.
+			*
+			* That second half is the whole point. A ban that leaves the credential working is not a ban, it is a note
+			* in a database; the person stays signed in until their token happens to lapse.
+			*/
+			setStatus: async (actor, userId, status) => {
+				const denial = requireAdmin(actor, userId);
+				if (denial) return denial;
+				if (!adapters.setStatus) return NOT_OFFERED;
+				if (!STATUSES.includes(status)) return refuse(400, `Status must be one of ${STATUSES.join(", ")}`);
+				if (!await adapters.findById?.(userId)) return refuse(404, "No such account");
+				await adapters.setStatus(userId, status);
+				if (status !== "active") await adapters.clearSession({ userId });
+				record({
+					type: "admin.status-changed",
+					userId,
+					actorId: actor?.id,
+					detail: { status }
+				});
+				return {
+					ok: true,
+					body: {
+						success: true,
+						status
+					}
+				};
+			},
+			setRoles: async (actor, userId, roles) => {
+				const denial = requireAdmin(actor);
+				if (denial) return denial;
+				if (!adapters.setRoles) return NOT_OFFERED;
+				if (!Array.isArray(roles) || roles.some((role) => typeof role !== "string")) return refuse(400, "Roles must be a list of names");
+				const names = roles;
+				if (!await adapters.findById?.(userId)) return refuse(404, "No such account");
+				await adapters.setRoles(userId, names);
+				record({
+					type: "admin.roles-changed",
+					userId,
+					actorId: actor?.id,
+					detail: { roles: names }
+				});
+				return {
+					ok: true,
+					body: {
+						success: true,
+						roles: names
+					}
+				};
+			},
+			remove: async (actor, userId) => {
+				const denial = requireAdmin(actor, userId);
+				if (denial) return denial;
+				if (!adapters.deleteAccount) return NOT_OFFERED;
+				if (!await adapters.findById?.(userId)) return refuse(404, "No such account");
+				await adapters.deleteAccount(userId);
+				record({
+					type: "admin.account-deleted",
+					userId,
+					actorId: actor?.id
+				});
+				return {
+					ok: true,
+					body: { success: true }
+				};
+			},
+			/**
+			* A session AS somebody else, for support that has to see what they see.
+			*
+			* Three properties make it something a deployment can live with, and all three are deliberate:
+			*
+			* - **It says so.** The credential carries `act` (RFC 8693), so every request made with it can be told from
+			*   one the account holder made — `Actor.impersonatedBy` is that claim, read back. A borrowed session that
+			*   is indistinguishable from a real one turns an audit log into fiction.
+			* - **It is short and cannot renew.** Fifteen minutes by default and no refresh token, so it expires rather
+			*   than becoming a permanent second key to somebody's account.
+			* - **It is off unless asked for**, behind its own permission — see `impersonationPermission`.
+			*
+			* The session is answered in the BODY and no cookie is written. Swapping the administrator's own session
+			* cookie for this one would sign them out of the account they administer from, and getting back would mean
+			* signing in again; whoever asked decides where to put a credential they were handed.
+			*
+			* One caveat a deployment has to know: a store that keeps a single session per account — no `session` table —
+			* will overwrite the subject's own session with this one, signing them out. Anything with per-session rows,
+			* which is what `createMysqlStore` builds, does not.
+			*/
+			impersonate: async (actor, userId, carrier) => {
+				if (!capabilities.impersonation || !impersonationPermission || !adapters.findById) return NOT_OFFERED;
+				const check = checkPermission(actor, impersonationPermission);
+				if (!check.ok) return refuse(check.status, check.error, check.status === 401 ? "missing" : void 0);
+				if (!actor || userId === actor.id) return refuse(400, "You are already signed in as yourself");
+				const account = await adapters.findById(userId);
+				if (!account) return refuse(404, "No such account");
+				if (!account.active) return refuse(403, "That account is not active");
+				const session = await issue(userId, { client: clientOf(carrier) }, {
+					actingAs: actor.id,
+					ttlSeconds: LIFETIME.impersonation,
+					renewable: false
+				});
+				record({
+					type: "admin.impersonated",
+					userId,
+					actorId: actor.id
+				});
+				return {
+					ok: true,
+					body: {
+						...await grantBody(account, session),
+						impersonatedBy: actor.id
+					}
+				};
+			}
+		},
+		/**
+		* A CSRF token for whoever is asking, bound to their session when they have one. Answered as a body AND as the
+		* cookie the binding writes, so a page can take whichever it finds easier to read.
+		*/
+		issueCsrf: (sessionToken) => {
+			if (!csrf) return NOT_OFFERED;
+			const token = csrf.issue(sessionToken);
+			return {
+				ok: true,
+				body: {
+					token,
+					headerName: csrf.headerName
+				},
+				csrf: token
+			};
+		},
 		/** Exposed so a deployment can mint a session outside the flows above — a rendered page's login form. */
 		issueSession: issue,
 		resolveActor: identity.resolveActor