@rebasepro/server 0.22.0 → 0.24.0

package/dist/{auth-CCDpk2rn.js → auth-DMLngxn_.js}

@@ -3,23 +3,37 @@ import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
 import { i as __toESM, n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
-import { F as revokeInternalTableSql, ot as ANONYMOUS_USER_ID, st as isAnonymousUid } from "./src-1vL-I1Po.js";
-import "./src-Br6ARbs6.js";
-import { n as createDdlBootstrapper, o as isSQLAdmin } from "./ddl-bootstrap-CfNvxMuK.js";
+import { P as revokeInternalTableSql, ct as isAnonymousUid, st as ANONYMOUS_USER_ID } from "./src-I3aG1PcY.js";
+import { _ as scopesForRoles, a as KEY_MANAGEMENT_SCOPES, b as validateScopes, c as intersectScopes, d as isDataPlaneScope, f as knownScopes, g as scopesBeyond, h as scopeGrantsAny, i as EMPTY_ACCESS_MODEL, l as isAdminScope, m as scopeGrants, n as ADMIN_SCOPES, o as SCOPE_TARGETS, p as parseScope, r as BUILT_IN_SCOPES, s as hasAdminRole, t as ADMIN_ROLE, u as isBuiltInScope, v as summarizeRoles } from "./src-CatHFUym.js";
+import { t as isSQLAdmin } from "./backend-DTAOsLQc.js";
 import { t as firstSqlRow } from "./sql-rows-C6GEc2oE.js";
-import { r as logger } from "./logger-DO2PZc4i.js";
-import { r as errorHandler, t as ApiError } from "./errors-DWsX4yTd.js";
-import { a as resolveListLimitParam } from "./query-parser-BleZmY18.js";
-import { C as require_jsonwebtoken, E as randomInt$1, O as sha256Hex, _ as verifyAccessToken, b as verifyMfaPendingToken, c as getAccessTokenExpiry, d as getRefreshTokenTtlMs, f as hasAsymmetricSigningKey, i as generateDownloadToken, l as getJwks, m as isJwtConfigured, n as configureJwt, o as generateMfaPendingToken, p as hashRefreshToken, r as generateAccessToken, s as generateRefreshToken, t as MAX_COOKIE_AGE_MS, u as getRefreshTokenExpiry, v as verifyDownloadToken, w as constantTimeEqual } from "./jwt-C4OW-DNq.js";
-import { n as hasAdministrativeRole, r as isAdministrativeRole, t as ADMINISTRATIVE_ROLES } from "./admin-roles-vYdp_Pil.js";
-import { c as tryCanonicalStorageKey, i as canonicalStorageId } from "./keys-Qfc4XieN.js";
+import { r as logger } from "./logger-D-S-hO5e.js";
+import { i as isDataException, r as errorHandler, t as ApiError } from "./errors-D6_y86c5.js";
+import { a as resolveListLimitParam } from "./query-parser-BgiKJKvc.js";
+import { D as constantTimeEqual, E as require_jsonwebtoken, S as verifyMfaPendingToken, a as generateAccessToken, b as verifyDownloadToken, c as generateMfaPendingToken, d as getJwks, f as getRefreshTokenExpiry, g as isJwtConfigured, h as hashRefreshToken, i as customClaimsOf, j as sha256Hex, k as randomInt$1, l as generateRefreshToken, m as hasAsymmetricSigningKey, n as configureJwt, o as generateDownloadToken, p as getRefreshTokenTtlMs, r as configuredJwtSecret, t as MAX_COOKIE_AGE_MS, u as getAccessTokenExpiry, y as verifyAccessToken } from "./jwt-R6bSPMjk.js";
+import { a as canonicalStorageId, o as canonicalStorageKey, r as InvalidStorageKeyError } from "./keys-GAVZqbqx.js";
+import { n as createDdlBootstrapper } from "./ddl-bootstrap-BaqMSa4Y.js";
 import { createHash, randomBytes, randomInt } from "node:crypto";
 import { Hono } from "hono";
 import { promisify } from "util";
-import { createCipheriv, createDecipheriv, createHash as createHash$1, createHmac, createPublicKey, randomBytes as randomBytes$1, randomUUID, scrypt, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash as createHash$1, createHmac, createPublicKey, randomBytes as randomBytes$1, randomUUID as randomUUID$1, scrypt, timingSafeEqual } from "crypto";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { createMiddleware } from "hono/factory";
 import { z } from "zod";
+//#region ../types/src/types/auth_adapter.ts
+/**
+* The request header that asks for a data-plane request to run as another
+* user, named by uid.
+*
+* The server honours it only on a signed-in administrator's own session —
+* never on an API key or the service key — and only through an adapter that
+* implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
+* carries it is refused, never run as its caller.
+*
+* @group Auth
+*/
+var IMPERSONATE_HEADER = "x-rebase-impersonate";
+//#endregion
 //#region ../types/src/controllers/storage.ts
 /**
 * Path prefix that marks an object as **public**. Files stored under this
@@ -31,9 +45,33 @@ import { z } from "zod";
 */
 var PUBLIC_STORAGE_PREFIX = "public/";
 /**
-* True when a storage key/path points at a public object (lives under
-* {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
-* bucket* — strip any `bucket/` and `scheme://` prefixes first.
+* True when a storage **key** is public: it lies under
+* {@link PUBLIC_STORAGE_PREFIX}.
+*
+* The key is read exactly as it is — the canonical key within its bucket, the
+* one the server stores, serves, and hands a `storageAuthorize` hook as
+* `key` — and nothing is parsed out of it. That is the difference from
+* {@link isPublicStoragePath}, which reads a client-side *path* and so strips
+* a `scheme://` and a leading `default/` bucket segment first. On a key both are
+* wrong: `default/public/x` is a key in a folder called `default`, and a
+* request path `notes://public/x` names the key `notes:/public/x`. Neither is
+* public, and the server decides on this function so that it never says they
+* are.
+*
+* @group Models
+*/
+function isPublicStorageKey(key) {
+	if (!key || !key.startsWith("public/")) return false;
+	return !key.split(/[\\/]/).includes("..");
+}
+/**
+* True when a storage key or client-side path points at a public object
+* (lives under {@link PUBLIC_STORAGE_PREFIX}).
+*
+* For a path as a client holds it: a `scheme://` prefix and a single leading
+* `default/` bucket segment are stripped first. The server and a
+* `storageAuthorize` hook, which hold the canonical key, use
+* {@link isPublicStorageKey}.
 *
 * @group Models
 */
@@ -46,6 +84,57 @@ function isPublicStoragePath(path) {
 	if (p.split("/").some((seg) => seg === "..")) return false;
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
+/**
+* The path the storage routes address an object by, from a key or from the
+* `storageUrl` an upload returned (`<scheme>://<bucket>/<key>`, which is what a
+* property with `includeBucketUrl: true` keeps in its column).
+*
+* The routes address a source's objects by key. On S3 and GCS the bucket in a
+* `storageUrl` is always the source's own — the server refuses any other — so
+* it is dropped: sent along, `s3://acme-media/products/a.png` reached the
+* server as the key `acme-media/products/a.png`, the preview found nothing and
+* a delete reported success while the object stayed. It worked on local disk
+* only, because `local://default/<key>` happens to carry the one bucket
+* segment the routes recognise — which is kept, as is any other local bucket.
+*
+* A bare key whose first folder is `default` is sent behind that bucket
+* segment. The routes read one leading `default/` (in any case) as the bucket,
+* so the key `default/photo.png` sent as it is names the root `photo.png`:
+* {@link defaultBucketPath} is the spelling that names the key itself.
+*
+* Shared by every storage source that talks to those routes — the SDK's and
+* the admin panel's `useBackendStorageSource` — so they address an object alike.
+*
+* @group Models
+*/
+function storageObjectPath(keyOrUrl, bucket) {
+	let filePath = keyOrUrl;
+	let bucketQualified = false;
+	const scheme = /^(local|s3|gs):\/\//.exec(filePath);
+	if (scheme) {
+		filePath = filePath.substring(scheme[0].length);
+		if (scheme[1] !== "local") {
+			const slash = filePath.indexOf("/");
+			if (slash > 0) filePath = filePath.substring(slash + 1);
+		} else bucketQualified = true;
+	}
+	if (bucket && filePath) {
+		if (!filePath.startsWith(`${bucket}/`)) filePath = `${bucket}/${filePath}`;
+		bucketQualified = true;
+	}
+	return bucketQualified ? filePath : defaultBucketPath(filePath);
+}
+/**
+* The request path of a key in the default bucket: the key itself, unless the
+* routes would read its first folder as the bucket — a first folder named
+* `default`, matched as the routes match it (case-insensitively, and only when
+* something follows it). Then the bucket segment goes in front, so exactly the
+* one segment the routes strip is the one added.
+*/
+function defaultBucketPath(key) {
+	const segments = key.split("/");
+	return segments.length > 1 && segments[0].toLowerCase() === "default" ? `default/${key}` : key;
+}
 //#endregion
 //#region ../common/src/util/email.ts
 /**
@@ -80,79 +169,26 @@ function normalizeEmail(email) {
 	return typeof email === "string" ? email.trim().toLowerCase() : email;
 }
 //#endregion
-//#region src/auth/api-keys/api-key-permission-guard.ts
+//#region src/auth/api-keys/http-operation.ts
 /**
-* Map an HTTP method string to an `ApiKeyOperation`.
+* Map an HTTP method to the operation it performs.
 *
 * - `GET`, `HEAD`, `OPTIONS` → `"read"`
 * - `POST`, `PUT`, `PATCH`  → `"write"`
 * - `DELETE`                → `"delete"`
+*
+* Any other method is a `"write"`: a verb this does not know is not assumed
+* to be harmless.
 */
 function httpMethodToOperation(method) {
 	switch (method.toUpperCase()) {
 		case "GET":
 		case "HEAD":
 		case "OPTIONS": return "read";
-		case "POST":
-		case "PUT":
-		case "PATCH": return "write";
 		case "DELETE": return "delete";
-		default: return "read";
+		default: return "write";
 	}
 }
-/**
-* Check whether the given permissions array allows `operation` on `collection`.
-*
-* Supports the `"*"` wildcard for the collection field, which matches any
-* collection. Returns `true` if at least one permission entry grants access.
-*
-* @param permissions - The API key's permission entries.
-* @param collection  - The target collection slug.
-* @param operation   - The requested operation.
-* @returns `true` if the operation is permitted.
-*/
-function isOperationAllowed(permissions, collection, operation) {
-	for (const perm of permissions) if ((perm.collection === "*" || perm.collection === collection) && perm.operations.includes(operation)) return true;
-	return false;
-}
-/**
-* Check whether the given permissions array allows a storage operation.
-*
-* Storage, like functions, lives outside the collection namespace: an entry
-* with collection `"storage"` grants storage access for the listed
-* operations (GET routes → `read`, upload/folder/tus → `write`,
-* DELETE routes → `delete`), and the global `"*"` wildcard also matches.
-* A collection-scoped key gets no storage access at all.
-*
-* Matching is exactly {@link isOperationAllowed} with `"storage"` as the
-* resource name — delegated so the semantics can never drift.
-*/
-function isStorageAllowed(permissions, operation) {
-	return isOperationAllowed(permissions, "storage", operation);
-}
-/**
-* Check whether the given permissions array allows invoking a custom function.
-*
-* Functions live outside the collection namespace, so they have their own
-* resource names in the permission list:
-*
-* - `{ collection: "functions", ... }` grants every function
-* - `{ collection: "functions/<name>", ... }` grants a single function
-* - the global `"*"` wildcard (full-access keys) also matches
-*
-* The operation is derived from the HTTP method as usual (GET → read,
-* POST/PUT/PATCH → write, DELETE → delete). The functions index route is
-* checked as `functionName === ""`, which only the `"functions"` and `"*"`
-* entries can grant.
-*
-* A collection-scoped key (e.g. read-only on `events`) therefore can NOT
-* invoke functions — before this guard existed, any valid key could call
-* every function.
-*/
-function isFunctionAllowed(permissions, functionName, operation) {
-	for (const perm of permissions) if ((perm.collection === "*" || perm.collection === "functions" || functionName !== "" && perm.collection === `functions/${functionName}`) && perm.operations.includes(operation)) return true;
-	return false;
-}
 //#endregion
 //#region src/email/html.ts
 /**
@@ -553,6 +589,16 @@ If you didn't create an account with ${appName}, you can safely ignore this emai
 	};
 }
 /**
+* How long an invitation's set-password link stays valid.
+*
+* One number for both halves: `finalizeAdminUserCreation` mints the token for
+* this long and the template below tells the invitee this long. They were two
+* literals, and the email said "1 hour" for a token that lived 24 — so an
+* invitee who opened it the next morning believed the link was dead.
+*/
+var USER_INVITATION_LINK_TTL_MS = 1440 * 60 * 1e3;
+var USER_INVITATION_LINK_TTL_HOURS = USER_INVITATION_LINK_TTL_MS / (3600 * 1e3);
+/**
 * Default user invitation email template
 * Sent when an admin creates a new user account
 */
@@ -593,7 +639,7 @@ function getUserInvitationTemplate(setPasswordUrl, user, appName = DEFAULT_APP_N
             </p>
             
             <div style="${styles.warning}">
-                ⏰ This link will expire in 1 hour for security reasons.
+                ⏰ This link will expire in ${USER_INVITATION_LINK_TTL_HOURS} hours for security reasons.
             </div>
             
             <div style="${styles.footer}">
@@ -616,7 +662,7 @@ An account has been created for you on ${appName}.
 Click this link to set your password and get started:
 ${setPasswordUrl}
 
-This link will expire in 1 hour for security reasons.
+This link will expire in ${USER_INVITATION_LINK_TTL_HOURS} hours for security reasons.
 
 If you weren't expecting this invitation, you can safely ignore this email.
     `.trim();
@@ -837,13 +883,219 @@ No action is needed.
 		text
 	};
 }
+/**
+* Default address-change confirmation, mailed to the NEW address.
+*
+* Names the account being moved — its current address — because the link
+* makes the address the account's: whoever follows it hands their inbox to
+* that account, and must be able to tell whether it is theirs.
+*/
+function getEmailChangeTemplate(confirmUrl, user, newEmail, appName = DEFAULT_APP_NAME, logoUrl) {
+	const greeting = getGreeting(user);
+	const subject = `Confirm your new ${appName} email address`;
+	const body = html`
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${subject}</title>
+</head>
+<body style="margin: 0; padding: 0; background-color: #f8fafc;">
+    <div style="${styles.container}">${renderHeader(appName, logoUrl)}
+        <div style="${styles.card}">
+            <h1 style="${styles.heading}">Confirm Your New Email</h1>
+
+            <p style="${styles.paragraph}">
+                Hi ${greeting},
+            </p>
+
+            <p style="${styles.paragraph}">
+                The ${appName} account ${user.email} asked to use ${newEmail} from now on.
+                Confirm it is yours by clicking the button below:
+            </p>
+
+            <div style="text-align: center;">
+                <a href="${confirmUrl}" style="${styles.button}">Confirm New Email</a>
+            </div>
+
+            <p style="${styles.paragraph}">
+                Or copy and paste this link into your browser:
+            </p>
+            <p style="color: #3b82f6; word-break: break-all; font-size: 14px;">
+                ${confirmUrl}
+            </p>
+
+            <div style="${styles.warning}">
+                ⏰ This link expires in 24 hours and can only be used once.
+            </div>
+
+            <div style="${styles.footer}">
+                <p style="margin: 0;">
+                    If you did not ask for this, ignore this email: nothing changes until the link is followed.
+                </p>
+            </div>
+        </div>
+    </div>
+</body>
+</html>
+    `;
+	const text = `
+Confirm Your New Email
+
+Hi ${greeting},
+
+The ${appName} account ${user.email} asked to use ${newEmail} from now on. Confirm it is yours by following this link:
+${confirmUrl}
+
+This link expires in 24 hours and can only be used once.
+
+If you did not ask for this, ignore this email: nothing changes until the link is followed.
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
+	};
+}
+/**
+* Default notice to the OLD address that a change was asked for. It carries
+* no link: the old inbox can do nothing about the change except know of it,
+* and a link here would be a second way to make it.
+*/
+function getEmailChangeNoticeTemplate(user, newEmail, appName = DEFAULT_APP_NAME, logoUrl) {
+	const greeting = getGreeting(user);
+	const subject = `Your ${appName} email address is being changed`;
+	const body = html`
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${subject}</title>
+</head>
+<body style="margin: 0; padding: 0; background-color: #f8fafc;">
+    <div style="${styles.container}">${renderHeader(appName, logoUrl)}
+        <div style="${styles.card}">
+            <h1 style="${styles.heading}">Email Change Requested</h1>
+
+            <p style="${styles.paragraph}">
+                Hi ${greeting},
+            </p>
+
+            <p style="${styles.paragraph}">
+                Someone signed in to your ${appName} account asked to change its email address
+                from ${user.email} to ${newEmail}. The change happens only when the link we sent
+                to ${newEmail} is followed.
+            </p>
+
+            <div style="${styles.footer}">
+                <p style="margin: 0;">
+                    If this was you, there is nothing to do here. If it was not, sign in, change your
+                    password and sign out of every other session.
+                </p>
+            </div>
+        </div>
+    </div>
+</body>
+</html>
+    `;
+	const text = `
+Email Change Requested
+
+Hi ${greeting},
+
+Someone signed in to your ${appName} account asked to change its email address from ${user.email} to ${newEmail}. The change happens only when the link we sent to ${newEmail} is followed.
+
+If this was you, there is nothing to do here. If it was not, sign in, change your password and sign out of every other session.
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
+	};
+}
+//#endregion
+//#region src/email/link-base.ts
+/**
+* The config fields consulted for each link kind, most specific first.
+*
+* `resetPasswordUrl` is the general fallback because it is the only one any boot
+* path sets, and in every real deployment all three point at the same frontend.
+*/
+var LINK_BASE_FIELDS = {
+	resetPassword: ["resetPasswordUrl"],
+	verifyEmail: ["verifyEmailUrl", "resetPasswordUrl"],
+	magicLink: ["magicLinkUrl", "resetPasswordUrl"]
+};
+/**
+* True when `value` is an absolute `http(s)` URL — the only kind a mail client
+* can follow. A protocol-relative or path-only base is treated as missing.
+*/
+function isAbsoluteHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/** Drop a trailing slash so callers can append `/verify-email?token=…`. */
+function normalizeBase(value) {
+	return value.replace(/\/+$/, "");
+}
+/**
+* The absolute base URL for a link kind, or `""` when the config has none.
+*
+* Callers append their path to the result. `""` is only reachable on a config
+* that never went through {@link assertEmailLinkBases} — a hand-constructed
+* `SMTPEmailService` in a test, say — and is kept rather than thrown so that a
+* misconfiguration cannot turn a password-reset request into a 500 that
+* distinguishes existing accounts from missing ones.
+*/
+function resolveEmailLinkBase(config, kind) {
+	if (!config) return "";
+	for (const field of LINK_BASE_FIELDS[kind]) {
+		const value = config[field];
+		if (typeof value === "string" && isAbsoluteHttpUrl(value)) return normalizeBase(value);
+	}
+	return "";
+}
+/**
+* Throw when an email configuration cannot produce a followable link of every
+* kind it sends.
+*
+* Called from `createEmailService`, i.e. from every boot path that wires email
+* up (the managed runtime, both driver bootstrappers, and any app that passes
+* `auth.email`). A base that is set but relative is reported separately from one
+* that is missing, because the two have different fixes.
+*/
+function assertEmailLinkBases(config) {
+	const relative = [
+		"resetPasswordUrl",
+		"verifyEmailUrl",
+		"magicLinkUrl"
+	].filter((field) => typeof config[field] === "string" && config[field] !== "" && !isAbsoluteHttpUrl(config[field]));
+	if (relative.length > 0) throw new Error(`Email is configured with a relative link base: ${relative.map((f) => `email.${f}`).join(", ")}. Emailed links must be absolute (e.g. "https://app.example.com") — a mail client has no base document to resolve a relative href against, so the link is dead.`);
+	const unresolved = Object.keys(LINK_BASE_FIELDS).filter((kind) => !resolveEmailLinkBase(config, kind));
+	if (unresolved.length === Object.keys(LINK_BASE_FIELDS).length) throw new Error("Email is configured but no base URL for emailed links is set. Password-reset, verification and magic-link emails would carry relative hrefs, which are dead links in every mail client. Set FRONTEND_URL (or `auth.email.resetPasswordUrl`) to an absolute URL such as \"https://app.example.com\".");
+	if (unresolved.length > 0) throw new Error(`Email is configured without a base URL for ${unresolved.map((kind) => LINK_KIND_LABELS[kind]).join(" and ")} emails, so their links would be relative hrefs — dead in every mail client. Those links fall back to \`auth.email.resetPasswordUrl\` only: set FRONTEND_URL (or \`auth.email.resetPasswordUrl\`) to an absolute URL such as "https://app.example.com".`);
+}
+/** How each link kind is named in a boot error. */
+var LINK_KIND_LABELS = {
+	resetPassword: "password-reset",
+	verifyEmail: "verification",
+	magicLink: "magic-link"
+};
 //#endregion
 //#region src/auth/admin-user-ops.ts
 /**
 * Admin User Operations
 *
 * Shared utilities and orchestration for admin-initiated user management
-* (user creation via REST API, password reset via admin panel).
+* (user creation via REST API, password reset via admin panel), and the rules
+* user administration holds to whichever door it arrives by — the admin user
+* routes, or the auth collection through the data API.
 *
 * Hook resolution order:
 * 1. Collection-level hook (`auth.onCreateUser` on the collection) — closest to the data
@@ -883,7 +1135,7 @@ function generateSecureToken() {
 /**
 * Hash a token for database storage using SHA-256.
 */
-function hashToken$1(token) {
+function hashToken(token) {
 	return createHash("sha256").update(token).digest("hex");
 }
 /**
@@ -964,10 +1216,10 @@ async function finalizeAdminUserCreation(entity, clearPassword, ctx) {
 	if (!clearPassword) return { invitationSent: false };
 	if (!!(ctx.emailService && ctx.emailService.isConfigured())) try {
 		const token = generateSecureToken();
-		const tokenHash = hashToken$1(token);
-		const expiresAt = new Date(Date.now() + 1440 * 60 * 1e3);
+		const tokenHash = hashToken(token);
+		const expiresAt = new Date(Date.now() + USER_INVITATION_LINK_TTL_MS);
 		await ctx.authRepo.createPasswordResetToken(entity.id, tokenHash, expiresAt);
-		const setPasswordUrl = `${ctx.emailConfig?.resetPasswordUrl || ""}/reset-password?token=${token}`;
+		const setPasswordUrl = `${resolveEmailLinkBase(ctx.emailConfig, "resetPassword")}/reset-password?token=${token}`;
 		const { appName, logoUrl } = resolveEmailBranding(ctx.emailConfig);
 		const templateFn = ctx.emailConfig?.templates?.userInvitation;
 		const emailContent = templateFn ? templateFn(setPasswordUrl, {
@@ -1029,6 +1281,88 @@ async function completeUserCreation(prepared, finalize) {
 		...result.emailDeliveryFailed ? { emailDeliveryFailed: true } : {}
 	};
 }
+/**
+* Refuse a change that leaves no administrator: `leaving` are users losing the
+* role (demoted, or deleted), and the project must keep at least one.
+*
+* Judged over the whole set, so a bulk write that takes every admin at once is
+* refused even though each of its rows alone would leave one behind.
+*/
+async function assertAdministratorsRemain(authRepo, leaving, message) {
+	const admins = [];
+	for (const uid of new Set(leaving)) if ((await authRepo.getUserRoleIds(uid)).includes("admin")) admins.push(uid);
+	if (admins.length === 0) return;
+	const { total } = await authRepo.listUsersPaginated({
+		roleId: "admin",
+		limit: 1
+	});
+	if (total <= admins.length) throw ApiError.forbidden(message, "LAST_ADMIN");
+}
+/** Refuse deleting these users when that would leave the project with no administrator. */
+async function assertUserDeletionsAllowed(authRepo, uids) {
+	await assertAdministratorsRemain(authRepo, uids, uids.length > 1 ? "Cannot delete every administrator" : "Cannot delete the last administrator");
+}
+/** Refuse setting these users' roles when that would leave the project with no administrator. */
+async function assertRoleChangesAllowed(authRepo, changes) {
+	await assertAdministratorsRemain(authRepo, changes.filter((change) => !change.roles.includes("admin")).map((change) => change.uid), changes.length > 1 ? "Cannot demote every administrator" : "Cannot demote the last administrator");
+}
+/**
+* A user's new email, in the form sign-in looks it up by — or a 409 when
+* another account holds it.
+*
+* Sign-in, password reset and magic links all find the account by
+* `normalizeEmail(input)`. An address stored as typed is one those lookups
+* never match: its owner is locked out, and registering the address again hits
+* the case-insensitive unique index.
+*/
+async function normalizeUserEmailChange(authRepo, uid, email) {
+	const normalized = normalizeEmail(email);
+	const holder = await authRepo.getUserByEmail(normalized);
+	if (holder && holder.id !== uid) throw ApiError.conflict("Email already registered", "EMAIL_EXISTS");
+	return normalized;
+}
+/**
+* Run `afterUserDelete` without letting it fail the deletion it follows: the
+* user is already gone, so a failing listener is logged, not answered.
+*/
+function runAfterUserDelete(resolvedHooks, uid) {
+	if (!resolvedHooks.afterUserDelete) return;
+	resolvedHooks.afterUserDelete(uid).catch((err) => {
+		logger.error("[AuthHooks] afterUserDelete error", { error: err instanceof Error ? err.message : err });
+	});
+}
+/**
+* The auth adapter's side of user administration through the auth collection
+* (`AuthAdapter.prepareUserUpdates` and the deletion pair): the admin user
+* routes' rules and hooks, for the data API's writes to the same rows.
+*/
+function authCollectionUserAdmin(ctx) {
+	const { authRepo, resolvedHooks } = ctx;
+	return {
+		async prepareUserUpdates(updates) {
+			await assertRoleChangesAllowed(authRepo, updates.flatMap(({ uid, values }) => Array.isArray(values.roles) ? [{
+				uid,
+				roles: values.roles
+			}] : []));
+			const prepared = [];
+			for (const { uid, values } of updates) prepared.push(typeof values.email === "string" ? {
+				...values,
+				email: await normalizeUserEmailChange(authRepo, uid, values.email)
+			} : values);
+			return prepared;
+		},
+		async prepareUserDeletions(uids) {
+			await assertUserDeletionsAllowed(authRepo, uids);
+			if (resolvedHooks.beforeUserDelete) for (const uid of uids) await resolvedHooks.beforeUserDelete(uid);
+		},
+		async finalizeUserDeletions(uids) {
+			for (const uid of uids) {
+				await authRepo.deleteAllRefreshTokensForUser(uid);
+				runAfterUserDelete(resolvedHooks, uid);
+			}
+		}
+	};
+}
 //#endregion
 //#region src/auth/token-revocation.ts
 /**
@@ -1080,7 +1414,75 @@ async function isAccessTokenRevoked(authRepo, payload) {
 		});
 		return false;
 	}
-	if (!validAfter) return false;
+	return issuedBefore(payload, validAfter);
+}
+/**
+* Is the account behind this verified access token still the one that may use
+* it — and with which roles?
+*
+* A verified signature says who the token was minted for, an hour ago at
+* most. This asks the database what has happened to that account since. Every
+* door that honours an access token — the data plane, the admin gates, the
+* realtime socket — asks it here, so they cannot disagree about it.
+*
+* They did. A deleted account read as "not revoked": the watermark lives on
+* the user row, so once the row was gone there was no watermark, and the
+* roles lookup answered `[]` rather than "nobody". A token its owner had
+* revoked came back to life when an administrator deleted the account, as an
+* authenticated principal with that uid, for the rest of its lifetime. MCP
+* refresh and personal API keys already treated a missing account as revoked;
+* the main door did not.
+*
+* Throws when the repository does. Unlike the watermark read on its own, this
+* one decides the roles a request runs with, so a failure is a refusal (the
+* callers answer 503) rather than a guess.
+*/
+async function judgeAccessToken(authRepo, payload) {
+	let roles;
+	let validAfter = null;
+	if (typeof authRepo.getAccountAccessState === "function") {
+		const state = await authRepo.getAccountAccessState(payload.uid, payload.sid);
+		if (!state) return {
+			live: false,
+			refusal: "account-deleted"
+		};
+		if (state.disabled) return {
+			live: false,
+			refusal: "account-disabled"
+		};
+		roles = state.roles;
+		validAfter = state.tokensValidAfter;
+		if (payload.sid && state.sessionActive === false) return {
+			live: false,
+			refusal: "session-revoked"
+		};
+	} else {
+		if (typeof authRepo.getUserWithRoles === "function") {
+			const account = await authRepo.getUserWithRoles(payload.uid);
+			if (!account) return {
+				live: false,
+				refusal: "account-deleted"
+			};
+			if (account.user.disabled) return {
+				live: false,
+				refusal: "account-disabled"
+			};
+			roles = account.roles;
+		}
+		if (typeof authRepo.getTokensValidAfter === "function") validAfter = await authRepo.getTokensValidAfter(payload.uid);
+	}
+	if (issuedBefore(payload, validAfter)) return {
+		live: false,
+		refusal: "revoked"
+	};
+	return {
+		live: true,
+		roles
+	};
+}
+/** The watermark comparison {@link isAccessTokenRevoked} and the judge share. */
+function issuedBefore(payload, validAfter) {
+	if (!validAfter || typeof payload.iat !== "number") return false;
 	return payload.iat < Math.floor(validAfter.getTime() / 1e3);
 }
 /**
@@ -1124,10 +1526,14 @@ async function revokeAllSessions(authRepo, uid) {
 * `test/password-change-revokes-sessions.test.ts` holds every route that sets a
 * password to this, and fails if anything but this function calls
 * `updatePassword`.
+*
+* `null` removes the password instead, for the same reason and with the same
+* revocation: see `confirmAddressOwnership`.
 */
 async function replaceUserPassword(authRepo, uid, passwordHash) {
 	await authRepo.updatePassword(uid, passwordHash);
 	await revokeAllSessions(authRepo, uid);
+	await authRepo.deleteAllPasswordResetTokensForUser?.(uid);
 }
 //#endregion
 //#region src/auth/rls-scope.ts
@@ -1255,59 +1661,221 @@ function extractBearerToken(authHeader) {
 	return authHeader.slice(separator + 1);
 }
 //#endregion
-//#region src/auth/api-keys/api-key-middleware.ts
+//#region src/auth/access.ts
+var configured = EMPTY_ACCESS_MODEL;
+var keyOwners;
+/** The access model the running backend serves. Built-ins only until boot configures it. */
+function getAccessModel() {
+	return configured;
+}
 /**
-* Check whether a token looks like a Rebase API key.
+* How a personal key finds its owner, or undefined when personal keys are
+* off — in which case every personal key, however valid, is refused.
 */
-function isApiKeyToken(token) {
-	return token.startsWith("rk_");
+function getKeyOwnerResolver() {
+	return keyOwners;
 }
 /**
-* Hash a plaintext API key token for database lookup.
-*
-* Async because it hashes with WebCrypto rather than `node:crypto` — the sole
-* caller was already awaiting the store lookup this feeds.
+* Install the access model, and — when the app enables `auth.personalKeys`
+* and has an account store to read owners from — how personal keys find
+* their owner. Called once by `initializeRebaseBackend`.
 */
-function hashToken(token) {
-	return sha256Hex(token);
+function configureAccess(options) {
+	configured = options.model;
+	keyOwners = options.resolveKeyOwner;
 }
+/** The resource names Rebase's own scopes use; an app scope may not reuse one. */
+var BUILT_IN_RESOURCES = new Set(BUILT_IN_SCOPES.map((scope) => scope.slice(0, scope.indexOf(":"))));
+/** A declaration the access model cannot be built from. Fails the boot. */
+var AccessModelError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AccessModelError";
+	}
+};
 /**
-* Validate an API key token and populate the Hono context.
+* Build the access model from the users collection's `auth` block, refusing
+* anything that would read as a grant it is not.
+*
+* - `admin` may not be declared: it is built in and holds everything, and a
+*   declaration would either repeat that or quietly narrow it.
+* - An app scope may not reuse a built-in resource name (`logs:export`): the
+*   built-in resources are Rebase's, and a reader of `logs:*` should not have
+*   to know which half is whose.
+* - A role may not list a data-plane scope: a person's data access is the
+*   collection's `securityRules`, so `data:write` on a role would grant nothing
+*   and look like it granted something.
+*/
+function accessModelFromCollections(collections) {
+	const authCollection = collections.find((collection) => {
+		const auth = collection.auth;
+		return auth === true || !!auth && typeof auth === "object" && auth.enabled === true;
+	});
+	const auth = authCollection && typeof authCollection.auth === "object" ? authCollection.auth : void 0;
+	const declaredScopes = { ...auth?.scopes ?? {} };
+	const declaredRoles = { ...auth?.roles ?? {} };
+	const where = `the "${authCollection?.slug ?? "users"}" collection's auth block`;
+	for (const [name, definition] of Object.entries(declaredScopes)) {
+		const parsed = parseScope(name);
+		if (!parsed || parsed.target !== void 0) throw new AccessModelError(`auth.scopes: "${name}" in ${where} is not a scope name. Name scopes resource:action, lower-case, without a target — for example "project:deploy".`);
+		const resource = name.slice(0, name.indexOf(":"));
+		if (BUILT_IN_RESOURCES.has(resource)) throw new AccessModelError(`auth.scopes: "${name}" in ${where} uses the built-in resource "${resource}". App scopes need their own resource name; the built-in ones are ${[...BUILT_IN_RESOURCES].join(", ")}.`);
+		if (typeof definition?.label !== "string" || definition.label.trim() === "") throw new AccessModelError(`auth.scopes: "${name}" in ${where} needs a label — it is what a person granting it reads.`);
+	}
+	const model = {
+		roles: declaredRoles,
+		scopes: declaredScopes
+	};
+	for (const [role, definition] of Object.entries(declaredRoles)) {
+		if (role === "admin") throw new AccessModelError(`auth.roles: "admin" in ${where} is built in — it holds every scope — and cannot be declared. Declare a role with another name for a narrower set.`);
+		if (!Array.isArray(definition?.scopes)) throw new AccessModelError(`auth.roles: "${role}" in ${where} needs a scopes list.`);
+		const dataPlane = definition.scopes.filter((scope) => isDataPlaneScope(parseScope(scope)?.scope ?? ""));
+		if (dataPlane.length > 0) throw new AccessModelError(`auth.roles: "${role}" in ${where} lists ${dataPlane.join(", ")}. Every signed-in person already holds the data plane; what they may do with rows is the collection's securityRules. List admin-plane and app scopes only.`);
+		const problems = validateScopes(definition.scopes, model);
+		if (problems.length > 0) throw new AccessModelError(`auth.roles: "${role}" in ${where} lists ${problems.map((p) => `"${p.scope}" (${p.reason})`).join(", ")}. Role scopes are ${ADMIN_SCOPES.join(", ")} and the app's own auth.scopes.`);
+	}
+	return model;
+}
+/** Narrow a context's user to the roles it carries. */
+function rolesOf(user) {
+	if (typeof user !== "object" || user === null || !("roles" in user)) return [];
+	const roles = user.roles;
+	return Array.isArray(roles) ? roles.filter((role) => typeof role === "string") : [];
+}
+/**
+* Everything the caller of this request may do. Empty for a request with no
+* caller.
+*/
+function callerScopes(c) {
+	const narrowed = c.get("scopes");
+	if (narrowed) return narrowed;
+	const user = c.get("user");
+	if (!user) return [];
+	return scopesForRoles(rolesOf(user), configured);
+}
+/** Does this request's caller hold `scope`, on `target` when one is given? */
+function hasScope(c, scope, target) {
+	return scopeGrants(callerScopes(c), scope, target);
+}
+/**
+* The refusal for a missing scope, worded for whoever is holding the
+* credential. `details.requiredScope` names it for clients that branch.
+*/
+function scopeMissing(c, scope, target) {
+	const wanted = target !== void 0 ? `${scope}:${target}` : scope;
+	return new ApiError(403, "SCOPE_MISSING", c.get("apiKey") !== void 0 ? `This API key does not hold the "${wanted}" scope. Create a key that includes it.` : c.get("scopes") ? `This token does not hold the "${wanted}" scope. Reconnect and grant it.` : `Your account does not hold the "${wanted}" scope. A role that lists it (auth.roles on the users collection) grants it; the admin role holds every scope.`, { requiredScope: wanted });
+}
+/**
+* Refuse a request whose caller does not hold `scope`.
 *
-* Returns `true` if the key is valid and context has been populated,
-* or returns an error Response if the key is invalid.
+* `target` narrows the check to one collection, bucket, function or app
+* resource, and may be read from the request. Mount after authentication: a
+* request with no caller is refused as unauthenticated, not as unscoped.
 *
-* This is NOT a standalone middleware — it's called from within
-* `createAuthMiddleware()` when a `rk_` prefixed token is detected.
+* @example
+* ```ts
+* app.post("/deploy/:project", requireScope("project:deploy", c => c.req.param("project")), handler);
+* ```
 */
-async function validateApiKey(c, token, options) {
-	const { store, driver } = options;
-	const hash = await hashToken(token);
-	const apiKey = await store.findByKeyHash(hash);
-	if (!apiKey) return c.json({ error: {
-		message: "Invalid API key",
-		code: "UNAUTHORIZED"
-	} }, 401);
-	if (apiKey.revoked_at) return c.json({ error: {
-		message: "API key has been revoked",
-		code: "UNAUTHORIZED"
-	} }, 401);
-	if (apiKey.expires_at && new Date(apiKey.expires_at) < /* @__PURE__ */ new Date()) return c.json({ error: {
-		message: "API key has expired",
-		code: "UNAUTHORIZED"
-	} }, 401);
-	const uid = `api-key:${apiKey.id}`;
-	const roles = apiKey.admin ? ["admin", "service"] : ["service"];
-	c.set("user", {
-		uid,
-		roles
-	});
+function requireScope(scope, target) {
+	return async (c, next) => {
+		if (!c.get("user")) return refuse(c, ApiError.unauthenticated("Authentication required"));
+		const resolvedTarget = typeof target === "function" ? target(c) : target;
+		if (!hasScope(c, scope, resolvedTarget)) return refuse(c, scopeMissing(c, scope, resolvedTarget));
+		return next();
+	};
+}
+/**
+* Refuse a request unless its caller holds the scope for its HTTP method:
+* `read` for GET and HEAD, `write` for everything else. For an admin surface
+* whose reads and writes split exactly along the method.
+*/
+function requireScopeByMethod(scopes) {
+	const read = requireScope(scopes.read);
+	const write = requireScope(scopes.write);
+	return async (c, next) => {
+		const method = c.req.method.toUpperCase();
+		return (method === "GET" || method === "HEAD" ? read : write)(c, next);
+	};
+}
+/**
+* What a set of roles holds beyond this request's caller — the scopes, plus
+* `admin` itself when the roles include it and the caller does not hold it.
+* Empty when the caller covers every one.
+*
+* `admin` is named separately because it is more than its scopes: it is the
+* RLS role that reads every row, so a role listing every admin-plane scope
+* still cannot hand it out.
+*/
+function beyondCaller(c, roles) {
+	const beyond = scopesBeyond(scopesForRoles(roles, configured), callerScopes(c));
+	if (hasAdminRole(roles) && !hasAdminRole(rolesOf(c.get("user")))) beyond.unshift(ADMIN_ROLE);
+	return beyond;
+}
+/**
+* Refuse to let the caller act on an account — edit it, reset its password,
+* delete it — when that account holds anything the caller does not.
+*
+* `users:write` is the scope that lets a support role manage accounts, and
+* without this it would also let that role reset an administrator's password
+* and sign in as them.
+*/
+function assertMayManageAccount(c, targetRoles) {
+	const beyond = beyondCaller(c, targetRoles);
+	if (beyond.length > 0) throw new ApiError(403, "ACCOUNT_OUTRANKS_CALLER", `This account holds ${beyond.join(", ")}, which you do not, so you cannot change it.`, { beyond });
+}
+/** Refuse to let the caller grant roles that hold anything the caller does not. */
+function assertMayGrantRoles(c, roles) {
+	const beyond = beyondCaller(c, roles);
+	if (beyond.length > 0) throw new ApiError(403, "ROLE_EXCEEDS_CALLER", `These roles hold ${beyond.join(", ")}, which you do not, so you cannot grant them.`, { beyond });
+}
+//#endregion
+//#region src/auth/api-keys/api-key-middleware.ts
+/**
+* Check whether a token looks like a Rebase API key.
+*/
+function isApiKeyToken(token) {
+	return token.startsWith("rk_");
+}
+/**
+* Verify a presented key: it exists, is live, and — for a personal key —
+* personal keys are on and its owner still exists. Records the use.
+*/
+async function resolveApiKey(store, token) {
+	const apiKey = await store.findByKeyHash(await sha256Hex(token));
+	if (!apiKey) return { message: "Invalid API key" };
+	if (apiKey.revoked_at) return { message: "API key has been revoked" };
+	if (apiKey.expires_at && new Date(apiKey.expires_at) < /* @__PURE__ */ new Date()) return { message: "API key has expired" };
+	let identity;
+	if (apiKey.kind === "personal") {
+		const resolveOwner = getKeyOwnerResolver();
+		if (!resolveOwner || !apiKey.owner_uid) return { message: "Personal API keys are switched off on this backend" };
+		const owner = await resolveOwner(apiKey.owner_uid);
+		if (!owner) return { message: "The account this API key acts as no longer exists" };
+		identity = {
+			uid: apiKey.owner_uid,
+			roles: owner.roles,
+			scopes: intersectScopes(apiKey.scopes, scopesForRoles(owner.roles, getAccessModel()))
+		};
+	} else identity = {
+		uid: `api-key:${apiKey.id}`,
+		roles: ["service", ...apiKey.roles.filter((role) => role !== "service")],
+		scopes: apiKey.scopes
+	};
+	const lastTouch = lastUsedTouchedAt.get(apiKey.id);
+	const now = Date.now();
+	if (!lastTouch || now - lastTouch >= LAST_USED_DEBOUNCE_MS) {
+		lastUsedTouchedAt.set(apiKey.id, now);
+		store.updateLastUsed(apiKey.id).catch(() => {});
+	}
 	const masked = {
 		id: apiKey.id,
 		name: apiKey.name,
+		kind: apiKey.kind,
 		key_prefix: apiKey.key_prefix,
-		permissions: apiKey.permissions,
-		admin: apiKey.admin,
+		scopes: apiKey.scopes,
+		roles: apiKey.roles,
+		owner_uid: apiKey.owner_uid,
 		rate_limit: apiKey.rate_limit,
 		created_by: apiKey.created_by,
 		created_at: apiKey.created_at,
@@ -1316,87 +1884,84 @@ async function validateApiKey(c, token, options) {
 		expires_at: apiKey.expires_at,
 		revoked_at: apiKey.revoked_at
 	};
-	c.set("apiKey", masked);
+	return {
+		...identity,
+		apiKey: masked
+	};
+}
+/** Per-process debounce state for last_used_at touches. */
+var lastUsedTouchedAt = /* @__PURE__ */ new Map();
+var LAST_USED_DEBOUNCE_MS = 6e4;
+/**
+* Validate an API key token and populate the Hono context: `user`, `apiKey`,
+* `scopes` and the RLS-scoped `driver`.
+*
+* Returns `true` when the context is populated, or the error Response.
+*/
+async function validateApiKey(c, token, options) {
+	const resolved = await resolveApiKey(options.store, token);
+	if (!("uid" in resolved)) return errorHandler(ApiError.unauthenticated(resolved.message), c);
+	c.set("user", {
+		uid: resolved.uid,
+		roles: resolved.roles
+	});
+	c.set("apiKey", resolved.apiKey);
+	c.set("scopes", resolved.scopes);
 	try {
-		const scopedDriver = await scopeDataDriver(driver, {
-			uid,
-			roles
-		});
-		c.set("driver", scopedDriver);
+		c.set("driver", await scopeDataDriver(options.driver, {
+			uid: resolved.uid,
+			roles: resolved.roles
+		}));
 	} catch (error) {
 		logger.error("[AUTH] RLS scoping failed for API key", { error });
-		return c.json({ error: {
-			message: "Internal authentication error",
-			code: "INTERNAL_ERROR"
-		} }, 500);
-	}
-	const lastTouch = lastUsedTouchedAt.get(apiKey.id);
-	const now = Date.now();
-	if (!lastTouch || now - lastTouch >= LAST_USED_DEBOUNCE_MS) {
-		lastUsedTouchedAt.set(apiKey.id, now);
-		store.updateLastUsed(apiKey.id).catch(() => {});
+		return errorHandler(ApiError.internal("Internal authentication error"), c);
 	}
 	return true;
 }
-/** Per-process debounce state for last_used_at touches. */
-var lastUsedTouchedAt = /* @__PURE__ */ new Map();
-var LAST_USED_DEBOUNCE_MS = 6e4;
 /**
-* Shared 403 response for API-key permission denials outside the REST
-* generator (storage and functions guards). One envelope, one code — a
-* change to the error contract happens in one place.
+* The 403 for a credential that lacks a data-plane scope outside the REST
+* generator (storage and functions). Names the scope that would grant it.
 */
-function forbidApiKey(c, operation, resource, grantHint) {
-	return c.json({ error: {
-		message: `API key does not have "${operation}" permission for ${resource}. Grant it with a permission entry like { "collection": "${grantHint}", "operations": ["${operation}"] }.`,
-		code: "API_KEY_FORBIDDEN"
-	} }, 403);
+function forbidScope(c, scope, target) {
+	const wanted = target !== void 0 && target !== "" ? `${scope}:${target}` : scope;
+	return errorHandler(new ApiError(403, "SCOPE_MISSING", `This credential does not hold the "${wanted}" scope.`, { requiredScope: wanted }), c);
+}
+/** Whether this request's caller holds `scope` — on `target` when given. */
+function callerHolds(c, scope, target) {
+	const narrowed = c.get("scopes");
+	if (!narrowed) return true;
+	return target === void 0 ? scopeGrantsAny(narrowed, scope) : scopeGrants(narrowed, scope, target);
 }
 /**
-* Permission guard for API-key requests to the storage router.
+* Scope guard for the resumable-upload routes (`/tus/:id`).
 *
-* Storage previously did not accept API keys at all (`rk_` tokens were
-* misparsed as JWTs and 401'd). Now that the pre-auth middleware
-* authenticates them, this guard decides what they may do: the key needs a
-* `"storage"` permission entry (or the global `"*"` wildcard) covering the
-* operation derived from the HTTP method. Requests not authenticated via an
-* API key pass through to the storage router's own auth gates.
-*
-* TUS resumable-upload routes (`/tus`, `/tus/:id`) are classified as `write`
-* for EVERY method: the protocol's offset check is a GET and its cancel is a
-* DELETE, but both are steps of an upload — a write-scoped key must be able
-* to complete (and abort) its own resumable upload without also holding
-* `read`/`delete` on stored objects.
+* Every step of an upload — the offset check (HEAD), the chunks (PATCH), the
+* cancel (DELETE) — is part of writing it, so all of them need
+* `storage:write`. Which source the upload writes to was checked when it was
+* created; these steps only reach an upload the same caller owns.
 */
-function createStorageApiKeyGuard() {
+function createTusScopeGuard() {
 	return async (c, next) => {
-		const apiKey = c.get("apiKey");
-		if (!apiKey) return next();
-		const operation = /\/tus(\/|$)/.test(c.req.path) ? "write" : httpMethodToOperation(c.req.method);
-		if (!isStorageAllowed(apiKey.permissions, operation)) return forbidApiKey(c, operation, "storage", "storage");
+		if (/\/tus\/[^/]+$/.test(c.req.path) && c.get("user") && !callerHolds(c, "storage:write")) return forbidScope(c, "storage:write");
 		return next();
 	};
 }
 /**
-* Permission guard for API-key requests to the custom-functions router.
+* Scope guard for the custom-functions router: a narrowed credential needs
+* `functions:invoke` on the function it calls. The functions index — the
+* listing at the mount point itself — needs the unqualified scope.
 *
-* The collection permission guard lives in the REST generator and never sees
-* function routes, so before this middleware existed ANY valid API key —
-* however narrowly scoped — could invoke every custom function. This guard
-* closes that: API-key requests must hold a `"functions"`/`"functions/<name>"`
-* permission entry (or the global `"*"` wildcard) for the derived operation.
-*
-* Non-API-key requests (JWT, service key, anonymous) pass through untouched —
-* functions decide their own auth for those, as before.
+* People pass: what a person may do inside a function is the function's own
+* business, as it always was.
 *
 * @param mountPrefix - The path the functions router is mounted at
 *                      (e.g. `/api/functions`), used to extract the function
 *                      name from the request path.
 */
-function createFunctionApiKeyGuard(mountPrefix) {
+function createFunctionScopeGuard(mountPrefix) {
 	return async (c, next) => {
-		const apiKey = c.get("apiKey");
-		if (!apiKey) return next();
+		const narrowed = c.get("scopes");
+		if (!narrowed) return next();
 		const path = c.req.path;
 		const idx = path.indexOf(mountPrefix);
 		const rawName = (idx < 0 ? "" : path.slice(idx + mountPrefix.length)).split("/").filter(Boolean)[0] ?? "";
@@ -1406,21 +1971,17 @@ function createFunctionApiKeyGuard(mountPrefix) {
 		} catch {
 			functionName = rawName;
 		}
-		const operation = httpMethodToOperation(c.req.method);
-		if (!isFunctionAllowed(apiKey.permissions, functionName, operation)) return forbidApiKey(c, operation, functionName ? `function "${functionName}"` : "the functions index", `functions${functionName ? `/${functionName}` : ""}`);
+		if (!(functionName === "" ? scopeGrants(narrowed, "functions:invoke") : scopeGrants(narrowed, "functions:invoke", functionName))) return forbidScope(c, "functions:invoke", functionName);
 		return next();
 	};
 }
 /**
-* Standalone pre-auth middleware for `rk_` bearer tokens.
+* Pre-auth middleware for `rk_` bearer tokens.
 *
-* Routers whose auth gate is JWT-based (`requireAuth` / `createRequireAuth` —
-* the admin surfaces: admin users/roles, api-keys management, cron, backups,
-* logs, schema editor) don't know about API keys. Mounting this middleware in
-* front of them authenticates `rk_` tokens and populates the request context;
-* the downstream gates then see the already-resolved user and apply their
-* role checks (`requireAdmin`) as usual — so an `admin: true` key passes and
-* a non-admin key is rejected with 403.
+* Routers whose auth gate is JWT-based (`createRequireAuth` — the admin
+* surfaces, the key routes) don't know about API keys. Mounted in front of
+* them, this authenticates `rk_` tokens and populates the request context; the
+* downstream gates then see the already-resolved caller and check its scopes.
 *
 * Requests without an `rk_` bearer token pass through untouched. An invalid,
 * revoked, or expired `rk_` token is rejected here (401) rather than falling
@@ -1437,6 +1998,257 @@ function createApiKeyPreAuth(options) {
 	};
 }
 //#endregion
+//#region src/auth/impersonation.ts
+var ADMIN_ONLY = "Only a signed-in administrator can run a request as another user.";
+var NOT_A_PERSON = {
+	"api-key": {
+		reason: "api-key",
+		message: "An API key cannot run a request as another user. Send it with an administrator's session instead."
+	},
+	"service-key": {
+		reason: "service-key",
+		message: "The service key cannot run a request as another user. Send it with an administrator's session instead."
+	},
+	none: {
+		reason: "anonymous",
+		message: ADMIN_ONLY
+	}
+};
+/**
+* Decide whether this caller may act as the user they named, and who that
+* user is now.
+*
+* The one decision both doors take — the HTTP data plane through
+* {@link applyImpersonation}, the realtime socket at `AUTHENTICATE` and before
+* every frame after it. The caller is judged before the named user is looked
+* up, so the answer to a caller who may not impersonate says nothing about
+* whether the uid exists.
+*
+* Throws when a lookup fails: that is not an answer about anyone, and each
+* door refuses it its own way.
+*/
+async function decideImpersonation(request) {
+	const { credential, caller, resolveUser, audit } = request;
+	const targetUid = request.requestedUid.trim();
+	const refuse = (reason, error) => {
+		if (audit) logger.warn("[Security Audit] Refused a request to act as another user", {
+			eventType: "auth.impersonation.refused",
+			reason,
+			callerUid: caller?.uid,
+			requestedUid: targetUid,
+			...audit
+		});
+		return { refused: error };
+	};
+	if (targetUid === "") return refuse("malformed", ApiError.badRequest(`The ${IMPERSONATE_HEADER} header names no user. Send the uid of the user to act as, or leave the header out.`, "IMPERSONATION_INVALID"));
+	if (credential !== "session") {
+		const { reason, message } = NOT_A_PERSON[credential];
+		return refuse(reason, ApiError.forbidden(message, "IMPERSONATION_FORBIDDEN"));
+	}
+	if (!caller || !hasAdminRole(caller.roles)) return refuse("not-admin", ApiError.forbidden(ADMIN_ONLY, "IMPERSONATION_FORBIDDEN"));
+	if (!resolveUser) return refuse("unavailable", new ApiError(501, "IMPERSONATION_UNAVAILABLE", "This backend's auth cannot run a request as another user: its auth adapter does not implement resolveUser."));
+	const self = await resolveUser(caller.uid);
+	if (!self || !hasAdminRole(self.roles)) return refuse("not-admin", ApiError.forbidden(ADMIN_ONLY, "IMPERSONATION_FORBIDDEN"));
+	const target = await resolveUser(targetUid);
+	if (!target) return refuse("unknown-target", ApiError.notFound(`No active user has the id "${targetUid}", so there is nobody to run this request as.`, "IMPERSONATION_TARGET_NOT_FOUND"));
+	if (audit) logger.info("[Security Audit] Ran a request as another user", {
+		eventType: "auth.impersonation",
+		impersonatorUid: caller.uid,
+		targetUid: target.uid,
+		targetRoles: target.roles,
+		...audit
+	});
+	return {
+		granted: target,
+		impersonator: caller.uid
+	};
+}
+/** The caller the auth middleware put on the context, narrowed. */
+function callerOf(c) {
+	const user = c.get("user");
+	if (typeof user !== "object" || user === null) return void 0;
+	const uid = "uid" in user && typeof user.uid === "string" && user.uid !== "" ? user.uid : void 0;
+	if (uid === void 0) return void 0;
+	return {
+		uid,
+		roles: "roles" in user && Array.isArray(user.roles) ? user.roles.filter((role) => typeof role === "string") : []
+	};
+}
+/**
+* Honour or refuse this request's {@link IMPERSONATE_HEADER}.
+*
+* Called by the data-plane auth middlewares once the caller is on the context
+* and its driver is scoped. When the header names a user the caller may act
+* as, the context's `user` and `driver` are replaced with that user's and
+* `impersonator` names the caller.
+*
+* @returns The refusal to send, or `undefined` to carry on — as the caller
+*          when the header is absent, as the named user when it was granted.
+*/
+async function applyImpersonation(c, { credential, driver, resolveUser }) {
+	const requested = c.req.header(IMPERSONATE_HEADER);
+	if (requested === void 0) return void 0;
+	const caller = callerOf(c);
+	let decision;
+	try {
+		decision = await decideImpersonation({
+			requestedUid: requested,
+			credential,
+			caller,
+			resolveUser,
+			audit: {
+				door: "http",
+				method: c.req.method,
+				path: c.req.path,
+				requestId: c.get("requestId")
+			}
+		});
+	} catch (error) {
+		return errorHandler(error instanceof Error ? error : new Error(String(error)), c);
+	}
+	if ("refused" in decision) return errorHandler(decision.refused, c);
+	const target = decision.granted;
+	const isAnonymous = target.isAnonymous === true;
+	c.set("user", {
+		uid: target.uid,
+		email: target.email,
+		roles: target.roles,
+		isAnonymous
+	});
+	c.set("impersonator", { uid: decision.impersonator });
+	try {
+		c.set("driver", await scopeDataDriver(driver, {
+			uid: target.uid,
+			roles: target.roles,
+			isAnonymous,
+			...target.claims ? { claims: target.claims } : {}
+		}));
+	} catch (error) {
+		logger.error("[AUTH] RLS scoping failed for an impersonated request", { error });
+		return errorHandler(ApiError.internal("Internal authentication error"), c);
+	}
+}
+/**
+* Refuse {@link IMPERSONATE_HEADER} on every route that does not honour it.
+*
+* Only the data API and custom functions run a request as another user; the
+* rest — storage, auth, the admin surfaces — authenticate the caller and
+* ignore the header. Ignored, a request asking to act as B would be answered
+* as the administrator who sent it, which is the one outcome impersonation
+* must never have. Mounted ahead of every route, so a surface added later is
+* refused until it is listed here as honouring the header.
+*
+* @param honouredMounts - The mount points whose auth middleware applies the
+*        header (`/api/data`, `/api/functions`). A path is under one when it
+*        is the mount itself or continues it with a `/`.
+*/
+function refuseUnhonouredImpersonation(honouredMounts) {
+	return async (c, next) => {
+		if (c.req.header("x-rebase-impersonate") === void 0) return next();
+		const path = c.req.path;
+		if (honouredMounts.some((mount) => path === mount || path.startsWith(`${mount}/`))) return next();
+		logger.warn("[Security Audit] Refused a request to act as another user", {
+			eventType: "auth.impersonation.refused",
+			reason: "unsupported-route",
+			method: c.req.method,
+			path,
+			requestId: c.get("requestId")
+		});
+		return errorHandler(ApiError.badRequest(`This route cannot run as another user, so it refuses the ${IMPERSONATE_HEADER} header. Only the data API and custom functions honour it.`, "IMPERSONATION_UNSUPPORTED"), c);
+	};
+}
+//#endregion
+//#region src/storage/requested-object.ts
+/**
+* Which object a storage request's URL path names.
+*
+* Three parties read the path of a `GET /file/*`, `GET /metadata/*` or
+* `DELETE /file/*`: the route, which serves or deletes an object;
+* `publicObjectAuth`, which lets an anonymous caller through when that object
+* is public; and `fileTokenAuth`, which compares it with the path a download
+* token grants. A decision is only about the object acted on if it is made on
+* the same key, so all three derive it here — the wildcard, the decoding, the
+* bucket segment and the canonical key — and none of them spells a step of its
+* own.
+*
+* They used to. `publicObjectAuth` judged the raw path with a check that strips
+* everything up to a `://`, while the route canonicalized it, folding `//` to
+* `/`: `GET /file/notes://public/secret.txt` was public to the one and served
+* the private key `notes:/public/secret.txt` from the other, with the authorize
+* hook never asked.
+*
+* Nothing here parses a scheme. A request path is a key, optionally behind the
+* one bucket segment the routes recognise; a `://` in it is a `:` followed by
+* an empty segment, and canonicalization folds the empty segment away.
+*/
+/**
+* The wildcard part of a storage route's path, still percent-encoded.
+*
+* Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
+* via `app.route(prefix, subRouter)`. Instead it is derived from the
+* fully-resolved `c.req.path` and `c.req.routePath`.
+*
+* For a route `/metadata/*` mounted at `/api/storage`, a request to
+* `/api/storage/metadata/default/file.jpg` yields routePath
+* `/api/storage/metadata/*`. The prefix (everything before `/*`) is stripped,
+* plus one character for the trailing `/`, to obtain `default/file.jpg`.
+*/
+function storageRequestWildcard(c) {
+	const prefix = c.req.routePath.replace("/*", "");
+	const fullPath = c.req.path;
+	const idx = fullPath.indexOf(prefix);
+	if (idx < 0) return "";
+	return fullPath.substring(idx + prefix.length + 1);
+}
+/**
+* The object a decoded path names: a key, behind an optional `default/` bucket
+* segment (matched case-insensitively). Throws {@link InvalidStorageKeyError}
+* when the key cannot be canonicalized.
+*
+* For a path that is already text — the folder route's JSON body. A URL path
+* goes through {@link requestedStorageObject}, which decodes it first.
+*/
+function storageObjectOfPath(decodedPath) {
+	const parts = decodedPath.split("/");
+	return {
+		bucket: "default",
+		key: canonicalStorageKey(parts.length > 1 && parts[0].toLowerCase() === "default" ? parts.slice(1).join("/") : decodedPath)
+	};
+}
+/**
+* The object a request's wildcard path names, or {@link InvalidStorageKeyError}.
+*
+* The wildcard arrives as Hono leaves it — `decodeURI`d, with the reserved
+* characters (`/`, `:`, `%25` among them) still escaped — so one
+* `decodeURIComponent` yields the path the client encoded. A `%` that does not
+* begin an escape names no key, and is refused like any other key that cannot be
+* canonicalized rather than thrown as a `URIError`.
+*/
+function requestedStorageObject(wildcard) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(wildcard);
+	} catch {
+		throw new InvalidStorageKeyError("Storage path is not valid percent-encoding: a '%' must begin an escape such as '%25' (a literal '%').");
+	}
+	return storageObjectOfPath(decoded);
+}
+/**
+* {@link requestedStorageObject}, or `null` when the path names no object.
+*
+* For the middleware, which must fail closed without an exception: a path that
+* names no object is neither public nor covered by any download token, and the
+* route answers it with a 400 of its own.
+*/
+function tryRequestedStorageObject(wildcard) {
+	try {
+		return requestedStorageObject(wildcard);
+	} catch (err) {
+		if (err instanceof InvalidStorageKeyError) return null;
+		throw err;
+	}
+}
+//#endregion
 //#region src/auth/middleware.ts
 /**
 * Answer a refusal with the canonical envelope, through the same formatter
@@ -1509,10 +2321,15 @@ function createRequireAuth(options) {
 		const payload = await verifyAccessToken(token);
 		if (!payload) return refuse(c, ApiError.unauthenticated("Invalid or expired token"));
 		if (resolveRoles || revocationRepo) try {
-			if (revocationRepo && await isAccessTokenRevoked(revocationRepo, payload)) return refuse(c, ApiError.unauthorized("Session has been revoked", "SESSION_REVOKED"));
+			let judgedRoles;
+			if (revocationRepo) {
+				const verdict = await judgeAccessToken(revocationRepo, payload);
+				if (!verdict.live) return refuse(c, verdict.refusal === "account-disabled" ? ApiError.unauthorized("This account has been disabled", "ACCOUNT_DISABLED") : ApiError.unauthorized(verdict.refusal === "account-deleted" ? "This account no longer exists" : "Session has been revoked", "SESSION_REVOKED"));
+				judgedRoles = verdict.roles;
+			}
 			c.set("user", resolveRoles ? {
 				...payload,
-				roles: await resolveRoles(payload.uid)
+				roles: judgedRoles ?? await resolveRoles(payload.uid)
 			} : payload);
 			return next();
 		} catch (error) {
@@ -1530,13 +2347,17 @@ function createRequireAuth(options) {
 	};
 }
 /**
-* Middleware that requires the user to have an admin or schema-admin role.
-* Must be used AFTER requireAuth or on a route where user is guaranteed.
+* Middleware that requires the user to hold the `admin` role, which holds
+* every scope. Must be used AFTER requireAuth or on a route where user is
+* guaranteed.
+*
+* Prefer `requireScope` from `./access` for anything a scope names: a scope
+* can be granted to a narrower role and to a key, and `admin` cannot.
 */
 var requireAdmin = async (c, next) => {
 	const user = c.get("user");
 	if (!user) return refuse(c, ApiError.unauthorized("User not authenticated. requireAuth middleware is missing?"));
-	if (!hasAdministrativeRole(typeof user === "object" && user !== null && "roles" in user ? user.roles || [] : [])) return refuse(c, ApiError.forbidden("Admin privileges required for this operation"));
+	if (!hasAdminRole(typeof user === "object" && user !== null && "roles" in user && Array.isArray(user.roles) ? user.roles.filter((role) => typeof role === "string") : [])) return refuse(c, ApiError.forbidden("Admin privileges required for this operation"));
 	return next();
 };
 /**
@@ -1584,12 +2405,14 @@ function createAuthMiddleware(options) {
 	const { driver: baseDriver, resolveDriver, requireAuth: enforceAuth = true, validator, serviceKey, apiKeyStore } = options;
 	return async (c, next) => {
 		const driver = resolveDriver ? resolveDriver(c) : baseDriver;
+		let credential = "none";
 		if (validator) try {
 			const authResult = await validator(c);
 			if (authResult && typeof authResult === "object") {
 				const id = "uid" in authResult ? authResult.uid : void 0;
 				if (id) {
 					const roles = authResult.roles || [];
+					credential = "session";
 					c.set("user", {
 						uid: id,
 						roles
@@ -1605,6 +2428,7 @@ function createAuthMiddleware(options) {
 					roles: ["anon"]
 				}));
 			} else if (authResult === true) {
+				credential = "session";
 				c.set("user", {
 					uid: "default",
 					roles: []
@@ -1623,10 +2447,12 @@ function createAuthMiddleware(options) {
 		else {
 			const token = extractBearerToken(c.req.header("authorization"));
 			if (token !== void 0) if (serviceKey && safeCompare(token, serviceKey)) {
-				c.set("user", {
+				const serviceUser = {
 					uid: "service",
 					roles: ["admin"]
-				});
+				};
+				credential = "service-key";
+				c.set("user", serviceUser);
 				try {
 					c.set("driver", await scopeDataDriver(driver, {
 						uid: "service",
@@ -1645,9 +2471,11 @@ function createAuthMiddleware(options) {
 					driver
 				});
 				if (result !== true) return result;
+				credential = "api-key";
 			} else {
 				const payload = await extractUserFromToken(token);
 				if (payload) {
+					credential = "session";
 					c.set("user", payload);
 					try {
 						const user = {
@@ -1679,6 +2507,11 @@ function createAuthMiddleware(options) {
 				} }, 500);
 			}
 		}
+		const refused = await applyImpersonation(c, {
+			credential,
+			driver
+		});
+		if (refused) return refused;
 		if (enforceAuth && !c.get("user")) return refuse(c, ApiError.unauthenticated("Unauthorized: Authentication required. This is the API-level gate, not a row rule — a collection granting public reads still needs a caller. Set AUTH_REQUIRE=false (or `auth.requireAuth: false`) to let RLS alone decide."));
 		return next();
 	};
@@ -1719,14 +2552,19 @@ var queryTokenAuth = async (c, next) => {
 * requested object path is public, it sets a minimal "public" principal so the
 * downstream `requireAuth` gate lets the read through. Private paths are left
 * untouched, so they still require a valid token.
+*
+* Public means the object the route will serve is public, so the decision is
+* made on that object's canonical key, derived by the route's own function
+* (`requestedStorageObject`). It used to be made on the raw path, through a
+* check that strips a `scheme://`: `notes://public/secret.txt` read as
+* `public/secret.txt` here while the route served the private
+* `notes:/public/secret.txt`, and the authorize hook — not asked about this
+* principal — never saw it.
 */
 var publicObjectAuth = async (c, next) => {
 	if (c.get("user")) return next();
-	const prefix = c.req.routePath.replace("/*", "");
-	const fullPath = c.req.path;
-	const idx = fullPath.indexOf(prefix);
-	const rawPath = idx < 0 ? "" : fullPath.substring(idx + prefix.length + 1);
-	if (rawPath && isPublicStoragePath(decodeURIComponent(rawPath))) c.set("user", {
+	const requested = tryRequestedStorageObject(storageRequestWildcard(c));
+	if (requested && isPublicStorageKey(requested.key)) c.set("user", {
 		uid: "public",
 		roles: ["public"]
 	});
@@ -1750,7 +2588,7 @@ var publicObjectAuth = async (c, next) => {
 * Hono routes the request, so this comparison already runs on a resolved path.
 * But that is a guarantee of the runtime rather than of this code, and it is
 * one line to not depend on it. The same rule already guards the public-object
-* path — see `isPublicStoragePath`.
+* path — see `isPublicStorageKey`.
 */
 function isPathMatch(requested, allowed) {
 	if (requested.split("/").some((seg) => seg === "..")) return false;
@@ -1767,34 +2605,6 @@ var fileTokenAuth = async (c, next) => {
 	const isFileRoute = c.req.path.includes("/storage/file/");
 	const authHeader = c.req.header("authorization");
 	const queryToken = c.req.query("token");
-	const extractWildcard = (ctx) => {
-		const prefix = ctx.req.routePath.replace("/*", "");
-		const fullPath = ctx.req.path;
-		const idx = fullPath.indexOf(prefix);
-		if (idx < 0) return "";
-		return fullPath.substring(idx + prefix.length + 1);
-	};
-	/**
-	* Must agree with `parseBucketAndPath` in `storage/routes.ts`, because the
-	* path a token GRANTS is minted there and the path a request ASKS FOR is
-	* derived here. `/metadata` canonicalizes before signing, so a raw
-	* comparison here would 403 an otherwise-valid request for any key whose
-	* URL form is not already canonical (`a//b.txt`, `a/./b.txt`).
-	*
-	* A key that cannot be canonicalized yields null, which matches no grant —
-	* the same fail-closed answer `isPathMatch` gives a `..` segment.
-	*/
-	const parseBucketPath = (filePath) => {
-		const parts = filePath.split("/");
-		if (parts.length > 1 && parts[0].toLowerCase() === "default") return {
-			bucket: "default",
-			resolvedPath: tryCanonicalStorageKey(parts.slice(1).join("/"))
-		};
-		return {
-			bucket: "default",
-			resolvedPath: tryCanonicalStorageKey(filePath)
-		};
-	};
 	/**
 	* Decide what a valid download token entitles this request to.
 	*
@@ -1809,11 +2619,11 @@ var fileTokenAuth = async (c, next) => {
 	*/
 	const evaluateGrant = (payload) => {
 		if (canonicalStorageId(c.req.query("storageId")) !== payload.storageId) return "deny-storage";
-		const rawPath = extractWildcard(c);
+		const rawPath = storageRequestWildcard(c);
 		if (!rawPath) return "no-path";
-		const { bucket, resolvedPath } = parseBucketPath(decodeURIComponent(rawPath));
-		if (resolvedPath === null) return "deny-path";
-		return isPathMatch(`${bucket}/${resolvedPath}`, payload.path) ? "grant" : "deny-path";
+		const requested = tryRequestedStorageObject(rawPath);
+		if (requested === null) return "deny-path";
+		return isPathMatch(`${requested.bucket}/${requested.key}`, payload.path) ? "grant" : "deny-path";
 	};
 	/**
 	* Which half of the scope failed is named in the message. The holder of the
@@ -1873,15 +2683,20 @@ function createAdapterAuthMiddleware(options) {
 					store: apiKeyStore,
 					driver
 				});
-				if (result === true) return next();
-				return result;
+				if (result !== true) return result;
+				const refused = await applyImpersonation(c, {
+					credential: "api-key",
+					driver
+				});
+				if (refused) return refused;
+				return next();
 			}
 		}
 		let authenticatedUser = null;
 		try {
 			authenticatedUser = await adapter.verifyRequest(c.req.raw);
 		} catch (error) {
-			return refuse(c, ApiError.unauthenticated("Unauthorized"));
+			return refuse(c, error instanceof ApiError && error.statusCode >= 400 ? error : ApiError.unauthenticated("Unauthorized"));
 		}
 		if (authenticatedUser) {
 			c.set("user", {
@@ -1894,7 +2709,8 @@ function createAdapterAuthMiddleware(options) {
 				c.set("driver", await scopeDataDriver(driver, {
 					uid: authenticatedUser.uid,
 					roles: authenticatedUser.roles,
-					isAnonymous: authenticatedUser.isAnonymous === true
+					isAnonymous: authenticatedUser.isAnonymous === true,
+					...authenticatedUser.claims ? { claims: authenticatedUser.claims } : {}
 				}));
 			} catch (error) {
 				logger.error("[AUTH-ADAPTER] RLS scoping failed for authenticated user", { error });
@@ -1912,6 +2728,12 @@ function createAdapterAuthMiddleware(options) {
 				return refuse(c, ApiError.internal("Server configuration error"));
 			}
 		}
+		const refused = await applyImpersonation(c, {
+			credential: !authenticatedUser ? "none" : authenticatedUser.uid === SERVICE_IDENTITY.uid ? "service-key" : "session",
+			driver,
+			resolveUser: adapter.resolveUser ? adapter.resolveUser.bind(adapter) : void 0
+		});
+		if (refused) return refused;
 		if (enforceAuth && !c.get("user")) return refuse(c, ApiError.unauthenticated("Unauthorized: Authentication required. This is the API-level gate, not a row rule — a collection granting public reads still needs a caller. Set AUTH_REQUIRE=false (or `auth.requireAuth: false`) to let RLS alone decide."));
 		return next();
 	};
@@ -1962,6 +2784,7 @@ async function verifyPassword(password, storedHash) {
 	if (!saltHex || !hashHex) return false;
 	const salt = Buffer.from(saltHex, "hex");
 	const storedKey = Buffer.from(hashHex, "hex");
+	if (storedKey.length !== KEY_LENGTH) return false;
 	return timingSafeEqual(await scryptAsync(password, salt, KEY_LENGTH, SCRYPT_PARAMS), storedKey);
 }
 //#endregion
@@ -2011,76 +2834,49 @@ async function verifyPassword(password, storedHash) {
 * This is the single point where defaults are applied — all consumers
 * call this once and use the resolved hooks throughout.
 */
-function resolveAuthHooks(hooks) {
-	return {
-		...hooks,
-		hashPassword: hooks?.hashPassword ?? hashPassword,
-		verifyPassword: hooks?.verifyPassword ?? verifyPassword,
-		validatePasswordStrength: hooks?.validatePasswordStrength ?? validatePasswordStrength
-	};
-}
-//#endregion
-//#region src/email/link-base.ts
-/**
-* The config fields consulted for each link kind, most specific first.
-*
-* `resetPasswordUrl` is the general fallback because it is the only one any boot
-* path sets, and in every real deployment all three point at the same frontend.
-*/
-var LINK_BASE_FIELDS = {
-	resetPassword: ["resetPasswordUrl"],
-	verifyEmail: ["verifyEmailUrl", "resetPasswordUrl"],
-	magicLink: ["magicLinkUrl", "resetPasswordUrl"]
-};
 /**
-* True when `value` is an absolute `http(s)` URL — the only kind a mail client
-* can follow. A protocol-relative or path-only base is treated as missing.
-*/
-function isAbsoluteHttpUrl(value) {
-	try {
-		const url = new URL(value);
-		return url.protocol === "http:" || url.protocol === "https:";
-	} catch {
-		return false;
-	}
-}
-/** Drop a trailing slash so callers can append `/verify-email?token=…`. */
-function normalizeBase(value) {
-	return value.replace(/\/+$/, "");
-}
-/**
-* The absolute base URL for a link kind, or `""` when the config has none.
-*
-* Callers append their path to the result. `""` is only reachable on a config
-* that never went through {@link assertEmailLinkBases} — a hand-constructed
-* `SMTPEmailService` in a test, say — and is kept rather than thrown so that a
-* misconfiguration cannot turn a password-reset request into a 500 that
-* distinguishes existing accounts from missing ones.
-*/
-function resolveEmailLinkBase(config, kind) {
-	if (!config) return "";
-	for (const field of LINK_BASE_FIELDS[kind]) {
-		const value = config[field];
-		if (typeof value === "string" && isAbsoluteHttpUrl(value)) return normalizeBase(value);
-	}
-	return "";
+* What a hook's thrown error answers.
+*
+* The hooks that refuse (`beforeUserCreate`, `beforeLogin`,
+* `beforeUserDelete`, `beforeEmailChange`) are documented as "throw to reject", and a plain
+* `Error` is what people throw. It reached the error handler as a 500
+* "Internal Server Error", so a deployment that limits sign-ups to its own
+* domain answered an outsider with a server fault. A refusal is the caller's
+* answer: 400 `HOOK_REJECTED` with the hook's message — or the status an
+* error carries, when the hook chose one (`ApiError`, or any error with a 4xx
+* `status`/`statusCode`).
+*/
+function hookRefusal(error, hook) {
+	if (error instanceof ApiError) return error;
+	const carried = typeof error === "object" && error !== null ? "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : "status" in error && typeof error.status === "number" ? error.status : void 0 : void 0;
+	const status = carried !== void 0 && carried >= 400 && carried < 500 ? carried : 400;
+	const ownCode = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && /^[A-Z][A-Z0-9_]+$/.test(error.code) ? error.code : void 0;
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : `${hook} refused the request`;
+	if (status === 400 && !ownCode) return ApiError.badRequest(message, "HOOK_REJECTED", { hook });
+	return new ApiError(status, ownCode ?? "HOOK_REJECTED", message, { hook });
+}
+/** A refusing hook whose throw answers as {@link hookRefusal} says. */
+function refusable(hook, fn) {
+	if (!fn) return void 0;
+	return async (...args) => {
+		try {
+			return await fn(...args);
+		} catch (error) {
+			throw hookRefusal(error, hook);
+		}
+	};
 }
-/**
-* Throw when an email configuration cannot produce a followable link.
-*
-* Called from `createEmailService`, i.e. from every boot path that wires email
-* up (the managed runtime, both driver bootstrappers, and any app that passes
-* `auth.email`). A base that is set but relative is reported separately from one
-* that is missing, because the two have different fixes.
-*/
-function assertEmailLinkBases(config) {
-	const relative = [
-		"resetPasswordUrl",
-		"verifyEmailUrl",
-		"magicLinkUrl"
-	].filter((field) => typeof config[field] === "string" && config[field] !== "" && !isAbsoluteHttpUrl(config[field]));
-	if (relative.length > 0) throw new Error(`Email is configured with a relative link base: ${relative.map((f) => `email.${f}`).join(", ")}. Emailed links must be absolute (e.g. "https://app.example.com") — a mail client has no base document to resolve a relative href against, so the link is dead.`);
-	if (!resolveEmailLinkBase(config, "resetPassword") && !resolveEmailLinkBase(config, "verifyEmail")) throw new Error("Email is configured but no base URL for emailed links is set. Password-reset, verification and magic-link emails would carry relative hrefs, which are dead links in every mail client. Set FRONTEND_URL (or `auth.email.resetPasswordUrl`) to an absolute URL such as \"https://app.example.com\".");
+function resolveAuthHooks(hooks) {
+	return {
+		...hooks,
+		beforeUserCreate: refusable("beforeUserCreate", hooks?.beforeUserCreate?.bind(hooks)),
+		beforeLogin: refusable("beforeLogin", hooks?.beforeLogin?.bind(hooks)),
+		beforeUserDelete: refusable("beforeUserDelete", hooks?.beforeUserDelete?.bind(hooks)),
+		beforeEmailChange: refusable("beforeEmailChange", hooks?.beforeEmailChange?.bind(hooks)),
+		hashPassword: hooks?.hashPassword ?? hashPassword,
+		verifyPassword: hooks?.verifyPassword ?? verifyPassword,
+		validatePasswordStrength: hooks?.validatePasswordStrength ?? validatePasswordStrength
+	};
 }
 //#endregion
 //#region src/email/smtp-email-service.ts
@@ -2136,16 +2932,32 @@ function normalizeMessageId(value) {
 var SMTPEmailService = class {
 	transporter = null;
 	config;
-	_initialized = false;
+	/**
+	* The transporter being built, shared by every send that arrives while it
+	* is.
+	*
+	* A flag set before the `await` said "initialised" while nodemailer was
+	* still loading, so a second send in that window found no transporter and
+	* threw "Email service not configured" — the first burst of mail after a
+	* boot lost every message but one. Every caller awaits this one promise
+	* instead. Cleared on failure, so one bad moment is not remembered for the
+	* life of the process.
+	*/
+	transporterReady = null;
 	constructor(config) {
 		this.config = config;
 	}
 	/**
 	* Lazily initialize the SMTP transporter on first use
 	*/
-	async ensureTransporter() {
-		if (this._initialized) return;
-		this._initialized = true;
+	ensureTransporter() {
+		if (!this.transporterReady) this.transporterReady = this.buildTransporter().catch((error) => {
+			this.transporterReady = null;
+			throw error;
+		});
+		return this.transporterReady;
+	}
+	async buildTransporter() {
 		if (this.config.smtp) {
 			const nodemailer = await loadNodemailer();
 			let smtpName = this.config.smtp.name;
@@ -2422,13 +3234,42 @@ function warnIfProxiedButUntrusted(hasForwardedFor) {
 	logger.warn("[RateLimit] Requests carry X-Forwarded-For but TRUSTED_PROXY_HOPS is 0, so it is being ignored and every client behind the proxy shares one rate-limit bucket. If this server really is behind a reverse proxy, set TRUSTED_PROXY_HOPS to the number of proxies in front of it (1 for a single ingress or load balancer). If it is exposed directly, this warning means someone is sending the header themselves and 0 is the correct setting.");
 }
 /**
+* The store this deployment shares its counts in, when it has one.
+*
+* Module state, because the limiters that read it are module constants: the
+* auth limiters are built at import time, before `initializeRebaseBackend`
+* has read `REBASE_RATE_LIMIT_STORE` or `rateLimit.store`, so they cannot be
+* handed the store the way the data limiter is. Without this they each kept a
+* private memory store whatever the deployment asked for, and on N replicas
+* every login, reset, OTP and MFA limit was N times looser than configured.
+*/
+var sharedRateLimitStore;
+/**
+* Point every named limiter at the deployment's shared store — or, with
+* `undefined`, back at its own memory. Called once per boot with the store
+* the data limiters use, and only when that store is shared (SQL, or one the
+* operator supplied): the default memory store is swept on the data window,
+* which is not every limiter's window.
+*/
+function setSharedRateLimitStore(store) {
+	sharedRateLimitStore = store;
+}
+/** The deployment's store under `name` when there is one, this limiter's own memory otherwise. */
+function namedStore(name, windowMs) {
+	const local = new MemoryRateLimitStore(windowMs);
+	return {
+		hit: (key, window, limit) => sharedRateLimitStore ? sharedRateLimitStore.hit(`${name}:${key}`, window, limit) : local.hit(key, window, limit),
+		dispose: () => local.dispose()
+	};
+}
+/**
 * Create a rate-limiting middleware.
 *
 * Uses a sliding window: only hits within the last `windowMs` are counted.
 */
 function createRateLimiter(options = {}) {
 	const trustedProxyHops = resolveTrustedProxyHops(options.trustedProxyHops);
-	const { windowMs = 900 * 1e3, limit = 100, keyGenerator = (c) => defaultKeyGenerator(c, trustedProxyHops), message = "Too many requests, please try again later.", store = new MemoryRateLimitStore(windowMs), resolveLimit } = options;
+	const { windowMs = 900 * 1e3, limit = 100, keyGenerator = (c) => defaultKeyGenerator(c, trustedProxyHops), message = "Too many requests, please try again later.", name, store = name ? namedStore(name, windowMs) : new MemoryRateLimitStore(windowMs), resolveLimit } = options;
 	return async (c, next) => {
 		const effectiveLimit = resolveLimit ? await resolveLimit(c) : limit;
 		if (effectiveLimit === null) return next();
@@ -2489,27 +3330,48 @@ function socketAddress(c) {
 * resort only, and it is a single shared bucket by design: better that
 * anonymous callers throttle each other than that any of them throttles nobody.
 */
+/**
+* Where a request comes from, as the rate limiters judge it: the socket's own
+* address, or — only behind as many proxies as `TRUSTED_PROXY_HOPS` declares —
+* the address they report. What a session row records as its IP, so the
+* sessions list shows the same address the limiter counted, rather than the
+* raw `X-Forwarded-For` (whose leftmost entry the caller chooses) or
+* `"unknown"` for every direct connection.
+*/
+function requestClientAddress(c) {
+	return defaultKeyGenerator(c);
+}
 function defaultKeyGenerator(c, trustedProxyHops = resolveTrustedProxyHops()) {
+	return clientAddress((name) => c.req.header(name), () => socketAddress(c), trustedProxyHops);
+}
+/**
+* {@link defaultKeyGenerator}'s rule, over a request's headers and connection
+* address rather than a Hono context — so a door that is not an HTTP request
+* (the realtime socket's upgrade request) reads the caller's address the same
+* way.
+*/
+function clientAddress(header, connectionAddress, trustedProxyHops) {
 	if (trustedProxyHops === 0) {
-		warnIfProxiedButUntrusted(!!c.req.header("x-forwarded-for"));
-		return socketAddress(c) ?? "unknown";
+		warnIfProxiedButUntrusted(!!header("x-forwarded-for"));
+		return connectionAddress() ?? "unknown";
 	}
 	{
-		const forwardedFor = c.req.header("x-forwarded-for");
+		const forwardedFor = header("x-forwarded-for");
 		if (forwardedFor) {
 			const ips = forwardedFor.split(",").map((s) => s.trim()).filter(Boolean);
 			if (ips.length > 0) return ips[Math.max(0, ips.length - trustedProxyHops)];
 		}
-		const realIp = c.req.header("x-real-ip");
+		const realIp = header("x-real-ip");
 		if (realIp) return realIp;
 	}
-	return socketAddress(c) ?? "unknown";
+	return connectionAddress() ?? "unknown";
 }
 /**
 * Pre-configured rate limiter for general auth endpoints (login, register).
 * 200 requests per 15 minutes per IP.
 */
 var defaultAuthLimiter = createRateLimiter({
+	name: "auth-default",
 	windowMs: 900 * 1e3,
 	limit: 200,
 	message: "Too many authentication attempts, please try again later."
@@ -2519,6 +3381,7 @@ var defaultAuthLimiter = createRateLimiter({
 * 50 requests per 15 minutes per IP.
 */
 var strictAuthLimiter = createRateLimiter({
+	name: "auth-strict",
 	windowMs: 900 * 1e3,
 	limit: 50,
 	message: "Too many requests to this sensitive endpoint, please try again later."
@@ -2577,6 +3440,7 @@ var captureRecipientEmail = async (c, next) => {
 * the limiter is never silently a no-op.
 */
 var recipientEmailLimiter = createRateLimiter({
+	name: "auth-recipient-email",
 	windowMs: 900 * 1e3,
 	limit: 5,
 	keyGenerator: (c) => {
@@ -2592,6 +3456,7 @@ async function notBefore$1(startedAt, floorMs, result) {
 	return result;
 }
 var verificationEmailLimiter = createRateLimiter({
+	name: "auth-verification-email",
 	windowMs: 900 * 1e3,
 	limit: 5,
 	keyGenerator: (c) => {
@@ -2632,8 +3497,9 @@ var DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3e3;
 * `enabled: false` rather than pay for it twice.
 */
 function createDataRateLimiter(config = {}) {
-	const { windowMs = 900 * 1e3, apiKey: apiKeyLimit = 1e3, user: userLimit = 1e3, anonymous: anonLimit = 300, store = new MemoryRateLimitStore(windowMs) } = config;
+	const { windowMs = 900 * 1e3, store = new MemoryRateLimitStore(windowMs) } = config;
 	const trustedProxyHops = resolveTrustedProxyHops(config.trustedProxyHops);
+	const bucketFor = dataRateLimitBuckets(config);
 	/**
 	* Who this request is, for bucketing only.
 	*
@@ -2659,30 +3525,98 @@ function createDataRateLimiter(config = {}) {
 		if (user?.uid) return isAnonymousUid(user.uid) ? void 0 : user.uid;
 		if (!isJwtConfigured()) return void 0;
 		const token = extractBearerToken(c.req.header("authorization"));
-		if (token === void 0) return void 0;
+		if (token === void 0) {
+			const queryToken = c.req.query("token");
+			if (!queryToken) return void 0;
+			const grant = await verifyDownloadToken(queryToken);
+			return grant?.rl ? `file:${grant.rl}` : void 0;
+		}
 		const payload = await verifyAccessToken(token);
 		if (!payload?.uid || isAnonymousUid(payload.uid)) return void 0;
 		return payload.uid;
 	};
+	const isServiceKey = (c) => {
+		if (!config.serviceKey) return false;
+		const token = extractBearerToken(c.req.header("authorization"));
+		return token !== void 0 && safeCompare(token, config.serviceKey);
+	};
+	const bucketOf = async (c) => {
+		if (c.get("user")?.uid === SERVICE_IDENTITY.uid) return null;
+		if (isServiceKey(c)) return null;
+		const apiKey = c.get("apiKey");
+		return bucketFor({
+			apiKey,
+			uid: apiKey ? void 0 : await identify(c),
+			address: () => defaultKeyGenerator(c, trustedProxyHops)
+		});
+	};
 	return createRateLimiter({
 		windowMs,
 		store,
 		message: "Too many requests, please try again later.",
-		keyGenerator: async (c) => {
-			const key = c.get("apiKey");
-			if (key) return `api-key:${key.id}`;
-			const uid = await identify(c);
-			if (uid) return `user:${uid}`;
-			return `ip:${defaultKeyGenerator(c, trustedProxyHops)}`;
-		},
-		resolveLimit: async (c) => {
-			if (c.get("user")?.uid === SERVICE_IDENTITY.uid) return null;
-			const key = c.get("apiKey");
-			if (key) return key.rate_limit ?? apiKeyLimit;
-			return await identify(c) ? userLimit : anonLimit;
-		}
+		keyGenerator: async (c) => (await bucketOf(c))?.key ?? `ip:${defaultKeyGenerator(c, trustedProxyHops)}`,
+		resolveLimit: async (c) => (await bucketOf(c))?.limit ?? null
 	});
 }
+/**
+* The data API's per-caller limit, as a check rather than a middleware — for
+* the door into the same data that is not an HTTP request.
+*
+* The realtime socket serves the rows the data API serves, one frame per
+* request. It counted them per connection only, so a caller bought more budget
+* by opening more sockets, and a frame never met the per-person limit its HTTP
+* twin does. Built from the same config and store as
+* {@link createDataRateLimiter}, it puts a caller in the same bucket under the
+* same key: one person's allowance, spent through either door.
+*/
+function createDataRateLimitCheck(config = {}) {
+	const { windowMs = 900 * 1e3, store = new MemoryRateLimitStore(windowMs) } = config;
+	const trustedProxyHops = resolveTrustedProxyHops(config.trustedProxyHops);
+	const bucketFor = dataRateLimitBuckets(config);
+	return async (caller) => {
+		if (caller.uid === SERVICE_IDENTITY.uid) return null;
+		const bucket = bucketFor({
+			apiKey: caller.apiKey,
+			uid: caller.uid !== void 0 && !isAnonymousUid(caller.uid) ? caller.uid : void 0,
+			address: () => clientAddress(caller.header, () => caller.socketAddress, trustedProxyHops)
+		});
+		return bucket ? store.hit(bucket.key, windowMs, bucket.limit) : null;
+	};
+}
+/**
+* Which bucket a data request counts in — the rule both doors share.
+*
+* Most specific first: an API key by its id, at its own `rate_limit`; a
+* signed-in user by their uid; anyone else by address at the anonymous
+* allowance, or not at all when that is `null`.
+*
+* The service key never reaches here: it is not a caller to bound. It is the
+* deployment's own credential and already reaches every row through
+* `SERVICE_IDENTITY`, so a limit on it protects nothing that is not already
+* open to whoever holds it — while reliably stopping the backfills,
+* migrations, imports and server-to-server jobs the key exists for, which
+* arrive as thousands of legitimate requests. A managed deployment has no
+* `rateLimit` surface to raise. Each door recognises it itself, where its
+* identity is known.
+*/
+function dataRateLimitBuckets(config) {
+	const { apiKey: apiKeyLimit = 1e3, user: userLimit = 1e3, anonymous: anonLimit = 300 } = config;
+	return (who) => {
+		if (who.apiKey) return {
+			key: `api-key:${who.apiKey.id}`,
+			limit: who.apiKey.rate_limit ?? apiKeyLimit
+		};
+		if (who.uid) return {
+			key: `user:${who.uid}`,
+			limit: userLimit
+		};
+		if (anonLimit === null) return null;
+		return {
+			key: `ip:${who.address()}`,
+			limit: anonLimit
+		};
+	};
+}
 //#endregion
 //#region src/auth/captcha.ts
 /**
@@ -3041,7 +3975,8 @@ function keyCandidates() {
 	add(process.env.MFA_ENCRYPTION_KEY, "MFA_ENCRYPTION_KEY");
 	for (const previous of (process.env.MFA_ENCRYPTION_KEY_PREVIOUS ?? "").split(",")) add(previous, "MFA_ENCRYPTION_KEY_PREVIOUS");
 	add(process.env.JWT_SECRET, "JWT_SECRET");
-	if (candidates.length === 0) throw new Error("Cannot encrypt or decrypt TOTP secrets: none of MFA_ENCRYPTION_KEY, MFA_ENCRYPTION_KEY_PREVIOUS or JWT_SECRET is configured.");
+	add(configuredJwtSecret(), "auth.jwtSecret");
+	if (candidates.length === 0) throw new Error("Cannot encrypt or decrypt TOTP secrets: none of MFA_ENCRYPTION_KEY, MFA_ENCRYPTION_KEY_PREVIOUS, JWT_SECRET or auth.jwtSecret is configured.");
 	if (!process.env.MFA_ENCRYPTION_KEY && !warnedAboutFallback) {
 		warnedAboutFallback = true;
 		logger.warn("[MFA-Crypto] MFA_ENCRYPTION_KEY is not set — falling back to JWT_SECRET. Set a dedicated MFA_ENCRYPTION_KEY for production; see the rotation steps in mfa-crypto.ts before you do it on a live deployment.");
@@ -3145,6 +4080,13 @@ function clearRefreshCookie(c, config) {
 }
 /**
 * Read the refresh token from the request — cookie first, then body fallback.
+*
+* An empty string is no token, wherever it comes from. In cookie mode every
+* response this server sends carries `refreshToken: ""` (see
+* `redactRefreshToken`), and a client that echoes it back — `@rebasepro/client`
+* did, on every refresh from a live tab — is presenting nothing. Taking the
+* body's `""` as the token, or refusing it at the schema, kept the cookie
+* beside it from ever being read.
 */
 function readRefreshToken(c, body, config) {
 	if (config) {
@@ -3154,10 +4096,13 @@ function readRefreshToken(c, body, config) {
 		const cookies = cookieHeader.split(";");
 		for (const part of cookies) {
 			const trimmed = part.trim();
-			if (trimmed.startsWith(prefix)) return decodeURIComponent(trimmed.slice(prefix.length));
+			if (trimmed.startsWith(prefix)) {
+				const fromCookie = decodeURIComponent(trimmed.slice(prefix.length));
+				if (fromCookie) return fromCookie;
+			}
 		}
 	}
-	return body.refreshToken;
+	return body.refreshToken || void 0;
 }
 /**
 * Redact the refresh token from the response body when cookie mode is active.
@@ -3226,7 +4171,8 @@ async function resolveStepUpPrincipal(c) {
 	if (existing?.uid) return {
 		uid: existing.uid,
 		aal: existing.aal === "aal2" ? "aal2" : "aal1",
-		pending: false
+		pending: false,
+		iat: existing.iat
 	};
 	const token = extractBearerToken(c.req.header("authorization"));
 	if (token === void 0) return null;
@@ -3234,13 +4180,15 @@ async function resolveStepUpPrincipal(c) {
 	if (session) return {
 		uid: session.uid,
 		aal: session.aal === "aal2" ? "aal2" : "aal1",
-		pending: false
+		pending: false,
+		iat: session.iat
 	};
 	const pending = await verifyMfaPendingToken(token);
 	if (pending) return {
 		uid: pending.uid,
 		aal: "aal1",
-		pending: true
+		pending: true,
+		iat: pending.iat
 	};
 	return null;
 }
@@ -3253,6 +4201,7 @@ async function resolveStepUpPrincipal(c) {
 * front of this one — they bound different things.
 */
 var mfaVerificationLimiter = createRateLimiter({
+	name: "auth-mfa-verify",
 	windowMs: 900 * 1e3,
 	limit: MFA_VERIFICATION_ATTEMPTS_PER_WINDOW,
 	keyGenerator: async (c) => `mfa-verify:${(await resolveStepUpPrincipal(c))?.uid ?? "unidentified"}`,
@@ -3263,6 +4212,26 @@ function mountMfaRoutes(opts) {
 	const authRepo = config.authRepo;
 	const emailConfig = config.emailConfig;
 	/**
+	* The caller of a challenge route, refused if the user has since ended
+	* every session.
+	*
+	* These two routes resolve their own caller, because a sign-in that
+	* answered `MFA_REQUIRED` has no session yet, and so they skipped the
+	* revocation mark that `requireLiveSession` checks everywhere else. A
+	* stolen access token that had enrolled its own factor (allowed at `aal1`
+	* while the account had none) kept working here after the victim signed
+	* out everywhere or changed their password, and the verify route then
+	* minted it a new session dated after the mark, which the mark could not
+	* reach. The pending token is a first factor accepted at its `iat`, so it
+	* is held to the same mark.
+	*/
+	async function resolveLiveStepUpPrincipal(c) {
+		const principal = await resolveStepUpPrincipal(c);
+		if (!principal) throw ApiError.unauthorized("Not authenticated");
+		if (!(await judgeAccessToken(authRepo, principal)).live) throw ApiError.unauthorized("Session has been revoked", "SESSION_REVOKED");
+		return principal;
+	}
+	/**
 	* Changing which factors an account trusts is itself a privileged act.
 	*
 	* An account that already has a verified factor may only gain or confirm
@@ -3312,9 +4281,11 @@ function mountMfaRoutes(opts) {
 		const { secret, uri } = generateTotpSecret(issuer, user.email);
 		const encryptedSecret = encryptTotpSecret(secret);
 		const factor = await authRepo.createMfaFactor(user.id, "totp", encryptedSecret, friendlyName);
-		const codes = generateRecoveryCodes(10);
-		const codeHashes = codes.map(hashRecoveryCode);
-		await authRepo.createRecoveryCodes(user.id, codeHashes);
+		let codes = null;
+		if (!await authRepo.hasVerifiedMfaFactors(user.id)) {
+			codes = generateRecoveryCodes(10);
+			await authRepo.createRecoveryCodes(user.id, codes.map(hashRecoveryCode));
+		}
 		return c.json({
 			factor: {
 				id: factor.id,
@@ -3330,6 +4301,24 @@ function mountMfaRoutes(opts) {
 		}, 201);
 	});
 	/**
+	* POST /auth/mfa/recovery-codes
+	* Replace the account's recovery codes with ten new ones, shown once.
+	*
+	* The deliberate way to get new codes — after using several, or after
+	* losing the printout. Needs `aal2` once a factor is verified, as every
+	* factor change does: whoever holds only the password must not be able to
+	* swap the codes for ones they know.
+	*/
+	router.post("/mfa/recovery-codes", strictAuthLimiter, requireLiveSession, async (c) => {
+		const userCtx = c.get("user");
+		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
+		if (!await authRepo.hasVerifiedMfaFactors(userCtx.uid)) throw ApiError.badRequest("This account has no verified second factor, so recovery codes would recover nothing.", "MFA_NOT_ENROLLED");
+		await requireStepUpForFactorChange(userCtx);
+		const codes = generateRecoveryCodes(10);
+		await authRepo.createRecoveryCodes(userCtx.uid, codes.map(hashRecoveryCode));
+		return c.json({ recoveryCodes: codes });
+	});
+	/**
 	* POST /auth/mfa/verify
 	* Verify TOTP code to complete MFA enrollment
 	*/
@@ -3359,14 +4348,13 @@ function mountMfaRoutes(opts) {
 	* `MFA_REQUIRED`, or to step an existing session up to `aal2`.
 	*/
 	router.post("/mfa/challenge", strictAuthLimiter, async (c) => {
-		const principal = await resolveStepUpPrincipal(c);
-		if (!principal) throw ApiError.unauthorized("Not authenticated");
+		const principal = await resolveLiveStepUpPrincipal(c);
 		const challengeSchema = z.object({ factorId: z.string().min(1, "Factor ID is required") });
 		const { factorId } = parseBody(challengeSchema, await c.req.json());
 		const factor = await authRepo.getMfaFactorById(factorId);
 		if (!factor || factor.uid !== principal.uid) throw ApiError.notFound("MFA factor not found");
 		if (!factor.verified) throw ApiError.badRequest("MFA factor is not yet verified", "FACTOR_NOT_VERIFIED");
-		const ipAddress = c.req.header("x-forwarded-for") || "unknown";
+		const ipAddress = requestClientAddress(c);
 		const challenge = await authRepo.createMfaChallenge(factorId, ipAddress);
 		return c.json({
 			challengeId: challenge.id,
@@ -3380,8 +4368,7 @@ function mountMfaRoutes(opts) {
 	* minted, at `aal2`.
 	*/
 	router.post("/mfa/challenge/verify", strictAuthLimiter, mfaVerificationLimiter, async (c) => {
-		const principal = await resolveStepUpPrincipal(c);
-		if (!principal) throw ApiError.unauthorized("Not authenticated");
+		const principal = await resolveLiveStepUpPrincipal(c);
 		const challengeVerifySchema = z.object({
 			challengeId: z.string().min(1, "Challenge ID is required"),
 			code: z.string().min(1, "Code is required")
@@ -3391,7 +4378,8 @@ function mountMfaRoutes(opts) {
 		if (!challenge) throw ApiError.badRequest("Invalid or expired challenge", "INVALID_CHALLENGE");
 		const factor = await authRepo.getMfaFactorById(challenge.factorId);
 		if (!factor || factor.uid !== principal.uid) throw ApiError.notFound("MFA factor not found");
-		if ((challenge.attempts ?? 0) >= MAX_CHALLENGE_ATTEMPTS) {
+		const attempts = (challenge.attempts ?? 0) >= MAX_CHALLENGE_ATTEMPTS ? 6 : typeof authRepo.recordMfaChallengeAttempt === "function" ? await authRepo.recordMfaChallengeAttempt(challengeId) : void 0;
+		if (attempts !== void 0 && attempts > MAX_CHALLENGE_ATTEMPTS) {
 			logger.warn("[Security Audit] MFA challenge attempt limit reached", {
 				eventType: "auth.mfa.challenge.exhausted",
 				uid: principal.uid,
@@ -3406,7 +4394,6 @@ function mountMfaRoutes(opts) {
 			isValid = await authRepo.useRecoveryCode(principal.uid, codeHash);
 		}
 		if (!isValid) {
-			const attempts = typeof authRepo.recordMfaChallengeAttempt === "function" ? await authRepo.recordMfaChallengeAttempt(challengeId) : void 0;
 			logger.warn("[Security Audit] MFA verification failed", {
 				eventType: "auth.mfa.verify.failure",
 				uid: principal.uid,
@@ -3416,10 +4403,17 @@ function mountMfaRoutes(opts) {
 			throw ApiError.unauthorized("Invalid verification code", "INVALID_CODE");
 		}
 		await authRepo.verifyMfaChallenge(challengeId);
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(principal.uid, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown", {
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(principal.uid, c.req.header("user-agent") || "unknown", requestClientAddress(c), {
 			skipMfaGate: true,
-			aal: "aal2"
+			aal: "aal2",
+			method: "mfa"
 		});
+		if (ops.onAuthenticated) {
+			const account = await authRepo.getUserById(principal.uid);
+			if (account) ops.onAuthenticated(account, "mfa").catch((err) => {
+				logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
+			});
+		}
 		if (ops.onMfaVerified) ops.onMfaVerified(principal.uid, factor.id).catch((err) => {
 			logger.error("[AuthHooks] onMfaVerified error", { error: err instanceof Error ? err.message : err });
 		});
@@ -3595,9 +4589,233 @@ function isAnonymousAuthOpen(policy) {
 	return !!policy.allowAnonymous;
 }
 //#endregion
+//#region src/auth/address-ownership.ts
+/**
+* What happens when the owner of an address proves it for the first time.
+*
+* Nothing verifies the address an account is made with: `POST /auth/register`
+* takes whatever it is given, and so does a sign-in through a provider that
+* does not vouch for the address (Spotify and Facebook never do; Discord and
+* multi-tenant Microsoft sometimes do not). So anyone can make an account for
+* someone else's address and leave a way in on it — a password, or the
+* provider identity they signed up with — then wait for the owner.
+*
+* The owner turns up by proving the address: a magic link, an email code or a
+* password reset, each read out of their inbox. That proof used to mark the
+* account verified and leave the attacker's way in where it was, so the owner
+* and the attacker shared the account from then on. Now the proof also removes
+* everything on the account that nobody proved: the password, every identity
+* whose provider did not vouch for this address, and every session.
+*
+* @module
+*/
+/**
+* The profile stored with a linked OAuth identity.
+*
+* `emailVerified` is recorded so that a later proof of the address can tell an
+* identity whose provider vouched for it from one whose provider did not.
+*/
+function identityProfileData(profile) {
+	return {
+		email: profile.email,
+		emailVerified: profile.emailVerified === true
+	};
+}
+/**
+* Did this identity's provider vouch for `email` when it was linked?
+*
+* Only whoever controls the inbox can hold a provider account that vouches for
+* the address, so such an identity is the owner's. An identity linked before
+* the flag was recorded reads as not vouching: it is detached, and if its
+* provider does vouch, the next sign-in with it links it again.
+*/
+function identityVouchesForAddress(identity, email) {
+	const profile = identity.profileData;
+	return profile?.emailVerified === true && typeof profile.email === "string" && normalizeEmail(profile.email) === normalizeEmail(email);
+}
+/**
+* Settle an account whose address its owner has just proven, and mark it
+* verified.
+*
+* Call it only for an account that is not yet verified, from a route that has
+* just consumed something mailed to the address. It detaches every identity
+* whose provider did not vouch for the address, sets the password to
+* `passwordHash` — the one the owner just chose on a reset, or `null` to remove
+* the one somebody else may have registered with — and ends every session, in
+* that order and before the account is marked verified.
+*
+* A repository that cannot detach an identity makes this refuse with 409 when
+* there is one to detach. Marking the account verified with the identity still
+* on it is the takeover itself, and leaving the account unverified while
+* signing the owner in would share the account all the same.
+*/
+async function confirmAddressOwnership(authRepo, user, passwordHash, options) {
+	if (options?.everythingProven) {
+		await authRepo.setEmailVerified(user.id, true);
+		return {
+			removedPassword: false,
+			removedProviders: []
+		};
+	}
+	const unproven = (await authRepo.getUserIdentities(user.id)).filter((identity) => !identityVouchesForAddress(identity, user.email));
+	if (unproven.length > 0) {
+		if (typeof authRepo.unlinkUserIdentity !== "function") {
+			logger.error("[Security Audit] Proof of address refused: the account has sign-in methods nobody proved, and this auth repository cannot remove them", {
+				eventType: "auth.address_proof.refused",
+				uid: user.id,
+				providers: unproven.map((identity) => identity.provider)
+			});
+			throw ApiError.conflict("This account has sign-in methods that were added before its email address was verified, and this backend cannot remove them. Ask an administrator to review the account.", "UNVERIFIED_IDENTITIES");
+		}
+		for (const identity of unproven) await authRepo.unlinkUserIdentity(user.id, identity.provider, identity.providerId);
+	}
+	await replaceUserPassword(authRepo, user.id, passwordHash);
+	await authRepo.setEmailVerified(user.id, true);
+	const outcome = {
+		removedPassword: Boolean(user.passwordHash) && passwordHash === null,
+		removedProviders: unproven.map((identity) => identity.provider)
+	};
+	if (unproven.length > 0 || user.passwordHash) logger.info("[Security Audit] First proof of address removed sign-in methods nobody proved", {
+		eventType: "auth.address_proof.cleared",
+		uid: user.id,
+		removedProviders: outcome.removedProviders,
+		replacedPassword: Boolean(user.passwordHash) && passwordHash !== user.passwordHash
+	});
+	return outcome;
+}
+//#endregion
+//#region src/auth/deliverable-address.ts
+/**
+* Addresses no mail can reach: the synthetic ones a guest and an X (Twitter)
+* account are given, because `email` is NOT NULL. Nothing is mailed to them,
+* and no account may move onto one.
+*/
+function isDeliverableAddress(email) {
+	const domain = email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+	return domain !== "anonymous.local" && domain !== "twitter.placeholder.rebase";
+}
+//#endregion
+//#region src/auth/email-change-routes.ts
+/** How long an address-change link stays usable. */
+var EMAIL_CHANGE_TTL_MS = 1440 * 60 * 1e3;
+function mountEmailChangeRoutes(opts) {
+	const { router, config, ops, parseBody, requireLiveSession } = opts;
+	const authRepo = config.authRepo;
+	const { emailService, emailConfig } = config;
+	const changeSchema = z.object({ newEmail: z.string().email("Invalid email address").max(255) });
+	const confirmSchema = z.object({ token: z.string().min(1, "Token is required") });
+	/** The repository's address-change methods, or a 501 saying it has none. */
+	function emailChangeStore() {
+		const { setPendingEmailChange, findPendingEmailChange, applyPendingEmailChange } = authRepo;
+		if (!setPendingEmailChange || !findPendingEmailChange || !applyPendingEmailChange) throw new ApiError(501, "NOT_SUPPORTED", "This backend's auth repository cannot change an account's email address.");
+		return {
+			setPendingEmailChange: setPendingEmailChange.bind(authRepo),
+			findPendingEmailChange: findPendingEmailChange.bind(authRepo),
+			applyPendingEmailChange: applyPendingEmailChange.bind(authRepo)
+		};
+	}
+	/**
+	* POST /auth/change-email { newEmail }
+	*
+	* Two limiters, as on `/send-verification`: per address of the caller's
+	* machine, and per account, which is what bounds the mail one account can
+	* have sent to addresses of its choosing.
+	*/
+	router.post("/change-email", strictAuthLimiter, requireLiveSession, verificationEmailLimiter, async (c) => {
+		const userCtx = c.get("user");
+		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
+		const { newEmail } = parseBody(changeSchema, await c.req.json());
+		const store = emailChangeStore();
+		if (!emailService?.isConfigured()) throw ApiError.serviceUnavailable("Email service not configured. The confirmation link cannot be sent.", "EMAIL_NOT_CONFIGURED");
+		const user = await authRepo.getUserById(userCtx.uid);
+		if (!user) throw ApiError.notFound("User not found");
+		if (user.isAnonymous) throw ApiError.forbidden("A guest has no address to change. Make it an account first (POST /auth/anonymous/link).", "ANONYMOUS_USER");
+		if (userCtx.aal !== "aal2" && await authRepo.hasVerifiedMfaFactors(user.id)) throw ApiError.forbidden("This account has a second factor. Sign in with it before changing the email address.", "AAL2_REQUIRED");
+		const email = normalizeEmail(newEmail);
+		if (email === normalizeEmail(user.email)) throw ApiError.badRequest("That is already this account's email address.", "EMAIL_UNCHANGED");
+		if (!isDeliverableAddress(email)) throw ApiError.conflict("No mail reaches that address.", "UNDELIVERABLE_ADDRESS");
+		if (await authRepo.getUserByEmail(email)) throw ApiError.conflict("Email already registered", "EMAIL_EXISTS");
+		if (ops.beforeEmailChange) await ops.beforeEmailChange(user, email);
+		const token = generateSecureToken();
+		await store.setPendingEmailChange(user.id, {
+			email,
+			tokenHash: hashToken(token)
+		});
+		const confirmUrl = `${resolveEmailLinkBase(emailConfig, "verifyEmail")}/confirm-email-change?token=${token}`;
+		const { appName, logoUrl } = resolveEmailBranding(emailConfig);
+		const recipient = {
+			email: user.email,
+			displayName: user.displayName
+		};
+		const confirmation = emailConfig?.templates?.emailChange ? emailConfig.templates.emailChange(confirmUrl, recipient, email) : getEmailChangeTemplate(confirmUrl, recipient, email, appName, logoUrl);
+		await emailService.send({
+			to: email,
+			subject: confirmation.subject,
+			html: confirmation.html,
+			text: confirmation.text
+		});
+		if (isDeliverableAddress(user.email)) {
+			const notice = emailConfig?.templates?.emailChangeNotice ? emailConfig.templates.emailChangeNotice(recipient, email) : getEmailChangeNoticeTemplate(recipient, email, appName, logoUrl);
+			emailService.send({
+				to: user.email,
+				subject: notice.subject,
+				html: notice.html,
+				text: notice.text
+			}).catch((err) => {
+				logger.error("Failed to send the email change notice", { error: err instanceof Error ? err.message : err });
+			});
+		}
+		logger.info("[Security Audit] Email change requested", {
+			eventType: "auth.email_change.requested",
+			uid: user.id
+		});
+		return c.json({
+			success: true,
+			pendingEmail: email,
+			expiresAt: new Date(Date.now() + EMAIL_CHANGE_TTL_MS).toISOString()
+		});
+	});
+	/**
+	* POST /auth/confirm-email-change { token }
+	*
+	* No session: the link is often opened on another device, and it proves
+	* the new inbox, which is all this needs.
+	*/
+	router.post("/confirm-email-change", strictAuthLimiter, async (c) => {
+		const { token } = parseBody(confirmSchema, await c.req.json());
+		const store = emailChangeStore();
+		const tokenHash = hashToken(token);
+		const invalid = () => ApiError.badRequest("Invalid or expired email change link", "INVALID_TOKEN");
+		const found = await store.findPendingEmailChange(tokenHash);
+		if (!found || Date.now() - found.change.sentAt.getTime() > 864e5) throw invalid();
+		const { user } = found;
+		const previousEmail = user.email;
+		const vouchingForOld = (await authRepo.getUserIdentities(user.id)).filter((identity) => identityVouchesForAddress(identity, previousEmail));
+		if (vouchingForOld.length > 0 && typeof authRepo.unlinkUserIdentity !== "function") throw ApiError.conflict("This account signs in through a provider that vouched for its current address, and this backend cannot detach it. Ask an administrator to change the address.", "UNVERIFIED_IDENTITIES");
+		const updated = await store.applyPendingEmailChange(user.id, tokenHash);
+		if (!updated) throw invalid();
+		for (const identity of vouchingForOld) await authRepo.unlinkUserIdentity?.(user.id, identity.provider, identity.providerId);
+		await authRepo.deleteAllPasswordResetTokensForUser(user.id);
+		logger.info("[Security Audit] Email address changed", {
+			eventType: "auth.email_change.confirmed",
+			uid: user.id,
+			detachedProviders: vouchingForOld.map((identity) => identity.provider)
+		});
+		return c.json({
+			success: true,
+			user: {
+				uid: updated.id,
+				email: updated.email,
+				emailVerified: true
+			},
+			removedProviders: vouchingForOld.map((identity) => identity.provider)
+		});
+	});
+}
+//#endregion
 //#region src/auth/session-routes.ts
 function mountSessionRoutes(opts) {
-	const { router, config, ops, parseBody, buildAuthResponse, createSessionAndTokens, applyTransformHook, requireLiveSession } = opts;
+	const { router, config, ops, parseBody, buildAuthResponse, createSessionAndTokens, applyTransformHook, requireLiveSession, registerCaptcha, sendVerificationMail } = opts;
 	const authRepo = config.authRepo;
 	/**
 	* Refuse the anonymous routes unless the deployment opted in.
@@ -3615,6 +4833,28 @@ function mountSessionRoutes(opts) {
 		})) return;
 		throw ApiError.forbidden(config.disableSelfRegistration ? "Anonymous sign-in is disabled: disableSelfRegistration blocks it." : "Anonymous sign-in is disabled. Set `auth.allowAnonymous: true` to enable it.", "ANONYMOUS_AUTH_DISABLED");
 	}
+	/**
+	* How the caller's session was signed in, as `providerId` reports it.
+	*
+	* Read off the session's refresh tokens, which carry it from sign-in
+	* through every rotation, found by the access token's `sid`. A token from
+	* before `sid`, or a session whose rows say nothing, reads `"password"` —
+	* what `/me` always answered.
+	*/
+	async function sessionMethod(userCtx) {
+		if (!userCtx.sid) return "password";
+		return (await authRepo.listRefreshTokensForUser(userCtx.uid).catch(() => [])).find((token) => (token.sessionId ?? token.id) === userCtx.sid && token.method)?.method ?? "password";
+	}
+	/**
+	* The address the account is moving to, while its link is still live —
+	* so a settings screen opened later still says a change is waiting.
+	* `null` otherwise, and on a repository that cannot change addresses.
+	*/
+	async function pendingEmail(uid) {
+		const change = await authRepo.getPendingEmailChange?.(uid).catch(() => null);
+		if (!change || Date.now() - change.sentAt.getTime() > 864e5) return null;
+		return change.email;
+	}
 	const logoutSchema = z.object({ refreshToken: z.string().optional() });
 	const linkSchema = z.object({
 		email: z.string().email("Invalid email address").max(255),
@@ -3631,18 +4871,25 @@ function mountSessionRoutes(opts) {
 	router.post("/logout", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const refreshToken = readRefreshToken(c, parseBody(logoutSchema, body), config.cookieAuth);
+		let signedOutUid;
 		if (refreshToken) {
 			const tokenHash = await hashRefreshToken(refreshToken);
-			const sessionId = (await authRepo.findRefreshTokenByHash(tokenHash).catch(() => null))?.sessionId;
+			const stored = await authRepo.findRefreshTokenByHash(tokenHash).catch(() => null);
+			signedOutUid = stored?.uid;
+			const sessionId = stored?.sessionId;
 			if (sessionId && authRepo.revokeRefreshTokenSession) await authRepo.revokeRefreshTokenSession(sessionId);
 			else await authRepo.deleteRefreshToken(tokenHash);
 		}
 		clearRefreshCookie(c, config.cookieAuth);
-		const accessToken = extractBearerToken(c.req.header("authorization"));
-		if (ops.afterLogout && accessToken !== void 0) {
-			const { verifyAccessToken } = await import("./jwt-C4OW-DNq.js").then((n) => n.h);
-			const payload = await verifyAccessToken(accessToken);
-			if (payload) ops.afterLogout(payload.uid).catch((err) => {
+		if (ops.afterLogout) {
+			if (!signedOutUid) {
+				const accessToken = extractBearerToken(c.req.header("authorization"));
+				if (accessToken !== void 0) {
+					const { verifyAccessToken } = await import("./jwt-R6bSPMjk.js").then((n) => n._);
+					signedOutUid = (await verifyAccessToken(accessToken))?.uid;
+				}
+			}
+			if (signedOutUid) ops.afterLogout(signedOutUid).catch((err) => {
 				logger.error("[AuthHooks] afterLogout error", { error: err instanceof Error ? err.message : err });
 			});
 		}
@@ -3655,7 +4902,7 @@ function mountSessionRoutes(opts) {
 	router.get("/sessions", requireLiveSession, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const currentRefreshToken = c.req.header("x-refresh-token");
+		const currentRefreshToken = userCtx.sid ? void 0 : c.req.header("x-refresh-token");
 		const currentTokenHash = currentRefreshToken ? await hashRefreshToken(currentRefreshToken) : null;
 		const tokens = await authRepo.listRefreshTokensForUser(userCtx.uid);
 		const bySession = /* @__PURE__ */ new Map();
@@ -3670,7 +4917,7 @@ function mountSessionRoutes(opts) {
 			userAgent: s.userAgent,
 			ipAddress: s.ipAddress,
 			createdAt: s.sessionStartedAt ?? s.createdAt,
-			isCurrentSession: currentTokenHash ? tokens.some((t) => t.tokenHash === currentTokenHash && (t.sessionId ?? t.id) === (s.sessionId ?? s.id)) : false
+			isCurrentSession: userCtx.sid ? (s.sessionId ?? s.id) === userCtx.sid : currentTokenHash ? tokens.some((t) => t.tokenHash === currentTokenHash && (t.sessionId ?? t.id) === (s.sessionId ?? s.id)) : false
 		}));
 		return c.json({ sessions: mappedSessions });
 	});
@@ -3718,10 +4965,11 @@ function mountSessionRoutes(opts) {
 			email: result.user.email,
 			displayName: result.user.displayName,
 			photoURL: result.user.photoUrl,
-			providerId: "password",
+			providerId: await sessionMethod(userCtx),
 			isAnonymous: result.user.isAnonymous ?? false,
 			emailVerified: result.user.emailVerified,
-			roles: result.roles.map((r) => r.id),
+			pendingEmail: await pendingEmail(userCtx.uid),
+			roles: result.roles,
 			metadata: result.user.metadata ?? {}
 		} });
 	});
@@ -3762,10 +5010,11 @@ function mountSessionRoutes(opts) {
 			email: result.user.email,
 			displayName: result.user.displayName,
 			photoURL: result.user.photoUrl,
-			providerId: "password",
+			providerId: await sessionMethod(userCtx),
 			isAnonymous: result.user.isAnonymous ?? false,
 			emailVerified: result.user.emailVerified,
-			roles: result.roles.map((r) => r.id),
+			pendingEmail: await pendingEmail(userCtx.uid),
+			roles: result.roles,
 			metadata: result.user.metadata ?? {}
 		} });
 	});
@@ -3783,7 +5032,7 @@ function mountSessionRoutes(opts) {
 		if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
 		const user = await authRepo.createUser(createData);
 		if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "anonymous" });
 		if (ops.afterUserCreate) ops.afterUserCreate(user).catch((err) => {
 			logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
 		});
@@ -3791,15 +5040,26 @@ function mountSessionRoutes(opts) {
 			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
 		});
 		const authResponse = buildAuthResponse(user, roleIds, accessToken, refreshToken, "anonymous");
-		const finalResponse = await applyTransformHook(authResponse, "anonymous", c.req.raw, user.id);
-		return c.json(finalResponse, 201);
+		const transformedResponse = await applyTransformHook(authResponse, "anonymous", c.req.raw, user.id);
+		return c.json(redactRefreshToken(transformedResponse, c, refreshToken, config.cookieAuth), 201);
 	});
 	/**
 	* POST /auth/anonymous/link
 	* Upgrade an anonymous user to a permanent account with email/password
+	*
+	* This is registration: before it the row is a guest, after it an account
+	* that signs in with a password. So it answers to registration's controls,
+	* the `register` captcha and `beforeUserCreate` on the credentials the
+	* account is getting. `/anonymous` carries neither, deliberately, because
+	* apps mint guests on page load; the two in a row used to be a way to make
+	* an account that passed neither.
 	*/
-	router.post("/anonymous/link", strictAuthLimiter, requireLiveSession, async (c) => {
+	router.post("/anonymous/link", strictAuthLimiter, requireLiveSession, ...registerCaptcha ? [registerCaptcha] : [], async (c) => {
 		assertAnonymousAuthOpen();
+		if (!isSteadyStateRegistrationOpen({
+			disableSelfRegistration: config.disableSelfRegistration,
+			allowRegistration: config.allowRegistration ?? false
+		})) throw ApiError.forbidden("A guest cannot become an account here: registration is disabled on this backend.", "REGISTRATION_DISABLED");
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const user = await authRepo.getUserById(userCtx.uid);
@@ -3809,17 +5069,73 @@ function mountSessionRoutes(opts) {
 		if (!passwordValidation.valid) throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
 		if (await authRepo.getUserByEmail(normalizeEmail(email))) throw ApiError.conflict("Email already registered", "EMAIL_EXISTS");
 		const passwordHash = await ops.hashPassword(password);
-		const updatedUser = await authRepo.updateUser(user.id, {
+		let linkData = {
 			email: normalizeEmail(email),
-			passwordHash,
+			passwordHash
+		};
+		if (ops.beforeUserCreate) linkData = await ops.beforeUserCreate(linkData);
+		const updatedUser = await authRepo.updateUser(user.id, {
+			...linkData,
+			email: normalizeEmail(linkData.email),
+			passwordHash: linkData.passwordHash,
 			isAnonymous: false
 		});
 		if (!updatedUser) throw ApiError.notFound("User not found");
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		sendVerificationMail?.(updatedUser);
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "password" });
 		const authResponse = buildAuthResponse(updatedUser, roleIds, accessToken, refreshToken, "password");
-		const finalResponse = await applyTransformHook(authResponse, "anonymous", c.req.raw, user.id);
-		return c.json(finalResponse);
+		const transformedResponse = await applyTransformHook(authResponse, "anonymous", c.req.raw, user.id);
+		return c.json(redactRefreshToken(transformedResponse, c, refreshToken, config.cookieAuth));
+	});
+}
+//#endregion
+//#region src/auth/passwordless-signup.ts
+/**
+* Sign-up by magic link or email code (`auth.magicLinkCreatesUsers`).
+*
+* Both passwordless doors refuse an address with no account — silently, so
+* they do not say which addresses have one. A passwordless-only app then had
+* no way to create accounts at all. With the option on, and registration open,
+* an unknown address gets an account at request time — no password, unverified
+* — and the link or code mailed to it is what proves the address and signs it
+* in, exactly as for an existing account. Supabase's `shouldCreateUser`.
+*
+* @module
+*/
+/**
+* The account a passwordless request for `email` should mail, creating it
+* when the deployment lets passwordless requests sign people up. `null` when
+* there is none and none may be made — the caller answers as for any unknown
+* address.
+*
+* Registration's controls hold: the kill switch, `allowRegistration` (with no
+* first-user exception: the first admin is made by registering or by the
+* operator, never by whoever asks for a link first), `beforeUserCreate`,
+* `afterUserCreate` and the default role.
+*/
+async function accountForPasswordlessRequest(config, ops, email) {
+	const authRepo = config.authRepo;
+	const existing = await authRepo.getUserByEmail(email);
+	if (existing || !config.magicLinkCreatesUsers) return existing;
+	if (!isSteadyStateRegistrationOpen({
+		disableSelfRegistration: config.disableSelfRegistration,
+		allowRegistration: config.allowRegistration ?? false
+	})) return null;
+	let createData = { email: normalizeEmail(email) };
+	if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
+	let user;
+	try {
+		user = await authRepo.createUser(createData);
+	} catch (error) {
+		const made = await authRepo.getUserByEmail(email);
+		if (made) return made;
+		throw error;
+	}
+	if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
+	if (ops.afterUserCreate) ops.afterUserCreate(user).catch((err) => {
+		logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
 	});
+	return user;
 }
 //#endregion
 //#region src/auth/magic-link-routes.ts
@@ -3845,15 +5161,24 @@ function mountMagicLinkRoutes(deps) {
 	/**
 	* POST /auth/magic-link
 	* Request a magic link email
+	*
+	* Answers the same words whether or not the address has an account, and
+	* is held to the same three things as its siblings `/otp` and
+	* `/forgot-password` so that nothing else answers the question either:
+	* the same response time, a per-address send limit, and `beforeLogin` on
+	* every attempt. This route had none of the three — the SMTP send was
+	* awaited only for a real account, and the only limit was per IP — so its
+	* timing named the customers and a spread-out run could fill one inbox.
 	*/
-	router.post("/magic-link", strictAuthLimiter, ...captchaMiddleware ? [captchaMiddleware] : [], async (c) => {
+	router.post("/magic-link", strictAuthLimiter, captureRecipientEmail, recipientEmailLimiter, ...captchaMiddleware ? [captchaMiddleware] : [], async (c) => {
+		const startedAt = Date.now();
 		const { email } = parseBody(magicLinkSchema, await c.req.json());
 		if (!isEmailConfigured()) throw ApiError.serviceUnavailable("Email service not configured. Magic link login is not available.", "EMAIL_NOT_CONFIGURED");
-		const user = await authRepo.getUserByEmail(email);
+		if (ops.beforeLogin) await ops.beforeLogin(email, "magic-link");
+		const user = await accountForPasswordlessRequest(config, ops, email);
 		if (user) {
-			if (ops.beforeLogin) await ops.beforeLogin(email, "magic-link");
 			const token = generateSecureToken();
-			const tokenHash = hashToken$1(token);
+			const tokenHash = hashToken(token);
 			const expiresAt = getMagicLinkExpiry();
 			await authRepo.createMagicLinkToken(user.id, tokenHash, expiresAt);
 			const magicLinkUrl = `${resolveEmailLinkBase(emailConfig, "magicLink")}/auth/magic-link?token=${token}`;
@@ -3866,21 +5191,19 @@ function mountMagicLinkRoutes(deps) {
 				email: user.email,
 				displayName: user.displayName
 			}, appName, logoUrl);
-			try {
-				await emailService.send({
-					to: user.email,
-					subject: emailContent.subject,
-					html: emailContent.html,
-					text: emailContent.text
-				});
-			} catch (emailError) {
+			emailService.send({
+				to: user.email,
+				subject: emailContent.subject,
+				html: emailContent.html,
+				text: emailContent.text
+			}).catch((emailError) => {
 				logger.error("Failed to send magic link email", { error: emailError instanceof Error ? emailError.message : emailError });
-			}
+			});
 		}
-		return c.json({
+		return notBefore$1(startedAt, 400, c.json({
 			success: true,
 			message: "If an account with that email exists, a magic link has been sent."
-		});
+		}));
 	});
 	/**
 	* POST /auth/magic-link/verify
@@ -3888,23 +5211,27 @@ function mountMagicLinkRoutes(deps) {
 	*/
 	router.post("/magic-link/verify", strictAuthLimiter, async (c) => {
 		const { token } = parseBody(verifyMagicLinkSchema, await c.req.json());
-		const tokenHash = hashToken$1(token);
+		const tokenHash = hashToken(token);
 		const storedToken = await authRepo.findValidMagicLinkToken(tokenHash);
 		if (!storedToken) throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
 		await authRepo.markMagicLinkTokenUsed(tokenHash);
-		const user = await authRepo.getUserById(storedToken.uid);
+		let user = await authRepo.getUserById(storedToken.uid);
 		if (!user) throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
 		if (!user.emailVerified) {
-			await authRepo.setEmailVerified(user.id, true);
-			user.emailVerified = true;
+			await confirmAddressOwnership(authRepo, user, null);
+			user = {
+				...user,
+				emailVerified: true,
+				passwordHash: null
+			};
 		}
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "magic-link" });
 		if (ops.onAuthenticated) ops.onAuthenticated(user, "magic-link").catch((err) => {
 			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
 		});
 		const authResponse = buildAuthResponse(user, roleIds, accessToken, refreshToken, "magic-link");
-		const finalResponse = await applyTransformHook(authResponse, "magic-link", c.req.raw, user.id);
-		return c.json(finalResponse);
+		const transformedResponse = await applyTransformHook(authResponse, "magic-link", c.req.raw, user.id);
+		return c.json(redactRefreshToken(transformedResponse, c, refreshToken, config.cookieAuth));
 	});
 }
 //#endregion
@@ -3949,6 +5276,7 @@ function otpTokenMaterial(email, code) {
 * replicas with the default, the effective budget is five attempts per replica.
 */
 var otpVerificationLimiter = createRateLimiter({
+	name: "auth-otp-verify",
 	windowMs: 900 * 1e3,
 	limit: OTP_ATTEMPTS_PER_WINDOW,
 	keyGenerator: (c) => {
@@ -3969,6 +5297,7 @@ var otpVerificationLimiter = createRateLimiter({
 * and useless as a mail bomb, matching `verificationEmailLimiter`.
 */
 var otpSendLimiter = createRateLimiter({
+	name: "auth-otp-send",
 	windowMs: 900 * 1e3,
 	limit: 5,
 	keyGenerator: (c) => {
@@ -4039,11 +5368,11 @@ function mountOtpRoutes(deps) {
 		const startedAt = Date.now();
 		const { email } = parseBody(requestSchema, await c.req.json());
 		if (!isEmailConfigured()) throw ApiError.serviceUnavailable("Email service not configured. One-time code login is not available.", "EMAIL_NOT_CONFIGURED");
-		const user = await authRepo.getUserByEmail(email);
 		if (ops.beforeLogin) await ops.beforeLogin(email, "otp");
+		const user = await accountForPasswordlessRequest(config, ops, email);
 		if (user) {
 			const code = generateOtpCode();
-			await authRepo.createMagicLinkToken(user.id, hashToken$1(otpTokenMaterial(user.email, code)), new Date(Date.now() + OTP_TTL_MS));
+			await authRepo.createMagicLinkToken(user.id, hashToken(otpTokenMaterial(user.email, code)), new Date(Date.now() + OTP_TTL_MS));
 			const { appName, logoUrl } = resolveEmailBranding(emailConfig);
 			const templateFn = emailConfig?.templates?.emailOtp;
 			const content = templateFn ? templateFn(code, {
@@ -4073,23 +5402,27 @@ function mountOtpRoutes(deps) {
 	*/
 	router.post("/otp/verify", strictAuthLimiter, captureOtpEmail, otpVerificationLimiter, async (c) => {
 		const { email, code } = parseBody(verifySchema, await c.req.json());
-		const tokenHash = hashToken$1(otpTokenMaterial(email, code));
+		const tokenHash = hashToken(otpTokenMaterial(email, code));
 		const storedToken = await authRepo.findValidMagicLinkToken(tokenHash);
 		if (!storedToken) throw ApiError.badRequest("Invalid or expired code", "INVALID_CODE");
 		await authRepo.markMagicLinkTokenUsed(tokenHash);
-		const user = await authRepo.getUserById(storedToken.uid);
+		let user = await authRepo.getUserById(storedToken.uid);
 		if (!user) throw ApiError.badRequest("Invalid or expired code", "INVALID_CODE");
 		if (!user.emailVerified) {
-			await authRepo.setEmailVerified(user.id, true);
-			user.emailVerified = true;
+			await confirmAddressOwnership(authRepo, user, null);
+			user = {
+				...user,
+				emailVerified: true,
+				passwordHash: null
+			};
 		}
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "otp" });
 		if (ops.onAuthenticated) ops.onAuthenticated(user, "otp").catch((err) => {
 			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
 		});
 		const authResponse = buildAuthResponse(user, roleIds, accessToken, refreshToken, "otp");
-		const finalResponse = await applyTransformHook(authResponse, "otp", c.req.raw, user.id);
-		return c.json(finalResponse);
+		const transformedResponse = await applyTransformHook(authResponse, "otp", c.req.raw, user.id);
+		return c.json(redactRefreshToken(transformedResponse, c, refreshToken, config.cookieAuth));
 	});
 }
 //#endregion
@@ -4097,26 +5430,34 @@ function mountOtpRoutes(deps) {
 /**
 * May an OAuth identity be attached to a pre-existing account found *by email*?
 *
-* Both sides have to be trustworthy, and only one of them used to be checked:
+* Both sides have to be trustworthy:
 *
 *  - the **provider** must have verified the address, or the caller has not
 *    shown they control it;
-*  - the **local account** must itself be trustworthy — either its address was
-*    verified, or it has no password at all (it was created by an OAuth
-*    sign-in or an invitation, so there is no credential an attacker could
-*    have planted in advance).
-*
-* A refusal is not a dead end: `POST /auth/link/<provider>` attaches the
-* identity once the caller proves ownership by holding a session.
+*  - the **local account**'s address must have been verified too. Whoever
+*    made an unverified account never proved the address, and every way in
+*    they left on it — a password, an identity from a provider that did not
+*    vouch for the address — would go on opening the account the owner is
+*    about to be signed into.
+*
+* The second rule used to exempt an account with no password, on the theory
+* that one made by an OAuth sign-in holds no credential an attacker could have
+* planted. It holds exactly one: the identity it was made with, which is an
+* attacker's whenever the provider did not vouch for the address.
+*
+* A refusal is not a dead end. `POST /auth/link/<provider>` attaches the
+* identity once the caller proves ownership by holding a session, and proving
+* the address (a magic link, an email code, a password reset) verifies the
+* account — removing what nobody proved — after which this answers yes.
 */
 function decideOAuthAutoLink(args) {
 	if (args.providerEmailVerified !== true) return {
 		allowed: false,
 		reason: "provider-email-unverified"
 	};
-	if (Boolean(args.existingUser.passwordHash) && !args.existingUser.emailVerified) return {
+	if (!args.existingUser.emailVerified) return {
 		allowed: false,
-		reason: "local-account-unverified"
+		reason: args.existingUser.passwordHash ? "local-account-unverified" : "local-account-unverified-passwordless"
 	};
 	return { allowed: true };
 }
@@ -4152,6 +5493,7 @@ function canonicalRedirectUri(uri) {
 }
 //#endregion
 //#region src/auth/routes.ts
+var REFRESH_TOKEN_REUSE_POLICIES = ["reject", "revoke-session"];
 /**
 * Helper to build standard auth response output
 */
@@ -4182,7 +5524,13 @@ function getPasswordResetExpiry() {
 	return new Date(Date.now() + 3600 * 1e3);
 }
 function createAuthRoutes(config) {
-	if (config.defaultRole && isAdministrativeRole(config.defaultRole)) throw new Error(`CRITICAL SECURITY ERROR: defaultRole cannot be '${config.defaultRole}'. Administrative privilege escalation via registration is strictly forbidden (administrative roles: ${ADMINISTRATIVE_ROLES.join(", ")}). Use the POST /admin/bootstrap endpoint to promote the initial administrator.`);
+	if (config.refreshTokenReuse !== void 0 && !REFRESH_TOKEN_REUSE_POLICIES.includes(config.refreshTokenReuse)) throw new Error(`auth.refreshTokenReuse is "${String(config.refreshTokenReuse)}"; it must be one of ${REFRESH_TOKEN_REUSE_POLICIES.map((p) => `"${p}"`).join(", ")}.`);
+	if (config.refreshTokenReuseIntervalSeconds !== void 0 && !(Number.isFinite(config.refreshTokenReuseIntervalSeconds) && config.refreshTokenReuseIntervalSeconds >= 0)) throw new Error(`auth.refreshTokenReuseIntervalSeconds is ${String(config.refreshTokenReuseIntervalSeconds)}; give a number of seconds, 0 or more.`);
+	if (config.defaultRole) {
+		const declared = getAccessModel().roles;
+		const adminPlane = config.defaultRole === "admin" ? ["every scope"] : Object.prototype.hasOwnProperty.call(declared, config.defaultRole) ? declared[config.defaultRole].scopes.filter((scope) => isAdminScope(parseScope(scope)?.scope ?? "")) : [];
+		if (adminPlane.length > 0) throw new Error(`CRITICAL SECURITY ERROR: defaultRole cannot be '${config.defaultRole}': every registrant would hold ${adminPlane.join(", ")}. Give the default role no admin-plane scopes, and use the POST /admin/bootstrap endpoint to promote the initial administrator.`);
+	}
 	const captcha = buildCaptchaMiddlewares(config.captcha);
 	const router = new Hono();
 	router.onError(errorHandler);
@@ -4235,11 +5583,16 @@ function createAuthRoutes(config) {
 		token: z.string().min(1, "Token is required"),
 		password: z.string().min(1, "Password is required").max(128)
 	});
+	const verifyEmailSchema = z.object({
+		token: z.string().min(1, "Token is required"),
+		password: z.string().min(1).max(128).optional(),
+		removeUnproven: z.boolean().optional()
+	});
 	const changePasswordSchema = z.object({
 		oldPassword: z.string().min(1, "Old password is required").max(128),
 		newPassword: z.string().min(1, "New password is required").max(128)
 	});
-	const refreshSchema = z.object({ refreshToken: z.string().min(1).optional() });
+	const refreshSchema = z.object({ refreshToken: z.string().optional() });
 	/** Parse a Zod schema against the request body, throwing ApiError on failure */
 	function parseBody(schema, body) {
 		const result = schema.safeParse(body);
@@ -4277,11 +5630,11 @@ function createAuthRoutes(config) {
 	* Send welcome email to a newly registered user (fire-and-forget).
 	*/
 	function sendWelcomeEmail(user) {
-		if (!isEmailConfigured()) return;
+		if (!isEmailConfigured() || !isDeliverableAddress(user.email)) return;
 		const { appName, logoUrl } = resolveEmailBranding(emailConfig);
 		const loginUrl = resolveEmailLinkBase(emailConfig, "resetPassword");
 		const templateFn = emailConfig?.templates?.welcomeEmail;
-		const emailContent = templateFn ? templateFn(user, appName) : getWelcomeEmailTemplate(user, appName, loginUrl ? `${loginUrl}/app` : void 0, logoUrl);
+		const emailContent = templateFn ? templateFn(user, appName) : getWelcomeEmailTemplate(user, appName, loginUrl || void 0, logoUrl);
 		emailService.send({
 			to: user.email,
 			subject: emailContent.subject,
@@ -4292,6 +5645,65 @@ function createAuthRoutes(config) {
 		});
 	}
 	/**
+	* Mail a verification link for `user`'s address, and record its token.
+	*
+	* Sent at registration as well as on request, so a self-registered
+	* account proves its address on its owner's terms — and keeps the
+	* password its owner chose, which a later first proof by link or code
+	* would otherwise have to remove (see `confirmAddressOwnership`).
+	* Returns whether a mail was handed to the email service.
+	*/
+	async function sendVerificationMail(user) {
+		if (!isEmailConfigured() || !isDeliverableAddress(user.email)) return false;
+		const token = generateSecureToken();
+		await authRepo.setVerificationToken(user.id, hashToken(token));
+		const verifyUrl = `${resolveEmailLinkBase(emailConfig, "verifyEmail")}/verify-email?token=${token}`;
+		const { appName, logoUrl } = resolveEmailBranding(emailConfig);
+		const templateFn = emailConfig?.templates?.emailVerification;
+		const emailContent = templateFn ? templateFn(verifyUrl, {
+			email: user.email,
+			displayName: user.displayName
+		}) : getEmailVerificationTemplate(verifyUrl, {
+			email: user.email,
+			displayName: user.displayName
+		}, appName, logoUrl);
+		await emailService.send({
+			to: user.email,
+			subject: emailContent.subject,
+			html: emailContent.html,
+			text: emailContent.text
+		});
+		return true;
+	}
+	/** {@link sendVerificationMail}, not awaited: a failure is logged, never answered. */
+	function sendVerificationMailInBackground(user) {
+		sendVerificationMail(user).catch((err) => {
+			logger.error("Failed to send verification email", { error: err instanceof Error ? err.message : err });
+		});
+	}
+	/**
+	* A hash of nothing anyone knows, made with this deployment's own
+	* `hashPassword`, so verifying against it costs what verifying a real
+	* password costs. Made once, on first use.
+	*/
+	let dummyHash;
+	function dummyPasswordHash() {
+		dummyHash ??= ops.hashPassword(randomBytes$1(24).toString("hex"));
+		return dummyHash;
+	}
+	/**
+	* Is the account just created the only one there is?
+	*
+	* Two rows at most: the total says whether anyone else exists, and the
+	* one row left when nobody does says whether it is this account. It used
+	* to be `listUsers()` — the whole users table, password hashes included,
+	* on every sign-up, to compare its length with one.
+	*/
+	async function isOnlyUser(uid) {
+		const { users, total } = await authRepo.listUsersPaginated({ limit: 2 });
+		return total === 1 && users[0]?.id === uid;
+	}
+	/**
 	* Helper to generate and store session tokens.
 	*
 	* Every route that signs somebody in comes through here — password login,
@@ -4305,11 +5717,12 @@ function createAuthRoutes(config) {
 	* itself, which has just seen the second factor and mints at `aal2`.
 	*/
 	async function createSessionAndTokens(uid, userAgent, ipAddress, options) {
-		if (!options?.skipMfaGate) await assertMfaSatisfied(authRepo, uid);
-		const aal = options?.aal ?? "aal1";
-		const roleIds = (await authRepo.getUserRoles(uid)).map((r) => r.id);
+		if (!options.skipMfaGate) await assertMfaSatisfied(authRepo, uid);
+		const aal = options.aal ?? "aal1";
+		const roleIds = await authRepo.getUserRoleIds(uid);
 		const sessionUser = await authRepo.getUserById(uid);
 		const isAnonymous = sessionUser?.isAnonymous === true;
+		if (sessionUser?.disabled) throw ApiError.forbidden("This account has been disabled. Contact an administrator.", "ACCOUNT_DISABLED");
 		let customClaims;
 		if (ops.customizeAccessToken) {
 			const user = sessionUser;
@@ -4322,12 +5735,14 @@ function createAuthRoutes(config) {
 				customClaims = await ops.customizeAccessToken(defaultClaims, user);
 			}
 		}
-		const accessToken = await generateAccessToken(uid, roleIds, aal, customClaims, isAnonymous);
+		const sessionId = randomUUID$1();
+		const accessToken = await generateAccessToken(uid, roleIds, aal, customClaims, isAnonymous, sessionId);
 		const refreshToken = generateRefreshToken();
 		await authRepo.createRefreshToken(uid, await hashRefreshToken(refreshToken), getRefreshTokenExpiry(), userAgent, ipAddress, {
-			id: randomUUID(),
+			id: sessionId,
 			startedAt: /* @__PURE__ */ new Date(),
-			aal
+			aal,
+			method: options.method
 		});
 		return {
 			roleIds,
@@ -4340,6 +5755,7 @@ function createAuthRoutes(config) {
 	* Create a new account with email/password
 	*/
 	router.post("/register", defaultAuthLimiter, ...captcha.register ? [captcha.register] : [], async (c) => {
+		const startedAt = Date.now();
 		const { email, password, displayName } = parseBody(registerSchema, await c.req.json());
 		if (config.disableSelfRegistration) throw ApiError.forbidden("Registration is disabled", "REGISTRATION_DISABLED");
 		let bootstrapRegistration = false;
@@ -4351,7 +5767,19 @@ function createAuthRoutes(config) {
 		}
 		const passwordValidation = ops.validatePasswordStrength(password);
 		if (!passwordValidation.valid) throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
-		if (await authRepo.getUserByEmail(email)) throw ApiError.conflict("Email already registered", "EMAIL_EXISTS");
+		const confirmFirst = () => notBefore$1(startedAt, 400, c.json({
+			success: true,
+			confirmationRequired: true,
+			message: "Check your inbox: follow the link we sent to confirm your address, then sign in."
+		}));
+		const existingUser = await authRepo.getUserByEmail(email);
+		if (existingUser) {
+			if (config.requireEmailVerification) {
+				if (!existingUser.emailVerified) sendVerificationMailInBackground(existingUser);
+				return confirmFirst();
+			}
+			throw ApiError.conflict("Email already registered", "EMAIL_EXISTS");
+		}
 		const passwordHash = await ops.hashPassword(password);
 		let createData = {
 			email: normalizeEmail(email),
@@ -4360,8 +5788,7 @@ function createAuthRoutes(config) {
 		};
 		if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
 		const user = await authRepo.createUser(createData);
-		const existingUsers = await authRepo.listUsers();
-		const isFirstUser = existingUsers.length === 1 && existingUsers[0].id === user.id;
+		const isFirstUser = await isOnlyUser(user.id);
 		if (bootstrapRegistration && !isFirstUser) {
 			await authRepo.deleteUser(user.id);
 			throw ApiError.forbidden("Registration is disabled", "REGISTRATION_DISABLED");
@@ -4371,11 +5798,21 @@ function createAuthRoutes(config) {
 			if (isFirstUser) logger.warn("[Auth] First account registered in production without promotion; set REBASE_ADMIN_EMAIL/REBASE_ADMIN_PASSWORD or use the service key to assign admin.");
 			if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
 		}
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		if (config.requireEmailVerification) {
+			sendVerificationMailInBackground(user);
+			if (ops.afterUserCreate) try {
+				await ops.afterUserCreate(user);
+			} catch (err) {
+				logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
+			}
+			return confirmFirst();
+		}
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "password" });
 		sendWelcomeEmail({
 			email: user.email,
 			displayName: user.displayName
 		});
+		sendVerificationMailInBackground(user);
 		if (ops.afterUserCreate) try {
 			await ops.afterUserCreate(user);
 		} catch (err) {
@@ -4400,8 +5837,10 @@ function createAuthRoutes(config) {
 			if (!user) throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
 		} else {
 			user = await authRepo.getUserByEmail(email);
-			if (!user) throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
-			if (!user.passwordHash) throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+			if (!user || !user.passwordHash) {
+				await ops.verifyPassword(password, await dummyPasswordHash());
+				throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+			}
 			if (!await ops.verifyPassword(password, user.passwordHash)) {
 				logger.warn("[Security Audit] Auth login failure", {
 					eventType: "auth.login.failure",
@@ -4411,7 +5850,12 @@ function createAuthRoutes(config) {
 				throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
 			}
 		}
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		if (config.requireEmailVerification && !user.emailVerified) {
+			const lastSent = user.emailVerificationSentAt?.getTime() ?? 0;
+			if (Date.now() - lastSent > 6e4) sendVerificationMailInBackground(user);
+			throw ApiError.forbidden("Confirm your email address first: follow the link we sent to it, then sign in.", "EMAIL_NOT_CONFIRMED");
+		}
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "password" });
 		if (ops.onAuthenticated) ops.onAuthenticated(user, "login").catch((err) => {
 			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
 		});
@@ -4424,21 +5868,47 @@ function createAuthRoutes(config) {
 		return c.json(finalResponse);
 	});
 	/**
+	* Turn an OAuth request body into the provider's profile of the caller.
+	*
+	* Both OAuth doors come through here — sign-in and `/link/<provider>` —
+	* because both end with that provider identity resolving to an account,
+	* so both need the same two controls. The link door used to spend the
+	* code without the first and echo the provider's error without the second:
+	* a victim's code leaked through a stale registered URI could be linked to
+	* the attacker's account, after which the victim's own "Sign in with …"
+	* landed there.
+	*
+	* The redirect URI is allowlisted before the code is spent. The provider's
+	* own registered-URI match authorises *every* URI on that OAuth client — a
+	* leftover localhost entry, a staging host, a second product sharing the
+	* client id — and any of them can mint a code this backend would otherwise
+	* accept.
+	*
+	* A provider's error message is logged, never returned: its token-endpoint
+	* error body routinely echoes the client_id, the redirect URI and
+	* diagnostics about the credential state.
+	*/
+	async function verifyProviderPayload(provider, payload) {
+		const requestedRedirectUri = typeof payload === "object" && payload !== null && "redirectUri" in payload ? payload.redirectUri : void 0;
+		if (typeof requestedRedirectUri === "string" && !isRedirectUriAllowed(requestedRedirectUri, config.allowedRedirectUris)) throw ApiError.badRequest("redirectUri is not allowed for this backend", "REDIRECT_URI_NOT_ALLOWED");
+		let externalUser;
+		try {
+			externalUser = await provider.verify(payload);
+		} catch (err) {
+			logger.error(`[OAuth] ${provider.id} verification threw`, { error: err instanceof Error ? err.message : String(err) });
+			throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "OAUTH_ERROR");
+		}
+		if (!externalUser) throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "INVALID_TOKEN");
+		return externalUser;
+	}
+	/**
 	* Dynamically mount OAuth provider routes
 	*/
 	if (config.oauthProviders && config.oauthProviders.length > 0) for (const provider of config.oauthProviders) {
 		router.post(`/${provider.id}`, defaultAuthLimiter, async (c) => {
 			const payload = parseBody(provider.schema, await c.req.json());
-			const requestedRedirectUri = payload.redirectUri;
-			if (typeof requestedRedirectUri === "string" && !isRedirectUriAllowed(requestedRedirectUri, config.allowedRedirectUris)) throw ApiError.badRequest("redirectUri is not allowed for this backend", "REDIRECT_URI_NOT_ALLOWED");
-			let externalUser;
-			try {
-				externalUser = await provider.verify(payload);
-			} catch (err) {
-				logger.error(`[OAuth] ${provider.id} verification threw`, { error: err instanceof Error ? err.message : String(err) });
-				throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "OAUTH_ERROR");
-			}
-			if (!externalUser) throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "INVALID_TOKEN");
+			const externalUser = await verifyProviderPayload(provider, payload);
+			if (ops.beforeLogin) await ops.beforeLogin(normalizeEmail(externalUser.email), "oauth");
 			let user = await authRepo.getUserByIdentity(provider.id, externalUser.providerId);
 			if (!user) {
 				user = await authRepo.getUserByEmail(externalUser.email);
@@ -4451,7 +5921,7 @@ function createAuthRoutes(config) {
 						reason: decision.reason,
 						provider: provider.id
 					});
-					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, { email: externalUser.email });
+					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, identityProfileData(externalUser));
 					await authRepo.updateUser(user.id, {
 						displayName: user.displayName || externalUser.displayName || void 0,
 						photoUrl: user.photoUrl || externalUser.photoUrl || void 0
@@ -4466,20 +5936,21 @@ function createAuthRoutes(config) {
 						if (!bootstrapRegistration) throw ApiError.forbidden(noSignupsMessage, "REGISTRATION_DISABLED");
 						if (!isBootstrapWindowOpen()) throw ApiError.forbidden(SETUP_REQUIRED_MESSAGE, "SETUP_REQUIRED");
 					}
-					user = await authRepo.createUser({
+					let createData = {
 						email: normalizeEmail(externalUser.email),
 						displayName: externalUser.displayName || void 0,
 						photoUrl: externalUser.photoUrl || void 0,
 						emailVerified: externalUser.emailVerified === true
-					});
-					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, { email: externalUser.email });
+					};
+					if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
+					user = await authRepo.createUser(createData);
+					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, identityProfileData(externalUser));
 					if (ops.afterUserCreate) try {
 						await ops.afterUserCreate(user);
 					} catch (err) {
 						logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
 					}
-					const allUsers = await authRepo.listUsers();
-					const isFirstUser = allUsers.length === 1 && allUsers[0].id === user.id;
+					const isFirstUser = await isOnlyUser(user.id);
 					if (bootstrapRegistration && !isFirstUser) {
 						await authRepo.deleteUser(user.id);
 						throw ApiError.forbidden(noSignupsMessage, "REGISTRATION_DISABLED");
@@ -4495,7 +5966,13 @@ function createAuthRoutes(config) {
 				displayName: externalUser.displayName || user.displayName || void 0,
 				photoUrl: externalUser.photoUrl || user.photoUrl || void 0
 			});
-			const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+			const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: provider.id });
+			if (ops.onAuthenticated) {
+				const signedIn = user;
+				ops.onAuthenticated(signedIn, "oauth").catch((err) => {
+					logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
+				});
+			}
 			const finalResponse = redactRefreshToken(await applyTransformHook(buildAuthResponse(user, roleIds, accessToken, refreshToken, provider.id), "oauth", c.req.raw, user.id), c, refreshToken, config.cookieAuth);
 			return c.json(finalResponse);
 		});
@@ -4522,14 +5999,7 @@ function createAuthRoutes(config) {
 			const userCtx = c.get("user");
 			if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 			const payload = parseBody(provider.schema, await c.req.json());
-			let externalUser;
-			try {
-				externalUser = await provider.verify(payload);
-			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
-				throw ApiError.unauthorized(`${provider.id} link failed: ${msg}`, "OAUTH_ERROR");
-			}
-			if (!externalUser) throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "INVALID_TOKEN");
+			const externalUser = await verifyProviderPayload(provider, payload);
 			const identityOwner = await authRepo.getUserByIdentity(provider.id, externalUser.providerId);
 			if (identityOwner && identityOwner.id !== userCtx.uid) throw ApiError.conflict(`That ${provider.id} account is already linked to a different user.`, "IDENTITY_ALREADY_LINKED");
 			if (identityOwner) return c.json({
@@ -4538,7 +6008,34 @@ function createAuthRoutes(config) {
 				alreadyLinked: true,
 				photoURL: externalUser.photoUrl ?? null
 			});
-			await authRepo.linkUserIdentity(userCtx.uid, provider.id, externalUser.providerId, { email: externalUser.email });
+			const linking = await authRepo.getUserById(userCtx.uid);
+			if (linking?.isAnonymous) {
+				if (!isRegistrationAllowed()) throw ApiError.forbidden("A guest cannot become an account here: registration is disabled on this backend.", "REGISTRATION_DISABLED");
+				const vouchedEmail = externalUser.emailVerified === true ? normalizeEmail(externalUser.email) : void 0;
+				if (vouchedEmail && await authRepo.getUserByEmail(vouchedEmail)) throw ApiError.conflict(`An account with this ${provider.id} address already exists. Sign in to it instead.`, "EMAIL_EXISTS");
+				let upgrade = {
+					email: vouchedEmail ?? linking.email,
+					...vouchedEmail ? { emailVerified: true } : {}
+				};
+				if (ops.beforeUserCreate) upgrade = await ops.beforeUserCreate(upgrade);
+				await authRepo.linkUserIdentity(userCtx.uid, provider.id, externalUser.providerId, identityProfileData(externalUser));
+				const upgraded = await authRepo.updateUser(userCtx.uid, {
+					email: normalizeEmail(upgrade.email),
+					...upgrade.emailVerified !== void 0 ? { emailVerified: upgrade.emailVerified } : {},
+					isAnonymous: false
+				});
+				if (!upgraded) throw ApiError.notFound("User not found");
+				const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(upgraded.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: provider.id });
+				const authResponse = buildAuthResponse(upgraded, roleIds, accessToken, refreshToken, provider.id);
+				return c.json({
+					...redactRefreshToken(authResponse, c, refreshToken, config.cookieAuth),
+					success: true,
+					provider: provider.id,
+					alreadyLinked: false,
+					photoURL: externalUser.photoUrl ?? null
+				});
+			}
+			await authRepo.linkUserIdentity(userCtx.uid, provider.id, externalUser.providerId, identityProfileData(externalUser));
 			return c.json({
 				success: true,
 				provider: provider.id,
@@ -4558,7 +6055,7 @@ function createAuthRoutes(config) {
 		const user = await authRepo.getUserByEmail(email);
 		if (user) {
 			const token = generateSecureToken();
-			const tokenHash = hashToken$1(token);
+			const tokenHash = hashToken(token);
 			const expiresAt = getPasswordResetExpiry();
 			await authRepo.createPasswordResetToken(user.id, tokenHash, expiresAt);
 			const resetUrl = `${resolveEmailLinkBase(emailConfig, "resetPassword")}/reset-password?token=${token}`;
@@ -4593,12 +6090,17 @@ function createAuthRoutes(config) {
 		const { token, password } = parseBody(resetPasswordSchema, await c.req.json());
 		const passwordValidation = ops.validatePasswordStrength(password);
 		if (!passwordValidation.valid) throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
-		const tokenHash = hashToken$1(token);
+		const tokenHash = hashToken(token);
 		const storedToken = await authRepo.findValidPasswordResetToken(tokenHash);
 		if (!storedToken) throw ApiError.badRequest("Invalid or expired reset token", "INVALID_TOKEN");
 		const passwordHash = await ops.hashPassword(password);
-		await replaceUserPassword(authRepo, storedToken.uid, passwordHash);
+		const account = await authRepo.getUserById(storedToken.uid);
+		if (account && !account.emailVerified) await confirmAddressOwnership(authRepo, account, passwordHash);
+		else await replaceUserPassword(authRepo, storedToken.uid, passwordHash);
 		await authRepo.markPasswordResetTokenUsed(tokenHash);
+		if (ops.onAuthenticated && account) ops.onAuthenticated(account, "password-reset").catch((err) => {
+			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
+		});
 		if (ops.onPasswordReset) ops.onPasswordReset(storedToken.uid).catch((err) => {
 			logger.error("[AuthHooks] onPasswordReset error", { error: err instanceof Error ? err.message : err });
 		});
@@ -4622,7 +6124,14 @@ function createAuthRoutes(config) {
 		if (!passwordValidation.valid) throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
 		const passwordHash = await ops.hashPassword(newPassword);
 		await replaceUserPassword(authRepo, user.id, passwordHash);
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), {
+			skipMfaGate: true,
+			aal: userCtx.aal === "aal2" ? "aal2" : "aal1",
+			method: "password"
+		});
+		const authResponse = buildAuthResponse(user, roleIds, accessToken, refreshToken, "password");
 		return c.json({
+			...redactRefreshToken(authResponse, c, refreshToken, config.cookieAuth),
 			success: true,
 			message: "Password has been changed successfully"
 		});
@@ -4645,42 +6154,109 @@ function createAuthRoutes(config) {
 		const user = await authRepo.getUserById(userCtx.uid);
 		if (!user) throw ApiError.notFound("User not found");
 		if (user.emailVerified) throw ApiError.badRequest("Email is already verified", "ALREADY_VERIFIED");
-		const token = generateSecureToken();
-		await authRepo.setVerificationToken(user.id, hashToken$1(token));
-		const verifyUrl = `${resolveEmailLinkBase(emailConfig, "verifyEmail")}/verify-email?token=${token}`;
-		const { appName, logoUrl } = resolveEmailBranding(emailConfig);
-		const templateFn = emailConfig?.templates?.emailVerification;
-		const emailContent = templateFn ? templateFn(verifyUrl, {
-			email: user.email,
-			displayName: user.displayName
-		}) : getEmailVerificationTemplate(verifyUrl, {
-			email: user.email,
-			displayName: user.displayName
-		}, appName, logoUrl);
-		await emailService.send({
-			to: user.email,
-			subject: emailContent.subject,
-			html: emailContent.html,
-			text: emailContent.text
-		});
+		if (!isDeliverableAddress(user.email)) throw ApiError.badRequest("This account has no address mail can reach. Set a real email address first.", "UNDELIVERABLE_ADDRESS");
+		await sendVerificationMail(user);
 		return c.json({
 			success: true,
 			message: "Verification email sent"
 		});
 	});
 	/**
-	* GET /auth/verify-email
-	* Verify email address using token
+	* Who proved what, when a verification link is followed.
+	*
+	* The link proves the inbox. It does not prove whoever registered the
+	* address is that inbox's owner: anyone can register someone else's
+	* address, leave a password on it, and ask for the link to be mailed. So a
+	* first proof of address keeps only what the person following the link
+	* also proved — and takes the rest off, as a magic link, an email code or
+	* a reset does (`confirmAddressOwnership`):
+	*
+	* - `session`: the request carries a live session of this very account.
+	*   Only whoever put the credentials on it can hold one, and they now hold
+	*   the inbox too — nothing on the account is a stranger's.
+	* - `password`: the request carries the account's password.
+	* - `none`: the password and every identity whose provider did not vouch
+	*   for the address are removed, and every session ends.
+	*/
+	async function verificationProof(c, user, password) {
+		const bearer = extractBearerToken(c.req.header("authorization"));
+		if (bearer !== void 0) {
+			const payload = await verifyAccessToken(bearer);
+			if (payload?.uid === user.id && (await judgeAccessToken(authRepo, payload)).live) return "session";
+		}
+		if (password !== void 0) {
+			if (!user.passwordHash || !await ops.verifyPassword(password, user.passwordHash)) throw ApiError.unauthorized("That is not this account's password.", "INVALID_CREDENTIALS");
+			return "password";
+		}
+		return "none";
+	}
+	/** The account a verification token names, if the token is live. */
+	async function accountForVerificationToken(token) {
+		const user = await authRepo.getUserByVerificationToken(hashToken(token));
+		const sentAt = user?.emailVerificationSentAt?.getTime();
+		if (!user || sentAt !== void 0 && Date.now() - sentAt > 864e5) throw ApiError.badRequest("Invalid or expired verification token", "INVALID_TOKEN");
+		return user;
+	}
+	/**
+	* GET /auth/verify-email?token=
+	* Verify an address by its link. Keeps what the request proves — a live
+	* session of the account — and removes what nobody proved. See
+	* `verificationProof`; `POST` is the same with a password and a choice.
 	*/
-	router.get("/verify-email", async (c) => {
+	router.get("/verify-email", strictAuthLimiter, async (c) => {
 		const token = c.req.query("token");
 		if (!token) throw ApiError.badRequest("Verification token is required", "INVALID_INPUT");
-		const user = await authRepo.getUserByVerificationToken(hashToken$1(token));
-		if (!user) throw ApiError.badRequest("Invalid or expired verification token", "INVALID_TOKEN");
-		await authRepo.setEmailVerified(user.id, true);
+		const user = await accountForVerificationToken(token);
+		const proof = await verificationProof(c, user, void 0);
+		const outcome = await confirmAddressOwnership(authRepo, user, null, { everythingProven: proof === "session" });
+		return c.json({
+			success: true,
+			message: "Email verified successfully",
+			passwordRemoved: outcome.removedPassword,
+			removedProviders: outcome.removedProviders
+		});
+	});
+	/**
+	* POST /auth/verify-email { token, password?, removeUnproven? }
+	*
+	* The same proof as `GET`, with the two things a link alone cannot say:
+	*
+	* - `password` proves the account's password, which is then kept, and
+	*   signs the caller in — they have just proven both the address and the
+	*   password. This is how a confirm-first registration completes.
+	* - With neither a session nor a password, an account carrying a password
+	*   or an identity nobody proved is answered `409 PROOF_REQUIRED` and the
+	*   token is left unspent, so the person holding the link can choose:
+	*   prove the password, or `removeUnproven: true` to verify without it.
+	*/
+	router.post("/verify-email", strictAuthLimiter, async (c) => {
+		const { token, password, removeUnproven } = parseBody(verifyEmailSchema, await c.req.json());
+		const user = await accountForVerificationToken(token);
+		const proof = await verificationProof(c, user, password);
+		if (proof === "none" && !removeUnproven) {
+			const unprovenProviders = (await authRepo.getUserIdentities(user.id)).filter((identity) => !identityVouchesForAddress(identity, user.email)).map((identity) => identity.provider);
+			if (user.passwordHash || unprovenProviders.length > 0) throw new ApiError(409, "PROOF_REQUIRED", "This account has a way to sign in that was set before its address was verified. Enter its password to keep it, or verify without it and it is removed.", {
+				password: Boolean(user.passwordHash),
+				providers: unprovenProviders
+			});
+		}
+		const outcome = await confirmAddressOwnership(authRepo, user, proof === "password" ? user.passwordHash ?? null : null, { everythingProven: proof === "session" });
+		if (proof !== "password") return c.json({
+			success: true,
+			message: "Email verified successfully",
+			passwordRemoved: outcome.removedPassword,
+			removedProviders: outcome.removedProviders
+		});
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", requestClientAddress(c), { method: "password" });
+		const transformedResponse = await applyTransformHook(buildAuthResponse({
+			...user,
+			emailVerified: true
+		}, roleIds, accessToken, refreshToken, "password"), "login", c.req.raw, user.id);
 		return c.json({
+			...redactRefreshToken(transformedResponse, c, refreshToken, config.cookieAuth),
 			success: true,
-			message: "Email verified successfully"
+			passwordRemoved: false,
+			removedProviders: outcome.removedProviders
 		});
 	});
 	/**
@@ -4713,15 +6289,24 @@ function createAuthRoutes(config) {
 		const reuseWindowMs = Math.max(0, config.refreshTokenReuseIntervalSeconds ?? 10) * 1e3;
 		const supersededAt = storedToken.rotatedAt ? new Date(storedToken.rotatedAt) : null;
 		if (supersededAt && Date.now() - supersededAt.getTime() > reuseWindowMs) {
-			logger.warn("[Auth] Refresh token replayed after the reuse window", {
+			const revoke = config.refreshTokenReuse === "revoke-session";
+			logger.warn("[Security Audit] Refresh token replayed after the reuse window", {
+				eventType: "auth.refresh.reuse",
 				uid: storedToken.uid,
 				sessionId: storedToken.sessionId,
 				supersededSecondsAgo: Math.round((Date.now() - supersededAt.getTime()) / 1e3),
-				userAgent: c.req.header("user-agent") || "unknown"
+				userAgent: c.req.header("user-agent") || "unknown",
+				sessionRevoked: revoke
 			});
+			if (revoke) {
+				if (storedToken.sessionId && authRepo.revokeRefreshTokenSession) await authRepo.revokeRefreshTokenSession(storedToken.sessionId);
+				else await authRepo.deleteRefreshToken(tokenHash);
+				clearRefreshCookie(c, config.cookieAuth);
+				throw ApiError.unauthorized("Refresh token already used; this session has been ended", "SESSION_REVOKED");
+			}
 			throw ApiError.unauthorized("Refresh token already used", "TOKEN_ALREADY_USED");
 		}
-		const roleIds = (await authRepo.getUserRoles(storedToken.uid)).map((r) => r.id);
+		const roleIds = await authRepo.getUserRoleIds(storedToken.uid);
 		const user = await authRepo.getUserById(storedToken.uid).catch((err) => {
 			logger.warn("[Auth] Could not load user during token refresh; returning tokens only", {
 				uid: storedToken.uid,
@@ -4729,7 +6314,13 @@ function createAuthRoutes(config) {
 			});
 			return null;
 		});
+		if (user?.disabled) {
+			await authRepo.deleteRefreshToken(tokenHash);
+			clearRefreshCookie(c, config.cookieAuth);
+			throw ApiError.unauthorized("This account has been disabled", "ACCOUNT_DISABLED");
+		}
 		const sessionAal = storedToken.aal === "aal2" ? "aal2" : "aal1";
+		const sessionMethod = storedToken.method ?? "password";
 		let customClaims;
 		if (ops.customizeAccessToken && user) {
 			const defaultClaims = {
@@ -4739,18 +6330,27 @@ function createAuthRoutes(config) {
 			};
 			customClaims = await ops.customizeAccessToken(defaultClaims, user);
 		}
-		const newAccessToken = await generateAccessToken(storedToken.uid, roleIds, sessionAal, customClaims, user?.isAnonymous === true);
+		const sessionId = storedToken.sessionId ?? storedToken.id;
+		const newAccessToken = await generateAccessToken(storedToken.uid, roleIds, sessionAal, customClaims, user?.isAnonymous === true, sessionId);
 		const newRefreshToken = generateRefreshToken();
 		const userAgent = c.req.header("user-agent") || "unknown";
-		const ipAddress = c.req.header("x-forwarded-for") || "unknown";
+		const ipAddress = requestClientAddress(c);
 		const session = {
-			id: storedToken.sessionId ?? storedToken.id,
+			id: sessionId,
 			startedAt: sessionStartedAt,
-			aal: sessionAal
+			aal: sessionAal,
+			method: sessionMethod
 		};
 		if (!supersededAt) if (authRepo.markRefreshTokenRotated) await authRepo.markRefreshTokenRotated(tokenHash);
 		else await authRepo.deleteRefreshToken(tokenHash);
-		await authRepo.createRefreshToken(storedToken.uid, await hashRefreshToken(newRefreshToken), getRefreshTokenExpiry(), userAgent, ipAddress, session);
+		const presentedKept = Boolean(supersededAt) || typeof authRepo.markRefreshTokenRotated === "function";
+		if (await authRepo.createRefreshToken(storedToken.uid, await hashRefreshToken(newRefreshToken), getRefreshTokenExpiry(), userAgent, ipAddress, presentedKept ? {
+			...session,
+			rotatedFrom: tokenHash
+		} : session) === false) {
+			clearRefreshCookie(c, config.cookieAuth);
+			throw ApiError.unauthorized("Session has been revoked", "SESSION_REVOKED");
+		}
 		authRepo.pruneRefreshTokens?.(storedToken.uid, session.id, new Date(Date.now() - reuseWindowMs)).catch((err) => {
 			logger.warn("[Auth] Refresh token prune failed", { error: err instanceof Error ? err.message : String(err) });
 		});
@@ -4761,14 +6361,24 @@ function createAuthRoutes(config) {
 		} };
 		let refreshResponse = tokensOnlyResponse;
 		if (user) try {
-			refreshResponse = buildAuthResponse(user, roleIds, newAccessToken, newRefreshToken, "password");
+			refreshResponse = buildAuthResponse(user, roleIds, newAccessToken, newRefreshToken, sessionMethod);
 		} catch (err) {
 			logger.warn("[Auth] Could not build enriched refresh response; returning tokens only", { error: err instanceof Error ? err.message : String(err) });
 			refreshResponse = tokensOnlyResponse;
 		}
+		if (ops.onAuthenticated && user) ops.onAuthenticated(user, "refresh").catch((err) => {
+			logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
+		});
 		const finalResponse = redactRefreshToken(await applyTransformHook(refreshResponse, "refresh", c.req.raw, storedToken.uid), c, newRefreshToken, config.cookieAuth);
 		return c.json(finalResponse);
 	});
+	mountEmailChangeRoutes({
+		router,
+		config,
+		ops,
+		parseBody,
+		requireLiveSession
+	});
 	mountSessionRoutes({
 		router,
 		config,
@@ -4777,7 +6387,9 @@ function createAuthRoutes(config) {
 		buildAuthResponse,
 		createSessionAndTokens,
 		applyTransformHook,
-		requireLiveSession
+		requireLiveSession,
+		registerCaptcha: captcha.register,
+		sendVerificationMail: sendVerificationMailInBackground
 	});
 	mountMfaRoutes({
 		router,
@@ -4875,10 +6487,11 @@ function createResetPasswordRoute(config) {
 		resolveRoles: (uid) => authRepo.getUserRoleIds(uid),
 		revocationRepo: authRepo
 	}));
-	router.post("/users/:uid/reset-password", requireAdmin, async (c) => {
+	router.post("/users/:uid/reset-password", requireScope("users:write"), async (c) => {
 		const uid = c.req.param("uid");
 		const existing = await authRepo.getUserById(uid);
 		if (!existing) throw ApiError.notFound("User not found");
+		assertMayManageAccount(c, await authRepo.getUserRoleIds(uid));
 		let invitationSent = false;
 		let temporaryPassword;
 		let emailDeliveryFailed = false;
@@ -4908,11 +6521,11 @@ function createResetPasswordRoute(config) {
 			invitationSent = hookResult.invitationSent ?? false;
 		} else if (!!(emailService && emailService.isConfigured())) {
 			const token = generateSecureToken();
-			const tokenHash = hashToken$1(token);
+			const tokenHash = hashToken(token);
 			const expiresAt = new Date(Date.now() + 3600 * 1e3);
 			await authRepo.createPasswordResetToken(existing.id, tokenHash, expiresAt);
 			try {
-				const setPasswordUrl = `${emailConfig?.resetPasswordUrl || ""}/reset-password?token=${token}`;
+				const setPasswordUrl = `${resolveEmailLinkBase(emailConfig, "resetPassword")}/reset-password?token=${token}`;
 				const { appName, logoUrl } = resolveEmailBranding(emailConfig);
 				const templateFn = emailConfig?.templates?.passwordReset;
 				const emailContent = templateFn ? templateFn(setPasswordUrl, {
@@ -4956,9 +6569,11 @@ function createResetPasswordRoute(config) {
 //#endregion
 //#region src/auth/admin-roles-route.ts
 /**
-* Admin endpoint for listing all roles.
+* Admin endpoint for listing roles.
 *
-* Mounts: GET /roles
+* Mounts: GET /roles — the built-in `admin` role and the roles the app
+* declares under `auth.roles` on the users collection, with the scopes each
+* holds. Requires `users:read`.
 */
 /**
 * Create a standalone admin route for listing roles.
@@ -4974,9 +6589,8 @@ function createAdminRolesRoute(config) {
 		resolveRoles: (uid) => authRepo.getUserRoleIds(uid),
 		revocationRepo: authRepo
 	}));
-	router.get("/roles", requireAdmin, async (c) => {
-		const roles = await authRepo.listRoles();
-		return c.json({ roles });
+	router.get("/roles", requireScope("users:read"), (c) => {
+		return c.json({ roles: summarizeRoles(getAccessModel()) });
 	});
 	return router;
 }
@@ -4991,6 +6605,7 @@ function createAdminRolesRoute(config) {
 *   POST /users
 *   PUT /users/:uid
 *   DELETE /users/:uid
+*   DELETE /users/:uid/mfa
 *   POST /bootstrap
 */
 /** Upper bound for `GET /users?ids=…`, so one request can't fan out unbounded. */
@@ -5008,6 +6623,7 @@ function createAdminUsersRoute(config) {
 			photoURL: u.photoUrl ?? null,
 			providerId: "custom",
 			roles,
+			disabled: u.disabled === true,
 			createdAt: u.createdAt instanceof Date ? u.createdAt.toISOString() : u.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 			updatedAt: u.updatedAt instanceof Date ? u.updatedAt.toISOString() : u.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString()
 		};
@@ -5034,15 +6650,18 @@ function createAdminUsersRoute(config) {
 		}
 		const uid = "uid" in user ? user.uid : void 0;
 		if (!uid) throw ApiError.unauthorized("User ID not found in auth context");
-		if (isAnonymousUid(uid)) {
+		const refuseAnonymousCaller = () => {
 			logger.warn("[Security Audit] Bootstrap denied: anonymous caller", {
 				eventType: "auth.bootstrap.denied.anonymous",
 				callerId: uid
 			});
 			throw ApiError.forbidden("An anonymous session cannot claim the initial admin role. Register a real account and bootstrap from it, or assign the admin role using the service key.", "BOOTSTRAP_ANONYMOUS");
-		}
-		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("Authenticated user does not exist in the database.", "USER_NOT_FOUND");
-		const registeredUsers = users.filter((u) => !isAnonymousUid(u.id));
+		};
+		if (isAnonymousUid(uid)) refuseAnonymousCaller();
+		const caller = await authRepo.getUserById(uid);
+		if (!caller) throw ApiError.notFound("Authenticated user does not exist in the database.", "USER_NOT_FOUND");
+		if (caller.isAnonymous === true) refuseAnonymousCaller();
+		const registeredUsers = users.filter((u) => u.isAnonymous !== true && !isAnonymousUid(u.id));
 		if (registeredUsers.length > 0) {
 			const earliest = registeredUsers.reduce((a, b) => {
 				const at = new Date(a.createdAt).getTime();
@@ -5073,13 +6692,13 @@ function createAdminUsersRoute(config) {
 			}
 		});
 	});
-	router.get("/users", requireAdmin, async (c) => {
+	router.get("/users", requireScope("users:read"), async (c) => {
 		const idsParam = c.req.query("ids");
 		if (idsParam !== void 0) {
 			const ids = [...new Set(idsParam.split(",").map((id) => id.trim()).filter(Boolean))].slice(0, MAX_USER_IDS_PER_LOOKUP);
 			const users = (await Promise.all(ids.map(async (id) => {
 				const result = await authRepo.getUserWithRoles(id);
-				return result ? toAdminUser(result.user, result.roles.map((r) => r.id)) : void 0;
+				return result ? toAdminUser(result.user, result.roles) : void 0;
 			}))).filter((u) => u !== void 0);
 			return c.json({
 				users,
@@ -5113,17 +6732,18 @@ function createAdminUsersRoute(config) {
 			offset: result.offset
 		});
 	});
-	router.get("/users/:uid", requireAdmin, async (c) => {
+	router.get("/users/:uid", requireScope("users:read"), async (c) => {
 		const uid = c.req.param("uid");
 		const result = await authRepo.getUserWithRoles(uid);
 		if (!result) throw ApiError.notFound("User not found");
-		const adminUser = toAdminUser(result.user, result.roles.map((r) => r.id));
+		const adminUser = toAdminUser(result.user, result.roles);
 		return c.json({ user: adminUser });
 	});
-	router.post("/users", requireAdmin, async (c) => {
+	router.post("/users", requireScope("users:write"), async (c) => {
 		const body = await c.req.json();
 		const { email, roles } = body;
 		if (!email) throw ApiError.badRequest("Email is required");
+		if (roles !== void 0 && Array.isArray(roles)) assertMayGrantRoles(c, roles.filter((role) => typeof role === "string"));
 		if (await authRepo.getUserByEmail(normalizeEmail(email))) throw ApiError.conflict("A user with this email already exists");
 		const prepResult = await prepareAdminUserValues(body, {
 			authRepo,
@@ -5137,7 +6757,8 @@ function createAdminUsersRoute(config) {
 			passwordHash: prepResult.values.passwordHash,
 			displayName: prepResult.values.displayName,
 			photoUrl: prepResult.values.photoUrl,
-			metadata: prepResult.values.metadata
+			metadata: prepResult.values.metadata,
+			emailVerified: prepResult.values.emailVerified === true
 		};
 		if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
 		const user = await authRepo.createUser(createData);
@@ -5158,12 +6779,26 @@ function createAdminUsersRoute(config) {
 			...delivery
 		}, 201);
 	});
-	router.put("/users/:uid", requireAdmin, async (c) => {
+	router.put("/users/:uid", requireScope("users:write"), async (c) => {
 		const uid = c.req.param("uid");
-		const { password, email, displayName, roles } = await c.req.json();
+		const { password, email, displayName, roles, disabled } = await c.req.json();
 		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("User not found");
+		if (disabled !== void 0) {
+			if (typeof disabled !== "boolean") throw ApiError.badRequest("`disabled` must be true or false", "INVALID_INPUT");
+			const caller = c.get("user");
+			if (disabled && caller?.uid === uid) throw ApiError.badRequest("Cannot disable your own account", "SELF_DISABLE");
+			if (typeof authRepo.setUserDisabled !== "function") throw new ApiError(501, "NOT_SUPPORTED", "This backend's auth repository cannot disable accounts.");
+		}
+		assertMayManageAccount(c, await authRepo.getUserRoleIds(uid));
+		if (roles !== void 0 && Array.isArray(roles)) {
+			assertMayGrantRoles(c, roles.filter((role) => typeof role === "string"));
+			await assertRoleChangesAllowed(authRepo, [{
+				uid,
+				roles
+			}]);
+		}
 		const updates = {};
-		if (email !== void 0) updates.email = normalizeEmail(email);
+		if (email !== void 0) updates.email = await normalizeUserEmailChange(authRepo, uid, email);
 		if (displayName !== void 0) updates.displayName = displayName;
 		let passwordHash;
 		if (password) {
@@ -5173,36 +6808,60 @@ function createAdminUsersRoute(config) {
 		}
 		if (Object.keys(updates).length > 0) await authRepo.updateUser(uid, updates);
 		if (passwordHash) await replaceUserPassword(authRepo, uid, passwordHash);
-		if (roles !== void 0 && Array.isArray(roles)) {
-			const wasAdmin = (await authRepo.getUserRoleIds(uid)).includes("admin");
-			const willBeAdmin = roles.includes("admin");
-			if (wasAdmin && !willBeAdmin) {
-				if ((await authRepo.listUsersPaginated({
-					roleId: "admin",
-					limit: 1
-				})).total <= 1) throw ApiError.forbidden("Cannot demote the last administrator", "LAST_ADMIN");
-			}
-			await authRepo.setUserRoles(uid, roles);
+		if (roles !== void 0 && Array.isArray(roles)) await authRepo.setUserRoles(uid, roles);
+		if (typeof disabled === "boolean" && authRepo.setUserDisabled) {
+			await authRepo.setUserDisabled(uid, disabled);
+			if (disabled) await revokeAllSessions(authRepo, uid);
+			logger.info("[Security Audit] Account " + (disabled ? "disabled" : "re-enabled") + " by an administrator", {
+				eventType: disabled ? "auth.account.disabled" : "auth.account.enabled",
+				uid,
+				by: c.get("user")?.uid
+			});
 		}
 		const result = await authRepo.getUserWithRoles(uid);
-		const adminUser = toAdminUser(result.user, result.roles.map((r) => r.id));
+		const adminUser = toAdminUser(result.user, result.roles);
 		return c.json({ user: adminUser });
 	});
-	router.delete("/users/:uid", requireAdmin, async (c) => {
+	/**
+	* DELETE /users/:uid/mfa — remove every second factor and recovery code
+	* an account has, and end its sessions.
+	*
+	* The way back in for someone who lost their authenticator and their
+	* codes, which used to be SQL. It lowers the account's protection, so it
+	* is held to what a password reset is held to: `users:write`, never on an
+	* account that outranks the caller, and every session ends — a session
+	* that passed the old factor must not outlive its removal.
+	*/
+	router.delete("/users/:uid/mfa", requireScope("users:write"), async (c) => {
+		const uid = c.req.param("uid");
+		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("User not found");
+		assertMayManageAccount(c, await authRepo.getUserRoleIds(uid));
+		const factors = await authRepo.getMfaFactors(uid);
+		for (const factor of factors) await authRepo.deleteMfaFactor(factor.id, uid);
+		await authRepo.deleteAllRecoveryCodes(uid);
+		await revokeAllSessions(authRepo, uid);
+		const caller = c.get("user");
+		logger.info("[Security Audit] Second factors reset by an administrator", {
+			eventType: "auth.mfa.admin_reset",
+			uid,
+			by: caller?.uid,
+			removedFactors: factors.length
+		});
+		return c.json({
+			success: true,
+			removedFactors: factors.length
+		});
+	});
+	router.delete("/users/:uid", requireScope("users:write"), async (c) => {
 		const uid = c.req.param("uid");
 		if (c.get("user")?.uid === uid) throw ApiError.badRequest("Cannot delete your own account", "SELF_DELETE");
 		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("User not found");
-		if ((await authRepo.getUserRoleIds(uid)).includes("admin")) {
-			if ((await authRepo.listUsersPaginated({
-				roleId: "admin",
-				limit: 1
-			})).total <= 1) throw ApiError.forbidden("Cannot delete the last administrator", "LAST_ADMIN");
-		}
+		assertMayManageAccount(c, await authRepo.getUserRoleIds(uid));
+		await assertUserDeletionsAllowed(authRepo, [uid]);
 		if (ops.beforeUserDelete) await ops.beforeUserDelete(uid);
+		await authRepo.deleteAllRefreshTokensForUser(uid);
 		await authRepo.deleteUser(uid);
-		if (ops.afterUserDelete) ops.afterUserDelete(uid).catch((err) => {
-			logger.error("[AuthHooks] afterUserDelete error", { error: err instanceof Error ? err.message : err });
-		});
+		runAfterUserDelete(ops, uid);
 		return c.json({ success: true });
 	});
 	return router;
@@ -5217,8 +6876,58 @@ function createAdminUsersRoute(config) {
 * when the user passes a plain `RebaseAuthConfig` object.
 */
 function createBuiltinAuthAdapter(config) {
-	const { authRepository, emailService, emailConfig, allowRegistration = false, disableSelfRegistration = false, allowAnonymous = false, allowUserLookup = false, captcha, defaultRole, oauthProviders = [], allowedRedirectUris, serviceKey, authHooks, collectionAuthConfig, enableMagicLink = false, enableEmailOtp = false, cookieAuth } = config;
+	const { authRepository, emailService, emailConfig, allowRegistration = false, disableSelfRegistration = false, allowAnonymous = false, allowUserLookup = false, captcha, defaultRole, oauthProviders = [], allowedRedirectUris, serviceKey, authHooks, collectionAuthConfig, enableMagicLink = false, enableEmailOtp = false, cookieAuth, requireEmailVerification = false, refreshTokenReuseIntervalSeconds, refreshTokenReuse, magicLinkCreatesUsers = false } = config;
 	const resolvedOps = resolveAuthHooks(authHooks);
+	/**
+	* The caller's roles as the database has them now.
+	*
+	* Read per request because the token's `roles` claim can be a whole
+	* access-token lifetime stale — a demoted admin still holds a token that
+	* says `admin`. So when the read fails, falling back to the claim hands
+	* that token exactly the access the lookup exists to take away; during a
+	* database blip it scoped a demoted admin with admin RLS. This refuses
+	* instead, with the 503 `createRequireAuth` already gives the admin
+	* routes: the adapter middleware answers with it, and the socket treats
+	* a throwing adapter as an invalid token.
+	*/
+	async function resolveLiveRoles(uid) {
+		try {
+			return await authRepository.getUserRoleIds(uid);
+		} catch (error) {
+			logger.warn("[Auth] Could not resolve roles for a request; refusing it", {
+				uid,
+				error
+			});
+			throw new ApiError(503, "ROLE_LOOKUP_FAILED", "Could not verify your permissions. Please try again.");
+		}
+	}
+	/**
+	* The roles a verified access token runs with now, or `null` when it must
+	* not be honoured at all: revoked, or its account deleted. See
+	* `judgeAccessToken`, which both verify paths ask. A repository that
+	* cannot answer refuses the request (503), as `resolveLiveRoles` does.
+	*/
+	async function liveRoles(payload) {
+		let verdict;
+		try {
+			verdict = await judgeAccessToken(authRepository, payload);
+		} catch (error) {
+			logger.warn("[Auth] Could not judge an access token; refusing it", {
+				uid: payload.uid,
+				error
+			});
+			throw new ApiError(503, "ROLE_LOOKUP_FAILED", "Could not verify your permissions. Please try again.");
+		}
+		if (!verdict.live) {
+			logger.warn("[Security Audit] Refused an access token", {
+				eventType: verdict.refusal === "revoked" ? "auth.token.revoked" : "auth.token.account_gone",
+				refusal: verdict.refusal,
+				uid: payload.uid
+			});
+			return null;
+		}
+		return verdict.roles ?? await resolveLiveRoles(payload.uid);
+	}
 	return {
 		id: "rebase-builtin",
 		serviceKey,
@@ -5234,23 +6943,9 @@ function createBuiltinAuthAdapter(config) {
 			};
 			const payload = await verifyAccessToken(token);
 			if (!payload) return null;
-			if (await isAccessTokenRevoked(authRepository, payload)) {
-				logger.warn("[Security Audit] Refused a revoked access token", {
-					eventType: "auth.token.revoked",
-					uid: payload.uid
-				});
-				return null;
-			}
-			let roles = payload.roles || [];
-			try {
-				roles = await authRepository.getUserRoleIds(payload.uid);
-			} catch (err) {
-				logger.warn("Role lookup from repository failed, using token roles as fallback", {
-					uid: payload.uid,
-					error: err
-				});
-			}
-			const isAdmin = hasAdministrativeRole(roles);
+			const roles = await liveRoles(payload);
+			if (!roles) return null;
+			const isAdmin = hasAdminRole(roles);
 			return {
 				uid: payload.uid,
 				email: payload.email ?? "",
@@ -5258,6 +6953,7 @@ function createBuiltinAuthAdapter(config) {
 				roles,
 				isAdmin,
 				isAnonymous: payload.isAnonymous === true,
+				...payload.claims ? { claims: payload.claims } : {},
 				rawToken: token
 			};
 		},
@@ -5271,23 +6967,9 @@ function createBuiltinAuthAdapter(config) {
 			};
 			const payload = await verifyAccessToken(token);
 			if (!payload) return null;
-			if (await isAccessTokenRevoked(authRepository, payload)) {
-				logger.warn("[Security Audit] Refused a revoked access token", {
-					eventType: "auth.token.revoked",
-					uid: payload.uid
-				});
-				return null;
-			}
-			let roles = payload.roles || [];
-			try {
-				roles = await authRepository.getUserRoleIds(payload.uid);
-			} catch (err) {
-				logger.warn("Role lookup from repository failed, using token roles as fallback", {
-					uid: payload.uid,
-					error: err
-				});
-			}
-			const isAdmin = hasAdministrativeRole(roles);
+			const roles = await liveRoles(payload);
+			if (!roles) return null;
+			const isAdmin = hasAdminRole(roles);
 			return {
 				uid: payload.uid,
 				email: payload.email ?? "",
@@ -5295,9 +6977,38 @@ function createBuiltinAuthAdapter(config) {
 				roles,
 				isAdmin,
 				isAnonymous: payload.isAnonymous === true,
+				...payload.claims ? { claims: payload.claims } : {},
 				rawToken: token
 			};
 		},
+		async resolveUser(uid) {
+			let user;
+			try {
+				user = await authRepository.getUserById(uid);
+			} catch (error) {
+				if (isDataException(error)) return null;
+				throw error;
+			}
+			if (!user || user.disabled) return null;
+			const roles = await resolveLiveRoles(uid);
+			const isAnonymous = user.isAnonymous === true;
+			let claims;
+			if (resolvedOps.customizeAccessToken) claims = customClaimsOf(await resolvedOps.customizeAccessToken({
+				uid,
+				roles,
+				aal: "aal1"
+			}, user));
+			return {
+				uid,
+				email: user.email,
+				displayName: user.displayName ?? null,
+				photoUrl: user.photoUrl ?? null,
+				roles,
+				isAdmin: hasAdminRole(roles),
+				isAnonymous,
+				...claims ? { claims } : {}
+			};
+		},
 		userManagement: createUserManagementFromRepo(authRepository, resolvedOps),
 		createAuthRoutes() {
 			return createAuthRoutes({
@@ -5315,7 +7026,11 @@ function createBuiltinAuthAdapter(config) {
 				enableMagicLink,
 				enableEmailOtp,
 				cookieAuth,
-				captcha
+				captcha,
+				requireEmailVerification,
+				refreshTokenReuseIntervalSeconds,
+				refreshTokenReuse,
+				magicLinkCreatesUsers
 			});
 		},
 		createAdminRoutes() {
@@ -5373,6 +7088,10 @@ function createBuiltinAuthAdapter(config) {
 				collectionAuthConfig
 			});
 		},
+		...authCollectionUserAdmin({
+			authRepo: authRepository,
+			resolvedHooks: resolvedOps
+		}),
 		async getCapabilities() {
 			let needsSetup = false;
 			try {
@@ -5422,7 +7141,8 @@ function createUserManagementFromRepo(repo, resolvedOps) {
 				passwordHash,
 				displayName: data.displayName,
 				photoUrl: data.photoUrl,
-				metadata: data.metadata
+				metadata: data.metadata,
+				...data.emailVerified !== void 0 ? { emailVerified: data.emailVerified } : {}
 			};
 			if (resolvedOps.beforeUserCreate) createData = await resolvedOps.beforeUserCreate(createData);
 			const user = await repo.createUser(createData);
@@ -5446,6 +7166,7 @@ function createUserManagementFromRepo(repo, resolvedOps) {
 		},
 		async deleteUser(id) {
 			if (resolvedOps.beforeUserDelete) await resolvedOps.beforeUserDelete(id);
+			await repo.deleteAllRefreshTokensForUser(id);
 			await repo.deleteUser(id);
 			if (resolvedOps.afterUserDelete) resolvedOps.afterUserDelete(id).catch((err) => {
 				logger.error("[AuthHooks] afterUserDelete error", { error: err instanceof Error ? err.message : err });
@@ -6700,9 +8421,76 @@ function resolveRateLimitStoreKind(env) {
 	throw new RateLimitStoreConfigurationError(`REBASE_RATE_LIMIT_STORE="${raw}" is not a rate-limit store.`, "Use \"sql\" to share counts across processes, or \"memory\" (the default) to keep them in this process. A deployment running more than one replica or more than one role wants \"sql\" — otherwise each process enforces the whole limit by itself.");
 }
 //#endregion
+//#region src/auth/api-keys/legacy-permissions.ts
+var OPERATIONS = [
+	"read",
+	"write",
+	"delete"
+];
+function isOperation(value) {
+	return OPERATIONS.includes(value);
+}
+/** The admin surfaces an `admin: true` key reached. */
+var ADMIN_KEY_SCOPES = [
+	"users:read",
+	"users:write",
+	"schema:read",
+	"schema:write",
+	"backups:read",
+	"cron:read",
+	"cron:write",
+	"logs:read"
+];
+/** Read a stored `permissions` value — JSON text or already-parsed — into entries. */
+function parseStoredPermissions(value) {
+	let raw = value;
+	if (typeof raw === "string") try {
+		raw = JSON.parse(raw);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(raw)) return [];
+	const entries = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		if (!("collection" in item) || typeof item.collection !== "string") continue;
+		const operations = "operations" in item && Array.isArray(item.operations) ? item.operations.filter((op) => typeof op === "string") : [];
+		entries.push({
+			collection: item.collection,
+			operations
+		});
+	}
+	return entries;
+}
+/** The scopes and RLS roles a stored key now holds. Never more than it did. */
+function scopesFromStoredPermissions(permissions, admin) {
+	const scopes = /* @__PURE__ */ new Set();
+	for (const { collection, operations } of permissions) {
+		const ops = operations.filter(isOperation);
+		if (collection === "*") {
+			for (const op of ops) {
+				scopes.add(`data:${op}`);
+				scopes.add(`storage:${op}`);
+			}
+			if (ops.includes("write")) scopes.add("functions:invoke");
+		} else if (collection === "storage") for (const op of ops) scopes.add(`storage:${op}`);
+		else if (collection === "functions") {
+			if (ops.includes("write")) scopes.add("functions:invoke");
+		} else if (collection.startsWith("functions/")) {
+			const name = collection.slice(10);
+			if (name && ops.includes("write")) scopes.add(`functions:invoke:${name}`);
+		} else if (collection) for (const op of ops) scopes.add(`data:${op}:${collection}`);
+	}
+	if (admin) for (const scope of ADMIN_KEY_SCOPES) scopes.add(scope);
+	return {
+		scopes: [...scopes],
+		roles: admin ? ["admin"] : []
+	};
+}
+//#endregion
 //#region src/auth/api-keys/api-key-store.ts
 /**
-* Database operations for Service API Keys.
+* Database operations for API keys.
 *
 * Uses the DataDriver's `admin.executeSql` capability (same pattern as
 * the cron-store and ensure-tables modules). All data lives in the
@@ -6738,9 +8526,11 @@ function toMasked(row) {
 	return {
 		id: row.id,
 		name: row.name,
+		kind: row.kind,
 		key_prefix: row.key_prefix,
-		permissions: row.permissions,
-		admin: row.admin,
+		scopes: row.scopes,
+		roles: row.roles,
+		owner_uid: row.owner_uid,
 		rate_limit: row.rate_limit,
 		created_by: row.created_by,
 		created_at: row.created_at,
@@ -6750,30 +8540,40 @@ function toMasked(row) {
 		revoked_at: row.revoked_at
 	};
 }
+/** A JSONB string array as the driver hands it back: parsed, or JSON text. */
+function stringList(value) {
+	let raw = value;
+	if (typeof raw === "string") try {
+		raw = JSON.parse(raw);
+	} catch {
+		return [];
+	}
+	return Array.isArray(raw) ? raw.filter((entry) => typeof entry === "string") : [];
+}
 /**
 * Parse a raw DB row into the typed `ApiKey` shape.
 */
 function rowToApiKey(row) {
-	let permissions = row.permissions ?? [];
-	if (typeof row.permissions === "string") try {
-		permissions = JSON.parse(row.permissions);
-	} catch {
-		permissions = [];
-	}
+	const grant = row.scopes === null || row.scopes === void 0 ? scopesFromStoredPermissions(parseStoredPermissions(row.permissions), row.admin === true) : {
+		scopes: stringList(row.scopes),
+		roles: stringList(row.roles)
+	};
 	return {
-		id: row.id,
-		name: row.name,
-		key_prefix: row.key_prefix,
-		key_hash: row.key_hash,
-		permissions,
-		admin: Boolean(row.admin),
+		id: String(row.id),
+		name: String(row.name),
+		kind: row.kind === "personal" ? "personal" : "service",
+		key_prefix: String(row.key_prefix),
+		key_hash: String(row.key_hash),
+		scopes: grant.scopes,
+		roles: grant.roles,
+		owner_uid: typeof row.owner_uid === "string" ? row.owner_uid : null,
 		rate_limit: row.rate_limit !== null && row.rate_limit !== void 0 ? Number(row.rate_limit) : null,
-		created_by: row.created_by,
-		created_at: new Date(row.created_at).toISOString(),
-		updated_at: new Date(row.updated_at).toISOString(),
-		last_used_at: row.last_used_at ? new Date(row.last_used_at).toISOString() : null,
-		expires_at: row.expires_at ? new Date(row.expires_at).toISOString() : null,
-		revoked_at: row.revoked_at ? new Date(row.revoked_at).toISOString() : null
+		created_by: String(row.created_by),
+		created_at: new Date(String(row.created_at)).toISOString(),
+		updated_at: new Date(String(row.updated_at)).toISOString(),
+		last_used_at: row.last_used_at ? new Date(String(row.last_used_at)).toISOString() : null,
+		expires_at: row.expires_at ? new Date(String(row.expires_at)).toISOString() : null,
+		revoked_at: row.revoked_at ? new Date(String(row.revoked_at)).toISOString() : null
 	};
 }
 /**
@@ -6789,6 +8589,26 @@ function createApiKeyStore(driver) {
 	}
 	const exec = (sqlText, options) => admin.executeSql(sqlText, options?.params ? { params: options.params } : void 0);
 	const ddl = createDdlBootstrapper(exec, "api-key-store");
+	/**
+	* Give every row stored before scopes existed the scopes it now holds.
+	*
+	* Idempotent and race-safe: a row is only written while its `scopes` is
+	* still NULL, so two instances backfilling together write the same value
+	* once. The `permissions` and `admin` columns are left as they are, so a
+	* runtime that predates scopes still reads its own keys after a rollback.
+	*/
+	async function backfillScopes() {
+		const rows = await exec(`SELECT id, permissions, admin FROM ${TABLE} WHERE scopes IS NULL`);
+		for (const row of rows) {
+			const { scopes, roles } = scopesFromStoredPermissions(parseStoredPermissions(row.permissions), row.admin === true);
+			await exec(`UPDATE ${TABLE} SET scopes = $1::jsonb, roles = $2::jsonb WHERE id = $3 AND scopes IS NULL`, { params: [
+				JSON.stringify(scopes),
+				JSON.stringify(roles),
+				row.id
+			] });
+		}
+		if (rows.length > 0) logger.info(`[api-key-store] Gave ${rows.length} stored API key(s) their scopes.`);
+	}
 	return {
 		async ensureTable() {
 			await ddl.ensureObject("Creating schema rebase", "CREATE SCHEMA IF NOT EXISTS rebase");
@@ -6796,10 +8616,12 @@ function createApiKeyStore(driver) {
                 CREATE TABLE IF NOT EXISTS ${TABLE} (
                     id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
                     name TEXT NOT NULL,
+                    kind TEXT NOT NULL DEFAULT 'service',
                     key_prefix TEXT NOT NULL,
                     key_hash TEXT NOT NULL UNIQUE,
-                    permissions JSONB NOT NULL DEFAULT '[]'::jsonb,
-                    admin BOOLEAN NOT NULL DEFAULT FALSE,
+                    scopes JSONB,
+                    roles JSONB NOT NULL DEFAULT '[]'::jsonb,
+                    owner_uid TEXT,
                     rate_limit INTEGER,
                     created_by TEXT NOT NULL,
                     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -6817,34 +8639,49 @@ function createApiKeyStore(driver) {
                 CREATE INDEX IF NOT EXISTS idx_api_keys_prefix
                 ON ${TABLE}(key_prefix)
             `);
-			await ddl.ensureObject(`Adding ${TABLE}.admin`, `
-                ALTER TABLE ${TABLE}
-                ADD COLUMN IF NOT EXISTS admin BOOLEAN NOT NULL DEFAULT FALSE
+			await ddl.ensureObject(`Adding ${TABLE}.kind`, `
+                ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS kind TEXT NOT NULL DEFAULT 'service'
+            `);
+			await ddl.ensureObject(`Adding ${TABLE}.scopes`, `
+                ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS scopes JSONB
+            `);
+			await ddl.ensureObject(`Adding ${TABLE}.roles`, `
+                ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS roles JSONB NOT NULL DEFAULT '[]'::jsonb
+            `);
+			await ddl.ensureObject(`Adding ${TABLE}.owner_uid`, `
+                ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS owner_uid TEXT
+            `);
+			await ddl.ensureObject("Creating idx_api_keys_owner", `
+                CREATE INDEX IF NOT EXISTS idx_api_keys_owner
+                ON ${TABLE}(owner_uid) WHERE owner_uid IS NOT NULL
             `);
 			if (!await ddl.isReadable(TABLE)) {
 				logger.error(`❌ [api-key-store] ${TABLE} is unavailable — every API-key authenticated request will be rejected on this instance, and the table could not be taken back off the end-user role.`);
 				return;
 			}
 			await ddl.step("Revoking end-user access to api_keys", () => exec(revokeInternalTableSql("rebase", "api_keys")));
+			if ((await exec(`SELECT 1 FROM information_schema.columns
+                 WHERE table_schema = 'rebase' AND table_name = 'api_keys' AND column_name = 'permissions'`)).length > 0) await ddl.step("Backfilling API key scopes", backfillScopes);
 			logger.debug("✅ API keys table ready");
 		},
-		async createApiKey(request, createdBy) {
+		async createApiKey(key, createdBy) {
 			const plaintext = generateApiKey();
 			const hash = hashKey(plaintext);
 			const prefix = keyPrefix(plaintext);
-			const permissionsJson = JSON.stringify(request.permissions);
 			return {
-				...toMasked(rowToApiKey((await exec(`INSERT INTO ${TABLE} (name, key_prefix, key_hash, permissions, admin, rate_limit, created_by, expires_at)
-                 VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, $8)
+				...toMasked(rowToApiKey((await exec(`INSERT INTO ${TABLE} (name, kind, key_prefix, key_hash, scopes, roles, owner_uid, rate_limit, created_by, expires_at)
+                 VALUES ($1, $2, $3, $4, $5::jsonb, $6::jsonb, $7, $8, $9, $10)
                  RETURNING *`, { params: [
-					request.name,
+					key.name,
+					key.kind,
 					prefix,
 					hash,
-					permissionsJson,
-					request.admin ?? false,
-					request.rate_limit ?? null,
+					JSON.stringify(key.scopes),
+					JSON.stringify(key.kind === "personal" ? [] : key.roles),
+					key.owner_uid,
+					key.rate_limit,
 					createdBy,
-					request.expires_at ?? null
+					key.expires_at
 				] }))[0])),
 				key: plaintext
 			};
@@ -6856,11 +8693,14 @@ function createApiKeyStore(driver) {
 			if (rows.length === 0) return null;
 			return rowToApiKey(rows[0]);
 		},
-		async listApiKeys() {
-			return (await exec(`
-                SELECT * FROM ${TABLE}
-                ORDER BY created_at DESC
-            `)).map((r) => toMasked(rowToApiKey(r)));
+		async listApiKeys(filter) {
+			return (filter.kind === "personal" ? await exec(`SELECT * FROM ${TABLE}
+                     WHERE kind = 'personal' AND owner_uid = $1
+                     ORDER BY created_at DESC`, { params: [filter.owner_uid] }) : await exec(`
+                    SELECT * FROM ${TABLE}
+                    WHERE kind = 'service'
+                    ORDER BY created_at DESC
+                `)).map((r) => toMasked(rowToApiKey(r)));
 		},
 		async getApiKeyById(id) {
 			const rows = await exec(`SELECT * FROM ${TABLE}
@@ -6877,13 +8717,13 @@ function createApiKeyStore(driver) {
 				setClauses.push(`name = $${paramIdx++}`);
 				params.push(updates.name);
 			}
-			if (updates.permissions !== void 0) {
-				setClauses.push(`permissions = $${paramIdx++}::jsonb`);
-				params.push(JSON.stringify(updates.permissions));
+			if (updates.scopes !== void 0) {
+				setClauses.push(`scopes = $${paramIdx++}::jsonb`);
+				params.push(JSON.stringify(updates.scopes));
 			}
-			if (updates.admin !== void 0) {
-				setClauses.push(`admin = $${paramIdx++}`);
-				params.push(updates.admin);
+			if (updates.roles !== void 0) {
+				setClauses.push(`roles = $${paramIdx++}::jsonb`);
+				params.push(JSON.stringify(updates.roles));
 			}
 			if (updates.rate_limit !== void 0) if (updates.rate_limit !== null) {
 				setClauses.push(`rate_limit = $${paramIdx++}`);
@@ -6898,16 +8738,19 @@ function createApiKeyStore(driver) {
 			params.push(id);
 			const rows = await exec(`UPDATE ${TABLE}
                  SET ${setClauses.join(", ")}
-                 WHERE id = $${paramIdx}
+                 WHERE id = $${paramIdx} AND kind = 'service'
                  RETURNING *`, { params });
 			if (rows.length === 0) return null;
 			return toMasked(rowToApiKey(rows[0]));
 		},
-		async revokeApiKey(id) {
-			return (await exec(`UPDATE ${TABLE}
-                 SET revoked_at = NOW(), updated_at = NOW()
-                 WHERE id = $1 AND revoked_at IS NULL
-                 RETURNING id`, { params: [id] })).length > 0;
+		async revokeApiKey(id, owner_uid) {
+			return (owner_uid === void 0 ? await exec(`UPDATE ${TABLE}
+                     SET revoked_at = NOW(), updated_at = NOW()
+                     WHERE id = $1 AND kind = 'service' AND revoked_at IS NULL
+                     RETURNING id`, { params: [id] }) : await exec(`UPDATE ${TABLE}
+                     SET revoked_at = NOW(), updated_at = NOW()
+                     WHERE id = $1 AND kind = 'personal' AND owner_uid = $2 AND revoked_at IS NULL
+                     RETURNING id`, { params: [id, owner_uid] })).length > 0;
 		},
 		async updateLastUsed(id) {
 			try {
@@ -6921,62 +8764,156 @@ function createApiKeyStore(driver) {
 	};
 }
 //#endregion
-//#region src/auth/api-keys/api-key-routes.ts
+//#region src/auth/api-keys/key-grant.ts
 /**
-* Admin routes for managing Service API Keys.
+* What a new or changed key may hold, decided against whoever asked for it.
 *
-* Mounted under `/api/admin/api-keys` with `requireAuth` + `requireAdmin`.
-* All routes return masked keys (never the hash). The full plaintext key
-* is returned exactly once in the POST response.
+* One rule for every door that mints a credential: **nothing is minted with
+* more than its minter holds.** A key's scopes must be within the creator's
+* own; a service key's RLS roles must be roles the creator holds, unless the
+* creator is an admin; and `keys:*` never goes on a key at all.
 *
 * @module
 */
+var TARGET_LISTS = {
+	collection: "collections",
+	bucket: "buckets",
+	function: "functions"
+};
+/** Read a `scopes` body field: a non-empty array of strings, deduplicated. */
+function readScopesField(value) {
+	if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== "string")) throw ApiError.badRequest("scopes must be a non-empty array of scope strings, e.g. [\"data:read\", \"data:write:posts\"]", "INVALID_INPUT");
+	return [...new Set(value.map((entry) => entry.trim()))];
+}
+/** Read a `roles` body field: an array of non-empty strings, deduplicated, without `service`. */
+function readRolesField(value) {
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim() === "")) throw ApiError.badRequest("roles must be an array of role names", "INVALID_INPUT");
+	return [...new Set(value.map((entry) => entry.trim()))].filter((role) => role !== "service");
+}
 /**
-* Validate that a permissions array is well-formed.
-*/
-function validatePermissions(permissions) {
-	if (!Array.isArray(permissions)) return false;
-	for (const perm of permissions) {
-		if (typeof perm !== "object" || perm === null) return false;
-		if (typeof perm.collection !== "string" || perm.collection.length === 0) return false;
-		if (!Array.isArray(perm.operations) || perm.operations.length === 0) return false;
-		const validOps = /* @__PURE__ */ new Set([
-			"read",
-			"write",
-			"delete"
-		]);
-		for (const op of perm.operations) if (!validOps.has(op)) return false;
+* Refuse scopes that are malformed, unknown, aimed at a target that does not
+* exist, for key management, or beyond what `minterScopes` covers.
+*/
+function assertScopesGrantable(requested, minterScopes, model, targets) {
+	const problems = validateScopes(requested, model);
+	if (problems.length > 0) throw new ApiError(400, "INVALID_SCOPES", `Not valid scopes: ${problems.map((p) => `"${p.scope}" (${p.reason})`).join(", ")}. Valid scopes are ${knownScopes(model).join(", ")}; data, storage and function scopes take a target after a second colon, e.g. "data:read:posts".`, {
+		problems,
+		validScopes: knownScopes(model)
+	});
+	const management = requested.filter((entry) => KEY_MANAGEMENT_SCOPES.includes(parseScope(entry)?.scope ?? ""));
+	if (management.length > 0) throw new ApiError(400, "KEY_MANAGEMENT_SCOPE", `${management.join(", ")} cannot go on a key: a key that manages keys could mint its own successor. Manage keys as a person, or with the service key.`, { scopes: management });
+	if (targets) {
+		const unknown = [];
+		for (const entry of requested) {
+			const parsed = parseScope(entry);
+			if (!parsed?.target || !isBuiltInScope(parsed.scope)) continue;
+			const kind = SCOPE_TARGETS[parsed.scope];
+			if (!kind) continue;
+			if (!targets[TARGET_LISTS[kind]]().includes(parsed.target)) unknown.push(entry);
+		}
+		if (unknown.length > 0) throw new ApiError(400, "UNKNOWN_SCOPE_TARGET", `These scopes name something this backend does not serve: ${unknown.join(", ")}. A target is a collection slug, a storage source id or a function name.`, {
+			scopes: unknown,
+			collections: targets.collections(),
+			buckets: targets.buckets(),
+			functions: targets.functions()
+		});
 	}
-	return true;
+	const beyond = scopesBeyond(requested, minterScopes);
+	if (beyond.length > 0) throw new ApiError(403, "SCOPE_EXCEEDS_CREATOR", `A key cannot hold more than the account creating it, and you do not hold ${beyond.join(", ")}.`, { scopes: beyond });
+}
+/**
+* Refuse RLS roles the minter does not hold. An admin may give any role — they
+* already read every row — and anyone else only their own.
+*/
+function assertRolesGrantable(requested, minterRoles) {
+	if (hasAdminRole(minterRoles)) return;
+	const beyond = requested.filter((role) => !minterRoles.includes(role));
+	if (beyond.length > 0) throw new ApiError(403, "ROLE_EXCEEDS_CREATOR", `A key cannot run as a role the account creating it does not hold: ${beyond.join(", ")}.`, { roles: beyond });
+}
+/** Read an optional `expires_at`: absent, null, or a future ISO-8601 instant. */
+function readExpiresAt(value, requireFuture) {
+	if (value === void 0) return void 0;
+	if (value === null) return null;
+	const parsed = typeof value === "string" ? new Date(value) : /* @__PURE__ */ new Date(NaN);
+	if (isNaN(parsed.getTime())) throw ApiError.badRequest("expires_at must be a valid ISO-8601 date", "INVALID_INPUT");
+	if (requireFuture && parsed <= /* @__PURE__ */ new Date()) throw ApiError.badRequest("expires_at must be in the future", "INVALID_INPUT");
+	return parsed.toISOString();
+}
+/** Read an optional `rate_limit`: absent, null, or a positive integer. */
+function readRateLimit(value) {
+	if (value === void 0) return void 0;
+	if (value === null) return null;
+	if (typeof value !== "number" || value < 1 || !Number.isInteger(value)) throw ApiError.badRequest("rate_limit must be a positive integer or null", "INVALID_INPUT");
+	return value;
+}
+/** Read a key name: a non-empty string, trimmed. */
+function readName(value) {
+	if (typeof value !== "string" || value.trim().length === 0) throw ApiError.badRequest("Name is required", "INVALID_INPUT");
+	return value.trim();
 }
+//#endregion
+//#region src/auth/api-keys/api-key-routes.ts
 /**
-* Refuse API-key-authenticated requests to the key-management routes.
+* Routes for managing API keys.
+*
+* - {@link createApiKeyRoutes} — the project's service keys, under
+*   `/api/admin/api-keys`, for holders of `keys:read` / `keys:write`.
+* - {@link createPersonalKeyRoutes} — the caller's own personal keys, under
+*   `/api/auth/keys`, when the app enables `auth.personalKeys`.
 *
-* `createApiKeyPreAuth` runs in front of every `/admin/*` router so that keys
-* created with `admin: true` genuinely reach the admin surfaces — their
-* documented behaviour, and the right behaviour everywhere except here.
-* Applied to *this* router it means an admin key can mint a second admin key,
-* widen its own grants through `PUT /:id`, or revoke the keys other
-* integrations run on. Revoking the original key undoes none of that, because
-* the keys it minted are ordinary rows with no link back to it.
+* All routes return masked keys (never the hash). The full plaintext key is
+* returned exactly once, in the response that creates it. No API key may call
+* either router.
+*
+* @module
+*/
+/**
+* Refuse API-key-authenticated requests to the key-management routes.
 *
-* So key management is reserved for callers that are not themselves an API
-* key: a human admin's session, or the service key.
+* A key that could manage keys could mint its own successor, widen itself, or
+* revoke the keys other integrations run on — and revoking it would undo none
+* of that, because the keys it minted are ordinary rows with no link back to
+* it. So key management is for a person, or the service key. Reads are
+* refused alongside writes: a listing of every key's name, prefix and scopes
+* is reconnaissance for exactly that.
 *
-* Reads are refused alongside writes. The list response enumerates every key's
-* name, prefix, permission set and admin flag — reconnaissance for exactly the
-* escalation above — and "an API key never touches API keys" is a rule with no
-* edges left to get wrong.
+* `keys:*` can never be granted to a key either (`key-grant.ts`); this guard is
+* what makes the rule hold for a key minted before that, and for personal
+* keys, whose routes need no scope.
 */
 var rejectApiKeyAuth = async (c, next) => {
-	if (c.get("apiKey")) throw ApiError.forbidden("API keys cannot manage API keys. Authenticate as an admin user, or use the service key — REBASE_SERVICE_KEY in this server's environment, or `rebase cloud env reveal REBASE_SERVICE_KEY` on Rebase Cloud.", "API_KEY_SELF_MANAGEMENT_FORBIDDEN");
+	if (c.get("apiKey")) throw ApiError.forbidden("API keys cannot manage API keys. Authenticate as a person, or use the service key — REBASE_SERVICE_KEY in this server's environment, or `rebase cloud env reveal REBASE_SERVICE_KEY` on Rebase Cloud.", "API_KEY_SELF_MANAGEMENT_FORBIDDEN");
 	return next();
 };
+/** The caller's uid and roles, as the auth gate resolved them. */
+function caller(c) {
+	const user = c.get("user");
+	if (!user || typeof user !== "object" || !("uid" in user) || typeof user.uid !== "string") throw ApiError.unauthenticated("Authentication required");
+	const roles = "roles" in user && Array.isArray(user.roles) ? user.roles.filter((role) => typeof role === "string") : [];
+	const isAnonymous = "isAnonymous" in user && user.isAnonymous === true;
+	return {
+		uid: user.uid,
+		roles,
+		isAnonymous
+	};
+}
+async function readBody(c) {
+	let body;
+	try {
+		body = await c.req.json();
+	} catch {
+		throw ApiError.badRequest("Request body must be JSON", "INVALID_INPUT");
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw ApiError.badRequest("Request body must be a JSON object", "INVALID_INPUT");
+	return Object.fromEntries(Object.entries(body));
+}
 /**
-* Create admin routes for API key management.
+* The project's service keys: `GET` needs `keys:read`, everything else
+* `keys:write`.
 */
 function createApiKeyRoutes(options) {
-	const { store, serviceKey, resolveRoles, revocationRepo } = options;
+	const { store, serviceKey, resolveRoles, revocationRepo, targets } = options;
+	const model = options.accessModel ?? getAccessModel;
 	const router = new Hono();
 	router.onError(errorHandler);
 	router.use("/*", createRequireAuth({
@@ -6985,72 +8922,127 @@ function createApiKeyRoutes(options) {
 		revocationRepo
 	}));
 	router.use("/*", rejectApiKeyAuth);
-	router.use("/*", requireAdmin);
+	router.use("/*", requireScopeByMethod({
+		read: "keys:read",
+		write: "keys:write"
+	}));
 	router.get("/", async (c) => {
-		const keys = await store.listApiKeys();
+		const keys = await store.listApiKeys({ kind: "service" });
 		return c.json({ keys });
 	});
 	router.post("/", async (c) => {
-		const { name, permissions, admin, rate_limit, expires_at } = await c.req.json();
-		if (!name || typeof name !== "string" || name.trim().length === 0) throw ApiError.badRequest("Name is required", "INVALID_INPUT");
-		if (!validatePermissions(permissions)) throw ApiError.badRequest("Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }", "INVALID_INPUT");
-		if (admin !== void 0 && typeof admin !== "boolean") throw ApiError.badRequest("admin must be a boolean", "INVALID_INPUT");
-		if (rate_limit !== void 0 && rate_limit !== null) {
-			if (typeof rate_limit !== "number" || rate_limit < 1 || !Number.isInteger(rate_limit)) throw ApiError.badRequest("rate_limit must be a positive integer or null", "INVALID_INPUT");
-		}
-		if (expires_at !== void 0 && expires_at !== null) {
-			const parsed = new Date(expires_at);
-			if (isNaN(parsed.getTime())) throw ApiError.badRequest("expires_at must be a valid ISO-8601 date", "INVALID_INPUT");
-			if (parsed <= /* @__PURE__ */ new Date()) throw ApiError.badRequest("expires_at must be in the future", "INVALID_INPUT");
-		}
-		const user = c.get("user");
-		const createdBy = user && typeof user === "object" && "uid" in user ? user.uid : "unknown";
-		const request = {
-			name: name.trim(),
-			permissions,
-			admin: admin ?? false,
-			rate_limit: rate_limit ?? null,
-			expires_at: expires_at ?? null
-		};
-		const keyWithSecret = await store.createApiKey(request, createdBy);
-		return c.json({ key: keyWithSecret }, 201);
+		const body = await readBody(c);
+		const name = readName(body.name);
+		const scopes = readScopesField(body.scopes);
+		const roles = body.roles === void 0 ? [] : readRolesField(body.roles);
+		const rate_limit = readRateLimit(body.rate_limit) ?? null;
+		const expires_at = readExpiresAt(body.expires_at, true) ?? null;
+		const minter = caller(c);
+		assertScopesGrantable(scopes, callerScopes(c), model(), targets);
+		assertRolesGrantable(roles, minter.roles);
+		const key = await store.createApiKey({
+			name,
+			kind: "service",
+			scopes,
+			roles,
+			owner_uid: null,
+			rate_limit,
+			expires_at
+		}, minter.uid);
+		return c.json({ key }, 201);
 	});
 	router.get("/:id", async (c) => {
-		const id = c.req.param("id");
-		const key = await store.getApiKeyById(id);
-		if (!key) throw ApiError.notFound("API key not found");
+		const key = await store.getApiKeyById(c.req.param("id"));
+		if (!key || key.kind !== "service") throw ApiError.notFound("API key not found");
 		return c.json({ key });
 	});
 	router.put("/:id", async (c) => {
 		const id = c.req.param("id");
-		const { name, permissions, admin, rate_limit, expires_at } = await c.req.json();
-		if (name !== void 0) {
-			if (typeof name !== "string" || name.trim().length === 0) throw ApiError.badRequest("Name must be a non-empty string", "INVALID_INPUT");
-		}
-		if (permissions !== void 0) {
-			if (!validatePermissions(permissions)) throw ApiError.badRequest("Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }", "INVALID_INPUT");
-		}
-		if (admin !== void 0 && typeof admin !== "boolean") throw ApiError.badRequest("admin must be a boolean", "INVALID_INPUT");
-		if (rate_limit !== void 0 && rate_limit !== null) {
-			if (typeof rate_limit !== "number" || rate_limit < 1 || !Number.isInteger(rate_limit)) throw ApiError.badRequest("rate_limit must be a positive integer or null", "INVALID_INPUT");
+		const body = await readBody(c);
+		const minter = caller(c);
+		const updates = {};
+		if (body.name !== void 0) updates.name = readName(body.name);
+		if (body.scopes !== void 0) {
+			updates.scopes = readScopesField(body.scopes);
+			assertScopesGrantable(updates.scopes, callerScopes(c), model(), targets);
 		}
-		if (expires_at !== void 0 && expires_at !== null) {
-			const parsed = new Date(expires_at);
-			if (isNaN(parsed.getTime())) throw ApiError.badRequest("expires_at must be a valid ISO-8601 date", "INVALID_INPUT");
+		if (body.roles !== void 0) {
+			updates.roles = readRolesField(body.roles);
+			assertRolesGrantable(updates.roles, minter.roles);
 		}
-		const updates = {};
-		if (name !== void 0) updates.name = name.trim();
-		if (permissions !== void 0) updates.permissions = permissions;
-		if (admin !== void 0) updates.admin = admin;
-		if (rate_limit !== void 0) updates.rate_limit = rate_limit;
-		if (expires_at !== void 0) updates.expires_at = expires_at;
+		const rateLimit = readRateLimit(body.rate_limit);
+		if (rateLimit !== void 0) updates.rate_limit = rateLimit;
+		const expiresAt = readExpiresAt(body.expires_at, false);
+		if (expiresAt !== void 0) updates.expires_at = expiresAt;
 		const key = await store.updateApiKey(id, updates);
 		if (!key) throw ApiError.notFound("API key not found");
 		return c.json({ key });
 	});
 	router.delete("/:id", async (c) => {
-		const id = c.req.param("id");
-		if (!await store.revokeApiKey(id)) throw ApiError.notFound("API key not found or already revoked");
+		if (!await store.revokeApiKey(c.req.param("id"))) throw ApiError.notFound("API key not found or already revoked");
+		return c.json({ success: true });
+	});
+	return router;
+}
+/**
+* The caller's own keys. Each acts as the caller — their account, their roles
+* as they are when the key is used — and holds no scope the caller does not.
+*
+* For a signed-in account only: not a key, not the service key (it has no
+* account to act as) and not a guest, whose account is one sign-out from gone.
+*/
+function createPersonalKeyRoutes(options) {
+	const { store, enabled, serviceKey, resolveRoles, revocationRepo, targets } = options;
+	const model = options.accessModel ?? getAccessModel;
+	const router = new Hono();
+	router.onError(errorHandler);
+	if (!enabled) {
+		router.all("/*", () => {
+			throw ApiError.forbidden("Personal API keys are switched off on this backend. Set `personalKeys: true` in the auth block of the users collection to let accounts create them.", "PERSONAL_KEYS_DISABLED");
+		});
+		return router;
+	}
+	router.use("/*", createRequireAuth({
+		serviceKey,
+		resolveRoles,
+		revocationRepo
+	}));
+	router.use("/*", rejectApiKeyAuth);
+	router.use("/*", async (c, next) => {
+		const me = caller(c);
+		if (me.uid === "service") throw ApiError.forbidden("The service key has no account for a personal key to act as. Create a service key under /api/admin/api-keys instead.", "PERSONAL_KEY_NEEDS_ACCOUNT");
+		if (me.isAnonymous) throw ApiError.forbidden("A guest session cannot create API keys. Sign in to an account first.", "PERSONAL_KEY_NEEDS_ACCOUNT");
+		return next();
+	});
+	router.get("/", async (c) => {
+		const keys = await store.listApiKeys({
+			kind: "personal",
+			owner_uid: caller(c).uid
+		});
+		return c.json({ keys });
+	});
+	router.post("/", async (c) => {
+		const body = await readBody(c);
+		if (body.roles !== void 0) throw ApiError.badRequest("A personal key runs as your account's roles and takes none of its own.", "INVALID_INPUT");
+		if (body.rate_limit !== void 0) throw ApiError.badRequest("A personal key uses the server's API-key rate limit and cannot set its own.", "INVALID_INPUT");
+		const name = readName(body.name);
+		const scopes = readScopesField(body.scopes);
+		const expires_at = readExpiresAt(body.expires_at, true) ?? null;
+		const me = caller(c);
+		assertScopesGrantable(scopes, callerScopes(c), model(), targets);
+		const key = await store.createApiKey({
+			name,
+			kind: "personal",
+			scopes,
+			roles: [],
+			owner_uid: me.uid,
+			rate_limit: null,
+			expires_at
+		}, me.uid);
+		return c.json({ key }, 201);
+	});
+	router.delete("/:id", async (c) => {
+		if (!await store.revokeApiKey(c.req.param("id"), caller(c).uid)) throw ApiError.notFound("API key not found or already revoked");
 		return c.json({ success: true });
 	});
 	return router;
@@ -7101,12 +9093,16 @@ function createCustomAuthAdapter(options) {
 //#endregion
 //#region src/auth/index.ts
 var auth_exports = /* @__PURE__ */ __exportAll({
+	AccessModelError: () => AccessModelError,
 	DEFAULT_CAPTCHA_ROUTES: () => DEFAULT_CAPTCHA_ROUTES,
 	MemoryRateLimitStore: () => MemoryRateLimitStore,
 	RateLimitStoreConfigurationError: () => RateLimitStoreConfigurationError,
+	accessModelFromCollections: () => accessModelFromCollections,
 	apiKeyKeyGenerator: () => apiKeyKeyGenerator,
 	buildBuiltinAuthCapabilities: () => buildBuiltinAuthCapabilities,
 	buildCaptchaMiddlewares: () => buildCaptchaMiddlewares,
+	callerScopes: () => callerScopes,
+	configureAccess: () => configureAccess,
 	configureJwt: () => configureJwt,
 	createAdapterAuthMiddleware: () => createAdapterAuthMiddleware,
 	createApiKeyRoutes: () => createApiKeyRoutes,
@@ -7128,6 +9124,7 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	createJwksRoutes: () => createJwksRoutes,
 	createLinkedinProvider: () => createLinkedinProvider,
 	createMicrosoftProvider: () => createMicrosoftProvider,
+	createPersonalKeyRoutes: () => createPersonalKeyRoutes,
 	createRateLimiter: () => createRateLimiter,
 	createResetPasswordRoute: () => createResetPasswordRoute,
 	createSlackProvider: () => createSlackProvider,
@@ -7144,17 +9141,18 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	generateRefreshToken: () => generateRefreshToken,
 	generateSecurePassword: () => generateSecurePassword,
 	generateSecureToken: () => generateSecureToken,
+	getAccessModel: () => getAccessModel,
 	getAccessTokenExpiry: () => getAccessTokenExpiry,
 	getJwks: () => getJwks,
 	getRefreshTokenExpiry: () => getRefreshTokenExpiry,
 	hasAsymmetricSigningKey: () => hasAsymmetricSigningKey,
+	hasScope: () => hasScope,
 	hashPassword: () => hashPassword,
 	hashRefreshToken: () => hashRefreshToken,
-	hashToken: () => hashToken$1,
+	hashToken: () => hashToken,
 	httpMethodToOperation: () => httpMethodToOperation,
 	isApiKeyToken: () => isApiKeyToken,
 	isJwtConfigured: () => isJwtConfigured,
-	isOperationAllowed: () => isOperationAllowed,
 	isRedirectUriAllowed: () => isRedirectUriAllowed,
 	mountMagicLinkRoutes: () => mountMagicLinkRoutes,
 	oauthCodeFlowSchema: () => oauthCodeFlowSchema,
@@ -7165,6 +9163,9 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	queryTokenAuth: () => queryTokenAuth,
 	requireAdmin: () => requireAdmin,
 	requireAuth: () => requireAuth,
+	requireScope: () => requireScope,
+	requireScopeByMethod: () => requireScopeByMethod,
+	resolveApiKey: () => resolveApiKey,
 	resolveAuthHooks: () => resolveAuthHooks,
 	resolveCaptchaVerifier: () => resolveCaptchaVerifier,
 	resolveRateLimitStoreKind: () => resolveRateLimitStoreKind,
@@ -7179,6 +9180,6 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	verifyPassword: () => verifyPassword
 });
 //#endregion
-export { requireAdmin as $, defaultAuthLimiter as A, resolveEmailLinkBase as B, providerVerifiedEmail as C, raw as Ct, DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT as D, isPublicStoragePath as Dt, isBootstrapWindowOpen as E, PUBLIC_STORAGE_PREFIX as Et, extractLinks as F, createAdapterAuthMiddleware as G, hashPassword as H, registerDevEmailSink as I, extractUserFromToken as J, createAuthMiddleware as K, SMTPEmailService as L, activeDevEmailSink as M, clearActiveDevEmailSink as N, createDataRateLimiter as O, createDevEmailSink as P, queryTokenAuth as Q, createEmailService as R, pkceTokenParams as S, html as St, createBuiltinAuthAdapter as T, isOperationAllowed as Tt, validatePasswordStrength as U, resolveAuthHooks as V, verifyPassword as W, optionalAuth as X, fileTokenAuth as Y, publicObjectAuth as Z, verifyOidcIdToken as _, getUserInvitationTemplate as _t, resolveRateLimitStoreKind as a, validateApiKey as at, createGoogleProvider as b, RawHtml as bt, createSlackProvider as c, SERVICE_IDENTITY as ct, createDiscordProvider as d, completeUserCreation as dt, requireAuth as et, createTwitterProvider as f, generateSecurePassword as ft, tryVerifyOidcIdToken as g, getPasswordResetTemplate as gt, createMicrosoftProvider as h, getMagicLinkTemplate as ht, createApiKeyStore as i, isApiKeyToken as it, MemoryRateLimitStore as j, createRateLimiter as k, createBitbucketProvider as l, scopeDataDriver as lt, createAppleProvider as m, getEmailVerificationTemplate as mt, createCustomAuthAdapter as n, createFunctionApiKeyGuard as nt, createSqlRateLimitStore as o, extractBearerToken as ot, createFacebookProvider as p, getEmailOtpTemplate as pt, createRequireAuth as q, createApiKeyRoutes as r, createStorageApiKeyGuard as rt, createSpotifyProvider as s, safeCompare as st, auth_exports as t, createApiKeyPreAuth as tt, createGitLabProvider as u, supportsRlsScoping as ut, createGitHubProvider as v, getWelcomeEmailTemplate as vt, createJwksRoutes as w, httpMethodToOperation as wt, oauthCodeFlowSchema as x, escapeHtml as xt, createLinkedinProvider as y, resolveEmailBranding as yt, assertEmailLinkBases as z };
+export { queryTokenAuth as $, createDataRateLimiter as A, getEmailChangeNoticeTemplate as At, SMTPEmailService as B, escapeHtml as Bt, pkceTokenParams as C, scopeDataDriver as Ct, isBootstrapWindowOpen as D, generateSecurePassword as Dt, createBuiltinAuthAdapter as E, completeUserCreation as Et, activeDevEmailSink as F, getPasswordResetTemplate as Ft, verifyPassword as G, isPublicStorageKey as Gt, resolveAuthHooks as H, raw as Ht, clearActiveDevEmailSink as I, getUserInvitationTemplate as It, createRequireAuth as J, IMPERSONATE_HEADER as Jt, createAdapterAuthMiddleware as K, isPublicStoragePath as Kt, createDevEmailSink as L, getWelcomeEmailTemplate as Lt, defaultAuthLimiter as M, getEmailOtpTemplate as Mt, setSharedRateLimitStore as N, getEmailVerificationTemplate as Nt, DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT as O, assertEmailLinkBases as Ot, MemoryRateLimitStore as P, getMagicLinkTemplate as Pt, publicObjectAuth as Q, extractLinks as R, resolveEmailBranding as Rt, oauthCodeFlowSchema as S, SERVICE_IDENTITY as St, createJwksRoutes as T, isAccessTokenRevoked as Tt, hashPassword as U, httpMethodToOperation as Ut, createEmailService as V, html as Vt, validatePasswordStrength as W, PUBLIC_STORAGE_PREFIX as Wt, fileTokenAuth as X, extractUserFromToken as Y, optionalAuth as Z, tryVerifyOidcIdToken as _, hasScope as _t, createApiKeyStore as a, decideImpersonation as at, createLinkedinProvider as b, extractBearerToken as bt, createSpotifyProvider as c, createFunctionScopeGuard as ct, createGitLabProvider as d, resolveApiKey as dt, requireAdmin as et, createDiscordProvider as f, validateApiKey as ft, createMicrosoftProvider as g, getAccessModel as gt, createAppleProvider as h, configureAccess as ht, createPersonalKeyRoutes as i, storageRequestWildcard as it, createRateLimiter as j, getEmailChangeTemplate as jt, createDataRateLimitCheck as k, resolveEmailLinkBase as kt, createSlackProvider as l, createTusScopeGuard as lt, createFacebookProvider as m, callerScopes as mt, createCustomAuthAdapter as n, requestedStorageObject as nt, resolveRateLimitStoreKind as o, refuseUnhonouredImpersonation as ot, createTwitterProvider as p, accessModelFromCollections as pt, createAuthMiddleware as q, storageObjectPath as qt, createApiKeyRoutes as r, storageObjectOfPath as rt, createSqlRateLimitStore as s, createApiKeyPreAuth as st, auth_exports as t, requireAuth as tt, createBitbucketProvider as u, isApiKeyToken as ut, verifyOidcIdToken as v, requireScope as vt, providerVerifiedEmail as w, supportsRlsScoping as wt, createGoogleProvider as x, safeCompare as xt, createGitHubProvider as y, requireScopeByMethod as yt, registerDevEmailSink as z, RawHtml as zt };
 
-//# sourceMappingURL=auth-CCDpk2rn.js.map
+//# sourceMappingURL=auth-DMLngxn_.js.map