@rebasepro/server 0.13.0 → 0.13.1-canary.g1822133

package/dist/{auth-CuC9M2x6.js → auth-CYoPVf-E.js}

@@ -2,38 +2,18 @@ import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
 import { i as __toESM, n as __exportAll } from "./rolldown-runtime-DSJWtz9O.js";
-import { _ as ANONYMOUS_USER_ID, v as isAnonymousUid } from "./src-Cum9kox5.js";
-import "./src-_qQ3RNCK.js";
-import { t as isSQLAdmin } from "./backend-CIxN4FVm.js";
-import { t as logger } from "./logger-BYU66ENZ.js";
-import { n as errorHandler, t as ApiError } from "./errors-CgkCzoj7.js";
-import { a as generateRefreshToken, c as getRefreshTokenTtlMs, d as verifyAccessToken, f as verifyDownloadToken, i as generateDownloadToken, l as hashRefreshToken, n as configureJwt, o as getAccessTokenExpiry, p as require_jsonwebtoken, r as generateAccessToken, s as getRefreshTokenExpiry, t as MAX_COOKIE_AGE_MS } from "./jwt-DD6EtpGj.js";
+import { C as resolveClientListLimit, T as isAnonymousUid, a as deserializeLogicalCondition, i as deserializeFilter, r as UnknownFilterOperatorError, w as ANONYMOUS_USER_ID, x as ListLimitError } from "./src-C7rkDGxA.js";
+import "./src-Cz9nMgUR.js";
+import { i as isSQLAdmin, r as revokeInternalTableSql, t as createDdlBootstrapper } from "./ddl-bootstrap-BhXbTnBl.js";
+import { t as logger } from "./logger-DfvF_8r-.js";
+import { n as errorHandler, t as ApiError } from "./errors-EBYiaJ2E.js";
+import { a as generateMfaPendingToken, c as getRefreshTokenExpiry, d as isJwtConfigured, g as require_jsonwebtoken, h as verifyMfaPendingToken, i as generateDownloadToken, l as getRefreshTokenTtlMs, m as verifyDownloadToken, n as configureJwt, o as generateRefreshToken, p as verifyAccessToken, r as generateAccessToken, s as getAccessTokenExpiry, t as MAX_COOKIE_AGE_MS, u as hashRefreshToken } from "./jwt-_IFqfTOg.js";
 import { createHash, randomBytes, randomInt } from "node:crypto";
 import { Hono } from "hono";
 import { promisify } from "util";
-import { createCipheriv, createDecipheriv, createHash as createHash$1, createHmac, randomBytes as randomBytes$1, randomUUID as randomUUID$1, scrypt, timingSafeEqual } from "crypto";
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
-var MAX_LIST_LIMIT = 1e3;
-/**
-* Resolve a client-supplied list `limit` into a safe, always-defined value.
-*
-* - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
-*   so `0`, negatives, and absurd values can never bypass the cap.
-* - An absent / blank / non-numeric limit falls back to the mode default:
-*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
-*
-* The return is never `undefined` — no ingress that routes its client limit
-* through this can produce an unbounded read.
-*/
-function resolveClientListLimit(rawLimit, opts = {}) {
-	const maxLimit = opts.maxLimit ?? 1e3;
-	if (rawLimit != null && String(rawLimit).trim() !== "") {
-		const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
-		if (Number.isFinite(parsed)) return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
-	}
-	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
-}
-//#endregion
+import { createCipheriv, createDecipheriv, createHash as createHash$1, createHmac, createPublicKey, randomBytes as randomBytes$1, randomUUID as randomUUID$1, scrypt, timingSafeEqual } from "crypto";
+import path from "node:path";
+import { getConnInfo } from "@hono/node-server/conninfo";
 //#region ../types/src/controllers/storage.ts
 /**
 * Path prefix that marks an object as **public**. Files stored under this
@@ -94,6 +74,290 @@ function normalizeEmail(email) {
 	return typeof email === "string" ? email.trim().toLowerCase() : email;
 }
 //#endregion
+//#region src/api/rest/query-parser.ts
+/**
+* A malformed query parameter, refused with a 400.
+*
+* Every rejection in this file is one of these, and every one of them is
+* `expected` — the flag `errorHandler` reads to log a routine outcome at debug
+* instead of warn. A client that mistypes an operator, a sort direction or a
+* limit is not an incident: nothing on the server is wrong, the request never
+* reached the database, and the caller has already been told what to fix in the
+* response body. Left at warn, a single frontend holding a stale field name
+* writes a `⚠️` line per request forever, and the warn level stops meaning
+* anything — which is why "routine 4xx logs at WARN" is a standing finding
+* against this API.
+*
+* Not a factory on `ApiError`: the class's members are part of the tracked
+* runtime surface (`api-surface/server.api.txt`), and this needs no addition to
+* it. `ApiError.unauthenticated` is the same idea one status code up.
+*/
+function invalidParam(message, code, details) {
+	return new ApiError(400, code, message, details, true);
+}
+/**
+* Decode a filter, turning the shared codec's operator rejection into a 400.
+*
+* `deserializeFilter` lives in `@rebasepro/common`, which cannot throw an
+* `ApiError` — it does not depend on this package, and the browser SDK decodes
+* through the same function and has nothing to render one with. So it throws
+* `UnknownFilterOperatorError`, and the HTTP boundary is where that becomes a
+* status code. Same seam `parseLogicalGroup` uses for the nesting bound.
+*
+* Without this the operator string became a *value*: `?where={"title":
+* ["!!","Hello"]}` compiled to `title IN ('!!','Hello')` and answered 200 with
+* the row the caller was filtering out, and `{"id":[">>",0]}` reached Postgres
+* and came back a 500 quoting `invalid input syntax for type integer`. Both are
+* malformed requests and now say so.
+*/
+function decodeFilter(query) {
+	try {
+		return deserializeFilter(query);
+	} catch (e) {
+		if (e instanceof UnknownFilterOperatorError) throw invalidParam(e.message, e.code, e.details);
+		throw e;
+	}
+}
+function getLastValue(val) {
+	if (Array.isArray(val)) return val[val.length - 1];
+	return val;
+}
+/**
+* Parse an `or(...)` / `and(...)` logical group from its wire form.
+*
+* The wire carries the inner conditions wrapped in parens (e.g.
+* `(status.eq.active,age.gte.18)`); we re-attach the `or`/`and` prefix and
+* delegate to the canonical filter dialect (`@rebasepro/common`). Values are
+* preserved as strings — type coercion is the schema-aware driver's job, so
+* this path stays byte-for-byte consistent with the SDK/admin path (which
+* also parses via the shared dialect).
+*/
+function parseLogicalGroup(type, raw) {
+	let inner = String(raw).trim();
+	if (inner.startsWith("(") && inner.endsWith(")")) inner = inner.slice(1, -1);
+	inner = inner.trim();
+	if (!inner) return void 0;
+	let parsed;
+	try {
+		parsed = deserializeLogicalCondition(`${type}(${inner})`);
+	} catch (e) {
+		throw invalidParam(`Invalid \`${type}\` parameter: ${e instanceof Error ? e.message : String(e)}`, "INVALID_LOGICAL_GROUP");
+	}
+	return "type" in parsed ? parsed : void 0;
+}
+/**
+* Parse the `?where=` JSON filter object.
+*
+* This is the dialect the OpenAPI document publishes on every
+* `GET /api/data/{slug}` — `{"status":["==","active"]}`: field → canonical
+* `[WhereFilterOp, value]` tuple. It is normalized through the same
+* `deserializeFilter` as the `?field=op.value` params below, so a value that
+* arrives as a PostgREST dot-string (`{"status":"eq.active"}`) or as a bare
+* scalar (`{"status":"active"}`) compiles to the same condition. Unlike the
+* querystring dialect, JSON carries types — a number stays a number.
+*
+* A malformed value is a 400 rather than a silent drop: dropping the filter
+* would run the read unfiltered and return everything RLS happens to allow.
+*/
+function parseWhereParam(raw) {
+	const str = String(raw).trim();
+	if (!str) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(str);
+	} catch {
+		throw invalidParam("Invalid `where` parameter: expected a JSON object, e.g. {\"status\":[\"==\",\"active\"]}", "INVALID_WHERE");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw invalidParam("Invalid `where` parameter: expected a JSON object mapping fields to conditions, e.g. {\"status\":[\"==\",\"active\"]}", "INVALID_WHERE");
+	const filter = decodeFilter(parsed);
+	return Object.keys(filter).length > 0 ? filter : void 0;
+}
+function invalidOrderBy(detail) {
+	throw invalidParam(`Invalid \`orderBy\` parameter: ${detail}. Expected \`field\`, \`field:desc\`, or a JSON array like [{"field":"created_at","direction":"desc"}]`, "INVALID_ORDER_BY");
+}
+/** `asc`/`desc`, in any case. Anything else is a request to sort in a way that does not exist. */
+function toDirection(raw, context) {
+	if (raw === void 0 || raw === null) return "asc";
+	if (typeof raw !== "string") invalidOrderBy(`${context} has a non-string \`direction\``);
+	const lowered = raw.toLowerCase();
+	if (lowered !== "asc" && lowered !== "desc") invalidOrderBy(`${context} has direction '${raw}'`);
+	return lowered;
+}
+/** One entry: the canonical `{field, direction}`, or the `field:direction` shorthand as a string. */
+function toOrderByEntry(raw, index) {
+	const context = `entry ${index}`;
+	if (typeof raw === "string") {
+		const idx = raw.indexOf(":");
+		const field = (idx === -1 ? raw : raw.slice(0, idx)).trim();
+		if (!field) invalidOrderBy(`${context} is an empty field name`);
+		return {
+			field,
+			direction: idx === -1 ? "asc" : toDirection(raw.slice(idx + 1), context)
+		};
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) invalidOrderBy(`${context} is not a field name or a {field, direction} object`);
+	const entry = raw;
+	if (typeof entry.field !== "string" || entry.field.trim() === "") invalidOrderBy(`${context} has no \`field\``);
+	return {
+		field: entry.field,
+		direction: toDirection(entry.direction, context)
+	};
+}
+/**
+* Parse the `orderBy` query parameter.
+*
+* The field *name* has been validated against the schema for a while — an
+* `?orderBy=titel` is a 400 rather than 200 with unsorted rows, on the grounds
+* that silently dropping the sort leaves the caller believing in an order that
+* is not there. The parameter's *shape* was never checked the same way, and it
+* failed in exactly the same silent manner one layer earlier: whatever
+* `JSON.parse` returned was assigned to an option declared as an array of
+* `{field, direction}`, and the REST layer reads only `orderBy[0].field`. So
+* `?orderBy={"field":"name"}` — an object rather than an array, and the most
+* natural thing for a client to try — read `undefined`, dropped the ORDER BY,
+* and answered 200. So did a number, a boolean, `null`, and `["name"]`.
+*
+* This refuses those, the way `parseWhereParam` above already refuses a
+* malformed filter and for the same reason. What it keeps working is every
+* shape that worked before: the `field` and `field:desc` shorthands, and the
+* canonical JSON array.
+*/
+function parseOrderByParam(raw) {
+	if (Array.isArray(raw)) return raw.length === 0 ? void 0 : raw.map(toOrderByEntry);
+	const str = String(raw).trim();
+	if (!str) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(str);
+	} catch {
+		return [toOrderByEntry(str, 0)];
+	}
+	if (Array.isArray(parsed)) {
+		if (parsed.length === 0) return void 0;
+		return parsed.map(toOrderByEntry);
+	}
+	if (typeof parsed === "string") return [toOrderByEntry(parsed, 0)];
+	if (typeof parsed === "object" && parsed !== null) invalidOrderBy("a single object was given where a JSON array was expected");
+	invalidOrderBy(`${typeof parsed} is not a field name or a list of them`);
+}
+/**
+* {@link resolveClientListLimit} for an HTTP route: the same bounds, answered
+* with a 400 rather than a 500.
+*
+* The shared resolver throws a `ListLimitError`, which carries `status` — but
+* the Hono error handler discriminates on `statusCode`, so an unconverted one
+* reaches the client as `INTERNAL_ERROR` with its message stripped, telling the
+* caller nothing about the parameter it got wrong. Every REST list ingress
+* routes its `limit` through here so all of them name the ceiling the same way.
+*/
+function resolveListLimitParam(rawLimit, opts = {}) {
+	try {
+		return resolveClientListLimit(rawLimit, opts);
+	} catch (e) {
+		if (e instanceof ListLimitError) throw invalidParam(e.message, "INVALID_LIMIT");
+		throw e;
+	}
+}
+/**
+* Parse query parameters into QueryOptions
+*/
+function parseQueryOptions(query, limits = {}) {
+	const options = {};
+	const rawLimit = getLastValue(query.limit);
+	const offsetVal = getLastValue(query.offset);
+	if (offsetVal) options.offset = parseInt(String(offsetVal));
+	const pageVal = getLastValue(query.page);
+	if (pageVal) {
+		const page = parseInt(String(pageVal));
+		const limit = resolveListLimitParam(rawLimit, {
+			defaultLimit: limits.defaultLimit,
+			maxLimit: limits.maxLimit
+		});
+		options.offset = (page - 1) * limit;
+	}
+	const orVal = getLastValue(query.or);
+	const andVal = getLastValue(query.and);
+	if (orVal) {
+		const logical = parseLogicalGroup("or", orVal);
+		if (logical) options.logical = logical;
+	} else if (andVal) {
+		const logical = parseLogicalGroup("and", andVal);
+		if (logical) options.logical = logical;
+	}
+	const reservedQueryKeys = [
+		"limit",
+		"offset",
+		"page",
+		"orderBy",
+		"include",
+		"fields",
+		"searchString",
+		"searchExplain",
+		"vector_search",
+		"vector",
+		"vector_distance",
+		"vector_threshold",
+		"or",
+		"and",
+		"where"
+	];
+	const filterDict = {};
+	for (const [key, rawValue] of Object.entries(query)) {
+		if (reservedQueryKeys.includes(key)) continue;
+		filterDict[key] = rawValue;
+	}
+	const whereVal = getLastValue(query.where);
+	const where = {
+		...whereVal !== void 0 && whereVal !== null ? parseWhereParam(whereVal) : void 0,
+		...decodeFilter(filterDict)
+	};
+	if (Object.keys(where).length > 0) options.where = where;
+	const orderByVal = getLastValue(query.orderBy);
+	if (orderByVal) options.orderBy = parseOrderByParam(orderByVal);
+	const includeVal = getLastValue(query.include);
+	if (includeVal) {
+		const includeStr = String(includeVal).trim();
+		if (includeStr === "*") options.include = ["*"];
+		else options.include = includeStr.split(",").map((s) => s.trim()).filter(Boolean);
+	}
+	const fieldsVal = getLastValue(query.fields);
+	if (fieldsVal) options.fields = String(fieldsVal).trim().split(",").map((s) => s.trim()).filter(Boolean);
+	const vectorSearchVal = getLastValue(query.vector_search);
+	const vectorVal = getLastValue(query.vector);
+	if (vectorSearchVal && vectorVal) {
+		const vectorStr = String(vectorVal);
+		let decoded;
+		try {
+			decoded = JSON.parse(vectorStr);
+		} catch {
+			decoded = void 0;
+		}
+		if (!Array.isArray(decoded) || !decoded.every((v) => typeof v === "number")) throw invalidParam("Invalid `vector` format. Expected a JSON array of numbers, e.g. [0.1,0.2,0.3]", "INVALID_VECTOR");
+		const queryVector = decoded;
+		const distanceParamVal = getLastValue(query.vector_distance);
+		const distanceParam = distanceParamVal ? String(distanceParamVal) : "cosine";
+		if (distanceParam !== "cosine" && distanceParam !== "l2" && distanceParam !== "inner_product") throw invalidParam(`Invalid \`vector_distance\`: ${distanceParam}. Expected: cosine, l2, or inner_product`, "INVALID_VECTOR_DISTANCE");
+		const vectorSearch = {
+			property: String(vectorSearchVal),
+			vector: queryVector,
+			distance: distanceParam
+		};
+		const thresholdVal = getLastValue(query.vector_threshold);
+		if (thresholdVal) {
+			const threshold = parseFloat(String(thresholdVal));
+			if (isNaN(threshold)) throw invalidParam("Invalid `vector_threshold`. Expected a number.", "INVALID_VECTOR_THRESHOLD");
+			vectorSearch.threshold = threshold;
+		}
+		options.vectorSearch = vectorSearch;
+	}
+	options.limit = resolveListLimitParam(rawLimit, {
+		vectorSearch: !!options.vectorSearch,
+		defaultLimit: limits.defaultLimit,
+		maxLimit: limits.maxLimit
+	});
+	return options;
+}
+//#endregion
 //#region src/auth/api-keys/api-key-permission-guard.ts
 /**
 * Map an HTTP method string to an `ApiKeyOperation`.
@@ -168,9 +432,116 @@ function isFunctionAllowed(permissions, functionName, operation) {
 	return false;
 }
 //#endregion
+//#region src/auth/token-revocation.ts
+/**
+* Has this access token been revoked?
+*
+* `logout`, `change-password`, `reset-password` and `DELETE /auth/sessions` all
+* stamp a `tokensValidAfter` watermark on the user. Every one of them also
+* deletes refresh-token rows, which is what made the gap easy to miss: the
+* session really is gone, and the *refresh* path really does check the
+* watermark — so signing out looked like it worked.
+*
+* The access token was untouched. It is a bearer credential that nothing
+* consulted a database about, so it stayed valid for its full lifetime after
+* every one of those actions. "Sign out everywhere" left the stolen token
+* working; so did changing your password because you thought it had leaked.
+*
+* The watermark had exactly one read in the repository, on refresh. This adds
+* the other one.
+*
+* ## Cost
+*
+* One indexed lookup per request, on the paths that already make one. The
+* adapter re-reads roles for every authenticated request; the admin routes now
+* do too. Both call this with the row they were already fetching in mind — a
+* repository that wants to serve both from one query is free to cache
+* internally, but nothing here assumes it.
+*
+* ## Failure
+*
+* Fails **open**, deliberately, and this is the one place in the auth stack
+* where that is right. The watermark is an extra revocation signal layered over
+* a token that has already been verified — signature, expiry and purpose all
+* checked. Refusing every request when the database is unreachable would turn a
+* transient outage into a total sign-out of an entire deployment, and the
+* attacker this protects against needs to have already stolen a live token. The
+* failure is logged at warn so it is visible rather than silent.
+*/
+async function isAccessTokenRevoked(authRepo, payload) {
+	if (typeof authRepo.getTokensValidAfter !== "function") return false;
+	if (typeof payload.iat !== "number") return false;
+	let validAfter;
+	try {
+		validAfter = await authRepo.getTokensValidAfter(payload.uid);
+	} catch (error) {
+		logger.warn("[Auth] Could not read the token revocation watermark; allowing the request", {
+			uid: payload.uid,
+			error
+		});
+		return false;
+	}
+	if (!validAfter) return false;
+	return payload.iat < Math.floor(validAfter.getTime() / 1e3);
+}
+//#endregion
+//#region src/auth/admin-roles.ts
+/**
+* Which role names carry administrative privilege.
+*
+* One definition, because there used to be several and they disagreed.
+* `requireAdmin` accepted `admin` **or** `schema-admin`; the guard that refuses
+* a dangerous `defaultRole` compared against `admin` alone. So
+* `AUTH_DEFAULT_ROLE=schema-admin` passed the guard and made every public
+* registrant an administrator — and, since a `schema-admin` may edit users, one
+* of them could then grant themselves real `admin` and keep it.
+*
+* The guard and the check have to read the same list or the gap comes back, so
+* neither of them owns it.
+*
+* `schema-admin` is here deliberately: it can reach the schema editor and the
+* SQL surfaces, which is administrative by any definition that matters. If a
+* genuinely lesser role is added later, it does not belong in this list — it
+* belongs in a capability check of its own.
+*/
+var ADMINISTRATIVE_ROLES = ["admin", "schema-admin"];
+/** Does this single role name carry administrative privilege? */
+function isAdministrativeRole(role) {
+	return ADMINISTRATIVE_ROLES.includes(role);
+}
+/** Does any role in this list carry administrative privilege? */
+function hasAdministrativeRole(roles) {
+	return !!roles?.some(isAdministrativeRole);
+}
+//#endregion
 //#region src/auth/rls-scope.ts
 var import_jsonwebtoken = /* @__PURE__ */ __toESM(require_jsonwebtoken(), 1);
 /**
+* The identity the trusted server plane runs as: `rebase.dataAsAdmin`, and any
+* caller presenting the service key.
+*
+* Naming it makes the privilege legible, because it is narrower than it reads.
+* This is **not** an RLS bypass — a driver scoped with it is an
+* `AuthenticatedPostgresBackendDriver`, so every statement runs in a
+* transaction that has done `SET LOCAL ROLE rebase_user` with
+* `app.uid = 'service'`, and policies are evaluated. Two consequences worth
+* knowing before you write a policy:
+*
+* - It passes the default policies through their `rolesOverlap(['admin'])`
+*   arm — the same arm an application user holding the `admin` role passes.
+* - `policy.serverContext()` compiles to `auth.uid() IS NULL` and is therefore
+*   **false** for it. A collection with `disableDefaultPolicies: true` whose
+*   only rule is `serverContext()` denies these writes (42501) and returns
+*   zero rows for these reads.
+*
+* The true bypass is `rebase.sql()`, which runs on the owner connection and
+* never goes near `withAuth`.
+*/
+var SERVICE_IDENTITY = {
+	uid: "service",
+	roles: ["admin"]
+};
+/**
 * Returns true if the driver supports RLS scoping via `withAuth()`.
 */
 function isRLSScopedDriver(driver) {
@@ -461,6 +832,137 @@ function createApiKeyPreAuth(options) {
 	};
 }
 //#endregion
+//#region src/storage/keys.ts
+/**
+* Canonical storage keys and bucket names.
+*
+* Storage is not under RLS, so a `storageAuthorize` hook is the whole access
+* control model — and a hook can only be correct if the key it is shown is the
+* key that is written. That is the invariant this module exists to hold: one
+* canonical string, computed once per request, handed to the hook, to the
+* controller, and to the download token alike.
+*
+* ## Why rejecting beats stripping
+*
+* The previous `sanitizeStorageKey` *stripped* `../` in a single pass. Two
+* things were wrong with that, and only one of them was the obvious one.
+*
+* The obvious one: a single pass is not a fixed point. `....//` contains `../`
+* at offset 2, so removing it leaves `../` behind — the sanitizer manufactured
+* the traversal it was there to remove. `users/alice/....//bob/x` came out as
+* `users/alice/../bob/x`, which a prefix hook reads as alice's (it starts with
+* `users/alice/`) and the filesystem reads as bob's. The hook approved one
+* object and the controller wrote another.
+*
+* The subtler one, and the reason this is a rewrite rather than a loop: even a
+* correct strip is a silent rewrite. A caller who asks to store at `a/../b` and
+* gets an object at `a/b` was not protected, they were misled — and every later
+* read, ownership row and audit line now refers to a path nobody chose. So a key
+* that means something other than what it says is refused (400), not repaired.
+*
+* Note what is NOT traversal under this rule: `....` is an ordinary directory
+* name, and `users/alice/....//bob/x` canonicalizes to
+* `users/alice/..../bob/x` — still comfortably inside alice's prefix, which is
+* exactly right. Only a real `..` segment is refused.
+*/
+/** Longest key accepted, in UTF-16 code units. Matches the previous cap. */
+var MAX_STORAGE_KEY_LENGTH = 1024;
+/**
+* A key that cannot be canonicalized. Carries no path back to the caller
+* beyond what they sent, so it is safe to surface as a 400 message.
+*/
+var InvalidStorageKeyError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidStorageKeyError";
+	}
+};
+/**
+* Canonicalize a caller-supplied storage key, or throw
+* {@link InvalidStorageKeyError}.
+*
+* Normalizations applied (safe, idempotent, and meaning-preserving):
+* - leading slashes removed — `/a/b` and `a/b` name the same object
+* - `.` segments and repeated slashes collapsed
+*
+* Refusals (the key means something other than what it says):
+* - any `..` segment, on either separator, at any depth
+* - null bytes
+* - keys longer than {@link MAX_STORAGE_KEY_LENGTH}
+*
+* A trailing slash is preserved: it is how the folder route marks a prefix.
+*/
+function canonicalStorageKey(rawKey) {
+	if (rawKey.includes("\0")) throw new InvalidStorageKeyError("Storage key contains a null byte.");
+	if (rawKey.length > 1024) throw new InvalidStorageKeyError(`Storage key exceeds the maximum length of ${MAX_STORAGE_KEY_LENGTH} characters.`);
+	if (rawKey.split(/[\\/]/).some((segment) => segment === "..")) throw new InvalidStorageKeyError("Storage key contains a '..' path segment. Keys must name an object directly.");
+	const withoutLeadingSlashes = rawKey.replace(/^\/+/, "");
+	if (withoutLeadingSlashes === "") return "";
+	const denotesDirectory = /(?:^|\/)\.?$/.test(withoutLeadingSlashes);
+	const normalized = path.posix.normalize(withoutLeadingSlashes);
+	if (normalized === "." || normalized === "./") return "";
+	const key = normalized.replace(/^\.\//, "").replace(/^\/+/, "");
+	if (key === "") return "";
+	return denotesDirectory && !key.endsWith("/") ? `${key}/` : key;
+}
+/**
+* Canonicalize, or return `null` when the key is not canonicalizable.
+*
+* For callers that must fail closed without an exception — the download-token
+* middleware compares a request path against a granted path, and a key it
+* cannot canonicalize simply matches nothing.
+*/
+function tryCanonicalStorageKey(rawKey) {
+	try {
+		return canonicalStorageKey(rawKey);
+	} catch {
+		return null;
+	}
+}
+/** A bucket name that does not name a bucket. See {@link canonicalStorageBucket}. */
+var InvalidStorageBucketError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidStorageBucketError";
+	}
+};
+/**
+* One path segment: letters, digits, `.`, `_`, `-`, first character
+* alphanumeric. Deliberately narrow — it is the intersection of what S3, GCS
+* and a filesystem directory all accept, and it makes `..`, `.tus-uploads`,
+* absolute paths and anything containing a separator unrepresentable.
+*/
+var STORAGE_BUCKET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+* Canonicalize a caller-supplied bucket name, or throw
+* {@link InvalidStorageBucketError}.
+*
+* The bucket is the *other* caller-controlled routing value in an upload
+* request, and it was the one nobody validated. `LocalStorageController`
+* builds `join(basePath, bucket)` and then checks containment against that
+* result, so a bucket of `../../etc` moved the boundary rather than crossing
+* it — the guard passed because the guard's reference point was the attacker's.
+* The containment check now resolves against the storage root, and this is the
+* check at the route boundary that stops the value before it gets there.
+*
+* A bucket is configuration, not user data: there is no legitimate caller that
+* needs a separator, a leading dot, or a `..` in one. So this refuses rather
+* than repairs, exactly as {@link canonicalStorageKey} does — a rewritten
+* bucket would silently store the object somewhere the caller did not ask for.
+*
+* Returns `undefined` when the caller named no bucket (absent, or an empty
+* form field), which is how every controller spells "use my default". An empty
+* string used to reach `getFullPath` and resolve to the storage *root* rather
+* than the `default` bucket, which is a third place a bare key did not
+* round-trip.
+*/
+function canonicalStorageBucket(rawBucket) {
+	if (rawBucket === void 0 || rawBucket === null || rawBucket === "") return void 0;
+	if (rawBucket.length > 63) throw new InvalidStorageBucketError(`Storage bucket exceeds the maximum length of 63 characters.`);
+	if (!STORAGE_BUCKET_PATTERN.test(rawBucket)) throw new InvalidStorageBucketError("Storage bucket must be a single name of letters, digits, '.', '_' or '-', starting with a letter or digit.");
+	return rawBucket;
+}
+//#endregion
 //#region src/auth/middleware.ts
 /**
 * Hono middleware that requires a valid JWT token via Authorization header.
@@ -500,6 +1002,8 @@ var requireAuth = async (c, next) => {
 function createRequireAuth(options) {
 	if (!options?.serviceKey) return requireAuth;
 	const key = options.serviceKey;
+	const resolveRoles = options.resolveRoles;
+	const revocationRepo = options.revocationRepo;
 	return async (c, next) => {
 		if (c.get("user")) return next();
 		const token = extractBearerToken(c.req.header("authorization"));
@@ -519,6 +1023,26 @@ function createRequireAuth(options) {
 			message: "Invalid or expired token",
 			code: "UNAUTHORIZED"
 		} }, 401);
+		if (resolveRoles) try {
+			if (revocationRepo && await isAccessTokenRevoked(revocationRepo, payload)) return c.json({ error: {
+				message: "Session has been revoked",
+				code: "SESSION_REVOKED"
+			} }, 401);
+			c.set("user", {
+				...payload,
+				roles: await resolveRoles(payload.uid)
+			});
+			return next();
+		} catch (error) {
+			logger.warn("[Auth] Could not resolve roles for an admin-gated request", {
+				uid: payload.uid,
+				error
+			});
+			return c.json({ error: {
+				message: "Could not verify your permissions. Please try again.",
+				code: "ROLE_LOOKUP_FAILED"
+			} }, 503);
+		}
 		c.set("user", payload);
 		return next();
 	};
@@ -533,9 +1057,7 @@ var requireAdmin = async (c, next) => {
 		message: "User not authenticated. requireAuth middleware is missing?",
 		code: "UNAUTHORIZED"
 	} }, 401);
-	if (!(typeof user === "object" && user !== null && "roles" in user ? user.roles || [] : []).some((role) => {
-		return role === "admin" || role === "schema-admin";
-	})) return c.json({ error: {
+	if (!hasAdministrativeRole(typeof user === "object" && user !== null && "roles" in user ? user.roles || [] : [])) return c.json({ error: {
 		message: "Admin privileges required for this operation",
 		code: "FORBIDDEN"
 	} }, 403);
@@ -551,7 +1073,7 @@ var requireAdmin = async (c, next) => {
 var optionalAuth = async (c, next) => {
 	if (c.get("user")) return next();
 	const token = extractBearerToken(c.req.header("authorization"));
-	if (token !== void 0) {
+	if (token !== void 0 && isJwtConfigured()) {
 		const payload = verifyAccessToken(token);
 		if (payload) c.set("user", payload);
 	}
@@ -561,6 +1083,7 @@ var optionalAuth = async (c, next) => {
 * Extract user from token - for WebSocket authentication
 */
 function extractUserFromToken(token) {
+	if (!isJwtConfigured()) return null;
 	return verifyAccessToken(token);
 }
 /**
@@ -711,7 +1234,7 @@ function createAuthMiddleware(options) {
 var queryTokenAuth = async (c, next) => {
 	if (extractBearerToken(c.req.header("authorization")) !== void 0) return next();
 	const queryToken = c.req.query("token");
-	if (queryToken) {
+	if (queryToken && isJwtConfigured()) {
 		const payload = verifyAccessToken(queryToken);
 		if (payload) c.set("user", payload);
 	}
@@ -782,15 +1305,25 @@ var fileTokenAuth = async (c, next) => {
 		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: parts.slice(1).join("/")
+			resolvedPath: tryCanonicalStorageKey(parts.slice(1).join("/"))
 		};
 		return {
 			bucket: "default",
-			resolvedPath: filePath
+			resolvedPath: tryCanonicalStorageKey(filePath)
 		};
 	};
 	const bearerToken = extractBearerToken(authHeader);
@@ -800,7 +1333,8 @@ var fileTokenAuth = async (c, next) => {
 			const rawPath = extractWildcard(c);
 			if (rawPath) {
 				const { bucket, resolvedPath } = parseBucketPath(decodeURIComponent(rawPath));
-				if (isPathMatch(`${bucket}/${resolvedPath}`, payload.path)) {
+				const requestedFullPath = resolvedPath === null ? null : `${bucket}/${resolvedPath}`;
+				if (requestedFullPath !== null && isPathMatch(requestedFullPath, payload.path)) {
 					c.set("user", {
 						uid: "download-token",
 						roles: ["reader"]
@@ -824,7 +1358,8 @@ var fileTokenAuth = async (c, next) => {
 			const rawPath = extractWildcard(c);
 			if (rawPath) {
 				const { bucket, resolvedPath } = parseBucketPath(decodeURIComponent(rawPath));
-				if (isPathMatch(`${bucket}/${resolvedPath}`, payload.path)) {
+				const requestedFullPath = resolvedPath === null ? null : `${bucket}/${resolvedPath}`;
+				if (requestedFullPath !== null && isPathMatch(requestedFullPath, payload.path)) {
 					c.set("user", {
 						uid: "download-token",
 						roles: ["reader"]
@@ -852,8 +1387,9 @@ function createAdapterAuthMiddleware(options) {
 	const { adapter, driver: baseDriver, resolveDriver, requireAuth: enforceAuth = true, apiKeyStore } = options;
 	return async (c, next) => {
 		const driver = resolveDriver ? resolveDriver(c) : baseDriver;
+		const presentedToken = extractBearerToken(c.req.header("authorization"));
 		if (apiKeyStore) {
-			const token = extractBearerToken(c.req.header("authorization")) ?? "";
+			const token = presentedToken ?? "";
 			if (token.startsWith("rk_")) {
 				const result = await validateApiKey(c, token, {
 					store: apiKeyStore,
@@ -890,17 +1426,23 @@ function createAdapterAuthMiddleware(options) {
 					code: "INTERNAL_ERROR"
 				} }, 500);
 			}
-		} else try {
-			c.set("driver", await scopeDataDriver(driver, {
-				uid: ANONYMOUS_USER_ID,
-				roles: ["anon"]
-			}));
-		} catch (error) {
-			logger.error("[AUTH-ADAPTER] Failed to create anon-scoped driver", { error });
-			return c.json({ error: {
-				message: "Server configuration error",
-				code: "INTERNAL_ERROR"
-			} }, 500);
+		} else {
+			if (presentedToken !== void 0) return c.json({ error: {
+				message: "Invalid or expired token",
+				code: "UNAUTHORIZED"
+			} }, 401);
+			try {
+				c.set("driver", await scopeDataDriver(driver, {
+					uid: ANONYMOUS_USER_ID,
+					roles: ["anon"]
+				}));
+			} catch (error) {
+				logger.error("[AUTH-ADAPTER] Failed to create anon-scoped driver", { error });
+				return c.json({ error: {
+					message: "Server configuration error",
+					code: "INTERNAL_ERROR"
+				} }, 500);
+			}
 		}
 		if (enforceAuth && !c.get("user")) return c.json({ error: {
 			message: "Unauthorized: Authentication required",
@@ -910,43 +1452,141 @@ function createAdapterAuthMiddleware(options) {
 	};
 }
 //#endregion
+//#region src/email/html.ts
+/**
+* HTML escaping for email bodies.
+*
+* Every default template interpolates values the server does not control — a
+* `displayName` chosen at registration, an `appName` from config, a link base a
+* host set — into markup that is then mailed, signed by the sending domain, to
+* an address the same request chose. Unescaped, that turns `POST /auth/register`
+* into a way to deliver arbitrary HTML (a heading, an anchor) from a domain
+* whose SPF and DKIM check out.
+*
+* The fix is deliberately not five escaping calls at five interpolation sites:
+* a sixth template would simply forget. Templates are built with the {@link html}
+* tag, which escapes *every* interpolated value by default, and markup that is
+* meant to pass through verbatim — the static style strings, a nested fragment —
+* must say so with {@link raw}. Forgetting `raw` produces visibly escaped text
+* in a test; forgetting to escape is invisible until someone exploits it.
+*/
+/**
+* Markup that has already been vetted and must be interpolated verbatim.
+*
+* Only ever construct this from a string literal in this package's own source
+* (or from the {@link html} tag, which produces one). Wrapping user input in
+* `raw()` defeats the entire mechanism.
+*/
+var RawHtml = class {
+	value;
+	constructor(value) {
+		this.value = value;
+	}
+	toString() {
+		return this.value;
+	}
+};
+/**
+* Mark a static, author-controlled string as safe to interpolate unescaped.
+*/
+function raw(markup) {
+	return new RawHtml(markup);
+}
+/**
+* Escape the five characters that can change the meaning of HTML text or of a
+* quoted attribute value.
+*
+* `&` goes first: escaping it after the others would double-escape the entities
+* they just produced. `'` is included because it is a legal attribute delimiter,
+* and `"` because it is the one this file uses.
+*/
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* Render one interpolated value: pass {@link RawHtml} through, drop nullish,
+* escape everything else.
+*/
+function interpolate(value) {
+	if (value instanceof RawHtml) return value.value;
+	if (value === null || value === void 0) return "";
+	return escapeHtml(String(value));
+}
+/**
+* Tagged template for email markup. Every `${...}` is escaped unless it is
+* {@link RawHtml}.
+*
+* Returns `RawHtml` so fragments nest without being escaped a second time:
+*
+* ```ts
+* const button = url ? html`<a href="${url}">Open</a>` : raw("");
+* const body = html`<div>${button}</div>`;
+* ```
+*/
+function html(strings, ...values) {
+	let out = strings[0];
+	for (let i = 0; i < values.length; i++) out += interpolate(values[i]) + strings[i + 1];
+	return new RawHtml(out);
+}
+//#endregion
 //#region src/email/templates.ts
 /**
-* Get a greeting name for the user
+* Default email templates for authentication emails.
+*
+* Every HTML body is built with the `html` tag from `./html`, which escapes each
+* interpolated value unless it is explicitly marked `raw`. `displayName` reaches
+* these templates straight from the registration body, and the resulting mail is
+* sent — signed by the sending domain — to an address the same anonymous request
+* chose, so an unescaped interpolation here is a phishing primitive, not a
+* rendering glitch. Escaping lives in the tag rather than at the call sites so a
+* sixth template inherits it instead of having to remember it.
+*/
+/**
+* Get a greeting name for the user.
+*
+* Returns the raw value — `displayName` is whatever the account was registered
+* with, including markup. Escaping is the `html` tag's job, so that a template
+* that interpolates the greeting into text (the plain-text bodies below) and one
+* that interpolates it into markup can share this.
 */
 function getGreeting(user) {
 	return user.displayName || user.email.split("@")[0];
 }
 /**
-* Common email styles
+* Common email styles.
+*
+* `raw` because these are static, author-written CSS — the one category of
+* interpolation the `html` tag lets through unescaped. (Escaping them would
+* survive an HTML parser but not every mail client's CSS parser: the
+* `'Segoe UI'` quotes would arrive as entities.)
 */
 var styles = {
-	container: `
+	container: raw(`
         font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
         max-width: 600px;
         margin: 0 auto;
         padding: 40px 20px;
         background-color: #f8fafc;
-    `,
-	card: `
+    `),
+	card: raw(`
         background-color: #ffffff;
         border-radius: 12px;
         padding: 40px;
         box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
-    `,
-	heading: `
+    `),
+	heading: raw(`
         color: #1e293b;
         font-size: 24px;
         font-weight: 600;
         margin: 0 0 20px 0;
-    `,
-	paragraph: `
+    `),
+	paragraph: raw(`
         color: #475569;
         font-size: 16px;
         line-height: 1.6;
         margin: 0 0 20px 0;
-    `,
-	button: `
+    `),
+	button: raw(`
         display: inline-block;
         background-color: #3b82f6;
         color: #ffffff;
@@ -956,22 +1596,22 @@ var styles = {
         padding: 14px 28px;
         border-radius: 8px;
         margin: 20px 0;
-    `,
-	footer: `
+    `),
+	footer: raw(`
         color: #94a3b8;
         font-size: 14px;
         margin-top: 30px;
         padding-top: 20px;
         border-top: 1px solid #e2e8f0;
-    `,
-	warning: `
+    `),
+	warning: raw(`
         color: #64748b;
         font-size: 14px;
         background-color: #fef3c7;
         padding: 12px 16px;
         border-radius: 6px;
         margin-top: 20px;
-    `
+    `)
 };
 /**
 * Default password reset email template
@@ -979,9 +1619,7 @@ var styles = {
 function getPasswordResetTemplate(resetUrl, user, appName = "Rebase") {
 	const greeting = getGreeting(user);
 	const subject = `Reset your ${appName} password`;
-	return {
-		subject,
-		html: `
+	const body = html`
 <!DOCTYPE html>
 <html>
 <head>
@@ -1028,8 +1666,8 @@ function getPasswordResetTemplate(resetUrl, user, appName = "Rebase") {
     </div>
 </body>
 </html>
-    `.trim(),
-		text: `
+    `;
+	const text = `
 Reset Your Password
 
 Hi ${greeting},
@@ -1043,7 +1681,11 @@ This link will expire in 1 hour for security reasons.
 
 If you didn't request a password reset, you can safely ignore this email.
 Your password will remain unchanged.
-    `.trim()
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
 	};
 }
 /**
@@ -1052,9 +1694,7 @@ Your password will remain unchanged.
 function getEmailVerificationTemplate(verifyUrl, user, appName = "Rebase") {
 	const greeting = getGreeting(user);
 	const subject = `Verify your ${appName} email address`;
-	return {
-		subject,
-		html: `
+	const body = html`
 <!DOCTYPE html>
 <html>
 <head>
@@ -1096,8 +1736,8 @@ function getEmailVerificationTemplate(verifyUrl, user, appName = "Rebase") {
     </div>
 </body>
 </html>
-    `.trim(),
-		text: `
+    `;
+	const text = `
 Verify Your Email
 
 Hi ${greeting},
@@ -1106,7 +1746,11 @@ Thanks for signing up for ${appName}! Please verify your email address by clicki
 ${verifyUrl}
 
 If you didn't create an account with ${appName}, you can safely ignore this email.
-    `.trim()
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
 	};
 }
 /**
@@ -1116,9 +1760,7 @@ If you didn't create an account with ${appName}, you can safely ignore this emai
 function getUserInvitationTemplate(setPasswordUrl, user, appName = "Rebase") {
 	const greeting = getGreeting(user);
 	const subject = `You've been invited to ${appName}`;
-	return {
-		subject,
-		html: `
+	const body = html`
 <!DOCTYPE html>
 <html>
 <head>
@@ -1164,8 +1806,8 @@ function getUserInvitationTemplate(setPasswordUrl, user, appName = "Rebase") {
     </div>
 </body>
 </html>
-    `.trim(),
-		text: `
+    `;
+	const text = `
 Welcome to ${appName}!
 
 Hi ${greeting},
@@ -1178,7 +1820,11 @@ ${setPasswordUrl}
 This link will expire in 1 hour for security reasons.
 
 If you weren't expecting this invitation, you can safely ignore this email.
-    `.trim()
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
 	};
 }
 /**
@@ -1189,9 +1835,7 @@ function getWelcomeEmailTemplate(user, appName = "Rebase", loginUrl) {
 	const greeting = getGreeting(user);
 	const url = loginUrl || "";
 	const subject = `¡Bienvenido/a a ${appName}!`;
-	return {
-		subject,
-		html: `
+	const body = html`
 <!DOCTYPE html>
 <html>
 <head>
@@ -1218,11 +1862,11 @@ function getWelcomeEmailTemplate(user, appName = "Rebase", loginUrl) {
                 que tenemos para ti.
             </p>
 
-            ${url ? `
+            ${url ? html`
             <div style="text-align: center;">
                 <a href="${url}" style="${styles.button}">Ir a mi Panel</a>
             </div>
-            ` : ""}
+            ` : raw("")}
             
             <p style="${styles.paragraph}">
                 Si tienes alguna pregunta, no dudes en contactarnos respondiendo a este correo.
@@ -1237,8 +1881,8 @@ function getWelcomeEmailTemplate(user, appName = "Rebase", loginUrl) {
     </div>
 </body>
 </html>
-    `.trim(),
-		text: `
+    `;
+	const text = `
 ¡Bienvenido/a a ${appName}!
 
 Hola ${greeting},
@@ -1250,7 +1894,11 @@ Ya puedes acceder a tu panel y empezar a explorar todas las oportunidades que te
 ${url ? `Ir a mi panel: ${url}` : ""}
 
 Si tienes alguna pregunta, no dudes en contactarnos respondiendo a este correo.
-    `.trim()
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
 	};
 }
 /**
@@ -1259,9 +1907,7 @@ Si tienes alguna pregunta, no dudes en contactarnos respondiendo a este correo.
 function getMagicLinkTemplate(magicLinkUrl, user, appName = "Rebase") {
 	const greeting = getGreeting(user);
 	const subject = `Sign in to ${appName}`;
-	return {
-		subject,
-		html: `
+	const body = html`
 <!DOCTYPE html>
 <html>
 <head>
@@ -1308,8 +1954,8 @@ function getMagicLinkTemplate(magicLinkUrl, user, appName = "Rebase") {
     </div>
 </body>
 </html>
-    `.trim(),
-		text: `
+    `;
+	const text = `
 Sign In to ${appName}
 
 Hi ${greeting},
@@ -1323,7 +1969,11 @@ This link will expire in 15 minutes for security reasons and can only be used on
 
 If you didn't request this sign-in link, you can safely ignore this email.
 No action is needed.
-    `.trim()
+    `.trim();
+	return {
+		subject,
+		html: body.toString().trim(),
+		text
 	};
 }
 //#endregion
@@ -1458,11 +2108,11 @@ async function finalizeAdminUserCreation(entity, clearPassword, ctx) {
 		await ctx.authRepo.createPasswordResetToken(entity.id, tokenHash, expiresAt);
 		const setPasswordUrl = `${ctx.emailConfig?.resetPasswordUrl || ""}/reset-password?token=${token}`;
 		const appName = ctx.emailConfig?.appName || "Rebase";
-		const templateFn = ctx.emailConfig?.templates?.passwordReset;
+		const templateFn = ctx.emailConfig?.templates?.userInvitation;
 		const emailContent = templateFn ? templateFn(setPasswordUrl, {
 			email: entity.values.email,
 			displayName: entity.values.displayName
-		}) : getPasswordResetTemplate(setPasswordUrl, {
+		}) : getUserInvitationTemplate(setPasswordUrl, {
 			email: entity.values.email,
 			displayName: entity.values.displayName
 		}, appName);
@@ -1491,6 +2141,11 @@ async function finalizeAdminUserCreation(entity, clearPassword, ctx) {
 var scryptAsync = promisify(scrypt);
 var SALT_LENGTH = 32;
 var KEY_LENGTH = 64;
+var SCRYPT_PARAMS = {
+	N: 16384,
+	r: 8,
+	p: 1
+};
 /**
 * Password requirements:
 * - Minimum 8 characters
@@ -1515,7 +2170,7 @@ function validatePasswordStrength(password) {
 */
 async function hashPassword(password) {
 	const salt = randomBytes$1(SALT_LENGTH);
-	const derivedKey = await scryptAsync(password, salt, KEY_LENGTH);
+	const derivedKey = await scryptAsync(password, salt, KEY_LENGTH, SCRYPT_PARAMS);
 	return `${salt.toString("hex")}:${derivedKey.toString("hex")}`;
 }
 /**
@@ -1527,7 +2182,7 @@ async function verifyPassword(password, storedHash) {
 	if (!saltHex || !hashHex) return false;
 	const salt = Buffer.from(saltHex, "hex");
 	const storedKey = Buffer.from(hashHex, "hex");
-	return timingSafeEqual(await scryptAsync(password, salt, KEY_LENGTH), storedKey);
+	return timingSafeEqual(await scryptAsync(password, salt, KEY_LENGTH, SCRYPT_PARAMS), storedKey);
 }
 //#endregion
 //#region src/auth/auth-hooks.ts
@@ -1585,6 +2240,196 @@ function resolveAuthHooks(hooks) {
 	};
 }
 //#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.
+*
+* 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\".");
+}
+//#endregion
+//#region src/email/smtp-email-service.ts
+var _nodemailer;
+async function loadNodemailer() {
+	if (!_nodemailer) try {
+		_nodemailer = await import("nodemailer");
+	} catch {
+		throw new Error("nodemailer is required for SMTP email. Install it: pnpm add nodemailer");
+	}
+	return _nodemailer;
+}
+/**
+* Safely parse a hostname from a URL string
+*/
+function getHostname(urlStr) {
+	try {
+		return new URL(urlStr.includes("://") ? urlStr : `https://${urlStr}`).hostname;
+	} catch {
+		return;
+	}
+}
+/**
+* SMTP Email Service implementation using Nodemailer
+*/
+var SMTPEmailService = class {
+	transporter = null;
+	config;
+	_initialized = false;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Lazily initialize the SMTP transporter on first use
+	*/
+	async ensureTransporter() {
+		if (this._initialized) return;
+		this._initialized = true;
+		if (this.config.smtp) {
+			const nodemailer = await loadNodemailer();
+			let smtpName = this.config.smtp.name;
+			if (!smtpName) {
+				const urlsToTry = [
+					process.env.FRONTEND_URL,
+					this.config.resetPasswordUrl,
+					this.config.verifyEmailUrl
+				];
+				for (const urlStr of urlsToTry) if (urlStr) {
+					const hostname = getHostname(urlStr);
+					if (hostname) {
+						smtpName = hostname;
+						break;
+					}
+				}
+			}
+			this.transporter = nodemailer.createTransport({
+				name: smtpName,
+				host: this.config.smtp.host,
+				port: this.config.smtp.port,
+				secure: this.config.smtp.secure ?? this.config.smtp.port === 465,
+				auth: this.config.smtp.auth ? {
+					user: this.config.smtp.auth.user,
+					pass: this.config.smtp.auth.pass
+				} : void 0
+			});
+		}
+	}
+	/**
+	* Check if the email service is properly configured
+	*/
+	isConfigured() {
+		return !!(this.config.smtp || this.config.sendEmail);
+	}
+	/**
+	* Send an email using SMTP or custom send function
+	*/
+	async send(options) {
+		if (this.config.sendEmail) {
+			await this.config.sendEmail(options);
+			return;
+		}
+		await this.ensureTransporter();
+		if (!this.transporter) throw new Error("Email service not configured. Provide SMTP config or sendEmail function.");
+		const to = Array.isArray(options.to) ? options.to.join(", ") : options.to;
+		try {
+			await this.transporter.sendMail({
+				from: this.config.from,
+				to,
+				subject: options.subject,
+				html: options.html,
+				text: options.text,
+				replyTo: options.replyTo
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.error("Failed to send email", { detail: message });
+			throw new Error(`Failed to send email: ${message}`);
+		}
+	}
+	/**
+	* Verify SMTP connection (useful for startup checks)
+	*/
+	async verifyConnection() {
+		await this.ensureTransporter();
+		if (!this.transporter) return !!this.config.sendEmail;
+		try {
+			await this.transporter.verify();
+			return true;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.error("SMTP connection verification failed", { detail: message });
+			return false;
+		}
+	}
+};
+/**
+* Create an email service from configuration.
+*
+* This is the choke point every boot path goes through — the managed runtime,
+* both driver bootstrappers, and any app that passes `auth.email` — so it is
+* where the link bases are checked. A config that can send mail but cannot build
+* an absolute link fails the start rather than delivering dead `href="/…"` links
+* and reporting success; see `assertEmailLinkBases`.
+*/
+function createEmailService(config) {
+	assertEmailLinkBases(config);
+	return new SMTPEmailService(config);
+}
+//#endregion
 //#region src/auth/rate-limit-store.ts
 /**
 * The default store: a sliding window in this process's memory.
@@ -1650,13 +2495,32 @@ var MemoryRateLimitStore = class {
 //#region src/auth/rate-limiter.ts
 /**
 * Resolve the number of trusted proxy hops from an explicit option, the
-* `TRUSTED_PROXY_HOPS` env var, or the default of 1.
+* `TRUSTED_PROXY_HOPS` env var, or the fail-safe default of 0.
+*
+* Zero, not one: trusting a hop that is not there hands the rate-limit key to
+* the caller, and a server has no way to detect the difference from a request.
 */
 function resolveTrustedProxyHops(optionValue) {
 	if (typeof optionValue === "number" && Number.isFinite(optionValue) && optionValue >= 0) return Math.floor(optionValue);
 	const fromEnv = Number(process.env.TRUSTED_PROXY_HOPS);
 	if (Number.isFinite(fromEnv) && fromEnv >= 0) return Math.floor(fromEnv);
-	return 1;
+	return 0;
+}
+/**
+* Warn once when the deployment looks proxied but has not said so.
+*
+* The safe default is the wrong answer for the other common topology: behind an
+* ingress, every request arrives from the proxy, so ignoring `X-Forwarded-For`
+* collapses every client into one bucket and the limiter starts locking real
+* users out of each other's quota. That is a loud failure in production and a
+* silent one in staging, so it gets a warning rather than a guess — guessing is
+* what made the header trustworthy in the first place.
+*/
+var warnedAboutUntrustedForwardedFor = false;
+function warnIfProxiedButUntrusted(hasForwardedFor) {
+	if (!hasForwardedFor || warnedAboutUntrustedForwardedFor) return;
+	warnedAboutUntrustedForwardedFor = true;
+	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.");
 }
 /**
 * Create a rate-limiting middleware.
@@ -1686,7 +2550,23 @@ function createRateLimiter(options = {}) {
 	};
 }
 /**
-* Default key generator: extract client IP from standard headers.
+* The address the socket is actually connected to, or `undefined` on a runtime
+* that cannot say. Unforgeable, unlike every header below.
+*
+* `getConnInfo` is Node-specific and throws elsewhere, so the failure is
+* swallowed: a runtime without connection info falls back to the shared bucket,
+* which is a availability trade the caller cannot exploit.
+*/
+function socketAddress(c) {
+	try {
+		return getConnInfo(c).remote.address;
+	} catch {
+		return;
+	}
+}
+/**
+* Default key generator: the client's address, from the most trustworthy source
+* this deployment has.
 *
 * `X-Forwarded-For` is a client-writable header; only the entries appended by
 * trusted reverse proxies can be believed. With `trustedProxyHops` proxies in
@@ -1695,18 +2575,36 @@ function createRateLimiter(options = {}) {
 * client-supplied and must be ignored. This is what prevents a caller from
 * spoofing `X-Forwarded-For` to spread its requests across many rate-limit keys.
 *
-* With `trustedProxyHops === 0` (server exposed directly, no proxy),
-* `X-Forwarded-For` is not trusted at all and `X-Real-IP` is used instead.
+* `X-Real-IP` is the *same* kind of header and needs the same rule, which it
+* did not have: it was read unconditionally, including under
+* `trustedProxyHops === 0` — the mode whose entire meaning is "no proxy is in
+* front of me". With no proxy there, nothing writes `X-Real-IP` except the
+* caller, so the key was theirs to choose: one header per request bought an
+* unlimited number of buckets, and the limiters on login, registration and
+* password reset counted to one. The reasoning had been done carefully for one
+* spelling of a proxy header and not carried to its twin.
+*
+* So `X-Real-IP` is now believed only where a proxy is declared to exist. With
+* none, the connection's own address is used — unforgeable, and available
+* because the server runs on `@hono/node-server`. `"unknown"` is the last
+* 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.
 */
 function defaultKeyGenerator(c, trustedProxyHops = resolveTrustedProxyHops()) {
-	if (trustedProxyHops > 0) {
+	if (trustedProxyHops === 0) {
+		warnIfProxiedButUntrusted(!!c.req.header("x-forwarded-for"));
+		return socketAddress(c) ?? "unknown";
+	}
+	{
 		const forwardedFor = c.req.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");
+		if (realIp) return realIp;
 	}
-	return c.req.header("x-real-ip") || "unknown";
+	return socketAddress(c) ?? "unknown";
 }
 /**
 * Pre-configured rate limiter for general auth endpoints (login, register).
@@ -1727,6 +2625,34 @@ var strictAuthLimiter = createRateLimiter({
 	message: "Too many requests to this sensitive endpoint, please try again later."
 });
 /**
+* Limiter for `POST /auth/send-verification`, keyed by the authenticated user.
+*
+* That route had no limiter at all while every one of its email-sending
+* siblings had one, and being authenticated is not the protection it looks
+* like: registration does not verify the address it is given, so an attacker
+* registers a victim's address, signs in to the account they just made, and
+* loops the route. Each call mints a token and mails the victim.
+*
+* An IP limiter cannot express what is wanted here — the recipient is the
+* quantity being protected, not the caller — so this one keys on the uid, which
+* on this route is one-to-one with the recipient address (emails are unique per
+* account). `strictAuthLimiter` still runs in front of it to bound the caller by
+* IP; this bounds what any single address can be sent.
+*
+* Five per 15 minutes is generous for "I didn't get the email, resend it" and
+* useless as a mail bomb. Unauthenticated requests fall back to the IP bucket so
+* the limiter is never a no-op if it is ever mounted before the auth middleware.
+*/
+var verificationEmailLimiter = createRateLimiter({
+	windowMs: 900 * 1e3,
+	limit: 5,
+	keyGenerator: (c) => {
+		const user = c.get("user");
+		return user?.uid ? `verification-email:user:${user.uid}` : `verification-email:ip:${defaultKeyGenerator(c)}`;
+	},
+	message: "Too many verification emails requested, please try again later."
+});
+/**
 * Key generator for API-key-based rate limiting.
 *
 * Uses the API key ID (from `c.get("apiKey")`) as the rate limit key.
@@ -1738,6 +2664,8 @@ function apiKeyKeyGenerator(c) {
 	if (apiKey) return `api-key:${apiKey.id}`;
 	return defaultKeyGenerator(c);
 }
+/** @see DataRateLimitConfig.anonymousFunctions */
+var DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3e3;
 /**
 * Rate limiting for the data API.
 *
@@ -1757,6 +2685,7 @@ function apiKeyKeyGenerator(c) {
 */
 function createDataRateLimiter(config = {}) {
 	const { windowMs = 900 * 1e3, apiKey: apiKeyLimit = 1e3, user: userLimit = 1e3, anonymous: anonLimit = 300, store = new MemoryRateLimitStore(windowMs) } = config;
+	const trustedProxyHops = resolveTrustedProxyHops(config.trustedProxyHops);
 	return createRateLimiter({
 		windowMs,
 		store,
@@ -1766,7 +2695,7 @@ function createDataRateLimiter(config = {}) {
 			if (key) return `api-key:${key.id}`;
 			const user = c.get("user");
 			if (user?.uid && !isAnonymousUid(user.uid)) return `user:${user.uid}`;
-			return `ip:${defaultKeyGenerator(c)}`;
+			return `ip:${defaultKeyGenerator(c, trustedProxyHops)}`;
 		},
 		resolveLimit: (c) => {
 			const key = c.get("apiKey");
@@ -5783,17 +6712,27 @@ function generateHotp(secret, counter) {
 	return (((hash[offset] & 127) << 24 | hash[offset + 1] << 16 | hash[offset + 2] << 8 | hash[offset + 3]) % 1e6).toString().padStart(6, "0");
 }
 /**
-* Verify a TOTP token with a configurable time window
+* Verify a TOTP token and report *which* time step matched.
+*
+* RFC 6238 §5.2 requires that an accepted OTP not be accepted a second time,
+* and a boolean cannot express what was accepted: with `window = 1` the same
+* six digits stay valid for up to 90 seconds, so a code observed once — by a
+* phishing relay, over a shoulder, in a pasted support message — can be
+* presented again for the rest of that window. The caller records the returned
+* counter against the factor and refuses anything at or below it.
 *
 * @param secret - The shared secret as a Buffer
 * @param token - The 6-digit TOTP code to verify
 * @param window - Number of time steps to check on each side (default: 1)
-* @returns true if the token is valid within the window
+* @returns The matched time step, or `null` when no step in the window matches
 */
-function verifyTotp(secret, token, window = 1) {
+function verifyTotpCounter(secret, token, window = 1) {
 	const counter = BigInt(Math.floor(Date.now() / 1e3 / 30));
-	for (let i = -window; i <= window; i++) if (generateHotp(secret, counter + BigInt(i)) === token) return true;
-	return false;
+	for (let i = -window; i <= window; i++) {
+		const step = counter + BigInt(i);
+		if (generateHotp(secret, step) === token) return Number(step);
+	}
+	return null;
 }
 /**
 * Generate a new TOTP secret and return the setup information
@@ -5836,79 +6775,335 @@ function hashRecoveryCode(code) {
 *
 * - Derives a 32-byte key via SHA-256 from `MFA_ENCRYPTION_KEY` or `JWT_SECRET`.
 * - Generates a random 12-byte IV per encryption call.
-* - Returns ciphertexts in the format `iv_hex:authTag_hex:ciphertext_hex`.
+* - Stamps the key that made the ciphertext, so the key can be changed without
+*   locking every enrolled user out — see "Rotating the key" below.
+*
+* ## Rotating the key
+*
+* A ciphertext used to be `iv:authTag:ciphertext` and recorded nothing about
+* which key produced it, while the key was re-derived from the environment on
+* every call. Setting `MFA_ENCRYPTION_KEY` on a deployment that had been
+* falling back to `JWT_SECRET` therefore made every stored factor undecryptable
+* — AES-GCM authenticates, so it did not return a wrong secret, it threw, and
+* every MFA sign-in failed until the variable was removed again.
+*
+* Now a ciphertext carries `v1.<keyId>`, where `keyId` is derived from the key
+* itself (no key names to keep in sync), and decryption runs against a list of
+* candidates: `MFA_ENCRYPTION_KEY`, then each comma-separated entry in
+* `MFA_ENCRYPTION_KEY_PREVIOUS`, then `JWT_SECRET`. To rotate:
+*
+* 1. **Deploy this code first.** It reads both formats. Doing it the other way
+*    round — setting the key before the readers understand the old ciphertexts
+*    — is the outage this exists to prevent.
+* 2. Move the old value into `MFA_ENCRYPTION_KEY_PREVIOUS` and set the new one
+*    as `MFA_ENCRYPTION_KEY`.
+* 3. Each factor is re-wrapped with the current key the next time its owner
+*    authenticates (`openTotpSecret` reports it via `rewrapped`).
+* 4. Once every enrolled user has signed in, drop `MFA_ENCRYPTION_KEY_PREVIOUS`.
+*    Any factor still on the old key then fails loudly, naming the key id,
+*    rather than being silently unreadable.
+*
+* Trial decryption across candidates is safe here: GCM's auth tag is a 128-bit
+* MAC, so a wrong key throws instead of yielding a plausible-looking secret.
 *
 * @module
 */
 var ALGORITHM = "aes-256-gcm";
 var IV_BYTES = 12;
 var AUTH_TAG_LENGTH = 16;
+/** Ciphertext prefix marking the key-stamped format. */
+var VERSION = "v1";
+/** Warn once, not once per sign-in. */
+var warnedAboutFallback = false;
+function toCandidate(raw, source) {
+	const digest = createHash$1("sha256").update(raw).digest();
+	return {
+		id: digest.toString("hex").slice(0, 8),
+		key: digest,
+		source
+	};
+}
 /**
-* Resolve the raw key string from environment variables.
+* Every key this process can decrypt with, most-preferred first.
 *
-* Prefers `MFA_ENCRYPTION_KEY`; falls back to `JWT_SECRET` with a warning.
-* Throws if neither is set.
+* The head of the list is the key new ciphertexts are written with; the rest
+* exist so that ciphertexts written before a rotation still open.
 */
-function resolveKeyString() {
-	const explicit = process.env.MFA_ENCRYPTION_KEY;
-	if (explicit) return explicit;
-	const fallback = process.env.JWT_SECRET;
-	if (fallback) {
-		logger.warn("[MFA-Crypto] MFA_ENCRYPTION_KEY is not set — falling back to JWT_SECRET. Set a dedicated MFA_ENCRYPTION_KEY for production.");
-		return fallback;
+function keyCandidates() {
+	const candidates = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (raw, source) => {
+		const trimmed = raw?.trim();
+		if (!trimmed || seen.has(trimmed)) return;
+		seen.add(trimmed);
+		candidates.push(toCandidate(trimmed, source));
+	};
+	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.");
+	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.");
 	}
-	throw new Error("Cannot encrypt TOTP secret: neither MFA_ENCRYPTION_KEY nor JWT_SECRET is configured.");
+	return candidates;
 }
-/**
-* Derive a deterministic 32-byte AES-256 key from the raw secret string.
-*/
-function deriveKey(raw) {
-	return createHash$1("sha256").update(raw).digest();
+/** The key new ciphertexts are written with. */
+function currentKey() {
+	return keyCandidates()[0];
 }
 /**
 * Encrypt a plaintext TOTP secret.
 *
 * @param plaintext - The Base32 TOTP secret to encrypt.
-* @returns A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+* @returns A string in the format `v1.<keyId>:iv_hex:authTag_hex:ciphertext_hex`.
 */
 function encryptTotpSecret(plaintext) {
-	const key = deriveKey(resolveKeyString());
+	const { id, key } = currentKey();
 	const iv = randomBytes$1(IV_BYTES);
 	const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
 	const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
 	const authTag = cipher.getAuthTag();
-	return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
+	return `${VERSION}.${id}:${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
+}
+function openWith(candidate, ivHex, authTagHex, encryptedHex) {
+	const decipher = createDecipheriv(ALGORITHM, candidate.key, Buffer.from(ivHex, "hex"), { authTagLength: AUTH_TAG_LENGTH });
+	decipher.setAuthTag(Buffer.from(authTagHex, "hex"));
+	return Buffer.concat([decipher.update(Buffer.from(encryptedHex, "hex")), decipher.final()]).toString("utf8");
 }
 /**
-* Decrypt a previously encrypted TOTP secret.
+* Decrypt a stored TOTP secret, reporting whether it wants re-wrapping.
 *
-* @param ciphertext - A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
-* @returns The original Base32 TOTP secret.
+* Accepts both the key-stamped format and the original unstamped
+* `iv:authTag:ciphertext`, which is tried against each candidate in turn.
 */
-function decryptTotpSecret(ciphertext) {
+function openTotpSecret(ciphertext) {
 	const parts = ciphertext.split(":");
-	if (parts.length !== 3) throw new Error("Invalid encrypted TOTP secret format — expected iv:authTag:ciphertext");
+	const candidates = keyCandidates();
+	const current = candidates[0];
+	if (parts.length === 4) {
+		const [stamp, ivHex, authTagHex, encryptedHex] = parts;
+		const [version, keyId] = stamp.split(".");
+		if (version !== VERSION || !keyId) throw new Error(`Unsupported encrypted TOTP secret version "${stamp}"`);
+		const named = candidates.find((c) => c.id === keyId);
+		if (!named) throw new Error(`No configured key matches this TOTP secret (key id "${keyId}"). Restore the key that encrypted it via MFA_ENCRYPTION_KEY_PREVIOUS. Configured key ids: ${candidates.map((c) => `${c.id} (${c.source})`).join(", ")}.`);
+		const secret = openWith(named, ivHex, authTagHex, encryptedHex);
+		return {
+			secret,
+			rewrapped: named.id === current.id ? null : encryptTotpSecret(secret)
+		};
+	}
+	if (parts.length !== 3) throw new Error("Invalid encrypted TOTP secret format — expected v1.<keyId>:iv:authTag:ciphertext or the legacy iv:authTag:ciphertext");
 	const [ivHex, authTagHex, encryptedHex] = parts;
-	const key = deriveKey(resolveKeyString());
-	const iv = Buffer.from(ivHex, "hex");
-	const authTag = Buffer.from(authTagHex, "hex");
-	const encrypted = Buffer.from(encryptedHex, "hex");
-	const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
-	decipher.setAuthTag(authTag);
-	return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+	for (const candidate of candidates) try {
+		const secret = openWith(candidate, ivHex, authTagHex, encryptedHex);
+		return {
+			secret,
+			rewrapped: encryptTotpSecret(secret)
+		};
+	} catch {}
+	throw new Error(`Could not decrypt TOTP secret with any configured key. Tried: ${candidates.map((c) => c.source).join(", ")}.`);
+}
+//#endregion
+//#region src/auth/cookie-utils.ts
+/**
+* Cookie auth helpers for httpOnly refresh tokens.
+*/
+function getCookieSettings(config) {
+	return {
+		name: config?.cookieName || "__rb_refresh",
+		path: config?.path || "/",
+		sameSite: config?.sameSite || "Lax",
+		domain: config?.domain,
+		secure: config?.secure
+	};
+}
+/**
+* Set the refresh token as an httpOnly cookie on the response.
+*/
+function setRefreshCookie(c, refreshToken, config) {
+	if (!config) return;
+	const settings = getCookieSettings(config);
+	const isSecure = settings.secure ?? true;
+	let cookie = `${settings.name}=${encodeURIComponent(refreshToken)}; Path=${settings.path}; HttpOnly; SameSite=${settings.sameSite}`;
+	if (isSecure) cookie += "; Secure";
+	if (settings.domain) cookie += `; Domain=${settings.domain}`;
+	const maxAgeSeconds = Math.floor(Math.min(getRefreshTokenTtlMs(), MAX_COOKIE_AGE_MS) / 1e3);
+	cookie += `; Max-Age=${maxAgeSeconds}`;
+	c.header("Set-Cookie", cookie, { append: true });
+}
+/**
+* Clear the refresh token cookie.
+*/
+function clearRefreshCookie(c, config) {
+	if (!config) return;
+	const settings = getCookieSettings(config);
+	let cookie = `${settings.name}=; Path=${settings.path}; HttpOnly; SameSite=${settings.sameSite}; Max-Age=0`;
+	if (settings.secure ?? true) cookie += "; Secure";
+	if (settings.domain) cookie += `; Domain=${settings.domain}`;
+	c.header("Set-Cookie", cookie, { append: true });
+}
+/**
+* Read the refresh token from the request — cookie first, then body fallback.
+*/
+function readRefreshToken(c, body, config) {
+	if (config) {
+		const settings = getCookieSettings(config);
+		const cookieHeader = c.req.header("cookie") || "";
+		const prefix = `${settings.name}=`;
+		const cookies = cookieHeader.split(";");
+		for (const part of cookies) {
+			const trimmed = part.trim();
+			if (trimmed.startsWith(prefix)) return decodeURIComponent(trimmed.slice(prefix.length));
+		}
+	}
+	return body.refreshToken;
+}
+/**
+* Redact the refresh token from the response body when cookie mode is active.
+*/
+function redactRefreshToken(response, c, refreshToken, config) {
+	if (!config) return response;
+	setRefreshCookie(c, refreshToken, config);
+	return {
+		...response,
+		tokens: {
+			...response.tokens,
+			refreshToken: ""
+		}
+	};
 }
 //#endregion
 //#region src/auth/mfa-routes.ts
-function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
+/**
+* How many failed verifications one challenge tolerates before it is spent.
+*
+* A 6-digit code with a ±1 step window accepts 3 of 1,000,000 values, so the
+* only thing standing between an attacker and the second factor is how many
+* guesses a challenge will take. Five, and then they must open another one —
+* which the per-user limiter below is counting.
+*/
+var MAX_CHALLENGE_ATTEMPTS = 5;
+/** Verification attempts one *account* may make per window, across all IPs. */
+var MFA_VERIFICATION_ATTEMPTS_PER_WINDOW = 10;
+/**
+* Resolve the caller of a challenge route from either a full session or a
+* pre-auth token.
+*
+* Both are parsed here rather than by `requireAuth` because the whole point of
+* the challenge pair is that it runs before the session exists — a login by an
+* MFA-enrolled user never receives an access token until it is finished.
+*/
+/**
+* Open a factor's stored secret, re-storing it under the current key if it
+* opened with an older one.
+*
+* This is what makes an `MFA_ENCRYPTION_KEY` rotation complete on its own: each
+* factor moves to the new key the next time its owner authenticates, so the
+* previous key can eventually be dropped. See `mfa-crypto.ts` for the sequence.
+*
+* A failed re-wrap must never fail the verification — the code the user typed
+* was already checked against the right secret, and the only cost of not
+* persisting is that this factor is re-wrapped again next time.
+*/
+async function openAndRewrap(authRepo, factorId, secretEncrypted) {
+	const { secret, rewrapped } = openTotpSecret(secretEncrypted);
+	if (!rewrapped) return secret;
+	if (typeof authRepo.updateMfaFactorSecret !== "function") return secret;
+	try {
+		await authRepo.updateMfaFactorSecret(factorId, rewrapped);
+		logger.info("[MFA-Crypto] Re-wrapped a TOTP secret under the current key", { factorId });
+	} catch (error) {
+		logger.warn("[MFA-Crypto] Could not re-wrap a TOTP secret; leaving it on its original key", {
+			factorId,
+			error
+		});
+	}
+	return secret;
+}
+function resolveStepUpPrincipal(c) {
+	const existing = c.get("user");
+	if (existing?.uid) return {
+		uid: existing.uid,
+		aal: existing.aal === "aal2" ? "aal2" : "aal1",
+		pending: false
+	};
+	const token = extractBearerToken(c.req.header("authorization"));
+	if (token === void 0) return null;
+	const session = verifyAccessToken(token);
+	if (session) return {
+		uid: session.uid,
+		aal: session.aal === "aal2" ? "aal2" : "aal1",
+		pending: false
+	};
+	const pending = verifyMfaPendingToken(token);
+	if (pending) return {
+		uid: pending.uid,
+		aal: "aal1",
+		pending: true
+	};
+	return null;
+}
+/**
+* Per-account throttle on code verification.
+*
+* Keyed on the uid rather than the IP because an IP is the attacker's to
+* rotate and the account under attack is not: a distributed run against one
+* account passes an IP-keyed limiter untouched. The IP limiter still runs in
+* front of this one — they bound different things.
+*/
+var mfaVerificationLimiter = createRateLimiter({
+	windowMs: 900 * 1e3,
+	limit: MFA_VERIFICATION_ATTEMPTS_PER_WINDOW,
+	keyGenerator: (c) => `mfa-verify:${resolveStepUpPrincipal(c)?.uid ?? "unidentified"}`,
+	message: "Too many verification attempts for this account, please try again later."
+});
+function mountMfaRoutes(opts) {
+	const { router, config, ops, parseBody, buildAuthResponse, createSessionAndTokens, applyTransformHook } = opts;
 	const authRepo = config.authRepo;
 	const emailConfig = config.emailConfig;
 	/**
+	* Changing which factors an account trusts is itself a privileged act.
+	*
+	* An account that already has a verified factor may only gain or confirm
+	* another one from a session that presented the existing one. Without this
+	* the `aal2` gate on unenroll was self-service: an `aal1` session enrolled
+	* a factor of its own, verified it with a code it computed from the secret
+	* the enrol response had just handed it, stepped up on that, and deleted
+	* the victim's real factor — arriving at `aal2` without ever holding the
+	* second factor the account was protected by.
+	*
+	* The first enrolment on an account with no verified factor is deliberately
+	* allowed at `aal1`: there is no second factor to demand yet.
+	*/
+	async function requireStepUpForFactorChange(userCtx) {
+		if (userCtx.aal === "aal2") return;
+		if (!await authRepo.hasVerifiedMfaFactors(userCtx.uid)) return;
+		throw ApiError.forbidden("This account already has a verified second factor. Re-authenticate with it before changing enrolled factors.", "AAL2_REQUIRED");
+	}
+	/**
+	* Spend a TOTP time step, or refuse it as already spent.
+	*
+	* RFC 6238 §5.2: an accepted OTP must not be accepted again. The window
+	* that exists for clock drift is also a 90-second replay window, and a
+	* replay here is not momentary — `challenge/verify` mints a refresh token,
+	* so one observed code buys a durable session.
+	*/
+	async function claimTotpStep(factorId, counter) {
+		if (typeof authRepo.claimMfaFactorCounter !== "function") {
+			logger.warn("[MFA] Auth repository cannot record spent TOTP steps; an accepted code stays replayable for its window", { factorId });
+			return true;
+		}
+		return authRepo.claimMfaFactorCounter(factorId, counter);
+	}
+	/**
 	* POST /auth/mfa/enroll
 	* Start MFA enrollment: generate TOTP secret and recovery codes
 	*/
-	router.post("/mfa/enroll", requireAuth, async (c) => {
+	router.post("/mfa/enroll", strictAuthLimiter, requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
+		await requireStepUpForFactorChange(userCtx);
 		const body = await c.req.json().catch(() => ({}));
 		const friendlyName = typeof body.friendlyName === "string" ? body.friendlyName : void 0;
 		const issuer = typeof body.issuer === "string" ? body.issuer : emailConfig?.appName || "Rebase";
@@ -5938,17 +7133,20 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	* POST /auth/mfa/verify
 	* Verify TOTP code to complete MFA enrollment
 	*/
-	router.post("/mfa/verify", requireAuth, async (c) => {
+	router.post("/mfa/verify", strictAuthLimiter, requireAuth, mfaVerificationLimiter, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const { factorId, code } = parseBody(object({
+		await requireStepUpForFactorChange(userCtx);
+		const verifySchema = object({
 			factorId: string().min(1, "Factor ID is required"),
 			code: string().length(6, "Code must be 6 digits")
-		}), await c.req.json());
+		});
+		const { factorId, code } = parseBody(verifySchema, await c.req.json());
 		const factor = await authRepo.getMfaFactorById(factorId);
 		if (!factor || factor.uid !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
 		if (factor.verified) throw ApiError.badRequest("Factor is already verified", "ALREADY_VERIFIED");
-		if (!verifyTotp(base32Decode(decryptTotpSecret(factor.secretEncrypted)), code)) throw ApiError.unauthorized("Invalid TOTP code", "INVALID_CODE");
+		const matchedCounter = verifyTotpCounter(base32Decode(await openAndRewrap(authRepo, factor.id, factor.secretEncrypted)), code);
+		if (matchedCounter === null || !await claimTotpStep(factor.id, matchedCounter)) throw ApiError.unauthorized("Invalid TOTP code", "INVALID_CODE");
 		await authRepo.verifyMfaFactor(factorId);
 		return c.json({
 			success: true,
@@ -5957,14 +7155,16 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	});
 	/**
 	* POST /auth/mfa/challenge
-	* Create an MFA challenge during login (user has MFA enrolled)
+	* Open a challenge — either to finish a sign-in that answered
+	* `MFA_REQUIRED`, or to step an existing session up to `aal2`.
 	*/
-	router.post("/mfa/challenge", requireAuth, async (c) => {
-		const userCtx = c.get("user");
-		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const { factorId } = parseBody(object({ factorId: string().min(1, "Factor ID is required") }), await c.req.json());
+	router.post("/mfa/challenge", strictAuthLimiter, async (c) => {
+		const principal = resolveStepUpPrincipal(c);
+		if (!principal) throw ApiError.unauthorized("Not authenticated");
+		const challengeSchema = object({ factorId: 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 !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
+		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 challenge = await authRepo.createMfaChallenge(factorId, ipAddress);
@@ -5976,49 +7176,73 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	});
 	/**
 	* POST /auth/mfa/challenge/verify
-	* Verify a TOTP code for an active challenge, upgrade aal1 → aal2
+	* Answer a challenge: this is where an MFA-enrolled account's session is
+	* minted, at `aal2`.
 	*/
-	router.post("/mfa/challenge/verify", requireAuth, async (c) => {
-		const userCtx = c.get("user");
-		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const { challengeId, code } = parseBody(object({
+	router.post("/mfa/challenge/verify", strictAuthLimiter, mfaVerificationLimiter, async (c) => {
+		const principal = resolveStepUpPrincipal(c);
+		if (!principal) throw ApiError.unauthorized("Not authenticated");
+		const challengeVerifySchema = object({
 			challengeId: string().min(1, "Challenge ID is required"),
 			code: string().min(1, "Code is required")
-		}), await c.req.json());
+		});
+		const { challengeId, code } = parseBody(challengeVerifySchema, await c.req.json());
 		const challenge = await authRepo.getMfaChallengeById(challengeId);
 		if (!challenge) throw ApiError.badRequest("Invalid or expired challenge", "INVALID_CHALLENGE");
 		const factor = await authRepo.getMfaFactorById(challenge.factorId);
-		if (!factor || factor.uid !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
-		let isValid = verifyTotp(base32Decode(decryptTotpSecret(factor.secretEncrypted)), code);
-		if (!isValid) {
+		if (!factor || factor.uid !== principal.uid) throw ApiError.notFound("MFA factor not found");
+		if ((challenge.attempts ?? 0) >= MAX_CHALLENGE_ATTEMPTS) {
+			logger.warn("[Security Audit] MFA challenge attempt limit reached", {
+				eventType: "auth.mfa.challenge.exhausted",
+				uid: principal.uid,
+				challengeId
+			});
+			throw ApiError.unauthorized("Too many failed attempts for this challenge", "CHALLENGE_EXHAUSTED");
+		}
+		const matchedCounter = verifyTotpCounter(base32Decode(await openAndRewrap(authRepo, factor.id, factor.secretEncrypted)), code);
+		let isValid = matchedCounter !== null && await claimTotpStep(factor.id, matchedCounter);
+		if (!isValid && matchedCounter === null) {
 			const codeHash = hashRecoveryCode(code);
-			isValid = await authRepo.useRecoveryCode(userCtx.uid, codeHash);
+			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,
+				challengeId,
+				attempts
+			});
+			throw ApiError.unauthorized("Invalid verification code", "INVALID_CODE");
 		}
-		if (!isValid) throw ApiError.unauthorized("Invalid verification code", "INVALID_CODE");
 		await authRepo.verifyMfaChallenge(challengeId);
-		const roleIds = (await authRepo.getUserRoles(userCtx.uid)).map((r) => r.id);
-		const accessToken = generateAccessToken(userCtx.uid, roleIds, "aal2");
-		const refreshToken = generateRefreshToken();
-		await authRepo.createRefreshToken(userCtx.uid, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown", {
-			id: randomUUID$1(),
-			startedAt: /* @__PURE__ */ new Date()
+		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(principal.uid, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown", {
+			skipMfaGate: true,
+			aal: "aal2"
 		});
-		if (ops.onMfaVerified) ops.onMfaVerified(userCtx.uid, factor.id).catch((err) => {
+		if (ops.onMfaVerified) ops.onMfaVerified(principal.uid, factor.id).catch((err) => {
 			logger.error("[AuthHooks] onMfaVerified error", { error: err instanceof Error ? err.message : err });
 		});
-		let mfaResponse = { tokens: {
+		logger.info("[Security Audit] MFA verification success", {
+			eventType: "auth.mfa.verify.success",
+			uid: principal.uid,
+			factorId: factor.id,
+			completedSignIn: principal.pending
+		});
+		const user = await authRepo.getUserById(principal.uid).catch(() => null);
+		let mfaResponse = user ? buildAuthResponse(user, roleIds, accessToken, refreshToken, "mfa") : { tokens: {
 			accessToken,
 			refreshToken,
 			accessTokenExpiresAt: getAccessTokenExpiry()
 		} };
-		if (applyTransformHook) mfaResponse = await applyTransformHook(mfaResponse, "mfa", c.req.raw, userCtx.uid);
-		return c.json(mfaResponse);
+		if (applyTransformHook) mfaResponse = await applyTransformHook(mfaResponse, "mfa", c.req.raw, principal.uid);
+		return c.json(redactRefreshToken(mfaResponse, c, refreshToken, config.cookieAuth));
 	});
 	/**
 	* GET /auth/mfa/factors
 	* List enrolled MFA factors for the current user
 	*/
-	router.get("/mfa/factors", requireAuth, async (c) => {
+	router.get("/mfa/factors", strictAuthLimiter, requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const factors = await authRepo.getMfaFactors(userCtx.uid);
@@ -6034,11 +7258,12 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	* DELETE /auth/mfa/unenroll
 	* Remove an MFA factor
 	*/
-	router.delete("/mfa/unenroll", requireAuth, async (c) => {
+	router.delete("/mfa/unenroll", strictAuthLimiter, requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		if (userCtx.aal !== "aal2") throw ApiError.forbidden("MFA verification required to unenroll. Please re-authenticate with your second factor.", "AAL2_REQUIRED");
-		const { factorId } = parseBody(object({ factorId: string().min(1, "Factor ID is required") }), await c.req.json());
+		const unenrollSchema = object({ factorId: string().min(1, "Factor ID is required") });
+		const { factorId } = parseBody(unenrollSchema, await c.req.json());
 		const factor = await authRepo.getMfaFactorById(factorId);
 		if (!factor || factor.uid !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
 		await authRepo.deleteMfaFactor(factorId, userCtx.uid);
@@ -6050,72 +7275,51 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	});
 }
 //#endregion
-//#region src/auth/cookie-utils.ts
-/**
-* Cookie auth helpers for httpOnly refresh tokens.
-*/
-function getCookieSettings(config) {
-	return {
-		name: config?.cookieName || "__rb_refresh",
-		path: config?.path || "/",
-		sameSite: config?.sameSite || "Lax",
-		domain: config?.domain,
-		secure: config?.secure
-	};
-}
-/**
-* Set the refresh token as an httpOnly cookie on the response.
-*/
-function setRefreshCookie(c, refreshToken, config) {
-	if (!config) return;
-	const settings = getCookieSettings(config);
-	const isSecure = settings.secure ?? (settings.sameSite === "None" ? true : c.req.url.startsWith("https"));
-	let cookie = `${settings.name}=${encodeURIComponent(refreshToken)}; Path=${settings.path}; HttpOnly; SameSite=${settings.sameSite}`;
-	if (isSecure) cookie += "; Secure";
-	if (settings.domain) cookie += `; Domain=${settings.domain}`;
-	const maxAgeSeconds = Math.floor(Math.min(getRefreshTokenTtlMs(), MAX_COOKIE_AGE_MS) / 1e3);
-	cookie += `; Max-Age=${maxAgeSeconds}`;
-	c.header("Set-Cookie", cookie, { append: true });
-}
+//#region src/auth/mfa-gate.ts
 /**
-* Clear the refresh token cookie.
+* The gate between "first factor accepted" and "session issued".
+*
+* MFA used to be modelled as an optional step-up that no resource required: a
+* user could enrol TOTP, print recovery codes, and change nothing about what a
+* stolen password bought, because every session-minting route issued a full
+* `aal1` token without ever asking whether the account had a second factor.
+* This module is the ask. It lives apart from the routes so that there is one
+* decision, made once, that `createSessionAndTokens` cannot be extended past —
+* a new sign-in route inherits the gate by construction rather than by the
+* author remembering it.
+*
+* @module
 */
-function clearRefreshCookie(c, config) {
-	if (!config) return;
-	const settings = getCookieSettings(config);
-	let cookie = `${settings.name}=; Path=${settings.path}; HttpOnly; SameSite=${settings.sameSite}; Max-Age=0`;
-	if (settings.domain) cookie += `; Domain=${settings.domain}`;
-	c.header("Set-Cookie", cookie, { append: true });
-}
+/** Error code a client watches for to switch a sign-in into its second step. */
+var MFA_REQUIRED_CODE = "MFA_REQUIRED";
 /**
-* Read the refresh token from the request — cookie first, then body fallback.
+* Refuse to mint a session for an account whose second factor has not been
+* presented, handing back what the client needs to present it.
+*
+* A 401 rather than a 200 with a different body: a client that has not been
+* taught about MFA must fail, not proceed. The credential in `details` is
+* useless for anything except the challenge routes.
 */
-function readRefreshToken(c, body, config) {
-	if (config) {
-		const settings = getCookieSettings(config);
-		const cookieHeader = c.req.header("cookie") || "";
-		const prefix = `${settings.name}=`;
-		const cookies = cookieHeader.split(";");
-		for (const part of cookies) {
-			const trimmed = part.trim();
-			if (trimmed.startsWith(prefix)) return decodeURIComponent(trimmed.slice(prefix.length));
-		}
+async function assertMfaSatisfied(authRepo, uid) {
+	if (typeof authRepo.hasVerifiedMfaFactors !== "function") {
+		logger.warn("[MFA] Auth repository cannot report enrolled factors; the login step-up gate is inert on this backend");
+		return;
 	}
-	return body.refreshToken;
-}
-/**
-* Redact the refresh token from the response body when cookie mode is active.
-*/
-function redactRefreshToken(response, c, refreshToken, config) {
-	if (!config) return response;
-	setRefreshCookie(c, refreshToken, config);
-	return {
-		...response,
-		tokens: {
-			...response.tokens,
-			refreshToken: ""
-		}
+	if (!await authRepo.hasVerifiedMfaFactors(uid)) return;
+	const factors = (await authRepo.getMfaFactors(uid)).filter((f) => f.verified);
+	const details = {
+		mfaToken: generateMfaPendingToken(uid),
+		factors: factors.map((f) => ({
+			id: f.id,
+			factorType: f.factorType,
+			friendlyName: f.friendlyName
+		}))
 	};
+	logger.info("[Security Audit] MFA step-up required", {
+		eventType: "auth.mfa.required",
+		uid
+	});
+	throw new ApiError(401, MFA_REQUIRED_CODE, "Multi-factor authentication is required to complete sign-in.", details, true);
 }
 //#endregion
 //#region src/auth/registration-policy.ts
@@ -6137,11 +7341,58 @@ function isSteadyStateRegistrationOpen(policy) {
 		needsSetup: false
 	});
 }
+/**
+* Whether `POST /auth/anonymous` may mint a user.
+*
+* Anonymous sign-in *is* registration: it inserts a `users` row and assigns
+* `defaultRole` exactly as `POST /auth/register` does. It simply never asked.
+* Both anonymous routes were mounted unconditionally and consulted none of the
+* gates above, so a backend with `allowRegistration: false` **and**
+* `disableSelfRegistration: true` — the documented hard kill switch — still
+* handed a permanent account to any caller in two unauthenticated requests:
+* `POST /auth/anonymous` for the row and the session, then
+* `POST /auth/anonymous/link` to put an email and password on it.
+*
+* Two terms, because the two questions are genuinely different:
+*
+*   - `allowAnonymous` is the feature switch, and it is **opt-in**. There was no
+*     key at all before, so a deployment could not turn anonymous auth off even
+*     after finding it on; defaulting it to `true` here would keep that hole
+*     open for everyone who never learns the key exists.
+*   - `disableSelfRegistration` still wins over it. Its docstring calls it a
+*     hard kill switch that blocks "self-registration outright", and an account
+*     created without credentials is still an account created by the public.
+*     An operator who sets both gets the kill switch they asked for.
+*
+* `allowRegistration` deliberately does **not** gate this. A public read-mostly
+* app that wants anonymous sessions but no sign-up forms is a real deployment,
+* and `allowAnonymous: true` says so precisely.
+*/
+function isAnonymousAuthOpen(policy) {
+	if (policy.disableSelfRegistration) return false;
+	return !!policy.allowAnonymous;
+}
 //#endregion
 //#region src/auth/session-routes.ts
 function mountSessionRoutes(opts) {
 	const { router, config, ops, parseBody, buildAuthResponse, createSessionAndTokens, applyTransformHook } = opts;
 	const authRepo = config.authRepo;
+	/**
+	* Refuse the anonymous routes unless the deployment opted in.
+	*
+	* 403 rather than 404: the route exists, and a client that was told
+	* `anonymousLogin: true` by `GET /auth/config` and then sees a 404 has no
+	* way to tell a disabled feature from a version skew. The error names the
+	* key, because the failure this closes was an operator believing they had
+	* already switched registration off.
+	*/
+	function assertAnonymousAuthOpen() {
+		if (isAnonymousAuthOpen({
+			allowAnonymous: config.allowAnonymous,
+			disableSelfRegistration: config.disableSelfRegistration
+		})) 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");
+	}
 	const logoutSchema = object({ refreshToken: string().optional() });
 	const linkSchema = object({
 		email: string().email("Invalid email address").max(255),
@@ -6168,7 +7419,7 @@ function mountSessionRoutes(opts) {
 		clearRefreshCookie(c, config.cookieAuth);
 		const accessToken = extractBearerToken(c.req.header("authorization"));
 		if (ops.afterLogout && accessToken !== void 0) {
-			const { verifyAccessToken } = await import("./jwt-DD6EtpGj.js").then((n) => n.u);
+			const { verifyAccessToken } = await import("./jwt-_IFqfTOg.js").then((n) => n.f);
 			const payload = verifyAccessToken(accessToken);
 			if (payload) ops.afterLogout(payload.uid).catch((err) => {
 				logger.error("[AuthHooks] afterLogout error", { error: err instanceof Error ? err.message : err });
@@ -6334,6 +7585,10 @@ function mountSessionRoutes(opts) {
 			registrationEnabled: registrationAllowed,
 			emailServiceEnabled: isEmailConfigured(),
 			magicLinkEnabled: !!config.enableMagicLink && isEmailConfigured(),
+			anonymousLoginEnabled: isAnonymousAuthOpen({
+				allowAnonymous: config.allowAnonymous,
+				disableSelfRegistration: config.disableSelfRegistration
+			}),
 			enabledProviders
 		});
 	});
@@ -6342,6 +7597,7 @@ function mountSessionRoutes(opts) {
 	* Create an anonymous user with temporary credentials
 	*/
 	router.post("/anonymous", strictAuthLimiter, async (c) => {
+		assertAnonymousAuthOpen();
 		let createData = {
 			email: `anon_${randomBytes$1(16).toString("hex")}@anonymous.local`,
 			emailVerified: false,
@@ -6365,7 +7621,8 @@ function mountSessionRoutes(opts) {
 	* POST /auth/anonymous/link
 	* Upgrade an anonymous user to a permanent account with email/password
 	*/
-	router.post("/anonymous/link", requireAuth, async (c) => {
+	router.post("/anonymous/link", strictAuthLimiter, requireAuth, async (c) => {
+		assertAnonymousAuthOpen();
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const user = await authRepo.getUserById(userCtx.uid);
@@ -6422,7 +7679,7 @@ function mountMagicLinkRoutes(deps) {
 			const tokenHash = hashToken(token);
 			const expiresAt = getMagicLinkExpiry();
 			await authRepo.createMagicLinkToken(user.id, tokenHash, expiresAt);
-			const magicLinkUrl = `${emailConfig?.magicLinkUrl || emailConfig?.resetPasswordUrl || ""}/auth/magic-link?token=${token}`;
+			const magicLinkUrl = `${resolveEmailLinkBase(emailConfig, "magicLink")}/auth/magic-link?token=${token}`;
 			const appName = emailConfig?.appName || "Rebase";
 			const templateFn = emailConfig?.templates?.magicLink;
 			const emailContent = templateFn ? templateFn(magicLinkUrl, {
@@ -6474,6 +7731,64 @@ function mountMagicLinkRoutes(deps) {
 	});
 }
 //#endregion
+//#region src/auth/oauth-signin-policy.ts
+/**
+* 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:
+*
+*  - 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.
+*/
+function decideOAuthAutoLink(args) {
+	if (args.providerEmailVerified !== true) return {
+		allowed: false,
+		reason: "provider-email-unverified"
+	};
+	if (Boolean(args.existingUser.passwordHash) && !args.existingUser.emailVerified) return {
+		allowed: false,
+		reason: "local-account-unverified"
+	};
+	return { allowed: true };
+}
+/**
+* Is `redirectUri` one the operator authorised?
+*
+* The provider's own registered-URI match is a real control but a coarse one:
+* it authorises *every* URI registered on that OAuth client, so a `localhost`
+* entry kept for development, or a second product sharing the client id, can
+* mint codes this backend accepts. An empty or absent allowlist keeps the old
+* behaviour (the provider's check is the only one) so existing deployments are
+* unaffected; setting one narrows it to the origins this backend serves.
+*
+* Comparison is on origin plus path, with the origin lowercased and a trailing
+* slash ignored — query strings and fragments are not part of the identity of a
+* redirect URI, and neither is the case of the host.
+*/
+function isRedirectUriAllowed(redirectUri, allowlist) {
+	if (!allowlist || allowlist.length === 0) return true;
+	const candidate = canonicalRedirectUri(redirectUri);
+	if (!candidate) return false;
+	return allowlist.some((allowed) => canonicalRedirectUri(allowed) === candidate);
+}
+function canonicalRedirectUri(uri) {
+	let parsed;
+	try {
+		parsed = new URL(uri);
+	} catch {
+		return null;
+	}
+	const path = parsed.pathname.replace(/\/+$/, "");
+	return `${parsed.protocol.toLowerCase()}//${parsed.host.toLowerCase()}${path}`;
+}
+//#endregion
 //#region src/auth/routes.ts
 /**
 * Helper to build standard auth response output
@@ -6505,7 +7820,7 @@ function getPasswordResetExpiry() {
 	return new Date(Date.now() + 3600 * 1e3);
 }
 function createAuthRoutes(config) {
-	if (config.defaultRole === "admin") throw new Error("CRITICAL SECURITY ERROR: defaultRole cannot be 'admin'. Administrative privilege escalation via registration is strictly forbidden. Use the POST /admin/bootstrap endpoint to promote the initial administrator.");
+	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.`);
 	const router = new Hono();
 	router.onError(errorHandler);
 	const authRepo = config.authRepo;
@@ -6549,11 +7864,6 @@ function createAuthRoutes(config) {
 		newPassword: string().min(1, "New password is required").max(128)
 	});
 	const refreshSchema = object({ refreshToken: string().min(1).optional() });
-	object({ refreshToken: string().optional() });
-	object({
-		displayName: string().max(255).optional(),
-		photoURL: string().url().max(2048).optional()
-	});
 	/** Parse a Zod schema against the request body, throwing ApiError on failure */
 	function parseBody(schema, body) {
 		const result = schema.safeParse(body);
@@ -6593,7 +7903,7 @@ function createAuthRoutes(config) {
 	function sendWelcomeEmail(user) {
 		if (!isEmailConfigured()) return;
 		const appName = emailConfig?.appName || "Rebase";
-		const loginUrl = emailConfig?.resetPasswordUrl || "";
+		const loginUrl = resolveEmailLinkBase(emailConfig, "resetPassword");
 		const templateFn = emailConfig?.templates?.welcomeEmail;
 		const emailContent = templateFn ? templateFn(user, appName) : getWelcomeEmailTemplate(user, appName, loginUrl ? `${loginUrl}/app` : void 0);
 		emailService.send({
@@ -6606,9 +7916,21 @@ function createAuthRoutes(config) {
 		});
 	}
 	/**
-	* Helper to generate and store session tokens
+	* Helper to generate and store session tokens.
+	*
+	* Every route that signs somebody in comes through here — password login,
+	* register, each OAuth provider, magic link, anonymous and anonymous-link —
+	* which is why the second-factor gate is *inside* it rather than repeated at
+	* each call site. An account with a verified factor gets no session from
+	* this function at all: it throws `MFA_REQUIRED`, and the only thing that
+	* mints a session for that user is `POST /auth/mfa/challenge/verify`.
+	*
+	* `skipMfaGate` exists for exactly one caller: the challenge-verify route
+	* itself, which has just seen the second factor and mints at `aal2`.
 	*/
-	async function createSessionAndTokens(uid, userAgent, ipAddress) {
+	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);
 		let customClaims;
 		if (ops.customizeAccessToken) {
@@ -6617,16 +7939,17 @@ function createAuthRoutes(config) {
 				const defaultClaims = {
 					uid,
 					roles: roleIds,
-					aal: "aal1"
+					aal
 				};
 				customClaims = await ops.customizeAccessToken(defaultClaims, user);
 			}
 		}
-		const accessToken = generateAccessToken(uid, roleIds, "aal1", customClaims);
+		const accessToken = generateAccessToken(uid, roleIds, aal, customClaims);
 		const refreshToken = generateRefreshToken();
 		await authRepo.createRefreshToken(uid, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), userAgent, ipAddress, {
 			id: randomUUID$1(),
-			startedAt: /* @__PURE__ */ new Date()
+			startedAt: /* @__PURE__ */ new Date(),
+			aal
 		});
 		return {
 			roleIds,
@@ -6724,29 +8047,46 @@ function createAuthRoutes(config) {
 	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) {
-				const msg = err instanceof Error ? err.message : String(err);
-				throw ApiError.unauthorized(`${provider.id} login failed: ${msg}`, "OAUTH_ERROR");
+				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");
 			let user = await authRepo.getUserByIdentity(provider.id, externalUser.providerId);
 			if (!user) {
 				user = await authRepo.getUserByEmail(externalUser.email);
 				if (user) {
-					if (!externalUser.emailVerified) throw ApiError.forbidden(`An account with this email already exists with a different sign-in method. ${provider.id} has not verified this email address, so it cannot be linked automatically. Sign in with your existing method, then POST to /auth/link/${provider.id} to link ${provider.id} to your account.`, "EMAIL_NOT_VERIFIED");
+					const decision = decideOAuthAutoLink({
+						providerEmailVerified: externalUser.emailVerified,
+						existingUser: user
+					});
+					if (!decision.allowed) {
+						const why = decision.reason === "provider-email-unverified" ? `${provider.id} has not verified this email address, so it cannot be linked automatically.` : "That account's email address was never verified, so it cannot be linked automatically.";
+						throw ApiError.forbidden(`An account with this email already exists with a different sign-in method. ${why} Sign in with your existing method, then POST to /auth/link/${provider.id} to link ${provider.id} to your account.`, "EMAIL_NOT_VERIFIED");
+					}
 					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, { email: externalUser.email });
 					await authRepo.updateUser(user.id, {
 						displayName: user.displayName || externalUser.displayName || void 0,
 						photoUrl: user.photoUrl || externalUser.photoUrl || void 0
 					});
 				} else {
+					if (config.disableSelfRegistration) throw ApiError.forbidden("Registration is disabled", "REGISTRATION_DISABLED");
+					let bootstrapRegistration = false;
+					if (!isRegistrationAllowed()) {
+						const { total } = await authRepo.listUsersPaginated({ limit: 1 });
+						bootstrapRegistration = total === 0;
+						if (!bootstrapRegistration) throw ApiError.forbidden("Registration is disabled", "REGISTRATION_DISABLED");
+					}
 					user = await authRepo.createUser({
 						email: normalizeEmail(externalUser.email),
 						displayName: externalUser.displayName || void 0,
-						photoUrl: externalUser.photoUrl || 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.afterUserCreate) try {
@@ -6755,7 +8095,12 @@ function createAuthRoutes(config) {
 						logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
 					}
 					const allUsers = await authRepo.listUsers();
-					if (allUsers.length === 1 && allUsers[0].id === user.id) await authRepo.setUserRoles(user.id, ["admin"]);
+					const isFirstUser = allUsers.length === 1 && allUsers[0].id === user.id;
+					if (bootstrapRegistration && !isFirstUser) {
+						await authRepo.deleteUser(user.id);
+						throw ApiError.forbidden("Registration is disabled", "REGISTRATION_DISABLED");
+					}
+					if (isFirstUser) await authRepo.setUserRoles(user.id, ["admin"]);
 					else if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
 					sendWelcomeEmail({
 						email: user.email,
@@ -6829,7 +8174,7 @@ function createAuthRoutes(config) {
 			const tokenHash = hashToken(token);
 			const expiresAt = getPasswordResetExpiry();
 			await authRepo.createPasswordResetToken(user.id, tokenHash, expiresAt);
-			const resetUrl = `${emailConfig?.resetPasswordUrl || ""}/reset-password?token=${token}`;
+			const resetUrl = `${resolveEmailLinkBase(emailConfig, "resetPassword")}/reset-password?token=${token}`;
 			const appName = emailConfig?.appName || "Rebase";
 			const templateFn = emailConfig?.templates?.passwordReset;
 			const emailContent = templateFn ? templateFn(resetUrl, {
@@ -6904,8 +8249,15 @@ function createAuthRoutes(config) {
 	/**
 	* POST /auth/send-verification
 	* Send email verification link (authenticated)
+	*
+	* Two limiters, because they bound different things: `strictAuthLimiter`
+	* bounds the caller by IP as it does on every other email-sending route, and
+	* `verificationEmailLimiter` bounds how much mail one account — i.e. one
+	* recipient address — can be made to receive. Authentication is not a bound
+	* here: the address is unverified by construction, so an attacker can hold a
+	* session for a mailbox that is not theirs.
 	*/
-	router.post("/send-verification", requireAuth, async (c) => {
+	router.post("/send-verification", strictAuthLimiter, requireAuth, verificationEmailLimiter, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		if (!isEmailConfigured()) throw ApiError.serviceUnavailable("Email service not configured. Email verification is not available.", "EMAIL_NOT_CONFIGURED");
@@ -6914,7 +8266,7 @@ function createAuthRoutes(config) {
 		if (user.emailVerified) throw ApiError.badRequest("Email is already verified", "ALREADY_VERIFIED");
 		const token = generateSecureToken();
 		await authRepo.setVerificationToken(user.id, hashToken(token));
-		const verifyUrl = `${emailConfig?.verifyEmailUrl || ""}/verify-email?token=${token}`;
+		const verifyUrl = `${resolveEmailLinkBase(emailConfig, "verifyEmail")}/verify-email?token=${token}`;
 		const appName = emailConfig?.appName || "Rebase";
 		const templateFn = emailConfig?.templates?.emailVerification;
 		const emailContent = templateFn ? templateFn(verifyUrl, {
@@ -6996,22 +8348,24 @@ function createAuthRoutes(config) {
 			});
 			return null;
 		});
+		const sessionAal = storedToken.aal === "aal2" ? "aal2" : "aal1";
 		let customClaims;
 		if (ops.customizeAccessToken && user) {
 			const defaultClaims = {
 				uid: storedToken.uid,
 				roles: roleIds,
-				aal: "aal1"
+				aal: sessionAal
 			};
 			customClaims = await ops.customizeAccessToken(defaultClaims, user);
 		}
-		const newAccessToken = generateAccessToken(storedToken.uid, roleIds, "aal1", customClaims);
+		const newAccessToken = generateAccessToken(storedToken.uid, roleIds, sessionAal, customClaims);
 		const newRefreshToken = generateRefreshToken();
 		const userAgent = c.req.header("user-agent") || "unknown";
 		const ipAddress = c.req.header("x-forwarded-for") || "unknown";
 		const session = {
 			id: storedToken.sessionId ?? storedToken.id,
-			startedAt: sessionStartedAt
+			startedAt: sessionStartedAt,
+			aal: sessionAal
 		};
 		if (!supersededAt) if (authRepo.markRefreshTokenRotated) await authRepo.markRefreshTokenRotated(tokenHash);
 		else await authRepo.deleteRefreshToken(tokenHash);
@@ -7043,7 +8397,15 @@ function createAuthRoutes(config) {
 		createSessionAndTokens,
 		applyTransformHook
 	});
-	mountMfaRoutes(router, config, ops, parseBody, applyTransformHook);
+	mountMfaRoutes({
+		router,
+		config,
+		ops,
+		parseBody,
+		buildAuthResponse,
+		createSessionAndTokens,
+		applyTransformHook
+	});
 	if (config.enableMagicLink) mountMagicLinkRoutes({
 		router,
 		config,
@@ -7076,7 +8438,11 @@ function createResetPasswordRoute(config) {
 	const { emailService, emailConfig, collectionAuthConfig } = config;
 	const ops = resolveAuthHooks(config.authHooks);
 	router.onError(errorHandler);
-	router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
+	router.use("/*", createRequireAuth({
+		serviceKey: config.serviceKey,
+		resolveRoles: (uid) => authRepo.getUserRoleIds(uid),
+		revocationRepo: authRepo
+	}));
 	router.post("/users/:uid/reset-password", requireAdmin, async (c) => {
 		const uid = c.req.param("uid");
 		const existing = await authRepo.getUserById(uid);
@@ -7179,7 +8545,11 @@ function createAdminRolesRoute(config) {
 	const router = new Hono();
 	const authRepo = config.authRepo;
 	router.onError(errorHandler);
-	router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
+	router.use("/*", createRequireAuth({
+		serviceKey: config.serviceKey,
+		resolveRoles: (uid) => authRepo.getUserRoleIds(uid),
+		revocationRepo: authRepo
+	}));
 	router.get("/roles", requireAdmin, async (c) => {
 		const roles = await authRepo.listRoles();
 		return c.json({ roles });
@@ -7219,7 +8589,11 @@ function createAdminUsersRoute(config) {
 		};
 	}
 	router.onError(errorHandler);
-	router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
+	router.use("/*", createRequireAuth({
+		serviceKey: config.serviceKey,
+		resolveRoles: (uid) => authRepo.getUserRoleIds(uid),
+		revocationRepo: authRepo
+	}));
 	router.post("/bootstrap", async (c) => {
 		const user = c.get("user");
 		if (!user || typeof user !== "object") throw ApiError.unauthorized("Not authenticated");
@@ -7233,11 +8607,19 @@ function createAdminUsersRoute(config) {
 			break;
 		}
 		if (hasAdmin) throw ApiError.forbidden("Admin users already exist. Bootstrap not allowed.", "BOOTSTRAP_COMPLETED");
-		const uid = "uid" in user ? user.uid : "uid" in user ? user.uid : void 0;
+		const uid = "uid" in user ? user.uid : void 0;
 		if (!uid) throw ApiError.unauthorized("User ID not found in auth context");
+		if (isAnonymousUid(uid)) {
+			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");
-		if (users.length > 0) {
-			const earliest = users.reduce((a, b) => {
+		const registeredUsers = users.filter((u) => !isAnonymousUid(u.id));
+		if (registeredUsers.length > 0) {
+			const earliest = registeredUsers.reduce((a, b) => {
 				const at = new Date(a.createdAt).getTime();
 				const bt = new Date(b.createdAt).getTime();
 				if (at !== bt) return at < bt ? a : b;
@@ -7287,7 +8669,7 @@ function createAdminUsersRoute(config) {
 		const search = c.req.query("search");
 		const orderBy = c.req.query("orderBy");
 		const orderDir = c.req.query("orderDir");
-		const limit = resolveClientListLimit(limitParam, { defaultLimit: 25 });
+		const limit = resolveListLimitParam(limitParam, { defaultLimit: 25 });
 		const offset = offsetParam ? Math.max(0, parseInt(offsetParam, 10) || 0) : 0;
 		const result = await authRepo.listUsersPaginated({
 			limit,
@@ -7326,13 +8708,15 @@ function createAdminUsersRoute(config) {
 			resolvedHooks: ops,
 			collectionAuthConfig
 		});
-		const user = await authRepo.createUser({
+		let createData = {
 			email: prepResult.values.email,
 			passwordHash: prepResult.values.passwordHash,
 			displayName: prepResult.values.displayName,
 			photoUrl: prepResult.values.photoUrl,
 			metadata: prepResult.values.metadata
-		});
+		};
+		if (ops.beforeUserCreate) createData = await ops.beforeUserCreate(createData);
+		const user = await authRepo.createUser(createData);
 		if (roles && Array.isArray(roles)) await authRepo.setUserRoles(user.id, roles);
 		const finalizeResult = await finalizeAdminUserCreation({
 			id: user.id,
@@ -7390,7 +8774,11 @@ function createAdminUsersRoute(config) {
 				limit: 1
 			})).total <= 1) throw ApiError.forbidden("Cannot delete the last administrator", "LAST_ADMIN");
 		}
+		if (ops.beforeUserDelete) await ops.beforeUserDelete(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 });
+		});
 		return c.json({ success: true });
 	});
 	return router;
@@ -7405,7 +8793,7 @@ function createAdminUsersRoute(config) {
 * when the user passes a plain `RebaseAuthConfig` object.
 */
 function createBuiltinAuthAdapter(config) {
-	const { authRepository, emailService, emailConfig, allowRegistration = false, disableSelfRegistration = false, allowUserLookup = false, defaultRole, oauthProviders = [], serviceKey, authHooks, collectionAuthConfig, enableMagicLink = false, cookieAuth } = config;
+	const { authRepository, emailService, emailConfig, allowRegistration = false, disableSelfRegistration = false, allowAnonymous = false, allowUserLookup = false, defaultRole, oauthProviders = [], allowedRedirectUris, serviceKey, authHooks, collectionAuthConfig, enableMagicLink = false, cookieAuth } = config;
 	const resolvedOps = resolveAuthHooks(authHooks);
 	return {
 		id: "rebase-builtin",
@@ -7422,6 +8810,13 @@ function createBuiltinAuthAdapter(config) {
 			};
 			const payload = 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);
@@ -7431,7 +8826,7 @@ function createBuiltinAuthAdapter(config) {
 					error: err
 				});
 			}
-			const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
+			const isAdmin = hasAdministrativeRole(roles);
 			return {
 				uid: payload.uid,
 				email: payload.email ?? "",
@@ -7460,7 +8855,7 @@ function createBuiltinAuthAdapter(config) {
 					error: err
 				});
 			}
-			const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
+			const isAdmin = hasAdministrativeRole(roles);
 			return {
 				uid: payload.uid,
 				email: payload.email ?? "",
@@ -7478,9 +8873,11 @@ function createBuiltinAuthAdapter(config) {
 				emailConfig,
 				allowRegistration,
 				disableSelfRegistration,
+				allowAnonymous,
 				allowUserLookup,
 				defaultRole,
 				oauthProviders,
+				allowedRedirectUris,
 				authHooks,
 				enableMagicLink,
 				cookieAuth
@@ -7552,6 +8949,10 @@ function createBuiltinAuthAdapter(config) {
 				allowRegistration,
 				needsSetup
 			});
+			const anonymousAllowed = isAnonymousAuthOpen({
+				allowAnonymous,
+				disableSelfRegistration
+			});
 			return {
 				hasBuiltInAuthRoutes: true,
 				emailPasswordLogin: true,
@@ -7563,6 +8964,7 @@ function createBuiltinAuthAdapter(config) {
 				profileUpdate: true,
 				emailVerification: !!emailService?.isConfigured(),
 				magicLink: enableMagicLink && !!emailService?.isConfigured(),
+				anonymousLogin: anonymousAllowed,
 				enabledProviders,
 				needsSetup
 			};
@@ -7647,6 +9049,54 @@ function toAuthUserData(user) {
 	};
 }
 //#endregion
+//#region src/auth/oauth-code-flow.ts
+/**
+* Build the request schema for an authorization-code provider.
+*
+* `pkce` defaults to `"optional"`: the client decides whether it sent a
+* `code_challenge`, and providers that do not implement PKCE simply never see
+* a verifier because their clients never generate one. `"required"` is for
+* providers that mandate PKCE (Twitter/X).
+*/
+function oauthCodeFlowSchema(opts = {}) {
+	const verifier = opts.pkce === "required" ? string().min(1, "PKCE code verifier is required") : string().min(1).optional();
+	return object({
+		code: string().min(1, "Auth code is required"),
+		redirectUri: string().url("Valid redirect URI is required"),
+		codeVerifier: verifier
+	});
+}
+/**
+* The `code_verifier` token-endpoint parameter, or nothing.
+*
+* Returned as a spreadable object so a provider adds PKCE with one `...` in
+* its existing body literal, rather than branching.
+*/
+function pkceTokenParams(codeVerifier) {
+	return codeVerifier ? { code_verifier: codeVerifier } : {};
+}
+/**
+* Normalise a provider's email-verification signal into the boolean that
+* `OAuthProviderProfile.emailVerified` promises.
+*
+* The whole point is the default: anything that is not an affirmative
+* verification signal — `undefined`, `null`, a missing field, an empty string,
+* `false` — becomes `false`. A provider that reports nothing therefore cannot
+* accidentally assert that it verified the address, which is exactly the
+* mistake five providers had made.
+*
+* Accepts the string forms because OIDC issuers are inconsistent about whether
+* `email_verified` is a JSON boolean or a string.
+*/
+function providerVerifiedEmail(signal) {
+	if (signal === true) return true;
+	if (typeof signal === "string") {
+		const normalized = signal.trim().toLowerCase();
+		return normalized === "true" || normalized === "1";
+	}
+	return false;
+}
+//#endregion
 //#region src/auth/google-oauth.ts
 var _googleAuth;
 async function loadGoogleAuth() {
@@ -7679,7 +9129,7 @@ async function verifyGoogleAccessToken(accessToken, expectedClientId) {
 	const tokenInfo = await tokenInfoRes.json();
 	if (tokenInfo.aud !== expectedClientId) throw new Error("Google access token audience mismatch: the token was not issued for this application");
 	if (!tokenInfo.sub || !tokenInfo.email) throw new Error("Google access token missing sub or email (the email scope is required)");
-	const emailVerified = tokenInfo.email_verified === true || tokenInfo.email_verified === "true";
+	const emailVerified = providerVerifiedEmail(tokenInfo.email_verified);
 	let displayName = null;
 	let photoUrl = null;
 	try {
@@ -7734,7 +9184,8 @@ function createGoogleProvider(config) {
 			idToken: string().min(1).optional(),
 			accessToken: string().min(1).optional(),
 			code: string().min(1).optional(),
-			redirectUri: string().min(1).optional()
+			redirectUri: string().min(1).optional(),
+			codeVerifier: string().min(1).optional()
 		}).refine((data) => data.idToken || data.accessToken || data.code && data.redirectUri, { message: "One of idToken, accessToken, or code+redirectUri is required" }),
 		verify: async (payload) => {
 			try {
@@ -7749,7 +9200,7 @@ function createGoogleProvider(config) {
 						email: content.email || "",
 						displayName: content.name || null,
 						photoUrl: content.picture || null,
-						emailVerified: content.email_verified === true
+						emailVerified: providerVerifiedEmail(content.email_verified)
 					};
 				}
 				if (payload.accessToken) return await verifyGoogleAccessToken(payload.accessToken, clientId);
@@ -7763,7 +9214,8 @@ function createGoogleProvider(config) {
 							client_id: clientId,
 							client_secret: clientSecret,
 							redirect_uri: payload.redirectUri,
-							grant_type: "authorization_code"
+							grant_type: "authorization_code",
+							...pkceTokenParams(payload.codeVerifier)
 						})
 					});
 					if (!tokenResponse.ok) {
@@ -7783,7 +9235,7 @@ function createGoogleProvider(config) {
 							email: content.email || "",
 							displayName: content.name || null,
 							photoUrl: content.picture || null,
-							emailVerified: content.email_verified === true
+							emailVerified: providerVerifiedEmail(content.email_verified)
 						};
 					}
 					if (tokenData.access_token) return await verifyGoogleAccessToken(tokenData.access_token, clientId);
@@ -7805,10 +9257,7 @@ function createGoogleProvider(config) {
 function createLinkedinProvider(config) {
 	return {
 		id: "linkedin",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch("https://www.linkedin.com/oauth/v2/accessToken", {
@@ -7819,7 +9268,8 @@ function createLinkedinProvider(config) {
 						code: payload.code,
 						redirect_uri: payload.redirectUri,
 						client_id: config.clientId,
-						client_secret: config.clientSecret
+						client_secret: config.clientSecret,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -7835,12 +9285,16 @@ function createLinkedinProvider(config) {
 					return null;
 				}
 				const profileData = await profileResponse.json();
+				if (!profileData.email) {
+					logger.error("LinkedIn user has no email (the 'email' scope may not have been granted)");
+					return null;
+				}
 				return {
 					providerId: profileData.sub,
 					email: profileData.email,
 					displayName: profileData.name || null,
 					photoUrl: profileData.picture || null,
-					emailVerified: profileData.email_verified === true
+					emailVerified: providerVerifiedEmail(profileData.email_verified)
 				};
 			} catch (error) {
 				logger.error("LinkedIn OAuth error", { error });
@@ -7861,10 +9315,7 @@ function createLinkedinProvider(config) {
 function createGitHubProvider(config) {
 	return {
 		id: "github",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch("https://github.com/login/oauth/access_token", {
@@ -7877,7 +9328,8 @@ function createGitHubProvider(config) {
 						client_id: config.clientId,
 						client_secret: config.clientSecret,
 						code: payload.code,
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -7901,19 +9353,22 @@ function createGitHubProvider(config) {
 				}
 				const profileData = await profileResponse.json();
 				let email = profileData.email;
-				if (!email) {
-					const emailsResponse = await fetch("https://api.github.com/user/emails", { headers: {
-						"Authorization": `Bearer ${accessToken}`,
-						"Accept": "application/vnd.github+json",
-						"User-Agent": "Rebase-Auth"
-					} });
-					if (emailsResponse.ok) {
-						const emails = await emailsResponse.json();
-						email = (emails.find((e) => e.primary && e.verified) || emails.find((e) => e.verified))?.email || null;
+				let emailVerified = false;
+				const emailsResponse = await fetch("https://api.github.com/user/emails", { headers: {
+					"Authorization": `Bearer ${accessToken}`,
+					"Accept": "application/vnd.github+json",
+					"User-Agent": "Rebase-Auth"
+				} });
+				if (emailsResponse.ok) {
+					const emails = await emailsResponse.json();
+					const chosen = emails.find((e) => e.primary && e.verified) || emails.find((e) => e.verified) || (email ? emails.find((e) => e.email.toLowerCase() === email.toLowerCase()) : void 0);
+					if (chosen) {
+						email = chosen.email;
+						emailVerified = providerVerifiedEmail(chosen.verified);
 					}
 				}
 				if (!email) {
-					logger.error("GitHub user has no verified email");
+					logger.error("GitHub user has no email");
 					return null;
 				}
 				return {
@@ -7921,7 +9376,7 @@ function createGitHubProvider(config) {
 					email,
 					displayName: profileData.name || profileData.login || null,
 					photoUrl: profileData.avatar_url || null,
-					emailVerified: true
+					emailVerified
 				};
 			} catch (error) {
 				logger.error("GitHub OAuth error", { error });
@@ -7931,21 +9386,109 @@ function createGitHubProvider(config) {
 	};
 }
 //#endregion
+//#region src/auth/oidc-id-token.ts
+var JWKS_TTL_MS = 600 * 1e3;
+var jwksCache = /* @__PURE__ */ new Map();
+async function loadJwks(jwksUri, fetchImpl, forceRefresh) {
+	const cached = jwksCache.get(jwksUri);
+	if (!forceRefresh && cached && Date.now() - cached.fetchedAt < JWKS_TTL_MS) return cached.keys;
+	const response = await fetchImpl(jwksUri);
+	if (!response.ok) throw new Error(`JWKS fetch failed (${response.status})`);
+	const body = await response.json();
+	const keys = Array.isArray(body.keys) ? body.keys : [];
+	jwksCache.set(jwksUri, {
+		keys,
+		fetchedAt: Date.now()
+	});
+	return keys;
+}
+function toKeyObject(jwk) {
+	return createPublicKey({
+		key: jwk,
+		format: "jwk"
+	});
+}
+function decodeKid(idToken) {
+	return import_jsonwebtoken.default.decode(idToken, { complete: true })?.header?.kid;
+}
+/**
+* Verify an id_token's signature, `aud`, `iss` and `exp`, and return its claims.
+*
+* Throws on any failure — callers treat a throw as "reject this sign-in",
+* never as "continue without the claims".
+*/
+async function verifyOidcIdToken(options) {
+	const { idToken, jwksUri, issuer, audience, algorithms = ["RS256"], clockToleranceSec = 60, nonce, fetchImpl = fetch } = options;
+	if (!idToken || typeof idToken !== "string") throw new Error("id_token missing");
+	const kid = decodeKid(idToken);
+	let keys = await loadJwks(jwksUri, fetchImpl, false);
+	let jwk = keys.find((k) => !kid || k.kid === kid);
+	if (!jwk) {
+		keys = await loadJwks(jwksUri, fetchImpl, true);
+		jwk = keys.find((k) => !kid || k.kid === kid);
+	}
+	if (!jwk) throw new Error(`No JWKS key matches kid "${kid ?? "<none>"}"`);
+	const claims = import_jsonwebtoken.default.verify(idToken, toKeyObject(jwk), {
+		algorithms,
+		audience,
+		clockTolerance: clockToleranceSec
+	});
+	if (!(typeof issuer === "string" ? claims.iss === issuer : issuer.test(String(claims.iss ?? "")))) throw new Error(`Unexpected id_token issuer "${claims.iss}"`);
+	if (nonce !== void 0 && claims.nonce !== nonce) throw new Error("id_token nonce mismatch");
+	return claims;
+}
+/**
+* `verifyOidcIdToken` that reports failure as `null` and logs it, for the one
+* call site that has to decide between "reject" and "degrade".
+*/
+async function tryVerifyOidcIdToken(providerId, options) {
+	try {
+		return await verifyOidcIdToken(options);
+	} catch (error) {
+		logger.error(`[${providerId}] id_token verification failed`, { error: error instanceof Error ? error.message : error });
+		return null;
+	}
+}
+//#endregion
 //#region src/auth/microsoft-oauth.ts
+/** Endpoints that federate to more than one directory. */
+var MULTI_TENANT_ENDPOINTS = /* @__PURE__ */ new Set([
+	"common",
+	"organizations",
+	"consumers"
+]);
 /**
 * Creates a Microsoft / Entra ID (Azure AD) OAuth Provider integration.
 *
 * Supports both personal Microsoft accounts and work/school (Azure AD) accounts
 * via the "common" tenant endpoint. Uses the authorization code flow.
+*
+* ## On `emailVerified`
+*
+* Microsoft Graph exposes no email-verification field, and `mail` is *not* a
+* substitute: it is a directory attribute a tenant administrator sets to any
+* string they like, through Graph or AAD Connect sync. With the default
+* `tenantId: "common"` every Entra tenant in the world is an accepted issuer,
+* so "there is a `mail` value" would mean "anybody who can create a free
+* tenant can nominate any address" — including one that already has an account
+* here.
+*
+* The only signal Microsoft offers is the `xms_edov` ("email domain owner
+* verified") optional claim on the id_token, so that is what this provider
+* reads, off a signature-verified token. If the app registration does not emit
+* `xms_edov`, sign-in still works and the address comes back unverified —
+* which routes the user to `POST /auth/link/microsoft` rather than silently
+* handing them somebody else's account.
 */
 function createMicrosoftProvider(config) {
 	const tenantId = config.tenantId || "common";
+	const multiTenant = MULTI_TENANT_ENDPOINTS.has(tenantId.toLowerCase());
+	const jwksUri = `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`;
+	const issuer = multiTenant ? /^https:\/\/login\.microsoftonline\.com\/[0-9a-fA-F-]{36}\/v2\.0$/ : `https://login.microsoftonline.com/${tenantId}/v2.0`;
+	if (multiTenant) logger.warn(`[Rebase] Microsoft provider configured with tenantId "${tenantId}", which accepts sign-ins from every Entra tenant. Email addresses are reported as unverified unless the app registration emits the xms_edov optional claim. Set an explicit tenantId, or enable xms_edov, to allow automatic linking onto existing accounts.`);
 	return {
 		id: "microsoft",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch(`https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`, {
@@ -7957,14 +9500,26 @@ function createMicrosoftProvider(config) {
 						code: payload.code,
 						redirect_uri: payload.redirectUri,
 						grant_type: "authorization_code",
-						scope: "openid profile email User.Read"
+						scope: "openid profile email User.Read",
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
 					logger.error("Failed to get Microsoft access token", { detail: await tokenResponse.text() });
 					return null;
 				}
-				const accessToken = (await tokenResponse.json()).access_token;
+				const tokenData = await tokenResponse.json();
+				const accessToken = tokenData.access_token;
+				let idTokenClaims = null;
+				if (tokenData.id_token) {
+					idTokenClaims = await tryVerifyOidcIdToken("microsoft", {
+						idToken: tokenData.id_token,
+						jwksUri,
+						issuer,
+						audience: config.clientId
+					});
+					if (!idTokenClaims) return null;
+				}
 				const profileResponse = await fetch("https://graph.microsoft.com/v1.0/me", { headers: { "Authorization": `Bearer ${accessToken}` } });
 				if (!profileResponse.ok) {
 					logger.error("Failed to get Microsoft user info", { detail: await profileResponse.text() });
@@ -7976,7 +9531,8 @@ function createMicrosoftProvider(config) {
 					logger.error("Microsoft user has no email");
 					return null;
 				}
-				const emailVerified = Boolean(profileData.mail);
+				const claimedEmail = idTokenClaims?.email ?? idTokenClaims?.preferred_username;
+				const emailVerified = providerVerifiedEmail(idTokenClaims?.xms_edov) && typeof claimedEmail === "string" && claimedEmail.toLowerCase() === email.toLowerCase();
 				return {
 					providerId: profileData.id,
 					email,
@@ -7993,6 +9549,8 @@ function createMicrosoftProvider(config) {
 }
 //#endregion
 //#region src/auth/apple-oauth.ts
+var APPLE_ISSUER = "https://appleid.apple.com";
+var APPLE_JWKS_URI = "https://appleid.apple.com/auth/keys";
 /**
 * Creates an Apple Sign In OAuth Provider integration.
 *
@@ -8022,18 +9580,19 @@ function createAppleProvider(config) {
 	}
 	return {
 		id: "apple",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required"),
-			/** Apple sends user info only on first authorization; the frontend must forward it. */
-			user: object({
-				name: object({
-					firstName: string().optional(),
-					lastName: string().optional()
-				}).optional(),
-				email: string().email().optional()
-			}).optional()
-		}),
+		schema: oauthCodeFlowSchema().extend({ 
+		/**
+		* Apple sends user info only on first authorization; the frontend
+		* must forward it. Only the *name* is accepted — an `email` here
+		* used to be promoted to the account's identity whenever the
+		* id_token had no `email` claim, and an attacker chooses whether
+		* that claim is absent simply by omitting the `email` scope from
+		* their own authorization request.
+		*/
+user: object({ name: object({
+			firstName: string().optional(),
+			lastName: string().optional()
+		}).optional() }).optional() }),
 		verify: async (payload) => {
 			try {
 				const clientSecret = await generateClientSecret();
@@ -8045,18 +9604,28 @@ function createAppleProvider(config) {
 						client_secret: clientSecret,
 						code: payload.code,
 						grant_type: "authorization_code",
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
 					logger.error("Failed to get Apple access token", { detail: await tokenResponse.text() });
 					return null;
 				}
-				const [, payloadB64] = (await tokenResponse.json()).id_token.split(".");
-				const decoded = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
-				const email = decoded.email || payload.user?.email;
+				const tokenData = await tokenResponse.json();
+				const decoded = tokenData.id_token ? await tryVerifyOidcIdToken("apple", {
+					idToken: tokenData.id_token,
+					jwksUri: APPLE_JWKS_URI,
+					issuer: APPLE_ISSUER,
+					audience: config.clientId
+				}) : null;
+				if (!decoded) {
+					logger.error("Apple token exchange returned no verifiable id_token");
+					return null;
+				}
+				const email = decoded.email;
 				if (!email) {
-					logger.error("Apple user has no email");
+					logger.error("Apple id_token carries no email claim");
 					return null;
 				}
 				let displayName = null;
@@ -8069,7 +9638,7 @@ function createAppleProvider(config) {
 					email,
 					displayName,
 					photoUrl: null,
-					emailVerified: decoded.email_verified === true || decoded.email_verified === "true"
+					emailVerified: providerVerifiedEmail(decoded.email_verified)
 				};
 			} catch (error) {
 				logger.error("Apple OAuth error", { error });
@@ -8089,18 +9658,20 @@ function createAppleProvider(config) {
 function createFacebookProvider(config) {
 	return {
 		id: "facebook",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
-				const tokenUrl = new URL("https://graph.facebook.com/v19.0/oauth/access_token");
-				tokenUrl.searchParams.set("client_id", config.clientId);
-				tokenUrl.searchParams.set("client_secret", config.clientSecret);
-				tokenUrl.searchParams.set("redirect_uri", payload.redirectUri);
-				tokenUrl.searchParams.set("code", payload.code);
-				const tokenResponse = await fetch(tokenUrl.toString());
+				const tokenResponse = await fetch("https://graph.facebook.com/v19.0/oauth/access_token", {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: new URLSearchParams({
+						client_id: config.clientId,
+						client_secret: config.clientSecret,
+						redirect_uri: payload.redirectUri,
+						code: payload.code,
+						...pkceTokenParams(payload.codeVerifier)
+					})
+				});
 				if (!tokenResponse.ok) {
 					logger.error("Failed to get Facebook access token", { detail: await tokenResponse.text() });
 					return null;
@@ -8108,8 +9679,7 @@ function createFacebookProvider(config) {
 				const accessToken = (await tokenResponse.json()).access_token;
 				const profileUrl = new URL("https://graph.facebook.com/v19.0/me");
 				profileUrl.searchParams.set("fields", "id,name,email,picture.type(large)");
-				profileUrl.searchParams.set("access_token", accessToken);
-				const profileResponse = await fetch(profileUrl.toString());
+				const profileResponse = await fetch(profileUrl.toString(), { headers: { "Authorization": `Bearer ${accessToken}` } });
 				if (!profileResponse.ok) {
 					logger.error("Failed to get Facebook user info", { detail: await profileResponse.text() });
 					return null;
@@ -8124,7 +9694,7 @@ function createFacebookProvider(config) {
 					email: profileData.email,
 					displayName: profileData.name || null,
 					photoUrl: profileData.picture?.data?.url || null,
-					emailVerified: true
+					emailVerified: false
 				};
 			} catch (error) {
 				logger.error("Facebook OAuth error", { error });
@@ -8147,11 +9717,7 @@ function createFacebookProvider(config) {
 function createTwitterProvider(config) {
 	return {
 		id: "twitter",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required"),
-			codeVerifier: string().min(1, "PKCE code verifier is required")
-		}),
+		schema: oauthCodeFlowSchema({ pkce: "required" }),
 		verify: async (payload) => {
 			try {
 				const basicAuth = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
@@ -8165,7 +9731,7 @@ function createTwitterProvider(config) {
 						code: payload.code,
 						grant_type: "authorization_code",
 						redirect_uri: payload.redirectUri,
-						code_verifier: payload.codeVerifier
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8211,16 +9777,14 @@ function createTwitterProvider(config) {
 /**
 * Creates a Discord OAuth2 Provider integration.
 *
-* Uses the authorization code flow. Requires the "identify" and "email"
-* scopes to retrieve the user's email and profile information.
+* Uses the authorization code flow (with PKCE when the client supplies a
+* verifier). Requires the "identify" and "email" scopes to retrieve the
+* user's email and profile information.
 */
 function createDiscordProvider(config) {
 	return {
 		id: "discord",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch("https://discord.com/api/v10/oauth2/token", {
@@ -8231,7 +9795,8 @@ function createDiscordProvider(config) {
 						client_secret: config.clientSecret,
 						grant_type: "authorization_code",
 						code: payload.code,
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8259,7 +9824,7 @@ function createDiscordProvider(config) {
 					email: profileData.email,
 					displayName: profileData.global_name || profileData.username || null,
 					photoUrl,
-					emailVerified: profileData.verified === true
+					emailVerified: providerVerifiedEmail(profileData.verified)
 				};
 			} catch (error) {
 				logger.error("Discord OAuth error", { error });
@@ -8273,15 +9838,16 @@ function createDiscordProvider(config) {
 /**
 * Creates a GitLab OAuth Provider integration.
 * Works with both GitLab.com and self-hosted instances.
+*
+* `baseUrl` is configuration only and must stay that way: a caller-supplied
+* instance URL would make this provider an SSRF primitive and an
+* arbitrary-identity oracle in one step.
 */
 function createGitLabProvider(config) {
 	const gitlabUrl = (config.baseUrl || "https://gitlab.com").replace(/\/$/, "");
 	return {
 		id: "gitlab",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch(`${gitlabUrl}/oauth/token`, {
@@ -8292,7 +9858,8 @@ function createGitLabProvider(config) {
 						client_secret: config.clientSecret,
 						code: payload.code,
 						grant_type: "authorization_code",
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8315,7 +9882,7 @@ function createGitLabProvider(config) {
 					email: p.email,
 					displayName: p.name || p.username || null,
 					photoUrl: p.avatar_url || null,
-					emailVerified: true
+					emailVerified: Boolean(p.confirmed_at)
 				};
 			} catch (error) {
 				logger.error("GitLab OAuth error", { error });
@@ -8332,10 +9899,7 @@ function createGitLabProvider(config) {
 function createBitbucketProvider(config) {
 	return {
 		id: "bitbucket",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const basicAuth = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
@@ -8348,7 +9912,8 @@ function createBitbucketProvider(config) {
 					body: new URLSearchParams({
 						grant_type: "authorization_code",
 						code: payload.code,
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8363,21 +9928,21 @@ function createBitbucketProvider(config) {
 				}
 				const p = await profileResponse.json();
 				const emailsResponse = await fetch("https://api.bitbucket.org/2.0/user/emails", { headers: { "Authorization": `Bearer ${accessToken}` } });
-				let email = null;
+				let selected;
 				if (emailsResponse.ok) {
 					const emailData = await emailsResponse.json();
-					email = (emailData.values.find((e) => e.is_primary && e.is_confirmed) || emailData.values.find((e) => e.is_confirmed))?.email || null;
+					selected = emailData.values.find((e) => e.is_primary && e.is_confirmed) || emailData.values.find((e) => e.is_confirmed);
 				}
-				if (!email) {
+				if (!selected?.email) {
 					logger.error("Bitbucket user has no verified email");
 					return null;
 				}
 				return {
 					providerId: p.uuid,
-					email,
+					email: selected.email,
 					displayName: p.display_name || p.username || null,
 					photoUrl: p.links?.avatar?.href || null,
-					emailVerified: true
+					emailVerified: providerVerifiedEmail(selected.is_confirmed)
 				};
 			} catch (error) {
 				logger.error("Bitbucket OAuth error", { error });
@@ -8395,10 +9960,7 @@ function createBitbucketProvider(config) {
 function createSlackProvider(config) {
 	return {
 		id: "slack",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const tokenResponse = await fetch("https://slack.com/api/openid.connect.token", {
@@ -8409,7 +9971,8 @@ function createSlackProvider(config) {
 						client_secret: config.clientSecret,
 						code: payload.code,
 						redirect_uri: payload.redirectUri,
-						grant_type: "authorization_code"
+						grant_type: "authorization_code",
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8436,7 +9999,7 @@ function createSlackProvider(config) {
 					email: p.email,
 					displayName: p.name || null,
 					photoUrl: p.picture || null,
-					emailVerified: p.email_verified === true
+					emailVerified: providerVerifiedEmail(p.email_verified)
 				};
 			} catch (error) {
 				logger.error("Slack OAuth error", { error });
@@ -8454,10 +10017,7 @@ function createSlackProvider(config) {
 function createSpotifyProvider(config) {
 	return {
 		id: "spotify",
-		schema: object({
-			code: string().min(1, "Auth code is required"),
-			redirectUri: string().url("Valid redirect URI is required")
-		}),
+		schema: oauthCodeFlowSchema(),
 		verify: async (payload) => {
 			try {
 				const basicAuth = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
@@ -8470,7 +10030,8 @@ function createSpotifyProvider(config) {
 					body: new URLSearchParams({
 						grant_type: "authorization_code",
 						code: payload.code,
-						redirect_uri: payload.redirectUri
+						redirect_uri: payload.redirectUri,
+						...pkceTokenParams(payload.codeVerifier)
 					})
 				});
 				if (!tokenResponse.ok) {
@@ -8493,7 +10054,7 @@ function createSpotifyProvider(config) {
 					email: p.email,
 					displayName: p.display_name || null,
 					photoUrl: p.images?.[0]?.url || null,
-					emailVerified: true
+					emailVerified: false
 				};
 			} catch (error) {
 				logger.error("Spotify OAuth error", { error });
@@ -8591,44 +10152,45 @@ function createApiKeyStore(driver) {
 		return;
 	}
 	const exec = (sqlText, options) => admin.executeSql(sqlText, options?.params ? { params: options.params } : void 0);
+	const ddl = createDdlBootstrapper(exec, "api-key-store");
 	return {
 		async ensureTable() {
-			try {
-				await exec("CREATE SCHEMA IF NOT EXISTS rebase");
-				await exec(`
-                    CREATE TABLE IF NOT EXISTS ${TABLE} (
-                        id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                        name TEXT NOT NULL,
-                        key_prefix TEXT NOT NULL,
-                        key_hash TEXT NOT NULL UNIQUE,
-                        permissions JSONB NOT NULL DEFAULT '[]'::jsonb,
-                        admin BOOLEAN NOT NULL DEFAULT FALSE,
-                        rate_limit INTEGER,
-                        created_by TEXT NOT NULL,
-                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-                        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-                        last_used_at TIMESTAMPTZ,
-                        expires_at TIMESTAMPTZ,
-                        revoked_at TIMESTAMPTZ
-                    )
-                `);
-				await exec(`
-                    CREATE INDEX IF NOT EXISTS idx_api_keys_hash
-                    ON ${TABLE}(key_hash)
-                `);
-				await exec(`
-                    CREATE INDEX IF NOT EXISTS idx_api_keys_prefix
-                    ON ${TABLE}(key_prefix)
-                `);
-				await exec(`
-                    ALTER TABLE ${TABLE}
-                    ADD COLUMN IF NOT EXISTS admin BOOLEAN NOT NULL DEFAULT FALSE
-                `);
-				logger.info("✅ API keys table ready");
-			} catch (err) {
-				logger.error("❌ Failed to create API keys table", { error: err });
-				logger.warn("⚠️ Continuing without API keys support.");
+			await ddl.ensureObject("Creating schema rebase", "CREATE SCHEMA IF NOT EXISTS rebase");
+			await ddl.ensureObject(`Creating ${TABLE}`, `
+                CREATE TABLE IF NOT EXISTS ${TABLE} (
+                    id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+                    name TEXT NOT NULL,
+                    key_prefix TEXT NOT NULL,
+                    key_hash TEXT NOT NULL UNIQUE,
+                    permissions JSONB NOT NULL DEFAULT '[]'::jsonb,
+                    admin BOOLEAN NOT NULL DEFAULT FALSE,
+                    rate_limit INTEGER,
+                    created_by TEXT NOT NULL,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    last_used_at TIMESTAMPTZ,
+                    expires_at TIMESTAMPTZ,
+                    revoked_at TIMESTAMPTZ
+                )
+            `);
+			await ddl.ensureObject("Creating idx_api_keys_hash", `
+                CREATE INDEX IF NOT EXISTS idx_api_keys_hash
+                ON ${TABLE}(key_hash)
+            `);
+			await ddl.ensureObject("Creating idx_api_keys_prefix", `
+                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
+            `);
+			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")));
+			logger.debug("✅ API keys table ready");
 		},
 		async createApiKey(request, createdBy) {
 			const plaintext = generateApiKey();
@@ -8923,6 +10485,7 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	createSlackProvider: () => createSlackProvider,
 	createSpotifyProvider: () => createSpotifyProvider,
 	createTwitterProvider: () => createTwitterProvider,
+	decideOAuthAutoLink: () => decideOAuthAutoLink,
 	defaultAuthLimiter: () => defaultAuthLimiter,
 	extractUserFromToken: () => extractUserFromToken,
 	fileTokenAuth: () => fileTokenAuth,
@@ -8939,23 +10502,30 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	hashToken: () => hashToken,
 	httpMethodToOperation: () => httpMethodToOperation,
 	isApiKeyToken: () => isApiKeyToken,
+	isJwtConfigured: () => isJwtConfigured,
 	isOperationAllowed: () => isOperationAllowed,
+	isRedirectUriAllowed: () => isRedirectUriAllowed,
 	mountMagicLinkRoutes: () => mountMagicLinkRoutes,
+	oauthCodeFlowSchema: () => oauthCodeFlowSchema,
 	optionalAuth: () => optionalAuth,
+	pkceTokenParams: () => pkceTokenParams,
 	prepareAdminUserValues: () => prepareAdminUserValues,
+	providerVerifiedEmail: () => providerVerifiedEmail,
 	queryTokenAuth: () => queryTokenAuth,
 	requireAdmin: () => requireAdmin,
 	requireAuth: () => requireAuth,
 	resolveAuthHooks: () => resolveAuthHooks,
 	safeCompare: () => safeCompare,
 	strictAuthLimiter: () => strictAuthLimiter,
+	tryVerifyOidcIdToken: () => tryVerifyOidcIdToken,
 	validateApiKey: () => validateApiKey,
 	validatePasswordStrength: () => validatePasswordStrength,
 	verifyAccessToken: () => verifyAccessToken,
 	verifyDownloadToken: () => verifyDownloadToken,
+	verifyOidcIdToken: () => verifyOidcIdToken,
 	verifyPassword: () => verifyPassword
 });
 //#endregion
-export { httpMethodToOperation as $, getEmailVerificationTemplate as A, optionalAuth as B, createDataRateLimiter as C, validatePasswordStrength as D, hashPassword as E, createAdapterAuthMiddleware as F, createApiKeyPreAuth as G, queryTokenAuth as H, createAuthMiddleware as I, isApiKeyToken as J, createFunctionApiKeyGuard as K, createRequireAuth as L, getPasswordResetTemplate as M, getUserInvitationTemplate as N, verifyPassword as O, getWelcomeEmailTemplate as P, scopeDataDriver as Q, extractUserFromToken as R, _coercedNumber as S, resolveAuthHooks as T, requireAdmin as U, publicObjectAuth as V, requireAuth as W, extractBearerToken as X, validateApiKey as Y, safeCompare as Z, createBuiltinAuthAdapter as _, createSpotifyProvider as a, object as b, createGitLabProvider as c, createFacebookProvider as d, isOperationAllowed as et, createAppleProvider as f, createGoogleProvider as g, createLinkedinProvider as h, createApiKeyStore as i, resolveClientListLimit as it, getMagicLinkTemplate as j, generateSecurePassword as k, createDiscordProvider as l, createGitHubProvider as m, createCustomAuthAdapter as n, isPublicStoragePath as nt, createSlackProvider as o, createMicrosoftProvider as p, createStorageApiKeyGuard as q, createApiKeyRoutes as r, MAX_LIST_LIMIT as rt, createBitbucketProvider as s, auth_exports as t, PUBLIC_STORAGE_PREFIX as tt, createTwitterProvider as u, ZodNumber as v, MemoryRateLimitStore as w, string as x, _enum as y, fileTokenAuth as z };
+export { fileTokenAuth as $, MemoryRateLimitStore as A, getEmailVerificationTemplate as B, ZodNumber as C, isPublicStoragePath as Ct, _coercedNumber as D, string as E, resolveAuthHooks as F, RawHtml as G, getPasswordResetTemplate as H, hashPassword as I, raw as J, escapeHtml as K, validatePasswordStrength as L, createEmailService as M, assertEmailLinkBases as N, DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT as O, resolveEmailLinkBase as P, extractUserFromToken as Q, verifyPassword as R, createBuiltinAuthAdapter as S, PUBLIC_STORAGE_PREFIX as St, object as T, getUserInvitationTemplate as U, getMagicLinkTemplate as V, getWelcomeEmailTemplate as W, createAuthMiddleware as X, createAdapterAuthMiddleware as Y, createRequireAuth as Z, createLinkedinProvider as _, scopeDataDriver as _t, createSpotifyProvider as a, InvalidStorageBucketError as at, pkceTokenParams as b, parseQueryOptions as bt, createGitLabProvider as c, canonicalStorageKey as ct, createFacebookProvider as d, createStorageApiKeyGuard as dt, optionalAuth as et, createAppleProvider as f, isApiKeyToken as ft, createGitHubProvider as g, SERVICE_IDENTITY as gt, verifyOidcIdToken as h, safeCompare as ht, createApiKeyStore as i, requireAuth as it, SMTPEmailService as j, createDataRateLimiter as k, createDiscordProvider as l, createApiKeyPreAuth as lt, tryVerifyOidcIdToken as m, extractBearerToken as mt, createCustomAuthAdapter as n, queryTokenAuth as nt, createSlackProvider as o, InvalidStorageKeyError as ot, createMicrosoftProvider as p, validateApiKey as pt, html as q, createApiKeyRoutes as r, requireAdmin as rt, createBitbucketProvider as s, canonicalStorageBucket as st, auth_exports as t, publicObjectAuth as tt, createTwitterProvider as u, createFunctionApiKeyGuard as ut, createGoogleProvider as v, httpMethodToOperation as vt, _enum as w, providerVerifiedEmail as x, resolveListLimitParam as xt, oauthCodeFlowSchema as y, isOperationAllowed as yt, generateSecurePassword as z };
 
-//# sourceMappingURL=auth-CuC9M2x6.js.map
+//# sourceMappingURL=auth-CYoPVf-E.js.map