@rebasepro/server 0.25.1 → 0.26.0

package/dist/access-BFAUvsSs.js

@@ -0,0 +1,1897 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+import { _ as scopesBeyond, c as intersectScopes, d as isDataPlaneScope, g as scopeGrantsAny, h as scopeGrants, i as EMPTY_ACCESS_MODEL, m as roleNameProblem, n as ADMIN_SCOPES, p as parseScope, r as BUILT_IN_SCOPES, s as hasAdminRole, t as ADMIN_ROLE, v as scopesForRoles, x as validateScopes } from "./src-Bh9LRPb9.js";
+import { t as ANONYMOUS_USER_ID } from "./policy-PdzX-Opd.js";
+import { a as SIMULATE_USER_ID_HEADER, i as SIMULATE_ROLE_HEADER, n as SIMULATED_CONTEXT_HEADER, o as formatSimulatedContext, r as SIMULATE_API_KEY_ID_HEADER, t as IMPERSONATE_HEADER } from "./auth_adapter-B7RUMk6e.js";
+import { a as logger } from "./logger-CW8pmTS6.js";
+import { r as restrictedFieldNames, t as apiHiddenFieldNames } from "./field-access-DYsvjI_P.js";
+import { E as sha256Hex, S as constantTimeEqual, h as processJwtService, m as jwtOf } from "./jwt-rDS0884_.js";
+import { a as isDataException, c as warnIfDatabaseClosed, i as errorHandler, o as isDatabaseUnreachable, t as ApiError } from "./errors-OMWkKSH-.js";
+import { a as canonicalStorageId, o as canonicalStorageKey, r as InvalidStorageKeyError } from "./keys-BXcdRNhJ.js";
+import { n as scopeGuardProblem } from "./admin-roles-DI9RsgN3.js";
+//#region ../types/src/controllers/storage.ts
+/**
+* Path prefix that marks an object as **public**. Files stored under this
+* prefix are served without any auth token via a stable, permanent,
+* CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the
+* client SDK and the backend so both agree on which objects are public.
+*
+* @group Models
+*/
+var PUBLIC_STORAGE_PREFIX = "public/";
+/**
+* True when a storage **key** is public: it lies under
+* {@link PUBLIC_STORAGE_PREFIX}.
+*
+* The key is read exactly as it is — the canonical key within its bucket, the
+* one the server stores, serves, and hands a `storageAuthorize` hook as
+* `key` — and nothing is parsed out of it. That is the difference from
+* {@link isPublicStoragePath}, which reads a client-side *path* and so strips
+* a `scheme://` and a leading `default/` bucket segment first. On a key both are
+* wrong: `default/public/x` is a key in a folder called `default`, and a
+* request path `notes://public/x` names the key `notes:/public/x`. Neither is
+* public, and the server decides on this function so that it never says they
+* are.
+*
+* @group Models
+*/
+function isPublicStorageKey(key) {
+	if (!key || !key.startsWith("public/")) return false;
+	return !key.split(/[\\/]/).includes("..");
+}
+/**
+* True when a storage key or client-side path points at a public object
+* (lives under {@link PUBLIC_STORAGE_PREFIX}).
+*
+* For a path as a client holds it: a `scheme://` prefix and a single leading
+* `default/` bucket segment are stripped first. The server and a
+* `storageAuthorize` hook, which hold the canonical key, use
+* {@link isPublicStorageKey}.
+*
+* @group Models
+*/
+function isPublicStoragePath(path) {
+	if (!path) return false;
+	let p = path;
+	const scheme = p.indexOf("://");
+	if (scheme !== -1) p = p.substring(scheme + 3);
+	p = p.replace(/^\/+/, "");
+	if (p.split("/").some((seg) => seg === "..")) return false;
+	return p.startsWith("public/") || p.startsWith(`default/public/`);
+}
+/**
+* The path the storage routes address an object by, from a key or from the
+* `storageUrl` an upload returned (`<scheme>://<bucket>/<key>`, which is what a
+* property with `includeBucketUrl: true` keeps in its column).
+*
+* The routes address a source's objects by key. On S3 and GCS the bucket in a
+* `storageUrl` is always the source's own — the server refuses any other — so
+* it is dropped: sent along, `s3://acme-media/products/a.png` reached the
+* server as the key `acme-media/products/a.png`, the preview found nothing and
+* a delete reported success while the object stayed. It worked on local disk
+* only, because `local://default/<key>` happens to carry the one bucket
+* segment the routes recognise — which is kept, as is any other local bucket.
+*
+* A bare key whose first folder is `default` is sent behind that bucket
+* segment. The routes read one leading `default/` (in any case) as the bucket,
+* so the key `default/photo.png` sent as it is names the root `photo.png`:
+* {@link defaultBucketPath} is the spelling that names the key itself.
+*
+* Shared by every storage source that talks to those routes, so they address
+* an object alike.
+*
+* @group Models
+*/
+function storageObjectPath(keyOrUrl, bucket) {
+	let filePath = keyOrUrl;
+	let bucketQualified = false;
+	const scheme = /^(local|s3|gs):\/\//.exec(filePath);
+	if (scheme) {
+		filePath = filePath.substring(scheme[0].length);
+		if (scheme[1] !== "local") {
+			const slash = filePath.indexOf("/");
+			if (slash > 0) filePath = filePath.substring(slash + 1);
+		} else bucketQualified = true;
+	}
+	if (bucket && filePath) {
+		if (!filePath.startsWith(`${bucket}/`)) filePath = `${bucket}/${filePath}`;
+		bucketQualified = true;
+	}
+	return bucketQualified ? filePath : defaultBucketPath(filePath);
+}
+/**
+* The request path of a key in the default bucket: the key itself, unless the
+* routes would read its first folder as the bucket — a first folder named
+* `default`, matched as the routes match it (case-insensitively, and only when
+* something follows it). Then the bucket segment goes in front, so exactly the
+* one segment the routes strip is the one added.
+*/
+function defaultBucketPath(key) {
+	const segments = key.split("/");
+	return segments.length > 1 && segments[0].toLowerCase() === "default" ? `default/${key}` : key;
+}
+//#endregion
+//#region src/auth/api-keys/http-operation.ts
+/**
+* Map an HTTP method to the operation it performs.
+*
+* - `GET`, `HEAD`, `OPTIONS` → `"read"`
+* - `POST`, `PUT`, `PATCH`  → `"write"`
+* - `DELETE`                → `"delete"`
+*
+* Any other method is a `"write"`: a verb this does not know is not assumed
+* to be harmless.
+*/
+function httpMethodToOperation(method) {
+	switch (method.toUpperCase()) {
+		case "GET":
+		case "HEAD":
+		case "OPTIONS": return "read";
+		case "DELETE": return "delete";
+		default: return "write";
+	}
+}
+//#endregion
+//#region src/auth/simulation-read-only.ts
+/**
+* "Simulate access" is read-only.
+*
+* The simulator answers "what does this role, user or key see". A write made
+* while simulating ran as the simulated identity for real: it committed as
+* `rebase_user` with `app.uid` set to the simulated uid, `entity_history`
+* recorded that uid as the author, callbacks saw `context.user` holding a role
+* the account may not even have, and a role-only simulation stamped owner
+* columns with the nobody uid. Only the request log named the administrator.
+* So every door that honours the simulation headers refuses anything but a
+* read, naming the simulation, rather than performing it as someone else.
+*
+* Its own module so the REST generator, history routes and the functions
+* guard can share it without importing the simulator itself.
+*
+* @module
+*/
+/**
+* Refuse a write or delete on a request that simulates access.
+*
+* `c` is anything with the request context's `get` — the REST generator calls
+* this with a per-operation stand-in for each operation of a `_batch`.
+* `operation` is what the request does, not its verb: `POST …/query` is a read.
+*/
+function refuseSimulatedWrite(c, operation) {
+	if (operation === "read" || !c.get("simulation")) return;
+	throw new ApiError(403, "SIMULATION_READ_ONLY", `This request simulates access (x-rebase-simulate-*), and simulated access is read-only: it would ${operation === "delete" ? "delete" : "write"} as the simulated identity, not as you. Stop simulating to make changes.`);
+}
+//#endregion
+//#region src/auth/token-revocation.ts
+/**
+* Has this access token been revoked?
+*
+* Everything that ends every session a user holds — a password change or reset
+* of any kind, and `DELETE /auth/sessions` — goes through
+* {@link revokeAllSessions}, which stamps a `tokensValidAfter` watermark on the
+* user. It 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;
+	}
+	return issuedBefore(payload, validAfter);
+}
+/**
+* Is the account behind this verified access token still the one that may use
+* it — and with which roles?
+*
+* A verified signature says who the token was minted for, an hour ago at
+* most. This asks the database what has happened to that account since. Every
+* door that honours an access token — the data plane, the admin gates, the
+* realtime socket — asks it here, so they cannot disagree about it.
+*
+* They did. A deleted account read as "not revoked": the watermark lives on
+* the user row, so once the row was gone there was no watermark, and the
+* roles lookup answered `[]` rather than "nobody". A token its owner had
+* revoked came back to life when an administrator deleted the account, as an
+* authenticated principal with that uid, for the rest of its lifetime. MCP
+* refresh and personal API keys already treated a missing account as revoked;
+* the main door did not.
+*
+* Throws when the repository does. Unlike the watermark read on its own, this
+* one decides the roles a request runs with, so a failure is a refusal (the
+* callers answer 503) rather than a guess.
+*
+* Except one failure that is an answer: the store refusing the uid as a value
+* its id column cannot hold — `u1` against a UUID key. That names no account,
+* exactly as a well-formed id nobody has does, so it is `account-deleted` and
+* the caller answers 401. Answered as a failure it was a 503 asking the
+* client to try again, which it would do forever.
+*/
+async function judgeAccessToken(authRepo, payload) {
+	try {
+		return await readAccessVerdict(authRepo, payload);
+	} catch (error) {
+		if (isDataException(error)) return {
+			live: false,
+			refusal: "account-deleted"
+		};
+		throw error;
+	}
+}
+async function readAccessVerdict(authRepo, payload) {
+	let roles;
+	let validAfter = null;
+	if (typeof authRepo.getAccountAccessState === "function") {
+		const state = await authRepo.getAccountAccessState(payload.uid, payload.sid);
+		if (!state) return {
+			live: false,
+			refusal: "account-deleted"
+		};
+		if (state.disabled) return {
+			live: false,
+			refusal: "account-disabled"
+		};
+		roles = state.roles;
+		validAfter = state.tokensValidAfter;
+		if (payload.sid && state.sessionActive === false) return {
+			live: false,
+			refusal: "session-revoked"
+		};
+	} else {
+		if (typeof authRepo.getUserWithRoles === "function") {
+			const account = await authRepo.getUserWithRoles(payload.uid);
+			if (!account) return {
+				live: false,
+				refusal: "account-deleted"
+			};
+			if (account.user.disabled) return {
+				live: false,
+				refusal: "account-disabled"
+			};
+			roles = account.roles;
+		}
+		if (typeof authRepo.getTokensValidAfter === "function") validAfter = await authRepo.getTokensValidAfter(payload.uid);
+	}
+	if (issuedBefore(payload, validAfter)) return {
+		live: false,
+		refusal: "revoked"
+	};
+	return {
+		live: true,
+		roles
+	};
+}
+/**
+* The 401 a door answers an access token with when {@link judgeAccessToken}
+* refuses it — one wording and one code for each reason, wherever the token
+* was presented.
+*
+* `SESSION_REVOKED` for a token whose session or account is gone: the client
+* SDK answers it with a refresh, which the refresh route refuses for the same
+* reason, and the client signs out. `ACCOUNT_DISABLED` for an account an
+* administrator switched off, which no refresh can mend.
+*/
+function accessTokenRefusalError(refusal) {
+	switch (refusal) {
+		case "account-disabled": return ApiError.unauthorized("This account has been disabled", "ACCOUNT_DISABLED");
+		case "account-deleted": return ApiError.unauthorized("This account no longer exists", "SESSION_REVOKED");
+		case "revoked":
+		case "session-revoked": return ApiError.unauthorized("Session has been revoked", "SESSION_REVOKED");
+	}
+}
+/** The watermark comparison {@link isAccessTokenRevoked} and the judge share. */
+function issuedBefore(payload, validAfter) {
+	if (!validAfter || typeof payload.iat !== "number") return false;
+	return payload.iat < Math.floor(validAfter.getTime() / 1e3);
+}
+/**
+* End every session this user holds, on every device.
+*
+* Two writes, because each covers what the other cannot. Deleting the refresh
+* rows ends the sessions that exist at this instant, and on a repository
+* without the watermark it is the only revocation there is. The watermark
+* voids what the delete cannot see: a refresh already in flight that inserts
+* its rotated token a moment after the delete ran, and every access token
+* already handed out, which {@link isAccessTokenRevoked} refuses from here on.
+*
+* The watermark write does not fail the caller. By the time it runs the
+* credential has usually already changed and the rows are gone, so a 500 would
+* tell someone their password did not change when it did. It is logged, because
+* a failure here leaves access tokens working until they expire.
+*/
+async function revokeAllSessions(authRepo, uid) {
+	await authRepo.deleteAllRefreshTokensForUser(uid);
+	try {
+		await authRepo.setTokensValidAfter?.(uid, /* @__PURE__ */ new Date());
+	} catch (error) {
+		logger.warn("[Auth] Could not write the token revocation watermark; access tokens issued before now stay valid until they expire", {
+			uid,
+			error
+		});
+	}
+}
+/**
+* Replace a user's password and end every session they hold.
+*
+* The one way a password hash is written over an existing account. A new
+* password is what someone sets when they believe the old one — or a session
+* signed in with it — is in someone else's hands, so a password change that
+* leaves those sessions alive does not do the thing it was done for.
+*
+* It used to be a pair of lines repeated after each `updatePassword`, and it
+* reached the two self-service routes and none of the admin ones: an
+* administrator resetting a phished account left the attacker's refresh token
+* minting access tokens for the rest of its lifetime.
+* `test/password-change-revokes-sessions.test.ts` holds every route that sets a
+* password to this, and fails if anything but this function calls
+* `updatePassword`.
+*
+* `null` removes the password instead, for the same reason and with the same
+* revocation: see `confirmAddressOwnership`.
+*/
+async function replaceUserPassword(authRepo, uid, passwordHash) {
+	await authRepo.updatePassword(uid, passwordHash);
+	await revokeAllSessions(authRepo, uid);
+	await authRepo.deleteAllPasswordResetTokensForUser?.(uid);
+}
+//#endregion
+//#region src/auth/rls-scope.ts
+/**
+* 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 `rebase.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) {
+	return "withAuth" in driver && typeof driver.withAuth === "function";
+}
+/**
+* Can this driver run a request as a specific user?
+*
+* The same question `scopeDataDriver` asks internally, exported because one
+* caller must act on the answer BEFORE it has a request to scope.
+*
+* `scopeDataDriver` returns the driver unscoped when the answer is no, which is
+* the right behaviour for `/api/data` — Mongo has no row-level security and
+* never claimed to, and the route's own checks still apply. It is the wrong
+* behaviour for a surface whose entire promise is "this runs as you": there,
+* an unscoped driver silently means "runs as the database owner". So the MCP
+* surface asks this at boot and declines to mount rather than degrade.
+*/
+function supportsRlsScoping(driver) {
+	return isRLSScopedDriver(driver);
+}
+/**
+* Scope a DataDriver via `withAuth()` for RLS.
+*
+* SECURITY: If `withAuth()` is available but fails, the error is re-thrown
+* so the request is **denied** rather than proceeding with unscoped access
+* (fail-closed behavior).
+*
+* If the driver does not support RLS, the original driver is returned.
+*
+* @param driver - The DataDriver to scope.
+* @param user   - The authenticated user identity for RLS.
+* @returns The RLS-scoped DataDriver (or the original if RLS is unsupported).
+*/
+async function scopeDataDriver(driver, user) {
+	if (isRLSScopedDriver(driver)) return await driver.withAuth(user);
+	return driver;
+}
+//#endregion
+//#region src/auth/crypto-utils.ts
+/**
+* Cryptographic utility functions for auth.
+*
+* @module
+*/
+/**
+* Constant-time string comparison to prevent timing attacks.
+*
+* Used for comparing service keys, tokens, and other secrets where
+* timing side-channels could leak information about the expected value.
+*
+* The implementation lives in `utils/portable-crypto.ts`, which does this over
+* UTF-8 bytes without `node:crypto` — this function is on the request path, and
+* the byte-level reasoning it depends on is documented there.
+*
+* @param a - First string to compare.
+* @param b - Second string to compare.
+* @returns `true` if the strings are identical, `false` otherwise.
+*/
+function safeCompare(a, b) {
+	return constantTimeEqual(a, b);
+}
+//#endregion
+//#region src/auth/bearer-token.ts
+/**
+* Parsing of the `Authorization: Bearer <token>` header.
+*
+* Its own module rather than a helper inside `middleware.ts`, because the
+* API-key middleware needs it too and `middleware.ts` already imports from
+* there — putting it in either one would close an import cycle.
+*
+* @module
+*/
+/**
+* Pull the token out of an `Authorization: Bearer <token>` header.
+*
+* RFC 7235 §2.1 makes the auth-scheme name case-insensitive, and plenty of
+* clients send `bearer` — HTTP libraries that lower-case what they emit,
+* hand-written curl, proxies that normalise headers. Matching `"Bearer "`
+* exactly turned those into a 401 that, from the caller's side, is
+* indistinguishable from a rejected token; people spend an afternoon
+* regenerating credentials that were fine. Only the scheme is folded — the
+* token itself is returned byte-for-byte.
+*
+* Returns `undefined` when there is no header or it names another scheme.
+* That is deliberately distinct from an empty token (`Bearer ` with nothing
+* after it), which callers still route into verification so it fails as a bad
+* token rather than as a missing header.
+*/
+function extractBearerToken(authHeader) {
+	if (!authHeader) return void 0;
+	const separator = authHeader.indexOf(" ");
+	if (separator < 0) return void 0;
+	if (authHeader.slice(0, separator).toLowerCase() !== "bearer") return void 0;
+	return authHeader.slice(separator + 1);
+}
+//#endregion
+//#region src/auth/api-keys/api-key-middleware.ts
+/**
+* Check whether a token looks like a Rebase API key.
+*/
+function isApiKeyToken(token) {
+	return token.startsWith("rk_");
+}
+/**
+* Verify a presented key: it exists, is live, and — for a personal key —
+* personal keys are on and its owner still exists. Records the use.
+*
+* `access` is the backend the key belongs to: whether it takes personal keys,
+* how it finds their owners, and what their roles hold. The process default
+* when omitted.
+*/
+async function resolveApiKey(store, token, access = processAccessControl) {
+	const apiKey = await store.findByKeyHash(await sha256Hex(token));
+	if (!apiKey) return { message: "Invalid API key" };
+	const identity = await identityOfKey(apiKey, access);
+	if (!("uid" in identity)) return identity;
+	const lastTouch = lastUsedTouchedAt.get(apiKey.id);
+	const now = Date.now();
+	if (!lastTouch || now - lastTouch >= LAST_USED_DEBOUNCE_MS) {
+		lastUsedTouchedAt.set(apiKey.id, now);
+		store.updateLastUsed(apiKey.id).catch(() => {});
+	}
+	const masked = {
+		id: apiKey.id,
+		name: apiKey.name,
+		kind: apiKey.kind,
+		key_prefix: apiKey.key_prefix,
+		scopes: apiKey.scopes,
+		roles: apiKey.roles,
+		owner_uid: apiKey.owner_uid,
+		rate_limit: apiKey.rate_limit,
+		created_by: apiKey.created_by,
+		created_at: apiKey.created_at,
+		updated_at: apiKey.updated_at,
+		last_used_at: apiKey.last_used_at,
+		expires_at: apiKey.expires_at,
+		revoked_at: apiKey.revoked_at
+	};
+	return {
+		...identity,
+		apiKey: masked
+	};
+}
+/**
+* What a collection callback is told about the key a request authenticated
+* with (`context.credential`): its kind, id and name, never the secret.
+*/
+function credentialOf(apiKey) {
+	return {
+		kind: apiKey.kind,
+		id: apiKey.id,
+		name: apiKey.name
+	};
+}
+/**
+* Who a stored key acts as and what it holds — the half of
+* {@link resolveApiKey} that does not depend on how the key was found. The RLS
+* simulator asks it of a key named by id, so "view as this key" and a request
+* presenting the key cannot drift apart.
+*/
+async function identityOfKey(apiKey, access = processAccessControl) {
+	if (apiKey.revoked_at) return { message: "API key has been revoked" };
+	if (apiKey.expires_at && new Date(apiKey.expires_at) < /* @__PURE__ */ new Date()) return { message: "API key has expired" };
+	if (apiKey.kind === "personal") {
+		const resolveOwner = access.resolveKeyOwner;
+		if (!resolveOwner || !apiKey.owner_uid) return { message: "Personal API keys are switched off on this backend" };
+		const owner = await resolveOwner(apiKey.owner_uid);
+		if (!owner) return { message: "The account this API key acts as no longer exists" };
+		return {
+			uid: apiKey.owner_uid,
+			roles: owner.roles,
+			scopes: intersectScopes(apiKey.scopes, scopesForRoles(owner.roles, access.model))
+		};
+	}
+	return {
+		uid: `api-key:${apiKey.id}`,
+		roles: ["service", ...apiKey.roles.filter((role) => role !== "service")],
+		scopes: apiKey.scopes
+	};
+}
+/** Per-process debounce state for last_used_at touches. */
+var lastUsedTouchedAt = /* @__PURE__ */ new Map();
+var LAST_USED_DEBOUNCE_MS = 6e4;
+/**
+* Validate an API key token and populate the Hono context: `user`, `apiKey`,
+* `scopes` and the RLS-scoped `driver`.
+*
+* Returns `true` when the context is populated, or the error Response.
+*/
+async function validateApiKey(c, token, options) {
+	const resolved = await resolveApiKey(options.store, token, accessOf(c));
+	if (!("uid" in resolved)) return errorHandler(ApiError.unauthenticated(resolved.message), c);
+	c.set("user", {
+		uid: resolved.uid,
+		roles: resolved.roles
+	});
+	c.set("apiKey", resolved.apiKey);
+	c.set("scopes", resolved.scopes);
+	try {
+		c.set("driver", await scopeDataDriver(options.driver, {
+			uid: resolved.uid,
+			roles: resolved.roles,
+			credential: credentialOf(resolved.apiKey)
+		}));
+	} catch (error) {
+		logger.error("[AUTH] RLS scoping failed for API key", { error });
+		return errorHandler(ApiError.internal("Internal authentication error"), c);
+	}
+	return true;
+}
+/**
+* The 403 for a credential that lacks a data-plane scope outside the REST
+* generator (storage and functions). Names the scope that would grant it.
+*/
+function forbidScope(c, scope, target) {
+	const wanted = target !== void 0 && target !== "" ? `${scope}:${target}` : scope;
+	return errorHandler(new ApiError(403, "SCOPE_MISSING", `This credential does not hold the "${wanted}" scope.`, { requiredScope: wanted }), c);
+}
+/** Whether this request's caller holds `scope` — on `target` when given. */
+function callerHolds(c, scope, target) {
+	const narrowed = c.get("scopes");
+	if (!narrowed) return true;
+	return target === void 0 ? scopeGrantsAny(narrowed, scope) : scopeGrants(narrowed, scope, target);
+}
+/**
+* Scope guard for the resumable-upload routes (`/tus/:id`).
+*
+* Every step of an upload — the offset check (HEAD), the chunks (PATCH), the
+* cancel (DELETE) — is part of writing it, so all of them need
+* `storage:write`. Which source the upload writes to was checked when it was
+* created; these steps only reach an upload the same caller owns.
+*/
+function createTusScopeGuard() {
+	return async (c, next) => {
+		if (/\/tus\/[^/]+$/.test(c.req.path) && c.get("user") && !callerHolds(c, "storage:write")) return forbidScope(c, "storage:write");
+		return next();
+	};
+}
+/**
+* Scope guard for the custom-functions router: a narrowed credential needs
+* `functions:invoke` on the function it calls. The functions index — the
+* listing at the mount point itself — needs the unqualified scope.
+*
+* People pass: what a person may do inside a function is the function's own
+* business, as it always was.
+*
+* @param mountPrefix - The path the functions router is mounted at
+*                      (e.g. `/api/functions`), used to extract the function
+*                      name from the request path. Omitted, it is the
+*                      `mountPath` the functions group recorded for this
+*                      request — wherever the application mounted it.
+*
+* It also keeps "Simulate access" read-only here: a function called with a
+* simulation header by any verb but GET, HEAD or OPTIONS is refused
+* (`SIMULATION_READ_ONLY`), since it would run as the simulated identity.
+*/
+function createFunctionScopeGuard(mountPrefix) {
+	return async (c, next) => {
+		try {
+			refuseSimulatedWrite(c, httpMethodToOperation(c.req.method));
+		} catch (error) {
+			return errorHandler(error instanceof Error ? error : new Error(String(error)), c);
+		}
+		const narrowed = c.get("scopes");
+		if (!narrowed) return next();
+		const path = c.req.path;
+		const prefix = mountPrefix ?? c.get("mountPath") ?? "";
+		const idx = path.indexOf(prefix);
+		const rawName = (idx < 0 ? "" : path.slice(idx + prefix.length)).split("/").filter(Boolean)[0] ?? "";
+		let functionName;
+		try {
+			functionName = decodeURIComponent(rawName);
+		} catch {
+			functionName = rawName;
+		}
+		if (!(functionName === "" ? scopeGrants(narrowed, "functions:invoke") : scopeGrants(narrowed, "functions:invoke", functionName))) return forbidScope(c, "functions:invoke", functionName);
+		return next();
+	};
+}
+/**
+* Pre-auth middleware for `rk_` bearer tokens.
+*
+* Routers whose auth gate is JWT-based (`createRequireAuth` — the admin
+* surfaces, the key routes) don't know about API keys. Mounted in front of
+* them, this authenticates `rk_` tokens and populates the request context; the
+* downstream gates then see the already-resolved caller and check its scopes.
+*
+* Requests without an `rk_` bearer token pass through untouched. An invalid,
+* revoked, or expired `rk_` token is rejected here (401) rather than falling
+* through to be misparsed as a JWT.
+*/
+function createApiKeyPreAuth(options) {
+	return async (c, next) => {
+		if (c.get("apiKey")) return next();
+		const token = extractBearerToken(c.req.header("authorization")) ?? "";
+		if (!token || !isApiKeyToken(token)) return next();
+		const result = await validateApiKey(c, token, options);
+		if (result !== true) return result;
+		return next();
+	};
+}
+/** Roles that mean "no session at all". */
+var ANONYMOUS_ROLES = /* @__PURE__ */ new Set(["anon", "anonymous"]);
+var ADMIN_ONLY$1 = "Only a signed-in administrator can simulate another role, user or API key.";
+/** Read the three simulation headers, or `undefined` when none was sent. */
+function simulationOf(header) {
+	const role = header(SIMULATE_ROLE_HEADER);
+	const userId = header(SIMULATE_USER_ID_HEADER);
+	const apiKeyId = header(SIMULATE_API_KEY_ID_HEADER);
+	if (role === void 0 && userId === void 0 && apiKeyId === void 0) return void 0;
+	return {
+		...role !== void 0 ? { role } : {},
+		...userId !== void 0 ? { userId } : {},
+		...apiKeyId !== void 0 ? { apiKeyId } : {}
+	};
+}
+/** Whether a request carries any simulation header. */
+function carriesSimulation(header) {
+	return simulationOf(header) !== void 0;
+}
+/**
+* Decide whether this caller may simulate what they asked for, and who the
+* request then runs as.
+*
+* The caller is judged before anything they named is looked up, so a refusal
+* says nothing about whether a user or key exists. Throws when a lookup fails.
+*/
+async function decideSimulation(request) {
+	const { credential, caller, resolveUser, apiKeyStore, audit } = request;
+	const role = request.simulation.role?.trim();
+	const userId = request.simulation.userId?.trim();
+	const apiKeyId = request.simulation.apiKeyId?.trim();
+	const refuse = (reason, error) => {
+		if (audit) logger.warn("[Security Audit] Refused a request to simulate access", {
+			eventType: "auth.simulation.refused",
+			reason,
+			callerUid: caller?.uid,
+			simulation: request.simulation,
+			...audit
+		});
+		return { refused: error };
+	};
+	if (role === "" || userId === "" || apiKeyId === "") return refuse("malformed", ApiError.badRequest("A simulation header was sent empty. Name a role, a user id or an API key id, or leave the header out.", "SIMULATION_INVALID"));
+	if (apiKeyId !== void 0 && (role !== void 0 || userId !== void 0)) return refuse("malformed", ApiError.badRequest(`${SIMULATE_API_KEY_ID_HEADER} runs as the key's own identity and roles, so it cannot be combined with ${SIMULATE_ROLE_HEADER} or ${SIMULATE_USER_ID_HEADER}.`, "SIMULATION_INVALID"));
+	if (credential !== "session" || !caller || !hasAdminRole(caller.roles)) return refuse(credential === "session" ? "not-admin" : credential, ApiError.forbidden(ADMIN_ONLY$1, "SIMULATION_FORBIDDEN"));
+	if (!resolveUser) return refuse("unavailable", new ApiError(501, "SIMULATION_UNAVAILABLE", "This backend's auth cannot confirm an administrator's roles: its auth adapter does not implement resolveUser."));
+	const self = await resolveUser(caller.uid);
+	if (!self || !hasAdminRole(self.roles)) return refuse("not-admin", ApiError.forbidden(ADMIN_ONLY$1, "SIMULATION_FORBIDDEN"));
+	let identity;
+	if (apiKeyId !== void 0) {
+		if (!apiKeyStore) return refuse("unavailable", new ApiError(501, "SIMULATION_UNAVAILABLE", "This backend has no API keys to simulate."));
+		const key = await apiKeyStore.getApiKeyById(apiKeyId);
+		const keyIdentity = key ? await identityOfKey(key, request.access) : void 0;
+		if (!key || !keyIdentity || !("uid" in keyIdentity)) return refuse("unknown-target", ApiError.notFound(`No active API key has the id "${apiKeyId}", so there is nothing to simulate.`, "SIMULATION_TARGET_NOT_FOUND"));
+		identity = {
+			uid: keyIdentity.uid,
+			roles: keyIdentity.roles,
+			isAnonymous: false,
+			scopes: keyIdentity.scopes,
+			apiKey: key,
+			role: keyIdentity.roles.join(",")
+		};
+	} else if (role !== void 0) identity = ANONYMOUS_ROLES.has(role) && userId === void 0 ? {
+		uid: ANONYMOUS_USER_ID,
+		roles: ["anon"],
+		isAnonymous: false,
+		role
+	} : {
+		uid: userId ?? "00000000-0000-0000-0000-000000000000",
+		roles: [role],
+		isAnonymous: false,
+		role
+	};
+	else {
+		const target = userId === void 0 ? null : await resolveUser(userId);
+		if (!target) return refuse("unknown-target", ApiError.notFound(`No active user has the id "${userId ?? ""}". Send ${SIMULATE_ROLE_HEADER} as well to simulate a uid that has no account.`, "SIMULATION_TARGET_NOT_FOUND"));
+		identity = {
+			uid: target.uid,
+			roles: target.roles,
+			isAnonymous: target.isAnonymous === true,
+			...target.claims ? { claims: target.claims } : {},
+			role: target.roles.join(",")
+		};
+	}
+	if (audit) logger.info("[Security Audit] Ran a request with simulated access", {
+		eventType: "auth.simulation",
+		simulatorUid: caller.uid,
+		targetUid: identity.uid,
+		targetRoles: identity.roles,
+		...identity.apiKey ? { apiKeyId: identity.apiKey.id } : {},
+		...audit
+	});
+	return {
+		granted: identity,
+		simulator: caller.uid
+	};
+}
+/** The caller the auth middleware put on the context, narrowed. */
+function callerOf$1(c) {
+	const user = c.get("user");
+	if (typeof user !== "object" || user === null) return void 0;
+	const uid = "uid" in user && typeof user.uid === "string" && user.uid !== "" ? user.uid : void 0;
+	if (uid === void 0) return void 0;
+	return {
+		uid,
+		roles: "roles" in user && Array.isArray(user.roles) ? user.roles.filter((entry) => typeof entry === "string") : []
+	};
+}
+/**
+* Honour or refuse this request's simulation headers.
+*
+* Called by the data-plane auth middlewares once the caller is on the context
+* and before impersonation, which it excludes. On a grant the context's
+* `user`, `driver`, `scopes` and `apiKey` become the simulated identity's,
+* `impersonator` names the administrator for the request log, and
+* `simulation` records what to report on the response.
+*
+* @returns The refusal to send, or `undefined` to carry on.
+*/
+async function applySimulation(c, { credential, driver, resolveUser, apiKeyStore }) {
+	const simulation = simulationOf((name) => c.req.header(name));
+	if (simulation === void 0) return void 0;
+	if (c.req.header("x-rebase-impersonate") !== void 0) return errorHandler(ApiError.badRequest(`A request either impersonates a user (${IMPERSONATE_HEADER}) or simulates access, not both.`, "SIMULATION_INVALID"), c);
+	let decision;
+	try {
+		decision = await decideSimulation({
+			simulation,
+			credential,
+			caller: callerOf$1(c),
+			resolveUser,
+			apiKeyStore,
+			access: accessOf(c),
+			audit: {
+				door: "http",
+				method: c.req.method,
+				path: c.req.path,
+				requestId: c.get("requestId")
+			}
+		});
+	} catch (error) {
+		return errorHandler(error instanceof Error ? error : new Error(String(error)), c);
+	}
+	if ("refused" in decision) return errorHandler(decision.refused, c);
+	const identity = decision.granted;
+	c.set("user", identity.uid === "anonymous" ? void 0 : {
+		uid: identity.uid,
+		roles: identity.roles,
+		isAnonymous: identity.isAnonymous
+	});
+	c.set("impersonator", { uid: decision.simulator });
+	c.set("scopes", identity.scopes);
+	c.set("apiKey", identity.apiKey);
+	c.set("simulation", {
+		role: identity.role,
+		sub: identity.uid,
+		roles: identity.roles,
+		...identity.apiKey ? { apiKeyId: identity.apiKey.id } : {}
+	});
+	try {
+		c.set("driver", await scopeDataDriver(driver, {
+			uid: identity.uid,
+			roles: identity.roles,
+			isAnonymous: identity.isAnonymous,
+			...identity.claims ? { claims: identity.claims } : {}
+		}));
+	} catch (error) {
+		logger.error("[AUTH] RLS scoping failed for a simulated request", { error });
+		return errorHandler(ApiError.internal("Internal authentication error"), c);
+	}
+}
+/**
+* The fields of `collection` the roles cannot read: what the driver strips
+* from every row it hands them. Fields hidden from everyone (`excludeFromApi`)
+* are left out — no role sees those, so they say nothing about this one.
+*/
+function maskedFieldsFor(collection, roles) {
+	const hiddenFromAll = apiHiddenFieldNames(collection);
+	return restrictedFieldNames(collection, { roles }, "read").declared.filter((name) => !hiddenFromAll.has(name));
+}
+/**
+* Name what a simulated request ran as on its response
+* ({@link SIMULATED_CONTEXT_HEADER}), refusals included.
+*
+* Mounted ahead of the data-plane groups; it reads, after the request is
+* answered, what {@link applySimulation} and the REST generator recorded on
+* the context — the identity, and which collection the request was about.
+*/
+function reportSimulatedContext() {
+	return async (c, next) => {
+		await next();
+		const simulation = c.get("simulation");
+		if (!simulation) return;
+		const slug = c.get("collection");
+		const collection = slug ? c.get("services")?.collections().find((entry) => entry.slug === slug) : void 0;
+		const value = formatSimulatedContext({
+			role: simulation.role,
+			sub: simulation.sub,
+			maskedColumns: collection ? maskedFieldsFor(collection, simulation.roles) : [],
+			...simulation.apiKeyId ? { apiKeyId: simulation.apiKeyId } : {},
+			...slug ? { collection: slug } : {}
+		});
+		try {
+			c.res.headers.set(SIMULATED_CONTEXT_HEADER, value);
+		} catch {}
+	};
+}
+//#endregion
+//#region src/auth/impersonation.ts
+var ADMIN_ONLY = "Only a signed-in administrator can run a request as another user.";
+var NOT_A_PERSON = {
+	"api-key": {
+		reason: "api-key",
+		message: "An API key cannot run a request as another user. Send it with an administrator's session instead."
+	},
+	"service-key": {
+		reason: "service-key",
+		message: "The service key cannot run a request as another user. Send it with an administrator's session instead."
+	},
+	none: {
+		reason: "anonymous",
+		message: ADMIN_ONLY
+	}
+};
+/**
+* Decide whether this caller may act as the user they named, and who that
+* user is now.
+*
+* The one decision both doors take — the HTTP data plane through
+* {@link applyImpersonation}, the realtime socket at `AUTHENTICATE` and before
+* every frame after it. The caller is judged before the named user is looked
+* up, so the answer to a caller who may not impersonate says nothing about
+* whether the uid exists.
+*
+* Throws when a lookup fails: that is not an answer about anyone, and each
+* door refuses it its own way.
+*/
+async function decideImpersonation(request) {
+	const { credential, caller, resolveUser, audit } = request;
+	const targetUid = request.requestedUid.trim();
+	const refuse = (reason, error) => {
+		if (audit) logger.warn("[Security Audit] Refused a request to act as another user", {
+			eventType: "auth.impersonation.refused",
+			reason,
+			callerUid: caller?.uid,
+			requestedUid: targetUid,
+			...audit
+		});
+		return { refused: error };
+	};
+	if (targetUid === "") return refuse("malformed", ApiError.badRequest(`The ${IMPERSONATE_HEADER} header names no user. Send the uid of the user to act as, or leave the header out.`, "IMPERSONATION_INVALID"));
+	if (credential !== "session") {
+		const { reason, message } = NOT_A_PERSON[credential];
+		return refuse(reason, ApiError.forbidden(message, "IMPERSONATION_FORBIDDEN"));
+	}
+	if (!caller || !hasAdminRole(caller.roles)) return refuse("not-admin", ApiError.forbidden(ADMIN_ONLY, "IMPERSONATION_FORBIDDEN"));
+	if (!resolveUser) return refuse("unavailable", new ApiError(501, "IMPERSONATION_UNAVAILABLE", "This backend's auth cannot run a request as another user: its auth adapter does not implement resolveUser."));
+	const self = await resolveUser(caller.uid);
+	if (!self || !hasAdminRole(self.roles)) return refuse("not-admin", ApiError.forbidden(ADMIN_ONLY, "IMPERSONATION_FORBIDDEN"));
+	const target = await resolveUser(targetUid);
+	if (!target) return refuse("unknown-target", ApiError.notFound(`No active user has the id "${targetUid}", so there is nobody to run this request as.`, "IMPERSONATION_TARGET_NOT_FOUND"));
+	if (audit) logger.info("[Security Audit] Ran a request as another user", {
+		eventType: "auth.impersonation",
+		impersonatorUid: caller.uid,
+		targetUid: target.uid,
+		targetRoles: target.roles,
+		...audit
+	});
+	return {
+		granted: target,
+		impersonator: caller.uid
+	};
+}
+/** The caller the auth middleware put on the context, narrowed. */
+function callerOf(c) {
+	const user = c.get("user");
+	if (typeof user !== "object" || user === null) return void 0;
+	const uid = "uid" in user && typeof user.uid === "string" && user.uid !== "" ? user.uid : void 0;
+	if (uid === void 0) return void 0;
+	return {
+		uid,
+		roles: "roles" in user && Array.isArray(user.roles) ? user.roles.filter((role) => typeof role === "string") : []
+	};
+}
+/**
+* Honour or refuse this request's {@link IMPERSONATE_HEADER}.
+*
+* Called by the data-plane auth middlewares once the caller is on the context
+* and its driver is scoped. When the header names a user the caller may act
+* as, the context's `user` and `driver` are replaced with that user's and
+* `impersonator` names the caller.
+*
+* @returns The refusal to send, or `undefined` to carry on — as the caller
+*          when the header is absent, as the named user when it was granted.
+*/
+async function applyImpersonation(c, { credential, driver, resolveUser }) {
+	const requested = c.req.header(IMPERSONATE_HEADER);
+	if (requested === void 0) return void 0;
+	const caller = callerOf(c);
+	let decision;
+	try {
+		decision = await decideImpersonation({
+			requestedUid: requested,
+			credential,
+			caller,
+			resolveUser,
+			audit: {
+				door: "http",
+				method: c.req.method,
+				path: c.req.path,
+				requestId: c.get("requestId")
+			}
+		});
+	} catch (error) {
+		return errorHandler(error instanceof Error ? error : new Error(String(error)), c);
+	}
+	if ("refused" in decision) return errorHandler(decision.refused, c);
+	const target = decision.granted;
+	const isAnonymous = target.isAnonymous === true;
+	c.set("user", {
+		uid: target.uid,
+		email: target.email,
+		roles: target.roles,
+		isAnonymous
+	});
+	c.set("impersonator", { uid: decision.impersonator });
+	try {
+		c.set("driver", await scopeDataDriver(driver, {
+			uid: target.uid,
+			roles: target.roles,
+			isAnonymous,
+			...target.claims ? { claims: target.claims } : {}
+		}));
+	} catch (error) {
+		logger.error("[AUTH] RLS scoping failed for an impersonated request", { error });
+		return errorHandler(ApiError.internal("Internal authentication error"), c);
+	}
+}
+/**
+* Refuse {@link IMPERSONATE_HEADER} — and the RLS simulator's
+* `x-rebase-simulate-*` headers (`auth/simulation.ts`) — on every route that
+* does not honour it.
+*
+* Only the data API and custom functions run a request as another user; the
+* rest — storage, auth, the admin surfaces — authenticate the caller and
+* ignore the header. Ignored, a request asking to act as B would be answered
+* as the administrator who sent it, which is the one outcome impersonation
+* must never have. Mounted ahead of every route, so a surface added later is
+* refused until it is listed here as honouring the header.
+*
+* @param honouredMounts - The mount points whose auth middleware applies the
+*        header (`/api/data`, `/api/functions`). A path is under one when it
+*        is the mount itself or continues it with a `/`.
+*/
+function refuseUnhonouredImpersonation(honouredMounts) {
+	return async (c, next) => {
+		const impersonating = c.req.header(IMPERSONATE_HEADER) !== void 0;
+		const simulating = carriesSimulation((name) => c.req.header(name));
+		if (!impersonating && !simulating) return next();
+		const path = c.req.path;
+		if (honouredMounts.some((mount) => path === mount || path.startsWith(`${mount}/`))) return next();
+		logger.warn(impersonating ? "[Security Audit] Refused a request to act as another user" : "[Security Audit] Refused a request to simulate access", {
+			eventType: impersonating ? "auth.impersonation.refused" : "auth.simulation.refused",
+			reason: "unsupported-route",
+			method: c.req.method,
+			path,
+			requestId: c.get("requestId")
+		});
+		return errorHandler(impersonating ? ApiError.badRequest(`This route cannot run as another user, so it refuses the ${IMPERSONATE_HEADER} header. Only the data API and custom functions honour it.`, "IMPERSONATION_UNSUPPORTED") : ApiError.badRequest("This route cannot run with simulated access, so it refuses the x-rebase-simulate-* headers. Only the data API and custom functions honour them.", "SIMULATION_UNSUPPORTED"), c);
+	};
+}
+//#endregion
+//#region src/storage/requested-object.ts
+/**
+* Which object a storage request's URL path names.
+*
+* Three parties read the path of a `GET /file/*`, `GET /metadata/*` or
+* `DELETE /file/*`: the route, which serves or deletes an object;
+* `publicObjectAuth`, which lets an anonymous caller through when that object
+* is public; and `fileTokenAuth`, which compares it with the path a download
+* token grants. A decision is only about the object acted on if it is made on
+* the same key, so all three derive it here — the wildcard, the decoding, the
+* bucket segment and the canonical key — and none of them spells a step of its
+* own.
+*
+* They used to. `publicObjectAuth` judged the raw path with a check that strips
+* everything up to a `://`, while the route canonicalized it, folding `//` to
+* `/`: `GET /file/notes://public/secret.txt` was public to the one and served
+* the private key `notes:/public/secret.txt` from the other, with the authorize
+* hook never asked.
+*
+* Nothing here parses a scheme. A request path is a key, optionally behind the
+* one bucket segment the routes recognise; a `://` in it is a `:` followed by
+* an empty segment, and canonicalization folds the empty segment away.
+*/
+/**
+* The wildcard part of a storage route's path, still percent-encoded.
+*
+* Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
+* via `app.route(prefix, subRouter)`. Instead it is derived from the
+* fully-resolved `c.req.path` and `c.req.routePath`.
+*
+* For a route `/metadata/*` mounted at `/api/storage`, a request to
+* `/api/storage/metadata/default/file.jpg` yields routePath
+* `/api/storage/metadata/*`. The prefix (everything before `/*`) is stripped,
+* plus one character for the trailing `/`, to obtain `default/file.jpg`.
+*/
+function storageRequestWildcard(c) {
+	const prefix = c.req.routePath.replace("/*", "");
+	const fullPath = c.req.path;
+	const idx = fullPath.indexOf(prefix);
+	if (idx < 0) return "";
+	return fullPath.substring(idx + prefix.length + 1);
+}
+/**
+* The object a decoded path names: a key, behind an optional `default/` bucket
+* segment (matched case-insensitively). Throws {@link InvalidStorageKeyError}
+* when the key cannot be canonicalized.
+*
+* For a path that is already text — the folder route's JSON body. A URL path
+* goes through {@link requestedStorageObject}, which decodes it first.
+*/
+function storageObjectOfPath(decodedPath) {
+	const parts = decodedPath.split("/");
+	return {
+		bucket: "default",
+		key: canonicalStorageKey(parts.length > 1 && parts[0].toLowerCase() === "default" ? parts.slice(1).join("/") : decodedPath)
+	};
+}
+/**
+* The object a request's wildcard path names, or {@link InvalidStorageKeyError}.
+*
+* The wildcard arrives as Hono leaves it — `decodeURI`d, with the reserved
+* characters (`/`, `:`, `%25` among them) still escaped — so one
+* `decodeURIComponent` yields the path the client encoded. A `%` that does not
+* begin an escape names no key, and is refused like any other key that cannot be
+* canonicalized rather than thrown as a `URIError`.
+*/
+function requestedStorageObject(wildcard) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(wildcard);
+	} catch {
+		throw new InvalidStorageKeyError("Storage path is not valid percent-encoding: a '%' must begin an escape such as '%25' (a literal '%').");
+	}
+	return storageObjectOfPath(decoded);
+}
+/**
+* {@link requestedStorageObject}, or `null` when the path names no object.
+*
+* For the middleware, which must fail closed without an exception: a path that
+* names no object is neither public nor covered by any download token, and the
+* route answers it with a 400 of its own.
+*/
+function tryRequestedStorageObject(wildcard) {
+	try {
+		return requestedStorageObject(wildcard);
+	} catch (err) {
+		if (err instanceof InvalidStorageKeyError) return null;
+		throw err;
+	}
+}
+//#endregion
+//#region src/storage/request-principals.ts
+/**
+* The two principals a storage read can be granted without a user: the reader
+* of a declared-public object, and the bearer of a download token.
+*
+* `checkAuthorized` does not ask the `storageAuthorize` hook about either — the
+* public prefix and the token are the authorization. That skip used to be
+* decided on the principal's `uid` string (`"public"`, `"download-token"`), so
+* any identity carrying that uid skipped the hook: a custom `AuthAdapter` whose
+* `verifyRequest` returns `{ uid: "public" }` for a guest could then upload,
+* delete and list anywhere, with the hook never asked.
+*
+* Each principal is now one object, set only by the middleware that granted
+* it (`publicObjectAuth`, `fileTokenAuth`) and recognised by identity. An
+* adapter builds a new object per request, so it can name the uid but never be
+* the grant.
+*/
+/** The principal `publicObjectAuth` grants an anonymous read of a public object. */
+var PUBLIC_OBJECT_PRINCIPAL = Object.freeze({
+	uid: "public",
+	roles: ["public"]
+});
+/** The principal `fileTokenAuth` grants a read covered by a valid download token. */
+var DOWNLOAD_TOKEN_PRINCIPAL = Object.freeze({
+	uid: "download-token",
+	roles: ["reader"]
+});
+/** Whether `user` is the grant `publicObjectAuth` made — the object, not the uid. */
+function isPublicObjectGrant(user) {
+	return user === PUBLIC_OBJECT_PRINCIPAL;
+}
+/** Whether `user` is the grant `fileTokenAuth` made — the object, not the uid. */
+function isDownloadTokenGrant(user) {
+	return user === DOWNLOAD_TOKEN_PRINCIPAL;
+}
+//#endregion
+//#region src/auth/middleware.ts
+/**
+* Answer a refusal with the canonical envelope, through the same formatter
+* every route uses.
+*
+* These middlewares used to hand-build `c.json({ error: { message, code } },
+* 401)` — seven near-copies of it, which is how they came to omit `requestId`
+* while every other error on the server carried it: the one string a bug report
+* quotes was missing from precisely the errors an app hits most. It also meant
+* a routine 401 (a client refreshing before it knows whether a session exists)
+* logged like an incident, because `ApiError.expected` never reached the
+* logger.
+*
+* `errorHandler` is *called* rather than thrown to. A throw only becomes an
+* envelope where an `onError` is registered, and these middlewares are mounted
+* by callers this package does not control — `defineFunction` hands users a
+* Hono app and invites them to put `requireAuth` on a route of it. Making the
+* status depend on the mount point would turn a 401 into a 500 for exactly
+* those callers. Calling the formatter directly gets the envelope with none of
+* that.
+*/
+function refuse(c, error) {
+	return errorHandler(error, c);
+}
+/**
+* Hono middleware that requires a valid JWT token via Authorization header.
+* Returns 401 if token is missing or invalid.
+*
+* **Security:** Tokens are only accepted via the `Authorization: Bearer`
+* header. Query-string tokens (`?token=`) are intentionally NOT accepted
+* here because URLs leak into access logs, proxies, Referer headers, and
+* browser history. Use {@link queryTokenAuth} on routes that legitimately
+* need query-string tokens (e.g. storage file serving for `<img src>`).
+*/
+var requireAuth = async (c, next) => {
+	if (c.get("user")) return next();
+	const token = extractBearerToken(c.req.header("authorization"));
+	if (token === void 0) return refuse(c, ApiError.unauthenticated("Authorization header missing or invalid"));
+	const payload = await jwtOf(c).verifyAccessToken(token);
+	if (!payload) return refuse(c, ApiError.unauthenticated("Invalid or expired token"));
+	c.set("user", payload);
+	return next();
+};
+/**
+* Factory that creates a requireAuth middleware with optional service key support.
+*
+* When `serviceKey` is provided, the middleware will check if the Bearer token
+* matches the service key using constant-time comparison. If it matches, the
+* request is authenticated as a service user with admin privileges.
+*
+* This allows admin routes (which use standalone requireAuth + requireAdmin)
+* to be accessed via service keys for scripts and server-to-server calls.
+*/
+function createRequireAuth(options) {
+	if (!options?.serviceKey && !options?.resolveRoles && !options?.revocationRepo) 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"));
+		if (token === void 0) return refuse(c, ApiError.unauthenticated("Authorization header missing or invalid"));
+		if (key !== void 0 && safeCompare(token, key)) {
+			c.set("user", {
+				uid: "service",
+				roles: ["admin"]
+			});
+			return next();
+		}
+		const payload = await jwtOf(c).verifyAccessToken(token);
+		if (!payload) return refuse(c, ApiError.unauthenticated("Invalid or expired token"));
+		if (resolveRoles || revocationRepo) try {
+			let judgedRoles;
+			if (revocationRepo) {
+				const verdict = await judgeAccessToken(revocationRepo, payload);
+				if (!verdict.live) return refuse(c, accessTokenRefusalError(verdict.refusal));
+				judgedRoles = verdict.roles;
+			}
+			c.set("user", resolveRoles ? {
+				...payload,
+				roles: judgedRoles ?? await resolveRoles(payload.uid)
+			} : payload);
+			return next();
+		} catch (error) {
+			if (isDatabaseUnreachable(error)) {
+				if (!warnIfDatabaseClosed(error)) logger.warn("[Auth] Could not resolve roles for an admin-gated request: the database is unreachable", { uid: payload.uid });
+				return refuse(c, ApiError.databaseUnavailable());
+			}
+			logger.warn("[Auth] Could not resolve roles for an admin-gated request", {
+				uid: payload.uid,
+				error
+			});
+			return refuse(c, ApiError.serviceUnavailable("Could not verify your permissions. Please try again.", "ROLE_LOOKUP_FAILED"));
+		}
+		c.set("user", payload);
+		return next();
+	};
+}
+/**
+* Middleware that requires the user to hold the `admin` role, which holds
+* every scope. Must be used AFTER requireAuth or on a route where user is
+* guaranteed.
+*
+* Prefer `requireScope` from `./access` for anything a scope names: a scope
+* can be granted to a narrower role and to a key, and `admin` cannot.
+*/
+var requireAdmin = async (c, next) => {
+	const user = c.get("user");
+	if (!user) return refuse(c, ApiError.unauthorized("User not authenticated. requireAuth middleware is missing?"));
+	if (!hasAdminRole(typeof user === "object" && user !== null && "roles" in user && Array.isArray(user.roles) ? user.roles.filter((role) => typeof role === "string") : [])) return refuse(c, ApiError.forbidden("Admin privileges required for this operation"));
+	return next();
+};
+/**
+* Middleware that optionally extracts user from JWT via Authorization header.
+* Does not return 401 if token is missing — allows anonymous access.
+*
+* Query-string tokens are NOT accepted here. Use {@link queryTokenAuth}
+* on routes that need them.
+*/
+var optionalAuth = async (c, next) => {
+	if (c.get("user")) return next();
+	const token = extractBearerToken(c.req.header("authorization"));
+	const jwt = jwtOf(c);
+	if (token !== void 0 && jwt.isConfigured()) {
+		const payload = await jwt.verifyAccessToken(token);
+		if (payload) c.set("user", payload);
+	}
+	return next();
+};
+/**
+* Who a session token names, as `jwt` verifies it — or "nobody" rather than a
+* throw on a backend with no JWT of its own, so a socket closes as
+* unauthenticated, which is the outcome this describes.
+*/
+async function userFromToken(jwt, token) {
+	if (!jwt.isConfigured()) return null;
+	return jwt.verifyAccessToken(token);
+}
+/**
+* Extract user from token - for WebSocket authentication. Answers for the
+* process default; a backend's own socket verifies with its own keys.
+*/
+async function extractUserFromToken(token) {
+	return userFromToken(processJwtService, token);
+}
+/**
+* Create a configurable auth middleware that handles:
+* 1. Token extraction (via custom validator or JWT Bearer token)
+* 2. RLS-scoped DataDriver via withAuth()
+* 3. Enforcement (401 when requireAuth is true and no user)
+*
+* **Secure by default:** `requireAuth` defaults to `true`. Anonymous
+* access is only allowed when the developer explicitly opts out by
+* setting `requireAuth: false`, indicating that Postgres RLS policies
+* fully control access.
+*
+* **Fail-closed:** The raw unscoped driver is never placed in the
+* request context. Every code path either scopes via `withAuth()` or
+* rejects the request. This prevents silent RLS bypass.
+*
+* This is the single source of truth for HTTP auth in Rebase.
+* Use this instead of manually parsing tokens in route handlers.
+*/
+function createAuthMiddleware(options) {
+	const { driver: baseDriver, resolveDriver, requireAuth: enforceAuth = true, validator, serviceKey, apiKeyStore } = options;
+	return async (c, next) => {
+		const driver = resolveDriver ? resolveDriver(c) : baseDriver;
+		let credential = "none";
+		if (validator) try {
+			const authResult = await validator(c);
+			if (authResult && typeof authResult === "object") {
+				const id = "uid" in authResult ? authResult.uid : void 0;
+				if (id) {
+					const roles = authResult.roles || [];
+					credential = "session";
+					c.set("user", {
+						uid: id,
+						roles
+					});
+					const user = {
+						uid: id,
+						roles,
+						...authResult
+					};
+					c.set("driver", await scopeDataDriver(driver, user));
+				} else c.set("driver", await scopeDataDriver(driver, {
+					uid: ANONYMOUS_USER_ID,
+					roles: ["anon"]
+				}));
+			} else if (authResult === true) {
+				credential = "session";
+				c.set("user", {
+					uid: "default",
+					roles: []
+				});
+				c.set("driver", await scopeDataDriver(driver, {
+					uid: "default",
+					roles: []
+				}));
+			} else c.set("driver", await scopeDataDriver(driver, {
+				uid: ANONYMOUS_USER_ID,
+				roles: ["anon"]
+			}));
+		} catch (error) {
+			return refuse(c, ApiError.unauthenticated("Unauthorized"));
+		}
+		else {
+			const token = extractBearerToken(c.req.header("authorization"));
+			if (token !== void 0) if (serviceKey && safeCompare(token, serviceKey)) {
+				const serviceUser = {
+					uid: "service",
+					roles: ["admin"]
+				};
+				credential = "service-key";
+				c.set("user", serviceUser);
+				try {
+					c.set("driver", await scopeDataDriver(driver, {
+						uid: "service",
+						roles: ["admin"]
+					}));
+				} catch (error) {
+					logger.error("[AUTH] RLS scoping failed for service key", { error });
+					return c.json({ error: {
+						message: "Internal authentication error",
+						code: "INTERNAL_ERROR"
+					} }, 500);
+				}
+			} else if (apiKeyStore && isApiKeyToken(token)) {
+				const result = await validateApiKey(c, token, {
+					store: apiKeyStore,
+					driver
+				});
+				if (result !== true) return result;
+				credential = "api-key";
+			} else {
+				const payload = await userFromToken(jwtOf(c), token);
+				if (payload) {
+					credential = "session";
+					c.set("user", payload);
+					try {
+						const user = {
+							uid: payload.uid,
+							roles: payload.roles,
+							isAnonymous: payload.isAnonymous === true,
+							claims: payload.claims
+						};
+						c.set("driver", await scopeDataDriver(driver, user));
+					} catch (error) {
+						logger.error("[AUTH] RLS scoping failed for authenticated user", { error });
+						return c.json({ error: {
+							message: "Internal authentication error",
+							code: "INTERNAL_ERROR"
+						} }, 500);
+					}
+				} else return refuse(c, ApiError.unauthenticated("Invalid or expired token"));
+			}
+			else try {
+				c.set("driver", await scopeDataDriver(driver, {
+					uid: ANONYMOUS_USER_ID,
+					roles: ["anon"]
+				}));
+			} catch (error) {
+				logger.error("[AUTH] Failed to create anon-scoped driver", { error });
+				return c.json({ error: {
+					message: "Server configuration error",
+					code: "INTERNAL_ERROR"
+				} }, 500);
+			}
+		}
+		const refusedSimulation = await applySimulation(c, {
+			credential,
+			driver,
+			apiKeyStore
+		});
+		if (refusedSimulation) return refusedSimulation;
+		const refused = await applyImpersonation(c, {
+			credential,
+			driver
+		});
+		if (refused) return refused;
+		if (enforceAuth && !c.get("user") && !c.get("simulation")) return refuse(c, ApiError.unauthenticated("Unauthorized: Authentication required. This is the API-level gate, not a row rule — a collection granting public reads still needs a caller. Set AUTH_REQUIRE=false (or `auth.requireAuth: false`) to let RLS alone decide."));
+		return next();
+	};
+}
+/**
+* Middleware that authenticates via a `?token=` query parameter.
+*
+* **Use sparingly.** Tokens in URLs leak into access logs, proxy logs,
+* Referer headers, and browser history. This middleware exists solely for
+* routes where the consumer cannot set HTTP headers — e.g. `<img src>`,
+* `<a href>` for file downloads, or similar browser-native requests.
+*
+* Apply it **before** `requireAuth` or `optionalAuth` on the specific
+* route that needs it. Those middlewares will see the user context this
+* middleware sets and skip their own 401 check.
+*
+* @example
+* ```ts
+* router.get("/file/*", queryTokenAuth, readAuthMiddleware, handler);
+* ```
+*/
+var queryTokenAuth = async (c, next) => {
+	if (extractBearerToken(c.req.header("authorization")) !== void 0) return next();
+	const queryToken = c.req.query("token");
+	const jwt = jwtOf(c);
+	if (queryToken && jwt.isConfigured()) {
+		const payload = await jwt.verifyAccessToken(queryToken);
+		if (payload) c.set("user", payload);
+	}
+	return next();
+};
+/**
+* Authorizes anonymous access to **public** storage objects (those under the
+* public prefix), which are served token-less via stable, permanent URLs.
+*
+* Runs on the storage `/file/*` and `/metadata/*` routes, *after* the token
+* middleware and *before* the read-auth gate. If the request is already
+* authenticated (Bearer or scoped token), it does nothing. Otherwise, when the
+* requested object path is public, it sets a minimal "public" principal so the
+* downstream `requireAuth` gate lets the read through. Private paths are left
+* untouched, so they still require a valid token.
+*
+* Public means the object the route will serve is public, so the decision is
+* made on that object's canonical key, derived by the route's own function
+* (`requestedStorageObject`). It used to be made on the raw path, through a
+* check that strips a `scheme://`: `notes://public/secret.txt` read as
+* `public/secret.txt` here while the route served the private
+* `notes:/public/secret.txt`, and the authorize hook — not asked about this
+* principal — never saw it.
+*/
+var publicObjectAuth = async (c, next) => {
+	if (c.get("user")) return next();
+	const requested = tryRequestedStorageObject(storageRequestWildcard(c));
+	if (requested && isPublicStorageKey(requested.key)) c.set("user", PUBLIC_OBJECT_PRINCIPAL);
+	return next();
+};
+/**
+* Helper to match paths for scoped file tokens.
+* Matches exact paths or prefixes (exact folder prefixes or ending with /).
+*
+* The traversal check is defence in depth, not the load-bearing defence.
+*
+* A prefix comparison is a lie for any path containing `..`: `user1/../user2/x`
+* starts with `user1/`, so a token scoped to `user1/` would authorize reading
+* user2's file — and the storage controller would not object, because its own
+* guard stops a path escaping the *bucket*, and that one resolves to `user2/x`,
+* comfortably inside it. The grant is what would be escaped, and this is the
+* only layer that knows what was granted.
+*
+* Nothing arrives here in that shape today: the URL parser resolves `..` (and
+* `%2e%2e`, which the WHATWG spec treats as a dot for normalization) before
+* Hono routes the request, so this comparison already runs on a resolved path.
+* But that is a guarantee of the runtime rather than of this code, and it is
+* one line to not depend on it. The same rule already guards the public-object
+* path — see `isPublicStorageKey`.
+*/
+function isPathMatch(requested, allowed) {
+	if (requested.split("/").some((seg) => seg === "..")) return false;
+	if (requested === allowed) return true;
+	if (allowed.endsWith("/")) return requested.startsWith(allowed);
+	return requested.startsWith(allowed + "/");
+}
+/**
+* Middleware that authenticates file-serving routes using scoped download tokens.
+* It enforces that only scoped "file-read" tokens can access "/file/*" and "?token=" query params.
+* Full access JWTs are explicitly rejected on "/file/*" routes, and in the "?token=" query param.
+*/
+var fileTokenAuth = async (c, next) => {
+	const isFileRoute = c.req.path.includes("/storage/file/");
+	const authHeader = c.req.header("authorization");
+	const queryToken = c.req.query("token");
+	/**
+	* Decide what a valid download token entitles this request to.
+	*
+	* One function rather than a copy per token location: a Bearer token and a
+	* `?token=` are the same grant presented two ways, and the whole failure
+	* this guards against is two places disagreeing about what was granted.
+	*
+	* `"no-path"` is distinct from the two denials because the caller treats it
+	* differently — a request with no object path at all is not a denied read,
+	* it is a request this middleware has nothing to say about, and on
+	* `/metadata/*` it must still reach the downstream auth gate.
+	*/
+	const evaluateGrant = (payload) => {
+		if (canonicalStorageId(c.req.query("storageId")) !== payload.storageId) return "deny-storage";
+		const rawPath = storageRequestWildcard(c);
+		if (!rawPath) return "no-path";
+		const requested = tryRequestedStorageObject(rawPath);
+		if (requested === null) return "deny-path";
+		return isPathMatch(`${requested.bucket}/${requested.key}`, payload.path) ? "grant" : "deny-path";
+	};
+	/**
+	* Which half of the scope failed is named in the message. The holder of the
+	* token already knows both values, so this reveals nothing to an attacker —
+	* and without it, a client that forgets to forward `?storageId=` on the file
+	* URL reports a "path mismatch" for a path that matches perfectly.
+	*/
+	const denyMismatch = (outcome) => refuse(c, ApiError.forbidden(outcome === "deny-storage" ? "Forbidden: Scoped token storage mismatch" : "Forbidden: Scoped token path mismatch"));
+	const bearerToken = extractBearerToken(authHeader);
+	if (bearerToken !== void 0) {
+		const token = bearerToken;
+		const payload = await jwtOf(c).verifyDownloadToken(token);
+		if (payload) {
+			const outcome = evaluateGrant(payload);
+			if (outcome === "grant") {
+				c.set("user", DOWNLOAD_TOKEN_PRINCIPAL);
+				return next();
+			}
+			if (outcome !== "no-path") return denyMismatch(outcome);
+		}
+		if (isFileRoute) return refuse(c, ApiError.unauthenticated("Unauthorized: Access JWT not allowed on file routes"));
+		return next();
+	}
+	if (queryToken) {
+		const payload = await jwtOf(c).verifyDownloadToken(queryToken);
+		if (payload) {
+			const outcome = evaluateGrant(payload);
+			if (outcome === "grant") {
+				c.set("user", DOWNLOAD_TOKEN_PRINCIPAL);
+				return next();
+			}
+			if (outcome !== "no-path") return denyMismatch(outcome);
+		}
+		return refuse(c, ApiError.unauthenticated("Unauthorized: Invalid or unauthorized token"));
+	}
+	return next();
+};
+//#endregion
+//#region src/auth/access.ts
+/**
+* How a personal key finds its owner in an account store: the account as it
+* is now — a missing or disabled one is no owner — and its roles.
+*
+* One read where the store answers both at once: `getAccountAccessState`, the
+* statement every access token is already judged against, which reads roles
+* and `disabled_at` together. Otherwise the account, then its roles — the two
+* reads this always made, one round trip more per request.
+*/
+function keyOwnerResolverFor(repo) {
+	if (typeof repo.getAccountAccessState === "function") {
+		const readAccount = repo.getAccountAccessState.bind(repo);
+		return async (uid) => {
+			const account = await readAccount(uid);
+			if (!account || account.disabled) return null;
+			return { roles: account.roles };
+		};
+	}
+	return async (uid) => {
+		const user = await repo.getUserById(uid);
+		if (!user || user.disabled) return null;
+		return { roles: await repo.getUserRoleIds(uid) };
+	};
+}
+/**
+* What the module-level API answers for: {@link getAccessModel},
+* {@link getKeyOwnerResolver}, and every scope check on a route mounted
+* outside any backend. Built-ins only until {@link configureAccess} or a
+* backend installed as the process default sets it.
+*/
+var processAccess = { model: EMPTY_ACCESS_MODEL };
+/** The process default's access model. Built-ins only until one is configured. */
+function getAccessModel() {
+	return processAccess.model;
+}
+/**
+* Set the process default's access model, and — when the app enables
+* `auth.personalKeys` and has an account store to read owners from — how
+* personal keys find their owner. For a test, or a server wired by hand that
+* uses the module-level API; a backend built by `createRebaseBackend` carries
+* its own.
+*/
+function configureAccess(options) {
+	processAccess = {
+		model: options.model,
+		resolveKeyOwner: options.resolveKeyOwner
+	};
+}
+/** @internal See {@link defaultAccessControl}. */
+function setDefaultAccessControl(access) {
+	processAccess = access;
+}
+/**
+* The process default as an {@link AccessControl} that follows it — what a
+* route or a key check built outside any backend falls back to.
+*/
+var processAccessControl = {
+	get model() {
+		return processAccess.model;
+	},
+	get resolveKeyOwner() {
+		return processAccess.resolveKeyOwner;
+	}
+};
+/**
+* The access control serving this request: the backend's whose route group is
+* answering it, or the process default for a route mounted outside any.
+*/
+function accessOf(c) {
+	return c.get("services")?.access ?? processAccessControl;
+}
+/** The resource names Rebase's own scopes use; an app scope may not reuse one. */
+var BUILT_IN_RESOURCES = new Set(BUILT_IN_SCOPES.map((scope) => scope.slice(0, scope.indexOf(":"))));
+/** A declaration the access model cannot be built from. Fails the boot. */
+var AccessModelError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AccessModelError";
+	}
+};
+/**
+* Build the access model from the users collection's `auth` block, refusing
+* anything that would read as a grant it is not.
+*
+* - `admin` may not be declared: it is built in and holds everything, and a
+*   declaration would either repeat that or quietly narrow it.
+* - An app scope may not reuse a built-in resource name (`logs:export`): the
+*   built-in resources are Rebase's, and a reader of `logs:*` should not have
+*   to know which half is whose.
+* - A role may not list a data-plane scope: a person's data access is the
+*   collection's `securityRules`, so `data:write` on a role would grant nothing
+*   and look like it granted something.
+*/
+function accessModelFromCollections(collections) {
+	const authCollection = collections.find((collection) => {
+		const auth = collection.auth;
+		return auth === true || !!auth && typeof auth === "object" && auth.enabled === true;
+	});
+	const auth = authCollection && typeof authCollection.auth === "object" ? authCollection.auth : void 0;
+	const declaredScopes = { ...auth?.scopes ?? {} };
+	const declaredRoles = { ...auth?.roles ?? {} };
+	const where = `the "${authCollection?.slug ?? "users"}" collection's auth block`;
+	for (const [name, definition] of Object.entries(declaredScopes)) {
+		const parsed = parseScope(name);
+		if (!parsed || parsed.target !== void 0) throw new AccessModelError(`auth.scopes: "${name}" in ${where} is not a scope name. Name scopes resource:action, lower-case, without a target — for example "project:deploy".`);
+		const resource = name.slice(0, name.indexOf(":"));
+		if (BUILT_IN_RESOURCES.has(resource)) throw new AccessModelError(`auth.scopes: "${name}" in ${where} uses the built-in resource "${resource}". App scopes need their own resource name; the built-in ones are ${[...BUILT_IN_RESOURCES].join(", ")}.`);
+		if (typeof definition?.label !== "string" || definition.label.trim() === "") throw new AccessModelError(`auth.scopes: "${name}" in ${where} needs a label — it is what a person granting it reads.`);
+	}
+	const model = {
+		roles: declaredRoles,
+		scopes: declaredScopes
+	};
+	for (const [role, definition] of Object.entries(declaredRoles)) {
+		if (role === "admin") throw new AccessModelError(`auth.roles: "admin" in ${where} is built in — it holds every scope — and cannot be declared. Declare a role with another name for a narrower set.`);
+		if (!Array.isArray(definition?.scopes)) throw new AccessModelError(`auth.roles: "${role}" in ${where} needs a scopes list.`);
+		const dataPlane = definition.scopes.filter((scope) => isDataPlaneScope(parseScope(scope)?.scope ?? ""));
+		if (dataPlane.length > 0) throw new AccessModelError(`auth.roles: "${role}" in ${where} lists ${dataPlane.join(", ")}. Every signed-in person already holds the data plane; what they may do with rows is the collection's securityRules. List admin-plane and app scopes only.`);
+		const problems = validateScopes(definition.scopes, model);
+		if (problems.length > 0) throw new AccessModelError(`auth.roles: "${role}" in ${where} lists ${problems.map((p) => `"${p.scope}" (${p.reason})`).join(", ")}. Role scopes are ${ADMIN_SCOPES.join(", ")} and the app's own auth.scopes.`);
+	}
+	return model;
+}
+/** Narrow a context's user to the roles it carries. */
+function rolesOf(user) {
+	if (typeof user !== "object" || user === null || !("roles" in user)) return [];
+	const roles = user.roles;
+	return Array.isArray(roles) ? roles.filter((role) => typeof role === "string") : [];
+}
+/**
+* Everything the caller of this request may do. Empty for a request with no
+* caller.
+*/
+function callerScopes(c) {
+	const narrowed = c.get("scopes");
+	if (narrowed) return narrowed;
+	const user = c.get("user");
+	if (!user) return [];
+	return scopesForRoles(rolesOf(user), accessOf(c).model);
+}
+/**
+* Whether this request's caller holds the `admin` role. The service key signs
+* in as one.
+*/
+function callerIsAdmin(c) {
+	return hasAdminRole(rolesOf(c.get("user")));
+}
+/** Does this request's caller hold `scope`, on `target` when one is given? */
+function hasScope(c, scope, target) {
+	return scopeGrants(callerScopes(c), scope, target);
+}
+/**
+* The refusal for a missing scope, worded for whoever is holding the
+* credential. `details.requiredScope` names it for clients that branch.
+*/
+function scopeMissing(c, scope, target) {
+	const wanted = target !== void 0 ? `${scope}:${target}` : scope;
+	return new ApiError(403, "SCOPE_MISSING", c.get("apiKey") !== void 0 ? `This API key does not hold the "${wanted}" scope. Create a key that includes it.` : c.get("scopes") ? `This token does not hold the "${wanted}" scope. Reconnect and grant it.` : `Your account does not hold the "${wanted}" scope. A role that lists it (auth.roles on the users collection) grants it; the admin role holds every scope.`, { requiredScope: wanted });
+}
+/**
+* Refuse a request whose caller does not hold `scope`.
+*
+* `scope` is a built-in scope or one this backend declares under
+* `auth.scopes`. A name no caller could ever hold — not a scope name, a typo
+* of a built-in one (`data:raed`) — throws as the route is registered; an app
+* scope the backend answering does not declare is answered
+* `500 SCOPE_NOT_DECLARED`, naming the declaration to add.
+*
+* `target` narrows the check to one collection, bucket, function or app
+* resource, and may be read from the request. A guard, not an authenticator:
+* it judges the caller an auth middleware identified, so mount it after one —
+* `requireAuth`, or a route group's own. A request with no caller is refused
+* as unauthenticated, not as unscoped.
+*
+* @example
+* ```ts
+* app.post("/deploy/:project", requireAuth, requireScope("project:deploy", c => c.req.param("project")), handler);
+* ```
+*/
+function requireScope(scope, target) {
+	const problem = scopeGuardProblem(scope, typeof target === "string" ? target : void 0);
+	if (problem) throw new Error(problem);
+	return async (c, next) => {
+		if (!c.get("user")) return refuse(c, noCallerRefusal(c));
+		const undeclared = scopeGuardProblem(scope, void 0, Object.keys(accessOf(c).model.scopes));
+		if (undeclared) return refuse(c, new ApiError(500, "SCOPE_NOT_DECLARED", undeclared));
+		const resolvedTarget = typeof target === "function" ? target(c) : target;
+		if (!hasScope(c, scope, resolvedTarget)) return refuse(c, scopeMissing(c, scope, resolvedTarget));
+		return next();
+	};
+}
+/**
+* The 401 for a guard that found no caller.
+*
+* A request that sent a credential, on a route where no auth middleware ran —
+* it sets `driver` for every caller, anonymous included — never had that
+* credential read. "Authentication required" sends whoever holds a valid
+* session to check it, so this names the wiring instead.
+*/
+function noCallerRefusal(c) {
+	if (c.req.header("authorization") !== void 0 && c.get("driver") === void 0) return ApiError.unauthenticated("Authentication required: this request carries a credential, but nothing on this route verified it. requireScope judges the caller an auth middleware identified; put requireAuth in front of it — app.post(path, requireAuth, requireScope(scope), handler).");
+	return ApiError.unauthenticated("Authentication required");
+}
+/**
+* Refuse a request unless its caller holds the scope for its HTTP method:
+* `read` for GET and HEAD, `write` for everything else. For an admin surface
+* whose reads and writes split exactly along the method.
+*/
+function requireScopeByMethod(scopes) {
+	const read = requireScope(scopes.read);
+	const write = requireScope(scopes.write);
+	return async (c, next) => {
+		const method = c.req.method.toUpperCase();
+		return (method === "GET" || method === "HEAD" ? read : write)(c, next);
+	};
+}
+/**
+* What a set of roles holds beyond this request's caller — the scopes, plus
+* `admin` itself when the roles include it and the caller does not hold it.
+* Empty when the caller covers every one.
+*
+* `admin` is named separately because it is more than its scopes: it is the
+* RLS role that reads every row, so a role listing every admin-plane scope
+* still cannot hand it out.
+*/
+function beyondCaller(c, roles) {
+	const beyond = scopesBeyond(scopesForRoles(roles, accessOf(c).model), callerScopes(c));
+	if (hasAdminRole(roles) && !hasAdminRole(rolesOf(c.get("user")))) beyond.unshift(ADMIN_ROLE);
+	return beyond;
+}
+/**
+* Refuse to let the caller act on an account — edit it, reset its password,
+* delete it — when that account holds anything the caller does not.
+*
+* `users:write` is the scope that lets a support role manage accounts, and
+* without this it would also let that role reset an administrator's password
+* and sign in as them.
+*/
+function assertMayManageAccount(c, targetRoles) {
+	const beyond = beyondCaller(c, targetRoles);
+	if (beyond.length > 0) throw new ApiError(403, "ACCOUNT_OUTRANKS_CALLER", `This account holds ${beyond.join(", ")}, which you do not, so you cannot change it.`, { beyond });
+}
+/**
+* Read a `roles` body field as the exact list that is then judged and written.
+*
+* Every entry must be a string `roleNameProblem` accepts. Filtering out the bad
+* entries instead is how the ceiling once judged one list and the write stored
+* another: `["support", ["admin"]]` was judged as `["support"]` and written as
+* `{support,admin}`, and `"support,admin"` was one undeclared role to the check
+* and two roles to Postgres.
+*/
+function readRoleNames(value) {
+	if (!Array.isArray(value)) throw new ApiError(400, "INVALID_ROLE", "roles must be an array of role names, e.g. [\"editor\"]");
+	const problems = value.flatMap((entry) => {
+		const problem = roleNameProblem(entry);
+		return problem ? [`${JSON.stringify(entry)} ${problem}`] : [];
+	});
+	if (problems.length > 0) throw new ApiError(400, "INVALID_ROLE", `Not valid role names: ${problems.join("; ")}. A role name is a non-empty string without , { } " \\ or control characters.`, { problems });
+	return [...new Set(value)];
+}
+/** Refuse to let the caller grant roles that hold anything the caller does not. */
+function assertMayGrantRoles(c, roles) {
+	const beyond = beyondCaller(c, roles);
+	if (beyond.length > 0) throw new ApiError(403, "ROLE_EXCEEDS_CALLER", `These roles hold ${beyond.join(", ")}, which you do not, so you cannot grant them.`, { beyond });
+}
+//#endregion
+export { accessTokenRefusalError as $, isPublicObjectGrant as A, maskedFieldsFor as B, queryTokenAuth as C, userFromToken as D, requireAuth as E, decideImpersonation as F, isApiKeyToken as G, createApiKeyPreAuth as H, refuseUnhonouredImpersonation as I, extractBearerToken as J, resolveApiKey as K, applySimulation as L, storageObjectOfPath as M, storageRequestWildcard as N, PUBLIC_OBJECT_PRINCIPAL as O, applyImpersonation as P, supportsRlsScoping as Q, callerOf$1 as R, publicObjectAuth as S, requireAdmin as T, createFunctionScopeGuard as U, reportSimulatedContext as V, createTusScopeGuard as W, SERVICE_IDENTITY as X, safeCompare as Y, scopeDataDriver as Z, createAuthMiddleware as _, assertMayManageAccount as a, httpMethodToOperation as at, fileTokenAuth as b, configureAccess as c, isPublicStoragePath as ct, keyOwnerResolverFor as d, isAccessTokenRevoked as et, processAccessControl as f, setDefaultAccessControl as g, requireScopeByMethod as h, assertMayGrantRoles as i, refuseSimulatedWrite as it, requestedStorageObject as j, isDownloadTokenGrant as k, getAccessModel as l, storageObjectPath as lt, requireScope as m, accessModelFromCollections as n, replaceUserPassword as nt, callerIsAdmin as o, PUBLIC_STORAGE_PREFIX as ot, readRoleNames as p, validateApiKey as q, accessOf as r, revokeAllSessions as rt, callerScopes as s, isPublicStorageKey as st, AccessModelError as t, judgeAccessToken as tt, hasScope as u, createRequireAuth as v, refuse as w, optionalAuth as x, extractUserFromToken as y, decideSimulation as z };
+
+//# sourceMappingURL=access-BFAUvsSs.js.map