@rebasepro/server 0.9.1-canary.ff338b5 → 0.10.0

package/dist/index.es.js

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
-import { a as getAccessTokenExpiry, d as require_jsonwebtoken, f as __commonJSMin, h as __toESM, i as generateRefreshToken, l as verifyAccessToken, m as __require, n as generateAccessToken, o as getRefreshTokenExpiry, p as __exportAll, r as generateDownloadToken, s as hashRefreshToken, t as configureJwt, u as verifyDownloadToken } from "./jwt-BJzQOa8a.js";
+import { a as getAccessTokenExpiry, d as require_jsonwebtoken, f as __commonJSMin, h as __toESM, i as generateRefreshToken, l as verifyAccessToken, m as __require, n as generateAccessToken, o as getRefreshTokenExpiry, p as __exportAll, r as generateDownloadToken, s as hashRefreshToken, t as configureJwt, u as verifyDownloadToken } from "./jwt-B3zjddCa.js";
 import { _ as RebaseApiError, a as policy, c as isPostgresCollectionConfig, d as REST_TO_CANONICAL, f as toCanonicalOp, g as Vector, h as GeoPoint, i as isSQLAdmin, l as CANONICAL_TO_REST, m as EntityRelation, o as getCollectionDataPath, p as EntityReference, r as getDataSourceCapabilities, s as getDeclaredSubcollections, t as DEFAULT_STORAGE_SOURCE_KEY, u as NULL_OPS, v as RebaseClientError } from "./src-CsHhSKbi.js";
 import { t as logger } from "./logger-BYU66ENZ.js";
 import { t as nativeDynamicImport } from "./dynamic-import-Dvh-K5fl.js";
@@ -3539,12 +3539,23 @@ var ApiError = class ApiError extends Error {
 	statusCode;
 	code;
 	details;
-	constructor(statusCode, code, message, details) {
+	/**
+	* Whether this outcome is a routine part of normal operation rather than
+	* something an operator should look at. Expected errors log at debug; every
+	* other operational error logs at warn.
+	*
+	* The motivating case is `POST /auth/refresh` with no session: clients
+	* refresh on page load before they know whether one exists, so every
+	* anonymous page view is a 401 — correct, and not worth a warning line.
+	*/
+	expected;
+	constructor(statusCode, code, message, details, expected = false) {
 		super(message);
 		this.name = "ApiError";
 		this.statusCode = statusCode;
 		this.code = code;
 		this.details = details;
+		this.expected = expected;
 	}
 	static badRequest(message, code = "BAD_REQUEST", details) {
 		return new ApiError(400, code, message, details);
@@ -3552,6 +3563,13 @@ var ApiError = class ApiError extends Error {
 	static unauthorized(message, code = "UNAUTHORIZED") {
 		return new ApiError(401, code, message);
 	}
+	/**
+	* A 401 that is a normal outcome, not an incident — logged at debug.
+	* See {@link ApiError.expected}.
+	*/
+	static unauthenticated(message, code = "UNAUTHORIZED") {
+		return new ApiError(401, code, message, void 0, true);
+	}
 	static forbidden(message, code = "FORBIDDEN") {
 		return new ApiError(403, code, message);
 	}
@@ -3584,7 +3602,10 @@ var errorHandler = (err, c) => {
 	const error = err;
 	const reqId = typeof c.get === "function" ? c.get("requestId") : void 0;
 	if (error instanceof ApiError || error.name === "ApiError") {
-		logger.warn(`⚠️ [API] ${c.req.method} ${c.req.path} → ${error.statusCode} ${error.code}: ${error.message}` + (reqId ? ` [${reqId}]` : ""));
+		const expected = error instanceof ApiError && error.expected;
+		const line = `[API] ${c.req.method} ${c.req.path} → ${error.statusCode} ${error.code}: ${error.message}` + (reqId ? ` [${reqId}]` : "");
+		if (expected) logger.debug(line);
+		else logger.warn(`⚠️ ${line}`);
 		return c.json({ error: {
 			message: error.message,
 			code: error.code || "INTERNAL_ERROR",
@@ -3826,6 +3847,8 @@ function parseQueryOptions(query) {
 *   columns, so the set is exact);
 * - the foreign-key column behind an owning relation, which callers may write
 *   directly instead of through the relation property;
+* - anything named in `options.extraKnownFields` — for an auth collection the
+*   credential keys the auth adapter consumes before a row is ever built;
 * - nothing else. `id` in particular is not automatically known — see below.
 */
 function assertKnownWriteFields(values, collection, options) {
@@ -3833,6 +3856,7 @@ function assertKnownWriteFields(values, collection, options) {
 	if (!collection.properties || Object.keys(collection.properties).length === 0) return;
 	const known = new Set(Object.keys(collection.properties));
 	for (const relation of Object.values(resolveCollectionRelations(collection))) if (relation.localKey) known.add(relation.localKey);
+	for (const field of options?.extraKnownFields ?? []) known.add(field);
 	const unknown = Object.keys(values).filter((key) => !known.has(key));
 	if (unknown.length === 0) return;
 	const where = options?.rowIndex !== void 0 ? `Row ${options.rowIndex}: ` : "";
@@ -4081,9 +4105,13 @@ var RestApiGenerator = class {
 				const body = await parseJsonBody(c);
 				const isAuth = collection.auth;
 				const isAuthCollection = isAuth === true || isAuth && typeof isAuth === "object" && isAuth.enabled === true;
+				const collectionAuthConfig = typeof isAuth === "object" ? isAuth : void 0;
 				if (!isAuthCollection) assertKnownWriteFields(body, resolvedCollection);
+				else {
+					const contract = this.authAdapter?.describeUserCreationContract?.(collectionAuthConfig);
+					if (contract?.validate) assertKnownWriteFields(body, resolvedCollection, { extraKnownFields: contract.extraFields });
+				}
 				if (isAuthCollection && this.authAdapter?.prepareUserCreation) {
-					const collectionAuthConfig = typeof isAuth === "object" ? isAuth : void 0;
 					const prepared = await this.authAdapter.prepareUserCreation(body, collectionAuthConfig);
 					const entity = await driver.save({
 						path,
@@ -4472,10 +4500,10 @@ async function validateApiKey(c, token, options) {
 		message: "API key has expired",
 		code: "UNAUTHORIZED"
 	} }, 401);
-	const userId = `api-key:${apiKey.id}`;
+	const uid = `api-key:${apiKey.id}`;
 	const roles = apiKey.admin ? ["admin", "service"] : ["service"];
 	c.set("user", {
-		userId,
+		uid,
 		roles
 	});
 	const masked = {
@@ -4495,7 +4523,7 @@ async function validateApiKey(c, token, options) {
 	c.set("apiKey", masked);
 	try {
 		const scopedDriver = await scopeDataDriver(driver, {
-			uid: userId,
+			uid,
 			roles
 		});
 		c.set("driver", scopedDriver);
@@ -4663,7 +4691,7 @@ function createRequireAuth(options) {
 		const token = authHeader.substring(7);
 		if (safeCompare(token, key)) {
 			c.set("user", {
-				userId: "service",
+				uid: "service",
 				roles: ["admin"]
 			});
 			return next();
@@ -4742,11 +4770,11 @@ function createAuthMiddleware(options) {
 		if (validator) try {
 			const authResult = await validator(c);
 			if (authResult && typeof authResult === "object") {
-				const id = ("userId" in authResult ? authResult.userId : void 0) || ("uid" in authResult ? authResult.uid : void 0);
+				const id = ("uid" in authResult ? authResult.uid : void 0) || ("uid" in authResult ? authResult.uid : void 0);
 				if (id) {
 					const roles = authResult.roles || [];
 					c.set("user", {
-						userId: id,
+						uid: id,
 						roles
 					});
 					const user = {
@@ -4761,7 +4789,7 @@ function createAuthMiddleware(options) {
 				}));
 			} else if (authResult === true) {
 				c.set("user", {
-					userId: "default",
+					uid: "default",
 					roles: []
 				});
 				c.set("driver", await scopeDataDriver(driver, {
@@ -4784,7 +4812,7 @@ function createAuthMiddleware(options) {
 				const token = authHeader.substring(7);
 				if (serviceKey && safeCompare(token, serviceKey)) {
 					c.set("user", {
-						userId: "service",
+						uid: "service",
 						roles: ["admin"]
 					});
 					try {
@@ -4811,7 +4839,7 @@ function createAuthMiddleware(options) {
 						c.set("user", payload);
 						try {
 							const user = {
-								uid: payload.userId,
+								uid: payload.uid,
 								roles: payload.roles
 							};
 							c.set("driver", await scopeDataDriver(driver, user));
@@ -4892,7 +4920,7 @@ var publicObjectAuth = async (c, next) => {
 	const idx = fullPath.indexOf(prefix);
 	const rawPath = idx < 0 ? "" : fullPath.substring(idx + prefix.length + 1);
 	if (rawPath && isPublicStoragePath(decodeURIComponent(rawPath))) c.set("user", {
-		userId: "public",
+		uid: "public",
 		roles: ["public"]
 	});
 	return next();
@@ -4958,7 +4986,7 @@ var fileTokenAuth = async (c, next) => {
 				const { bucket, resolvedPath } = parseBucketPath(decodeURIComponent(rawPath));
 				if (isPathMatch(`${bucket}/${resolvedPath}`, payload.path)) {
 					c.set("user", {
-						userId: "download-token",
+						uid: "download-token",
 						roles: ["reader"]
 					});
 					return next();
@@ -4982,7 +5010,7 @@ var fileTokenAuth = async (c, next) => {
 				const { bucket, resolvedPath } = parseBucketPath(decodeURIComponent(rawPath));
 				if (isPathMatch(`${bucket}/${resolvedPath}`, payload.path)) {
 					c.set("user", {
-						userId: "download-token",
+						uid: "download-token",
 						roles: ["reader"]
 					});
 					return next();
@@ -5031,7 +5059,7 @@ function createAdapterAuthMiddleware(options) {
 		}
 		if (authenticatedUser) {
 			c.set("user", {
-				userId: authenticatedUser.uid,
+				uid: authenticatedUser.uid,
 				email: authenticatedUser.email,
 				roles: authenticatedUser.roles
 			});
@@ -5914,14 +5942,14 @@ function createDataRateLimiter(config = {}) {
 			const key = c.get("apiKey");
 			if (key) return `api-key:${key.id}`;
 			const user = c.get("user");
-			if (user?.userId && user.userId !== "anon") return `user:${user.userId}`;
+			if (user?.uid && user.uid !== "anon") return `user:${user.uid}`;
 			return `ip:${defaultKeyGenerator(c)}`;
 		},
 		resolveLimit: (c) => {
 			const key = c.get("apiKey");
 			if (key) return key.rate_limit ?? apiKeyLimit;
 			const user = c.get("user");
-			if (user?.userId && user.userId !== "anon") return userLimit;
+			if (user?.uid && user.uid !== "anon") return userLimit;
 			return anonLimit;
 		}
 	});
@@ -9773,7 +9801,7 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 		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";
-		const user = await authRepo.getUserById(userCtx.userId);
+		const user = await authRepo.getUserById(userCtx.uid);
 		if (!user) throw ApiError.notFound("User not found");
 		const { secret, uri } = generateTotpSecret(issuer, user.email);
 		const encryptedSecret = encryptTotpSecret(secret);
@@ -9807,7 +9835,7 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 			code: string().length(6, "Code must be 6 digits")
 		}), await c.req.json());
 		const factor = await authRepo.getMfaFactorById(factorId);
-		if (!factor || factor.userId !== userCtx.userId) throw ApiError.notFound("MFA factor not found");
+		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");
 		await authRepo.verifyMfaFactor(factorId);
@@ -9825,7 +9853,7 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const { factorId } = parseBody(object({ factorId: string().min(1, "Factor ID is required") }), await c.req.json());
 		const factor = await authRepo.getMfaFactorById(factorId);
-		if (!factor || factor.userId !== userCtx.userId) throw ApiError.notFound("MFA factor not found");
+		if (!factor || factor.uid !== userCtx.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);
@@ -9849,19 +9877,19 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 		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.userId !== userCtx.userId) throw ApiError.notFound("MFA factor not found");
+		if (!factor || factor.uid !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
 		let isValid = verifyTotp(base32Decode(decryptTotpSecret(factor.secretEncrypted)), code);
 		if (!isValid) {
 			const codeHash = hashRecoveryCode(code);
-			isValid = await authRepo.useRecoveryCode(userCtx.userId, codeHash);
+			isValid = await authRepo.useRecoveryCode(userCtx.uid, codeHash);
 		}
 		if (!isValid) throw ApiError.unauthorized("Invalid verification code", "INVALID_CODE");
 		await authRepo.verifyMfaChallenge(challengeId);
-		const roleIds = (await authRepo.getUserRoles(userCtx.userId)).map((r) => r.id);
-		const accessToken = generateAccessToken(userCtx.userId, roleIds, "aal2");
+		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.userId, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
-		if (ops.onMfaVerified) ops.onMfaVerified(userCtx.userId, factor.id).catch((err) => {
+		await authRepo.createRefreshToken(userCtx.uid, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+		if (ops.onMfaVerified) ops.onMfaVerified(userCtx.uid, factor.id).catch((err) => {
 			logger.error("[AuthHooks] onMfaVerified error", { error: err instanceof Error ? err.message : err });
 		});
 		let mfaResponse = { tokens: {
@@ -9869,7 +9897,7 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 			refreshToken,
 			accessTokenExpiresAt: getAccessTokenExpiry()
 		} };
-		if (applyTransformHook) mfaResponse = await applyTransformHook(mfaResponse, "mfa", c.req.raw, userCtx.userId);
+		if (applyTransformHook) mfaResponse = await applyTransformHook(mfaResponse, "mfa", c.req.raw, userCtx.uid);
 		return c.json(mfaResponse);
 	});
 	/**
@@ -9879,7 +9907,7 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 	router.get("/mfa/factors", requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const factors = await authRepo.getMfaFactors(userCtx.userId);
+		const factors = await authRepo.getMfaFactors(userCtx.uid);
 		return c.json({ factors: factors.map((f) => ({
 			id: f.id,
 			factorType: f.factorType,
@@ -9898,9 +9926,9 @@ function mountMfaRoutes(router, config, ops, parseBody, applyTransformHook) {
 		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 factor = await authRepo.getMfaFactorById(factorId);
-		if (!factor || factor.userId !== userCtx.userId) throw ApiError.notFound("MFA factor not found");
-		await authRepo.deleteMfaFactor(factorId, userCtx.userId);
-		if (!await authRepo.hasVerifiedMfaFactors(userCtx.userId)) await authRepo.deleteAllRecoveryCodes(userCtx.userId);
+		if (!factor || factor.uid !== userCtx.uid) throw ApiError.notFound("MFA factor not found");
+		await authRepo.deleteMfaFactor(factorId, userCtx.uid);
+		if (!await authRepo.hasVerifiedMfaFactors(userCtx.uid)) await authRepo.deleteAllRecoveryCodes(userCtx.uid);
 		return c.json({
 			success: true,
 			message: "MFA factor removed"
@@ -10002,9 +10030,9 @@ function mountSessionRoutes(opts) {
 		clearRefreshCookie(c, config.cookieAuth);
 		const authHeader = c.req.header("authorization");
 		if (ops.afterLogout && authHeader?.startsWith("Bearer ")) {
-			const { verifyAccessToken } = await import("./jwt-BJzQOa8a.js").then((n) => n.c);
+			const { verifyAccessToken } = await import("./jwt-B3zjddCa.js").then((n) => n.c);
 			const payload = verifyAccessToken(authHeader.substring(7));
-			if (payload) ops.afterLogout(payload.userId).catch((err) => {
+			if (payload) ops.afterLogout(payload.uid).catch((err) => {
 				logger.error("[AuthHooks] afterLogout error", { error: err instanceof Error ? err.message : err });
 			});
 		}
@@ -10019,7 +10047,7 @@ function mountSessionRoutes(opts) {
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const currentRefreshToken = c.req.header("x-refresh-token");
 		const currentTokenHash = currentRefreshToken ? hashRefreshToken(currentRefreshToken) : null;
-		const mappedSessions = (await authRepo.listRefreshTokensForUser(userCtx.userId)).map((s) => ({
+		const mappedSessions = (await authRepo.listRefreshTokensForUser(userCtx.uid)).map((s) => ({
 			id: s.id,
 			userAgent: s.userAgent,
 			ipAddress: s.ipAddress,
@@ -10035,7 +10063,7 @@ function mountSessionRoutes(opts) {
 	router.delete("/sessions", requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		await authRepo.deleteAllRefreshTokensForUser(userCtx.userId);
+		await authRepo.deleteAllRefreshTokensForUser(userCtx.uid);
 		return c.json({
 			success: true,
 			message: "All sessions revoked successfully"
@@ -10050,7 +10078,7 @@ function mountSessionRoutes(opts) {
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const id = c.req.param("id");
 		if (!id) throw ApiError.badRequest("Session ID is required", "INVALID_INPUT");
-		await authRepo.deleteRefreshTokenById(id, userCtx.userId);
+		await authRepo.deleteRefreshTokenById(id, userCtx.uid);
 		return c.json({
 			success: true,
 			message: "Session revoked successfully"
@@ -10063,7 +10091,7 @@ function mountSessionRoutes(opts) {
 	router.get("/me", requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const result = await authRepo.getUserWithRoles(userCtx.userId);
+		const result = await authRepo.getUserWithRoles(userCtx.uid);
 		if (!result) throw ApiError.notFound("User not found");
 		return c.json({ user: {
 			uid: result.user.id,
@@ -10103,11 +10131,11 @@ function mountSessionRoutes(opts) {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const { displayName, photoURL } = parseBody(updateProfileSchema, await c.req.json());
-		if (!await authRepo.updateUser(userCtx.userId, {
+		if (!await authRepo.updateUser(userCtx.uid, {
 			displayName: displayName !== void 0 ? displayName : void 0,
 			photoUrl: photoURL !== void 0 ? photoURL : void 0
 		})) throw ApiError.notFound("User not found");
-		const result = await authRepo.getUserWithRoles(userCtx.userId);
+		const result = await authRepo.getUserWithRoles(userCtx.uid);
 		if (!result) throw ApiError.notFound("User not found");
 		return c.json({ user: {
 			uid: result.user.id,
@@ -10169,7 +10197,7 @@ function mountSessionRoutes(opts) {
 	router.post("/anonymous/link", requireAuth, async (c) => {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
-		const user = await authRepo.getUserById(userCtx.userId);
+		const user = await authRepo.getUserById(userCtx.uid);
 		if (!user?.isAnonymous) throw ApiError.badRequest("User is not anonymous", "NOT_ANONYMOUS");
 		const { email, password } = parseBody(linkSchema, await c.req.json());
 		const passwordValidation = ops.validatePasswordStrength(password);
@@ -10258,7 +10286,7 @@ function mountMagicLinkRoutes(deps) {
 		const storedToken = await authRepo.findValidMagicLinkToken(tokenHash);
 		if (!storedToken) throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
 		await authRepo.markMagicLinkTokenUsed(tokenHash);
-		const user = await authRepo.getUserById(storedToken.userId);
+		const user = await authRepo.getUserById(storedToken.uid);
 		if (!user) throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
 		if (!user.emailVerified) {
 			await authRepo.setEmailVerified(user.id, true);
@@ -10316,11 +10344,11 @@ function createAuthRoutes(config) {
 	* Errors are caught and logged — the untransformed response is returned
 	* as a graceful fallback so auth never breaks due to a hook failure.
 	*/
-	async function applyTransformHook(response, method, request, userId) {
+	async function applyTransformHook(response, method, request, uid) {
 		if (!ops.transformAuthResponse) return response;
 		try {
 			return await ops.transformAuthResponse(response, {
-				userId,
+				uid,
 				method,
 				request
 			});
@@ -10347,7 +10375,7 @@ function createAuthRoutes(config) {
 		oldPassword: string().min(1, "Old password is required").max(128),
 		newPassword: string().min(1, "New password is required").max(128)
 	});
-	const refreshSchema = object({ refreshToken: config.cookieAuth ? string().optional() : string().min(1, "Refresh token is required") });
+	const refreshSchema = object({ refreshToken: string().min(1).optional() });
 	object({ refreshToken: string().optional() });
 	object({
 		displayName: string().max(255).optional(),
@@ -10398,23 +10426,23 @@ function createAuthRoutes(config) {
 	/**
 	* Helper to generate and store session tokens
 	*/
-	async function createSessionAndTokens(userId, userAgent, ipAddress) {
-		const roleIds = (await authRepo.getUserRoles(userId)).map((r) => r.id);
+	async function createSessionAndTokens(uid, userAgent, ipAddress) {
+		const roleIds = (await authRepo.getUserRoles(uid)).map((r) => r.id);
 		let customClaims;
 		if (ops.customizeAccessToken) {
-			const user = await authRepo.getUserById(userId);
+			const user = await authRepo.getUserById(uid);
 			if (user) {
 				const defaultClaims = {
-					userId,
+					uid,
 					roles: roleIds,
 					aal: "aal1"
 				};
 				customClaims = await ops.customizeAccessToken(defaultClaims, user);
 			}
 		}
-		const accessToken = generateAccessToken(userId, roleIds, "aal1", customClaims);
+		const accessToken = generateAccessToken(uid, roleIds, "aal1", customClaims);
 		const refreshToken = generateRefreshToken();
-		await authRepo.createRefreshToken(userId, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), userAgent, ipAddress);
+		await authRepo.createRefreshToken(uid, hashRefreshToken(refreshToken), getRefreshTokenExpiry(), userAgent, ipAddress);
 		return {
 			roleIds,
 			accessToken,
@@ -10478,7 +10506,7 @@ function createAuthRoutes(config) {
 				logger.warn("[Security Audit] Auth login failure", {
 					eventType: "auth.login.failure",
 					email,
-					userId: user.id
+					uid: user.id
 				});
 				throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
 			}
@@ -10489,7 +10517,7 @@ function createAuthRoutes(config) {
 		});
 		logger.info("[Security Audit] Auth login success", {
 			eventType: "auth.login.success",
-			userId: user.id,
+			uid: user.id,
 			email
 		});
 		const finalResponse = redactRefreshToken(await applyTransformHook(buildAuthResponse(user, roleIds, accessToken, refreshToken, "password"), "login", c.req.raw, user.id), c, refreshToken, config.cookieAuth);
@@ -10498,54 +10526,101 @@ function createAuthRoutes(config) {
 	/**
 	* Dynamically mount OAuth provider routes
 	*/
-	if (config.oauthProviders && config.oauthProviders.length > 0) for (const provider of config.oauthProviders) router.post(`/${provider.id}`, defaultAuthLimiter, async (c) => {
-		const payload = parseBody(provider.schema, await c.req.json());
-		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");
-		}
-		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("Cannot auto-link account: email not verified by the OAuth provider. Please log in with your password first and link the provider from your profile.", "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 {
-				user = await authRepo.createUser({
-					email: externalUser.email.toLowerCase(),
-					displayName: externalUser.displayName || void 0,
-					photoUrl: externalUser.photoUrl || void 0
-				});
-				await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, { email: externalUser.email });
-				if (ops.afterUserCreate) try {
-					await ops.afterUserCreate(user);
-				} catch (err) {
-					logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
+	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());
+			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");
+			}
+			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");
+					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 {
+					user = await authRepo.createUser({
+						email: externalUser.email.toLowerCase(),
+						displayName: externalUser.displayName || void 0,
+						photoUrl: externalUser.photoUrl || void 0
+					});
+					await authRepo.linkUserIdentity(user.id, provider.id, externalUser.providerId, { email: externalUser.email });
+					if (ops.afterUserCreate) try {
+						await ops.afterUserCreate(user);
+					} catch (err) {
+						logger.error("[AuthHooks] afterUserCreate error", { error: err instanceof Error ? err.message : err });
+					}
+					const allUsers = await authRepo.listUsers();
+					if (allUsers.length === 1 && allUsers[0].id === user.id) await authRepo.setUserRoles(user.id, ["admin"]);
+					else if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
+					sendWelcomeEmail({
+						email: user.email,
+						displayName: user.displayName
+					});
 				}
-				const allUsers = await authRepo.listUsers();
-				if (allUsers.length === 1 && allUsers[0].id === user.id) await authRepo.setUserRoles(user.id, ["admin"]);
-				else if (config.defaultRole) await authRepo.assignDefaultRole(user.id, config.defaultRole);
-				sendWelcomeEmail({
-					email: user.email,
-					displayName: user.displayName
-				});
+			} else await authRepo.updateUser(user.id, {
+				displayName: externalUser.displayName || user.displayName || void 0,
+				photoUrl: externalUser.photoUrl || user.photoUrl || void 0
+			});
+			const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
+			const finalResponse = redactRefreshToken(await applyTransformHook(buildAuthResponse(user, roleIds, accessToken, refreshToken, provider.id), "oauth", c.req.raw, user.id), c, refreshToken, config.cookieAuth);
+			return c.json(finalResponse);
+		});
+		/**
+		* POST /auth/link/:provider
+		* Attach an OAuth identity to the *already authenticated* account.
+		*
+		* This is the escape hatch from the `EMAIL_NOT_VERIFIED` rejection
+		* on the sign-in route above, and the way to attach a provider
+		* whose email differs from the account's.
+		*
+		* Note the deliberate asymmetry with sign-in: linking here does
+		* NOT require the provider to have verified the email, and does
+		* not require the emails to match at all. On the sign-in route the
+		* provider's email is the *only* evidence tying the incoming
+		* identity to an existing account, so an unverified address would
+		* let an attacker claim someone else's account. Here the caller
+		* has already proven ownership by holding a valid session, and the
+		* OAuth credential proves control of the provider identity — the
+		* email plays no part in the decision, so its verification status
+		* is irrelevant.
+		*/
+		router.post(`/link/${provider.id}`, defaultAuthLimiter, requireAuth, async (c) => {
+			const userCtx = c.get("user");
+			if (!userCtx) throw ApiError.unauthorized("Not authenticated");
+			const payload = parseBody(provider.schema, await c.req.json());
+			let externalUser;
+			try {
+				externalUser = await provider.verify(payload);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				throw ApiError.unauthorized(`${provider.id} link failed: ${msg}`, "OAUTH_ERROR");
 			}
-		} else await authRepo.updateUser(user.id, {
-			displayName: externalUser.displayName || user.displayName || void 0,
-			photoUrl: externalUser.photoUrl || user.photoUrl || void 0
+			if (!externalUser) throw ApiError.unauthorized(`Invalid ${provider.id} credentials`, "INVALID_TOKEN");
+			const identityOwner = await authRepo.getUserByIdentity(provider.id, externalUser.providerId);
+			if (identityOwner && identityOwner.id !== userCtx.uid) throw ApiError.conflict(`That ${provider.id} account is already linked to a different user.`, "IDENTITY_ALREADY_LINKED");
+			if (identityOwner) return c.json({
+				success: true,
+				provider: provider.id,
+				alreadyLinked: true
+			});
+			await authRepo.linkUserIdentity(userCtx.uid, provider.id, externalUser.providerId, { email: externalUser.email });
+			return c.json({
+				success: true,
+				provider: provider.id,
+				alreadyLinked: false
+			});
 		});
-		const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(user.id, c.req.header("user-agent") || "unknown", c.req.header("x-forwarded-for") || "unknown");
-		const finalResponse = redactRefreshToken(await applyTransformHook(buildAuthResponse(user, roleIds, accessToken, refreshToken, provider.id), "oauth", c.req.raw, user.id), c, refreshToken, config.cookieAuth);
-		return c.json(finalResponse);
-	});
+	}
 	/**
 	* POST /auth/forgot-password
 	* Request password reset email
@@ -10597,10 +10672,10 @@ function createAuthRoutes(config) {
 		const storedToken = await authRepo.findValidPasswordResetToken(tokenHash);
 		if (!storedToken) throw ApiError.badRequest("Invalid or expired reset token", "INVALID_TOKEN");
 		const passwordHash = await ops.hashPassword(password);
-		await authRepo.updatePassword(storedToken.userId, passwordHash);
+		await authRepo.updatePassword(storedToken.uid, passwordHash);
 		await authRepo.markPasswordResetTokenUsed(tokenHash);
-		await authRepo.deleteAllRefreshTokensForUser(storedToken.userId);
-		if (ops.onPasswordReset) ops.onPasswordReset(storedToken.userId).catch((err) => {
+		await authRepo.deleteAllRefreshTokensForUser(storedToken.uid);
+		if (ops.onPasswordReset) ops.onPasswordReset(storedToken.uid).catch((err) => {
 			logger.error("[AuthHooks] onPasswordReset error", { error: err instanceof Error ? err.message : err });
 		});
 		return c.json({
@@ -10616,7 +10691,7 @@ function createAuthRoutes(config) {
 		const userCtx = c.get("user");
 		if (!userCtx) throw ApiError.unauthorized("Not authenticated");
 		const { oldPassword, newPassword } = parseBody(changePasswordSchema, await c.req.json());
-		const user = await authRepo.getUserById(userCtx.userId);
+		const user = await authRepo.getUserById(userCtx.uid);
 		if (!user || !user.passwordHash) throw ApiError.badRequest("Cannot change password for this account", "INVALID_ACCOUNT");
 		if (!await ops.verifyPassword(oldPassword, user.passwordHash)) throw ApiError.unauthorized("Current password is incorrect", "INVALID_CREDENTIALS");
 		const passwordValidation = ops.validatePasswordStrength(newPassword);
@@ -10637,7 +10712,7 @@ function createAuthRoutes(config) {
 		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");
-		const user = await authRepo.getUserById(userCtx.userId);
+		const user = await authRepo.getUserById(userCtx.uid);
 		if (!user) throw ApiError.notFound("User not found");
 		if (user.emailVerified) throw ApiError.badRequest("Email is already verified", "ALREADY_VERIFIED");
 		const token = generateSecureToken();
@@ -10683,8 +10758,8 @@ function createAuthRoutes(config) {
 	* Refresh access token using refresh token
 	*/
 	router.post("/refresh", async (c) => {
-		const refreshToken = readRefreshToken(c, parseBody(refreshSchema, await c.req.json()), config.cookieAuth);
-		if (!refreshToken) throw ApiError.badRequest("Refresh token is required", "INVALID_INPUT");
+		const refreshToken = readRefreshToken(c, parseBody(refreshSchema, await c.req.json().catch(() => ({}))), config.cookieAuth);
+		if (!refreshToken) throw ApiError.unauthenticated("No refresh token presented", "NO_SESSION");
 		const tokenHash = hashRefreshToken(refreshToken);
 		const storedToken = await authRepo.findRefreshTokenByHash(tokenHash);
 		if (!storedToken) {
@@ -10696,10 +10771,10 @@ function createAuthRoutes(config) {
 			clearRefreshCookie(c, config.cookieAuth);
 			throw ApiError.unauthorized("Refresh token expired", "TOKEN_EXPIRED");
 		}
-		const roleIds = (await authRepo.getUserRoles(storedToken.userId)).map((r) => r.id);
-		const user = await authRepo.getUserById(storedToken.userId).catch((err) => {
+		const roleIds = (await authRepo.getUserRoles(storedToken.uid)).map((r) => r.id);
+		const user = await authRepo.getUserById(storedToken.uid).catch((err) => {
 			logger.warn("[Auth] Could not load user during token refresh; returning tokens only", {
-				userId: storedToken.userId,
+				uid: storedToken.uid,
 				error: err instanceof Error ? err.message : String(err)
 			});
 			return null;
@@ -10707,18 +10782,18 @@ function createAuthRoutes(config) {
 		let customClaims;
 		if (ops.customizeAccessToken && user) {
 			const defaultClaims = {
-				userId: storedToken.userId,
+				uid: storedToken.uid,
 				roles: roleIds,
 				aal: "aal1"
 			};
 			customClaims = await ops.customizeAccessToken(defaultClaims, user);
 		}
-		const newAccessToken = generateAccessToken(storedToken.userId, roleIds, "aal1", customClaims);
+		const newAccessToken = generateAccessToken(storedToken.uid, roleIds, "aal1", customClaims);
 		const newRefreshToken = generateRefreshToken();
 		const userAgent = c.req.header("user-agent") || "unknown";
 		const ipAddress = c.req.header("x-forwarded-for") || "unknown";
 		await authRepo.deleteRefreshToken(tokenHash);
-		await authRepo.createRefreshToken(storedToken.userId, hashRefreshToken(newRefreshToken), getRefreshTokenExpiry(), userAgent, ipAddress);
+		await authRepo.createRefreshToken(storedToken.uid, hashRefreshToken(newRefreshToken), getRefreshTokenExpiry(), userAgent, ipAddress);
 		const tokensOnlyResponse = { tokens: {
 			accessToken: newAccessToken,
 			refreshToken: newRefreshToken,
@@ -10731,7 +10806,7 @@ function createAuthRoutes(config) {
 			logger.warn("[Auth] Could not build enriched refresh response; returning tokens only", { error: err instanceof Error ? err.message : String(err) });
 			refreshResponse = tokensOnlyResponse;
 		}
-		const finalResponse = redactRefreshToken(await applyTransformHook(refreshResponse, "refresh", c.req.raw, storedToken.userId), c, newRefreshToken, config.cookieAuth);
+		const finalResponse = redactRefreshToken(await applyTransformHook(refreshResponse, "refresh", c.req.raw, storedToken.uid), c, newRefreshToken, config.cookieAuth);
 		return c.json(finalResponse);
 	});
 	mountSessionRoutes({
@@ -10768,7 +10843,7 @@ function createAuthRoutes(config) {
 /**
 * Create a standalone admin route for resetting user passwords.
 *
-* Mounts: POST /users/:userId/reset-password
+* Mounts: POST /users/:uid/reset-password
 */
 function createResetPasswordRoute(config) {
 	const router = new Hono();
@@ -10777,9 +10852,9 @@ function createResetPasswordRoute(config) {
 	const ops = resolveAuthHooks(config.authHooks);
 	router.onError(errorHandler);
 	router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
-	router.post("/users/:userId/reset-password", requireAdmin, async (c) => {
-		const userId = c.req.param("userId");
-		const existing = await authRepo.getUserById(userId);
+	router.post("/users/:uid/reset-password", requireAdmin, async (c) => {
+		const uid = c.req.param("uid");
+		const existing = await authRepo.getUserById(uid);
 		if (!existing) throw ApiError.notFound("User not found");
 		let invitationSent = false;
 		let temporaryPassword;
@@ -10893,10 +10968,10 @@ function createAdminRolesRoute(config) {
 *
 * Mounts:
 *   GET /users
-*   GET /users/:userId
+*   GET /users/:uid
 *   POST /users
-*   PUT /users/:userId
-*   DELETE /users/:userId
+*   PUT /users/:uid
+*   DELETE /users/:uid
 *   POST /bootstrap
 */
 function createAdminUsersRoute(config) {
@@ -10931,9 +11006,9 @@ function createAdminUsersRoute(config) {
 			break;
 		}
 		if (hasAdmin) throw ApiError.forbidden("Admin users already exist. Bootstrap not allowed.", "BOOTSTRAP_COMPLETED");
-		const userId = "userId" in user ? user.userId : "uid" in user ? user.uid : void 0;
-		if (!userId) throw ApiError.unauthorized("User ID not found in auth context");
-		if (!await authRepo.getUserById(userId)) throw ApiError.notFound("Authenticated user does not exist in the database.", "USER_NOT_FOUND");
+		const uid = "uid" in user ? user.uid : "uid" in user ? user.uid : void 0;
+		if (!uid) throw ApiError.unauthorized("User ID not found in auth context");
+		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 at = new Date(a.createdAt).getTime();
@@ -10941,26 +11016,26 @@ function createAdminUsersRoute(config) {
 				if (at !== bt) return at < bt ? a : b;
 				return a.id < b.id ? a : b;
 			});
-			if (earliest.id !== userId) {
+			if (earliest.id !== uid) {
 				logger.warn("[Security Audit] Bootstrap denied: caller is not the earliest-registered user", {
 					eventType: "auth.bootstrap.denied",
-					callerId: userId,
+					callerId: uid,
 					earliestUserId: earliest.id
 				});
 				throw ApiError.forbidden("Only the first registered user may claim the initial admin role. Ask that user to bootstrap, or assign the admin role using the service key.", "BOOTSTRAP_NOT_FIRST_USER");
 			}
 		}
-		await authRepo.setUserRoles(userId, ["admin"]);
+		await authRepo.setUserRoles(uid, ["admin"]);
 		logger.info("[Security Audit] Initial admin bootstrapped", {
 			eventType: "auth.bootstrap.success",
-			userId
+			uid
 		});
 		if (config.setBootstrapCompleted) await config.setBootstrapCompleted();
 		return c.json({
 			success: true,
 			message: "You are now an admin",
 			user: {
-				uid: userId,
+				uid,
 				roles: ["admin"]
 			}
 		});
@@ -10991,9 +11066,9 @@ function createAdminUsersRoute(config) {
 			offset: result.offset
 		});
 	});
-	router.get("/users/:userId", requireAdmin, async (c) => {
-		const userId = c.req.param("userId");
-		const result = await authRepo.getUserWithRoles(userId);
+	router.get("/users/:uid", requireAdmin, async (c) => {
+		const uid = c.req.param("uid");
+		const result = await authRepo.getUserWithRoles(uid);
 		if (!result) throw ApiError.notFound("User not found");
 		const adminUser = toAdminUser(result.user, result.roles.map((r) => r.id));
 		return c.json({ user: adminUser });
@@ -11036,10 +11111,10 @@ function createAdminUsersRoute(config) {
 			...finalizeResult.emailDeliveryFailed ? { emailDeliveryFailed: true } : {}
 		}, 201);
 	});
-	router.put("/users/:userId", requireAdmin, async (c) => {
-		const userId = c.req.param("userId");
+	router.put("/users/:uid", requireAdmin, async (c) => {
+		const uid = c.req.param("uid");
 		const { password, email, displayName, roles } = await c.req.json();
-		if (!await authRepo.getUserById(userId)) throw ApiError.notFound("User not found");
+		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("User not found");
 		const updates = {};
 		if (email !== void 0) updates.email = email.toLowerCase();
 		if (displayName !== void 0) updates.displayName = displayName;
@@ -11048,9 +11123,9 @@ function createAdminUsersRoute(config) {
 			if (!validation.valid) throw ApiError.badRequest(`Password too weak: ${validation.errors.join(". ")}`);
 			updates.passwordHash = await ops.hashPassword(password);
 		}
-		if (Object.keys(updates).length > 0) await authRepo.updateUser(userId, updates);
+		if (Object.keys(updates).length > 0) await authRepo.updateUser(uid, updates);
 		if (roles !== void 0 && Array.isArray(roles)) {
-			const wasAdmin = (await authRepo.getUserRoleIds(userId)).includes("admin");
+			const wasAdmin = (await authRepo.getUserRoleIds(uid)).includes("admin");
 			const willBeAdmin = roles.includes("admin");
 			if (wasAdmin && !willBeAdmin) {
 				if ((await authRepo.listUsersPaginated({
@@ -11058,24 +11133,23 @@ function createAdminUsersRoute(config) {
 					limit: 1
 				})).total <= 1) throw ApiError.forbidden("Cannot demote the last administrator", "LAST_ADMIN");
 			}
-			await authRepo.setUserRoles(userId, roles);
+			await authRepo.setUserRoles(uid, roles);
 		}
-		const result = await authRepo.getUserWithRoles(userId);
+		const result = await authRepo.getUserWithRoles(uid);
 		const adminUser = toAdminUser(result.user, result.roles.map((r) => r.id));
 		return c.json({ user: adminUser });
 	});
-	router.delete("/users/:userId", requireAdmin, async (c) => {
-		const userId = c.req.param("userId");
-		const authUser = c.get("user");
-		if ((authUser?.uid || authUser?.userId) === userId) throw ApiError.badRequest("Cannot delete your own account", "SELF_DELETE");
-		if (!await authRepo.getUserById(userId)) throw ApiError.notFound("User not found");
-		if ((await authRepo.getUserRoleIds(userId)).includes("admin")) {
+	router.delete("/users/:uid", requireAdmin, async (c) => {
+		const uid = c.req.param("uid");
+		if (c.get("user")?.uid === uid) throw ApiError.badRequest("Cannot delete your own account", "SELF_DELETE");
+		if (!await authRepo.getUserById(uid)) throw ApiError.notFound("User not found");
+		if ((await authRepo.getUserRoleIds(uid)).includes("admin")) {
 			if ((await authRepo.listUsersPaginated({
 				roleId: "admin",
 				limit: 1
 			})).total <= 1) throw ApiError.forbidden("Cannot delete the last administrator", "LAST_ADMIN");
 		}
-		await authRepo.deleteUser(userId);
+		await authRepo.deleteUser(uid);
 		return c.json({ success: true });
 	});
 	return router;
@@ -11110,16 +11184,16 @@ function createBuiltinAuthAdapter(config) {
 			if (!payload) return null;
 			let roles = payload.roles || [];
 			try {
-				roles = await authRepository.getUserRoleIds(payload.userId);
+				roles = await authRepository.getUserRoleIds(payload.uid);
 			} catch (err) {
 				logger.warn("Role lookup from repository failed, using token roles as fallback", {
-					userId: payload.userId,
+					uid: payload.uid,
 					error: err
 				});
 			}
 			const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
 			return {
-				uid: payload.userId,
+				uid: payload.uid,
 				email: payload.email ?? "",
 				displayName: payload.displayName ?? null,
 				roles,
@@ -11139,16 +11213,16 @@ function createBuiltinAuthAdapter(config) {
 			if (!payload) return null;
 			let roles = payload.roles || [];
 			try {
-				roles = await authRepository.getUserRoleIds(payload.userId);
+				roles = await authRepository.getUserRoleIds(payload.uid);
 			} catch (err) {
 				logger.warn("Role lookup from repository failed, using token roles as fallback", {
-					userId: payload.userId,
+					uid: payload.uid,
 					error: err
 				});
 			}
 			const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
 			return {
-				uid: payload.userId,
+				uid: payload.uid,
 				email: payload.email ?? "",
 				displayName: payload.displayName ?? null,
 				roles,
@@ -11207,6 +11281,16 @@ function createBuiltinAuthAdapter(config) {
 				collectionAuthConfig: collectionAuth ?? collectionAuthConfig
 			});
 		},
+		describeUserCreationContract(collectionAuth) {
+			if ((collectionAuth ?? collectionAuthConfig)?.onCreateUser || resolvedOps.onAdminCreateUser) return {
+				validate: false,
+				extraFields: []
+			};
+			return {
+				validate: true,
+				extraFields: ["password"]
+			};
+		},
 		async finalizeUserCreation(entity, clearPassword) {
 			return finalizeAdminUserCreation(entity, clearPassword, {
 				authRepo: authRepository,
@@ -11296,11 +11380,11 @@ function createUserManagementFromRepo(repo, resolvedOps) {
 				logger.error("[AuthHooks] afterUserDelete error", { error: err instanceof Error ? err.message : err });
 			});
 		},
-		async getUserRoles(userId) {
-			return repo.getUserRoleIds(userId);
+		async getUserRoles(uid) {
+			return repo.getUserRoleIds(uid);
 		},
-		async setUserRoles(userId, roleIds) {
-			await repo.setUserRoles(userId, roleIds);
+		async setUserRoles(uid, roleIds) {
+			await repo.setUserRoles(uid, roleIds);
 		}
 	};
 }
@@ -11416,8 +11500,8 @@ function requestLogger(options) {
 		const reqId = c.get("requestId");
 		if (reqId) data.requestId = reqId;
 		if (contentLength) data.contentLength = parseInt(contentLength, 10);
-		const userId = c.get("userId");
-		if (userId) data.userId = userId;
+		const uid = c.get("user")?.uid;
+		if (uid) data.uid = uid;
 		if (status >= 500) logger.error("request", data);
 		else if (status >= 400) logger.warn("request", data);
 		else logger.info("request", data);
@@ -13420,7 +13504,7 @@ function createApiKeyRoutes(options) {
 			if (parsed <= /* @__PURE__ */ new Date()) throw ApiError.badRequest("expires_at must be in the future", "INVALID_INPUT");
 		}
 		const user = c.get("user");
-		const createdBy = user && typeof user === "object" && "userId" in user ? user.userId : "unknown";
+		const createdBy = user && typeof user === "object" && "uid" in user ? user.uid : "unknown";
 		const request = {
 			name: name.trim(),
 			permissions,
@@ -14031,7 +14115,7 @@ function buildAdapterAuthMiddleware(adapter, requireAuth, publicRead) {
 				} }, 401);
 			}
 			if (authenticatedUser) c.set("user", {
-				userId: authenticatedUser.uid,
+				uid: authenticatedUser.uid,
 				email: authenticatedUser.email,
 				roles: authenticatedUser.roles
 			});
@@ -14066,7 +14150,7 @@ function createStorageRoutes(config) {
 	const checkAuthorized = async (c, operation, key, bucket, storageId) => {
 		if (!authorize) return;
 		const user = c.get("user") ?? null;
-		if (user?.userId === "download-token" || user?.userId === "public") return;
+		if (user?.uid === "download-token" || user?.uid === "public") return;
 		let allowed;
 		try {
 			allowed = await authorize({
@@ -14709,6 +14793,28 @@ function buildQueryString(params) {
 	}
 	return parts.length > 0 ? "?" + parts.join("&") : "";
 }
+/**
+* The base every request and every caller-built URL resolves against.
+*
+* `baseUrl` is optional because the common production shape is a Rebase
+* backend serving its own SPA, where the API is simply the page's origin.
+* Leaving it unset is therefore the *correct* configuration there — and the
+* one that keeps working when a second hostname (a custom domain) points at
+* the same app.
+*
+* When unset in a browser this resolves to the page origin rather than "".
+* Requests behave identically either way, but the empty string is a trap for
+* anything that builds a URL from `client.baseUrl`: `new URL("" + path)`
+* throws, so apps "fixed" it by baking an absolute host into their bundle —
+* which is exactly what breaks the day a custom domain is added, and which no
+* amount of CORS configuration repairs, because a SameSite=Lax auth cookie is
+* not sent cross-site either.
+*/
+function resolveBaseUrl(configured) {
+	if (configured) return configured.replace(/\/$/, "");
+	if (typeof window !== "undefined" && window.location?.origin) return window.location.origin;
+	return "";
+}
 function createTransport(config) {
 	const fetchFn = config.fetch || globalThis.fetch;
 	const apiPath = config.apiPath || "/api";
@@ -14723,7 +14829,7 @@ function createTransport(config) {
 		};
 	}
 	async function request(path, init) {
-		const url = (config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "") + apiPath + path;
+		const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 		let activeToken = token;
 		if (tokenGetter) try {
 			const fetched = await tokenGetter();
@@ -14798,7 +14904,7 @@ function createTransport(config) {
 			onUnauthorizedHandler = handler;
 		},
 		get baseUrl() {
-			return config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "";
+			return resolveBaseUrl(config.baseUrl);
 		},
 		get apiPath() {
 			return apiPath;
@@ -15258,6 +15364,30 @@ function createAuth(transport, options) {
 			})
 		});
 	}
+	/**
+	* Link an OAuth provider to the **currently signed-in** account.
+	*
+	* Use this when `signIn*` failed with `EMAIL_NOT_VERIFIED` — an account
+	* with that email already exists under a different sign-in method — or to
+	* attach a provider whose email differs from the account's.
+	*
+	* The payload is the same one the provider's sign-in method takes, e.g.
+	* `linkProvider("google", { idToken })`.
+	*
+	* Unlike sign-in, this does not require the provider to have verified the
+	* email, and the emails need not match: the active session already proves
+	* account ownership.
+	*
+	* Throws `IDENTITY_ALREADY_LINKED` (409) if that provider identity is
+	* attached to a different user. Succeeds idempotently (`alreadyLinked:
+	* true`) if it is already attached to the current one.
+	*/
+	async function linkProvider(providerId, payload) {
+		return transport.request(authPath + "/link/" + providerId, {
+			method: "POST",
+			body: JSON.stringify(payload)
+		});
+	}
 	async function sendVerificationEmail() {
 		return transport.request(authPath + "/send-verification", { method: "POST" });
 	}
@@ -15379,6 +15509,7 @@ function createAuth(transport, options) {
 		resetPasswordForEmail,
 		resetPassword,
 		changePassword,
+		linkProvider,
 		sendVerificationEmail,
 		verifyEmail,
 		sendMagicLink,
@@ -16012,7 +16143,8 @@ var CHANNEL_MESSAGE_TYPES = new Set([
 	"broadcast",
 	"presence_track",
 	"presence_untrack",
-	"presence_state"
+	"presence_state",
+	"channel_history"
 ]);
 /**
 * Low-level realtime WebSocket client.
@@ -16351,7 +16483,7 @@ var RebaseWebSocketClient = class {
 			}
 			return;
 		}
-		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff")) {
+		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history")) {
 			const handlers = this.channelHandlers.get(message.channel);
 			if (handlers) for (const handler of [...handlers]) try {
 				handler(message);
@@ -16647,6 +16779,9 @@ var RebaseWebSocketClient = class {
 	async fetchAvailableRoles() {
 		return (await this.sendMessage({ type: "FETCH_ROLES" })).roles || [];
 	}
+	async fetchApplicationRoles() {
+		return (await this.sendMessage({ type: "FETCH_APPLICATION_ROLES" })).roles || [];
+	}
 	async fetchCurrentDatabase() {
 		return (await this.sendMessage({ type: "FETCH_CURRENT_DATABASE" })).database;
 	}
@@ -17133,6 +17268,14 @@ var RebaseWebSocketClient = class {
 * before the entry is reaped, so a single dropped frame is not a disappearance.
 */
 var PRESENCE_HEARTBEAT_MS = 2e4;
+/**
+* How long live messages are held back waiting for a catch-up response.
+*
+* Short, because the cost of waiting is visible — on a collaborative document
+* this is a stall in everyone else's edits appearing. Long enough that a slow
+* replay of a busy channel is not abandoned needlessly.
+*/
+var CATCH_UP_TIMEOUT_MS = 1e4;
 var RebaseRealtimeChannel = class {
 	name;
 	transport;
@@ -17145,9 +17288,63 @@ var RebaseRealtimeChannel = class {
 	trackedState = null;
 	heartbeat = null;
 	joined = false;
-	constructor(name, transport) {
+	/** Whether this handle asks the server to replay missed messages. */
+	wantsHistory;
+	/**
+	* Highest sequence number delivered to handlers so far.
+	*
+	* This is the resume point sent as `sinceSeq`, and the watermark that makes
+	* replay idempotent: catch-up ranges overlap with what arrived live, and
+	* anything at or below this has already been seen.
+	*/
+	lastSeq = 0;
+	/**
+	* Live messages that arrived while a catch-up was in flight.
+	*
+	* Without this they would be delivered ahead of the older messages being
+	* fetched, and — worse — would advance {@link lastSeq} past them, so the
+	* catch-up response would then be discarded as already-seen and those
+	* messages would be lost for good. Held here and flushed, in order, once
+	* the replay lands.
+	*/
+	pendingLive = [];
+	catchUpInFlight = false;
+	/**
+	* Deadline for a catch-up response.
+	*
+	* Buffering live messages is only safe because the wait is bounded. A
+	* catch-up frame that never arrives — a server that dropped it, a socket
+	* that died between request and reply — would otherwise leave the channel
+	* silently holding every subsequent edit forever, which is a worse failure
+	* than the one replay was added to fix.
+	*/
+	catchUpTimeout = null;
+	/**
+	* Callers of {@link history} awaiting the next `channel_history` frame.
+	*
+	* These frames are addressed by channel rather than by request id, so they
+	* are matched in arrival order. Requests on one channel are serialized by
+	* the socket, so FIFO is the right correlation here.
+	*/
+	historyWaiters = [];
+	constructor(name, transport, options = {}) {
 		this.name = name;
 		this.transport = transport;
+		this.wantsHistory = options.history ?? false;
+	}
+	/**
+	* Turn on catch-up for a handle that was created without it.
+	*
+	* The client hands back the same channel object for a given name, so a
+	* later `channel(name, { history: true })` has no new object to configure —
+	* it upgrades this one instead. Idempotent, and never downgrades: one
+	* caller asking for history must not be switched off by another that did
+	* not ask.
+	*/
+	enableHistory() {
+		if (this.wantsHistory) return;
+		this.wantsHistory = true;
+		if (this.joined) this.requestHistory();
 	}
 	/**
 	* Join the channel and ask for the current roster.
@@ -17186,15 +17383,58 @@ var RebaseRealtimeChannel = class {
 		}));
 		await this.send("join_channel");
 		await this.send("presence_state");
+		if (this.wantsHistory) await this.requestHistory();
 	}
 	async rejoin() {
 		try {
 			await this.send("join_channel");
 			await this.send("presence_state");
 			if (this.trackedState) await this.send("presence_track", { state: this.trackedState });
+			if (this.wantsHistory) await this.requestHistory();
 		} catch {}
 	}
 	/**
+	* Ask the server for everything after {@link lastSeq}.
+	*
+	* Live messages are buffered from here until the answer arrives — see
+	* {@link pendingLive}.
+	*/
+	async requestHistory(limit) {
+		this.catchUpInFlight = true;
+		if (this.catchUpTimeout) clearTimeout(this.catchUpTimeout);
+		this.catchUpTimeout = setTimeout(() => this.abandonCatchUp(), CATCH_UP_TIMEOUT_MS);
+		this.catchUpTimeout.unref?.();
+		try {
+			await this.send("channel_history", {
+				sinceSeq: this.lastSeq,
+				...limit !== void 0 ? { limit } : {}
+			});
+		} catch {
+			this.abandonCatchUp();
+		}
+	}
+	/**
+	* Give up waiting for a catch-up and release what was held back.
+	*
+	* The buffered messages are still the freshest thing this client has, so
+	* they are delivered rather than dropped. Callers of {@link history} are
+	* answered with `retained: false` — accurate in the sense that matters:
+	* this client has no history to work from and has to resync.
+	*/
+	abandonCatchUp() {
+		if (this.catchUpTimeout) {
+			clearTimeout(this.catchUpTimeout);
+			this.catchUpTimeout = null;
+		}
+		if (!this.catchUpInFlight) return;
+		this.catchUpInFlight = false;
+		for (const resolve of this.historyWaiters.splice(0)) resolve({
+			messages: [],
+			retained: false
+		});
+		this.flushPendingLive();
+	}
+	/**
 	* Publish this client's presence state, and keep publishing it.
 	*
 	* Calling `track` again replaces the state (and restarts the heartbeat),
@@ -17244,6 +17484,34 @@ var RebaseRealtimeChannel = class {
 		this.join();
 		return () => this.broadcastHandlers.delete(wrapped);
 	}
+	/**
+	* The last sequence number this channel has delivered.
+	*
+	* Zero on a channel that retains nothing. Persist it if you want catch-up
+	* to survive a page reload as well as a reconnect, and pass it back via
+	* {@link history}.
+	*/
+	get sequence() {
+		return this.lastSeq;
+	}
+	/**
+	* Fetch retained messages explicitly, instead of waiting for join or
+	* reconnect to do it.
+	*
+	* Defaults to resuming from {@link sequence}. Messages are delivered to
+	* `onBroadcast` handlers as usual — the returned value is for callers that
+	* want to inspect the batch, or to learn from `retained` that the channel
+	* keeps no history at all.
+	*/
+	async history(options = {}) {
+		await this.join();
+		if (options.sinceSeq !== void 0) this.lastSeq = options.sinceSeq;
+		const result = new Promise((resolve) => {
+			this.historyWaiters.push(resolve);
+		});
+		await this.requestHistory(options.limit);
+		return result;
+	}
 	/** Leave the channel and release every listener and timer. */
 	async leave() {
 		this.stopHeartbeat();
@@ -17251,6 +17519,17 @@ var RebaseRealtimeChannel = class {
 		this.presences = {};
 		this.presenceHandlers.clear();
 		this.broadcastHandlers.clear();
+		this.lastSeq = 0;
+		this.pendingLive = [];
+		this.catchUpInFlight = false;
+		if (this.catchUpTimeout) {
+			clearTimeout(this.catchUpTimeout);
+			this.catchUpTimeout = null;
+		}
+		for (const resolve of this.historyWaiters.splice(0)) resolve({
+			messages: [],
+			retained: false
+		});
 		for (const off of this.unsubscribers) off();
 		this.unsubscribers = [];
 		if (this.joined) {
@@ -17283,15 +17562,71 @@ var RebaseRealtimeChannel = class {
 				break;
 			}
 			case "broadcast": {
+				const seq = typeof message.seq === "number" ? message.seq : void 0;
 				const event = {
 					event: message.event,
-					payload: message.payload
+					payload: message.payload,
+					...seq !== void 0 ? { seq } : {}
 				};
-				for (const handler of this.broadcastHandlers) handler(event);
+				if (seq === void 0) {
+					this.deliver(event);
+					break;
+				}
+				if (this.catchUpInFlight) {
+					this.pendingLive.push(event);
+					break;
+				}
+				if (seq <= this.lastSeq) break;
+				this.lastSeq = seq;
+				this.deliver(event);
+				break;
+			}
+			case "channel_history": {
+				this.catchUpInFlight = false;
+				if (this.catchUpTimeout) {
+					clearTimeout(this.catchUpTimeout);
+					this.catchUpTimeout = null;
+				}
+				const entries = message.messages ?? [];
+				const retained = message.retained === true;
+				const latestSeq = typeof message.latestSeq === "number" ? message.latestSeq : void 0;
+				for (const resolve of this.historyWaiters.splice(0)) resolve({
+					messages: entries,
+					retained,
+					latestSeq
+				});
+				for (const entry of entries) {
+					if (entry.seq <= this.lastSeq) continue;
+					this.lastSeq = entry.seq;
+					this.deliver({
+						event: entry.event,
+						payload: entry.payload,
+						seq: entry.seq,
+						replayed: true
+					});
+				}
+				this.flushPendingLive();
 				break;
 			}
 		}
 	}
+	/** Deliver everything held back during a catch-up, in sequence order. */
+	flushPendingLive() {
+		if (this.pendingLive.length === 0) return;
+		const buffered = this.pendingLive.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+		this.pendingLive = [];
+		for (const event of buffered) {
+			const seq = event.seq;
+			if (seq !== void 0) {
+				if (seq <= this.lastSeq) continue;
+				this.lastSeq = seq;
+			}
+			this.deliver(event);
+		}
+	}
+	deliver(event) {
+		for (const handler of [...this.broadcastHandlers]) handler(event);
+	}
 	emitPresence(diff) {
 		const snapshot = { ...this.presences };
 		for (const handler of this.presenceHandlers) handler(snapshot, diff);
@@ -17467,13 +17802,13 @@ function createRebaseClient(options) {
 		* own membership — and `leave()` from one would otherwise silently
 		* cut off the others.
 		*/
-channel: (name) => {
+channel: (name, options) => {
 			if (!ws) throw new RebaseClientError("Realtime is disabled on this client (realtime: false), so channels are unavailable.");
 			let existing = realtimeChannels.get(name);
 			if (!existing) {
-				existing = new RebaseRealtimeChannel(name, ws);
+				existing = new RebaseRealtimeChannel(name, ws, options);
 				realtimeChannels.set(name, existing);
-			}
+			} else if (options?.history) existing.enableHistory();
 			return existing;
 		} },
 		/**
@@ -19407,10 +19742,10 @@ var backup_exports = /* @__PURE__ */ __exportAll({
 /**
 * Returns a SQL chunk calling `auth.uid()` — the current user's ID.
 * This is a PostgreSQL RLS helper function created in the `auth` schema
-* that reads `app.user_id` set per-transaction by `withAuth()`.
+* that reads `app.uid` set per-transaction by `withAuth()`.
 *
 * @example
-* sql`${table.user_id} = ${authUid()}`
+* sql`${table.uid} = ${authUid()}`
 */
 var authUid = () => {
 	return sql`auth.uid()`;