@protobase/server 0.0.0-stage → 0.1.0

package/dist/better-auth/create-auth.js

@@ -0,0 +1,93 @@
+import { readMailSettings } from "../mail/mail-settings.js";
+import { smtpMailer } from "../mail/smtp-mailer.js";
+import { passwordResetOptions } from "./password-reset.js";
+import { APIError } from "better-auth/api";
+import { betterAuth } from "better-auth";
+import { admin, jwt } from "better-auth/plugins";
+import { adminAc, userAc } from "better-auth/plugins/admin/access";
+//#region src/better-auth/create-auth.ts
+const platformMailer = () => {
+	const settings = readMailSettings(globalThis.process?.env ?? {});
+	return settings && smtpMailer(settings);
+};
+const tokenLifetime = "15m";
+const authBasePath = "/api/auth";
+/**
+* Better Auth for a single-tenant admin: email and password sign-in, no public sign-up (every account is created on the
+* host with `createUser`, or by an admin through the admin plugin), roles from the admin plugin's `role` column, 15 minute JWTs
+* at `/api/auth/token` with the keys at `/api/auth/jwks`.
+*/
+const roleName = /^[a-z][a-z0-9_-]*$/;
+/** The configured roles with `admin` first; `admin` is added when missing. */
+const normalizeRoles = (roles = ["admin", "user"]) => {
+	const bad = roles.find((role) => !roleName.test(role));
+	if (bad !== void 0) throw new Error(`Invalid role "${bad}": use lowercase letters, digits, "_" or "-"`);
+	return ["admin", ...new Set(roles.filter((role) => role !== "admin"))];
+};
+const createAuth = (options) => {
+	const secure = options.baseURL.startsWith("https://");
+	const roles = normalizeRoles(options.roles);
+	if (options.defaultRole !== void 0 && !roles.includes(options.defaultRole)) throw new Error(`defaultRole "${options.defaultRole}" is not one of the roles: ${roles.join(", ")}`);
+	const others = roles.filter((role) => role !== "admin");
+	const defaultRole = options.defaultRole ?? (others.length === 1 ? others[0] : void 0);
+	const mailer = options.mailer === void 0 ? platformMailer() : options.mailer || void 0;
+	const auth = betterAuth({
+		database: options.database,
+		baseURL: options.baseURL,
+		basePath: authBasePath,
+		secret: options.secret,
+		trustedOrigins: [
+			options.baseURL,
+			"https://*.trycloudflare.com",
+			...options.trustedOrigins ?? []
+		],
+		emailAndPassword: {
+			enabled: true,
+			disableSignUp: true,
+			minPasswordLength: 12,
+			...mailer && passwordResetOptions(mailer)
+		},
+		plugins: [admin({
+			defaultRole: defaultRole ?? "unassigned",
+			roles: Object.fromEntries(roles.map((role) => [role, role === "admin" ? adminAc : userAc]))
+		}), jwt({ jwt: {
+			expirationTime: tokenLifetime,
+			issuer: options.baseURL,
+			audience: options.baseURL,
+			definePayload: ({ user }) => ({
+				email: user.email,
+				role: user.role
+			})
+		} })],
+		databaseHooks: { user: { create: { before: async (user) => {
+			const given = String(user.role ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+			const unknown = given.find((name) => !roles.includes(name));
+			if (given.length === 0 || unknown !== void 0) throw new APIError("BAD_REQUEST", { message: `Choose a role for the new user: ${roles.join(", ")}` });
+			return { data: user };
+		} } } },
+		rateLimit: {
+			enabled: true,
+			window: 60,
+			max: 100,
+			customRules: { "/sign-in/email": {
+				window: 60,
+				max: options.signInPerMinute ?? 5
+			} }
+		},
+		advanced: {
+			useSecureCookies: secure,
+			defaultCookieAttributes: {
+				sameSite: "lax",
+				secure
+			},
+			backgroundTasks: { handler: () => {} }
+		}
+	});
+	return Object.assign(auth, {
+		roles,
+		defaultRole,
+		passwordReset: Boolean(mailer)
+	});
+};
+//#endregion
+export { authBasePath, createAuth, normalizeRoles };

package/dist/better-auth/jwks-cache.d.ts

@@ -0,0 +1,9 @@
+import { JWTVerifyGetKey } from "jose";
+//#region src/better-auth/jwks-cache.d.ts
+export type JwksCacheOptions = {
+  /** Reload the whole key set this often, so removed keys stop being accepted. Default 10 minutes. */
+  refreshMs?: number;
+  /** A token with an unknown `kid` reloads the set, but at most this often. Default 30 seconds. */
+  minReloadMs?: number;
+};
+//#endregion

package/dist/better-auth/jwks-cache.js

@@ -0,0 +1,31 @@
+import { createLocalJWKSet, errors } from "jose";
+//#region src/better-auth/jwks-cache.ts
+/**
+* Key lookup for `jwtVerify` that keeps the key set in memory. It is read once, again when a token names a `kid`
+* that is not in it (a rotated key), never more often than `minReloadMs`, and every `refreshMs`.
+*/
+const cachedKeys = (load, options = {}) => {
+	const { refreshMs = 6e5, minReloadMs = 3e4 } = options;
+	let current;
+	let loading;
+	const reload = () => {
+		loading ??= load().then((set) => current = {
+			lookup: createLocalJWKSet(set),
+			loadedAt: Date.now()
+		}).finally(() => {
+			loading = void 0;
+		});
+		return loading;
+	};
+	return async (header, token) => {
+		const fresh = current && Date.now() - current.loadedAt < refreshMs ? current : await reload();
+		try {
+			return await fresh.lookup(header, token);
+		} catch (error) {
+			if (!(error instanceof errors.JWKSNoMatchingKey) || Date.now() - fresh.loadedAt < minReloadMs) throw error;
+			return (await reload()).lookup(header, token);
+		}
+	};
+};
+//#endregion
+export { cachedKeys };

package/dist/better-auth/password-reset.js

@@ -0,0 +1,32 @@
+//#region src/better-auth/password-reset.ts
+/** How long an emailed reset link works, in seconds and in the email's words. */
+const resetLinkLifetimeSeconds = 3600;
+const resetLinkLifetime = "1 hour";
+/** The reset email: the link, how long it works, and that it can be ignored. */
+const resetEmail = ({ to, url }) => ({
+	to,
+	subject: "Reset your password",
+	text: [
+		"Someone asked to reset the password of your account. To choose a new password, open this link:",
+		"",
+		url,
+		"",
+		`The link works for ${resetLinkLifetime}, once.`,
+		"If you did not ask for this, ignore this email: your password stays as it is.",
+		""
+	].join("\n")
+});
+/**
+* Better Auth's own password reset, sending the link with `mailer`. Resetting ends the user's sessions, so a reset
+* after a leaked password also signs out whoever used it.
+*/
+const passwordResetOptions = (mailer) => ({
+	resetPasswordTokenExpiresIn: resetLinkLifetimeSeconds,
+	revokeSessionsOnPasswordReset: true,
+	sendResetPassword: ({ user, url }) => mailer.send(resetEmail({
+		to: user.email,
+		url
+	}))
+});
+//#endregion
+export { passwordResetOptions, resetEmail, resetLinkLifetimeSeconds };

package/dist/better-auth/status-route.js

@@ -0,0 +1,17 @@
+import { hasUsers } from "./users.js";
+import { Hono } from "hono";
+//#region src/better-auth/status-route.ts
+/**
+* `GET {authBase}/status`: `needsAdmin` while the admin store has no user, so a login page can say how to create one,
+* and `passwordReset` when reset mail can be sent, so it offers "Forgot password?" only then.
+*/
+const statusRoute = (auth) => {
+	const app = new Hono();
+	app.get("/status", async (c) => c.json({
+		needsAdmin: !await hasUsers(auth),
+		passwordReset: auth.passwordReset
+	}));
+	return app;
+};
+//#endregion
+export { statusRoute };

package/dist/better-auth/tokens.d.ts

@@ -0,0 +1,18 @@
+import { AdminAuth } from "./create-auth.js";
+//#region src/better-auth/tokens.d.ts
+export type IssueTokenOptions = {
+  email: string;
+  /** Lifetime in seconds. Default 15 minutes, at most 24 hours. */
+  ttlSeconds?: number;
+};
+export declare const maxTokenTtlSeconds: number;
+/**
+ * Mints a bearer token for an existing user: signed with the JWT plugin's keys, same issuer, audience and claims
+ * (`sub`, `email`, `role`) as `/api/auth/token`, so the API accepts it like a token from a browser session.
+ * Host side only: there is no HTTP route for this.
+ */
+export declare const issueToken: (auth: AdminAuth, options: IssueTokenOptions) => Promise<{
+  token: string;
+  expiresAt: string;
+}>;
+//#endregion

package/dist/better-auth/tokens.js

@@ -0,0 +1,37 @@
+import { parseRoles } from "./users.js";
+//#region src/better-auth/tokens.ts
+const defaultTtlSeconds = 900;
+const maxTokenTtlSeconds = 86400;
+/**
+* Mints a bearer token for an existing user: signed with the JWT plugin's keys, same issuer, audience and claims
+* (`sub`, `email`, `role`) as `/api/auth/token`, so the API accepts it like a token from a browser session.
+* Host side only: there is no HTTP route for this.
+*/
+const issueToken = async (auth, options) => {
+	const ttl = options.ttlSeconds ?? defaultTtlSeconds;
+	if (!Number.isInteger(ttl) || ttl < 1 || ttl > 86400) throw new Error(`Token lifetime must be between 1 second and ${maxTokenTtlSeconds} seconds (24 hours)`);
+	const { adapter } = await auth.$context;
+	const user = await adapter.findOne({
+		model: "user",
+		where: [{
+			field: "email",
+			value: options.email.toLowerCase()
+		}]
+	});
+	if (!user) throw new Error(`No user with email ${options.email}`);
+	if (user.banned) throw new Error(`${options.email} is banned`);
+	const issuedAt = Math.floor(Date.now() / 1e3);
+	const { token } = await auth.api.signJWT({ body: { payload: {
+		iat: issuedAt,
+		exp: issuedAt + ttl,
+		sub: user.id,
+		email: user.email,
+		role: parseRoles(user.role).join(",")
+	} } });
+	return {
+		token,
+		expiresAt: (/* @__PURE__ */ new Date((issuedAt + ttl) * 1e3)).toISOString()
+	};
+};
+//#endregion
+export { issueToken, maxTokenTtlSeconds };

package/dist/better-auth/users.d.ts

@@ -0,0 +1,50 @@
+import { AdminAuth } from "./create-auth.js";
+//#region src/better-auth/users.d.ts
+/** The roles this auth instance allows, `admin` first. */
+export declare const roleChoices: (auth: AdminAuth) => string[];
+export type NewUser = {
+  email: string;
+  password: string;
+  name?: string;
+  role?: string;
+};
+export type StoredUser = {
+  id: string;
+  email: string;
+  role: string;
+  banned: boolean;
+  createdAt: string;
+};
+/** Whether the admin store has any user yet. */
+export declare const hasUsers: (auth: AdminAuth) => Promise<boolean>;
+/**
+ * Creates a user directly in the admin store. Host side only (no HTTP route creates accounts while the store is empty):
+ * the first user is always an `admin`, later ones get `role` (default `user`).
+ */
+export declare const createUser: (auth: AdminAuth, input: NewUser) => Promise<{
+  id: string;
+  email: string;
+  role: string;
+}>;
+/**
+ * The admin plugin stores roles as a comma separated string. A value written as a JS array through a Postgres driver
+ * comes back as an array literal (`{admin,sales}`); that is read too, and rewritten as a plain string on the next change.
+ */
+export declare const parseRoles: (role: string | string[] | null | undefined) => string[];
+export declare const listUsers: (auth: AdminAuth) => Promise<StoredUser[]>;
+/** Deletes the user with their sessions and accounts; refuses to delete the last active admin. */
+export declare const deleteUser: (auth: AdminAuth, email: string) => Promise<void>;
+/** Sets the role: one of the configured roles, or several separated by commas; refuses to demote the last active admin. */
+export declare const setUserRole: (auth: AdminAuth, input: {
+  email: string;
+  role: string;
+}) => Promise<{
+  email: string;
+  role: string;
+}>;
+/** Disables or re-enables sign-in. Banning ends the user's sessions; the last active admin cannot be banned. */
+export declare const setUserBanned: (auth: AdminAuth, input: {
+  email: string;
+  banned: boolean;
+}) => Promise<void>;
+//#endregion

package/dist/better-auth/users.js

@@ -0,0 +1,111 @@
+//#region src/better-auth/users.ts
+/** The roles this auth instance allows, `admin` first. */
+const roleChoices = (auth) => [...auth.roles];
+const checkRoles = (auth, role) => {
+	const wanted = role.split(",").map((name) => name.trim()).filter(Boolean);
+	const unknown = wanted.filter((name) => !auth.roles.includes(name));
+	if (wanted.length === 0 || unknown.length > 0) throw new Error(`Unknown role "${unknown[0] ?? role}"; use ${auth.roles.join(", ")}`);
+	return wanted;
+};
+/** Whether the admin store has any user yet. */
+const hasUsers = async (auth) => (await auth.$context).adapter.count({ model: "user" }).then((count) => count > 0);
+/**
+* Creates a user directly in the admin store. Host side only (no HTTP route creates accounts while the store is empty):
+* the first user is always an `admin`, later ones get `role` (default `user`).
+*/
+const createUser = async (auth, input) => {
+	const first = !await hasUsers(auth);
+	const requested = input.role ?? auth.defaultRole;
+	if (!first && requested === void 0) throw new Error(`A role is required: choose one of ${auth.roles.join(", ")}`);
+	const role = first ? "admin" : checkRoles(auth, requested).join(",");
+	const { user } = await auth.api.createUser({ body: {
+		email: input.email,
+		password: input.password,
+		name: input.name ?? input.email.split("@")[0],
+		role
+	} });
+	return {
+		id: user.id,
+		email: user.email,
+		role: String(user.role)
+	};
+};
+/**
+* The admin plugin stores roles as a comma separated string. A value written as a JS array through a Postgres driver
+* comes back as an array literal (`{admin,sales}`); that is read too, and rewritten as a plain string on the next change.
+*/
+const parseRoles = (role) => {
+	if (Array.isArray(role)) return role;
+	const text = (role ?? "user").trim();
+	return (text.startsWith("{") && text.endsWith("}") ? text.slice(1, -1) : text).split(",").map((name) => name.trim().replace(/^"|"$/g, "")).filter(Boolean);
+};
+const allUsers = async (auth) => {
+	const { adapter } = await auth.$context;
+	return adapter.findMany({
+		model: "user",
+		sortBy: {
+			field: "createdAt",
+			direction: "asc"
+		}
+	});
+};
+const rolesOf = (user) => parseRoles(user.role);
+const isAdmin = (user) => rolesOf(user).includes("admin");
+const isActiveAdmin = (user) => isAdmin(user) && !user.banned;
+const findUser = async (auth, email) => {
+	const user = (await allUsers(auth)).find((candidate) => candidate.email.toLowerCase() === email.toLowerCase());
+	if (!user) throw new Error(`No user with email ${email}`);
+	return user;
+};
+const refuseLastAdmin = async (auth, user, action) => {
+	if (!isActiveAdmin(user)) return;
+	if ((await allUsers(auth)).filter(isActiveAdmin).length <= 1) throw new Error(`Cannot ${action} the last admin`);
+};
+const listUsers = async (auth) => (await allUsers(auth)).map((user) => ({
+	id: user.id,
+	email: user.email,
+	role: rolesOf(user).join(","),
+	banned: Boolean(user.banned),
+	createdAt: new Date(user.createdAt).toISOString()
+}));
+/** Deletes the user with their sessions and accounts; refuses to delete the last active admin. */
+const deleteUser = async (auth, email) => {
+	const user = await findUser(auth, email);
+	await refuseLastAdmin(auth, user, "delete");
+	const { internalAdapter } = await auth.$context;
+	await internalAdapter.deleteUserSessions(user.id);
+	await internalAdapter.deleteUser(user.id);
+};
+/** Sets the role: one of the configured roles, or several separated by commas; refuses to demote the last active admin. */
+const setUserRole = async (auth, input) => {
+	const wanted = checkRoles(auth, input.role);
+	const user = await findUser(auth, input.email);
+	if (!wanted.includes("admin")) await refuseLastAdmin(auth, user, "demote");
+	await (await auth.$context).internalAdapter.updateUser(user.id, { role: wanted.join(",") });
+	return {
+		email: user.email,
+		role: wanted.join(",")
+	};
+};
+/** Disables or re-enables sign-in. Banning ends the user's sessions; the last active admin cannot be banned. */
+const setUserBanned = async (auth, input) => {
+	const user = await findUser(auth, input.email);
+	const { internalAdapter } = await auth.$context;
+	if (!input.banned) {
+		await internalAdapter.updateUser(user.id, {
+			banned: false,
+			banReason: null,
+			banExpires: null
+		});
+		return;
+	}
+	await refuseLastAdmin(auth, user, "ban");
+	await internalAdapter.updateUser(user.id, {
+		banned: true,
+		banReason: "Disabled by an administrator",
+		banExpires: null
+	});
+	await internalAdapter.deleteUserSessions(user.id);
+};
+//#endregion
+export { createUser, deleteUser, hasUsers, listUsers, parseRoles, roleChoices, setUserBanned, setUserRole };

package/dist/check-shell.js

@@ -0,0 +1,17 @@
+import { navRecentErrors } from "@protobase/schema";
+//#region src/check-shell.ts
+/** Fails at startup when a sidebar group or a user menu entry does not fit the resources, instead of on the first page load. */
+const checkShell = (registry, views, userMenu, pages = []) => {
+	for (const view of views) {
+		const entry = registry.find(view.resource);
+		if (!entry || !view.nav?.recent) continue;
+		const errors = navRecentErrors(view.nav.recent, entry.model);
+		if (errors.length > 0) throw new Error(`View "${view.resource}": nav.recent ${errors.join("; ")}`);
+	}
+	for (const item of userMenu?.items ?? []) {
+		if (item.kind === "resource" && !registry.find(item.resource)) throw new Error(`User menu: resource "${item.resource}" does not exist`);
+		if (item.kind === "page" && !pages.includes(item.page)) throw new Error(`User menu: page "${item.page}" does not exist`);
+	}
+};
+//#endregion
+export { checkShell };

package/dist/check-views.js

@@ -0,0 +1,45 @@
+import { relatedErrors } from "./view-related.js";
+//#region src/check-views.ts
+const sensitiveErrors = (view, model) => {
+	const sensitive = (name) => Boolean(model.fields[name]?.sensitive);
+	return [
+		["the title", view.title === void 0 ? [] : [view.title]],
+		["the search result", [...view.searchResult?.title ?? [], ...view.searchResult?.subtitle ? [view.searchResult.subtitle] : []]],
+		["a list column, sort or search", [
+			...view.list?.columns ?? [],
+			...(view.list?.sort ?? []).map(([name]) => name),
+			...view.list?.search ?? []
+		]],
+		["a filter", view.filters.map((widget) => widget.field)],
+		["the chart", view.chart ? [view.chart.field] : []],
+		["the sidebar", view.layout.flatMap((item) => item.kind === "sidebar" ? item.fields : [])],
+		["the recent records", view.nav?.recent ? [view.nav.recent.status] : []],
+		["an action", view.actions.flatMap((action) => action.run?.kind === "update" ? Object.keys(action.run.values) : action.run?.kind === "link" ? [...action.run.href.matchAll(/\{(\w+)\}/g)].map((match) => match[1]) : [])]
+	].flatMap(([place, names]) => [...new Set(names.filter(sensitive))].map((name) => `sensitive field "${name}" cannot be in ${place}`));
+};
+const valueLabelErrors = (view, model) => Object.entries(view.fields).flatMap(([name, hints]) => {
+	if (!hints.valueLabels) return [];
+	const field = model.fields[name];
+	if (field?.type !== "enum") return [`value labels of "${name}" need an enum field`];
+	return Object.keys(hints.valueLabels).filter((value) => !field.enumValues?.includes(value)).map((value) => `value label "${value}" is not a value of "${name}"`);
+});
+/**
+* Fails at startup when a view uses a sensitive field where it would show empty, labels values its enum does not have,
+* or has a related section that does not fit the resources.
+*/
+const checkViews = (registry, views) => {
+	const models = Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model]));
+	const problems = views.flatMap((view) => {
+		const model = models[view.resource];
+		if (!model) return [];
+		const related = view.layout.flatMap((item) => item.kind === "related" ? relatedErrors(item, view.resource, models).map((error) => `related "${item.title}": ${error}`) : []);
+		return [
+			...sensitiveErrors(view, model),
+			...valueLabelErrors(view, model),
+			...related
+		].map((problem) => `View "${view.resource}": ${problem}`);
+	});
+	if (problems.length > 0) throw new Error(`The views do not match the resources:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+};
+//#endregion
+export { checkViews };

package/dist/create-admin.d.ts

@@ -0,0 +1,23 @@
+import { AdminAuth } from "./better-auth/create-auth.js";
+import { ResourceSource } from "./resource-source.js";
+import { AdminEnv, AdminOptions, Authenticator, PageSource, ViewSource } from "./types.js";
+import { Hono } from "hono";
+import { UserMenuSource } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/create-admin.d.ts
+export type CreateAdminInput = {
+  resources: ResourceSource[];
+  views?: ViewSource[];
+  /** The `userMenu(...)` export of the config module: pages under the signed-in user in the sidebar. */
+  userMenu?: UserMenuSource;
+  /** Composed pages (`page()` from @protobase/layout), served by /meta and checked against the resources here. */
+  pages?: PageSource[];
+  db: Db;
+  authenticate: Authenticator;
+  /** A Better Auth instance (see `createAuth`): its handler is mounted at `/api/auth`. */
+  auth?: AdminAuth;
+  options?: AdminOptions;
+};
+/** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
+export declare const createAdmin: ({ resources, views, pages, userMenu, db, authenticate, auth, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
+//#endregion

package/dist/create-admin.js

@@ -0,0 +1,85 @@
+import { consoleAuditQueue } from "./audit/console-queue.js";
+import { authBasePath } from "./better-auth/create-auth.js";
+import { statusRoute } from "./better-auth/status-route.js";
+import { checkShell } from "./check-shell.js";
+import { checkViews } from "./check-views.js";
+import { createErrorHandler } from "./error-handler.js";
+import { createMeta } from "./meta.js";
+import { buildRegistry } from "./registry.js";
+import { batchRoute } from "./routes/batch.js";
+import { collectionRoutes } from "./routes/collection.js";
+import { docsRoutes } from "./routes/docs.js";
+import { metaRoutes } from "./routes/meta.js";
+import { recordRoutes } from "./routes/record.js";
+import { createScanGuard } from "./scan-guard.js";
+import { Hono } from "hono";
+import { checkPages } from "@protobase/layout";
+//#region src/create-admin.ts
+/** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
+const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenticate, auth, options = {} }) => {
+	const basePath = options.basePath ?? "/api/v1";
+	const registry = buildRegistry(resources);
+	const viewModels = views.map((view) => view.toModel());
+	const userMenuModel = userMenu?.toUserMenuModel();
+	const pageModels = pages.map((entry) => entry.toModel());
+	checkShell(registry, viewModels, userMenuModel, pageModels.map((entry) => entry.name));
+	checkViews(registry, viewModels);
+	checkPages(pageModels, {
+		models: Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model])),
+		actions: (resource) => new Set(viewModels.filter((view) => view.resource === resource).flatMap((view) => view.actions.map((action) => action.name)))
+	});
+	const deps = {
+		db,
+		registry,
+		views: viewModels,
+		pages: pageModels,
+		...userMenuModel && { userMenu: userMenuModel },
+		basePath,
+		systemPath: basePath.slice(0, basePath.lastIndexOf("/")),
+		statementTimeoutMs: options.statementTimeoutMs ?? 15e3,
+		guard: createScanGuard(db, options.scanGuard),
+		hooks: options.writeHooks ?? [],
+		audit: options.audit ?? consoleAuditQueue(),
+		accessOptions: {
+			...options.roles && { roles: options.roles },
+			...options.defaultAccess && { defaultAccess: options.defaultAccess }
+		},
+		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false
+	};
+	const meta = createMeta(deps);
+	const onError = createErrorHandler(options.onUnhandledError);
+	const guarded = (routes) => {
+		const app = new Hono();
+		app.onError(onError);
+		app.use("*", async (c, next) => {
+			await next();
+			c.res.headers.set("X-Meta-Version", await meta.version(c.get("session")?.user.roles ?? []));
+		});
+		app.use("*", async (c, next) => {
+			c.set("session", await authenticate(c.req.raw));
+			await next();
+		});
+		routes(app);
+		return app;
+	};
+	const api = guarded((app) => {
+		app.route("/", collectionRoutes(deps));
+		app.route("/", recordRoutes(deps));
+	});
+	const system = guarded((app) => {
+		app.route("/", docsRoutes(deps));
+		app.route("/", metaRoutes(meta));
+	});
+	const app = new Hono();
+	app.onError(onError);
+	if (auth) {
+		app.route(authBasePath, statusRoute(auth));
+		app.on(["GET", "POST"], `${authBasePath}/*`, (c) => auth.handler(c.req.raw));
+	}
+	app.route("/", batchRoute(deps, authenticate, meta));
+	app.route(basePath, api);
+	app.route(deps.systemPath || "/", system);
+	return app;
+};
+//#endregion
+export { createAdmin };

package/dist/error-handler.js

@@ -0,0 +1,44 @@
+import { HttpProblem, problemResponse } from "./problem.js";
+import { HTTPException } from "hono/http-exception";
+import { QueryError } from "@protobase/query";
+//#region src/error-handler.ts
+const titles = {
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	405: "Method Not Allowed",
+	409: "Conflict",
+	413: "Payload Too Large",
+	415: "Unsupported Media Type",
+	500: "Internal Server Error"
+};
+const queryStatus = {
+	missing_tenant: 403,
+	no_statistics: 409,
+	missing_extension: 501
+};
+const queryProblem = (error) => {
+	const status = queryStatus[error.code] ?? 400;
+	return new HttpProblem(status, error.code.replaceAll("_", "-"), titles[status] ?? "Not Implemented", error.message);
+};
+const isDatabaseError = (error) => error instanceof Error && /^[0-9A-Z]{5}$/.test(String(error.code));
+const databaseProblem = (error) => {
+	if (error.code === "57014") return new HttpProblem(504, "statement-timeout", "Gateway Timeout", "The query exceeded the statement timeout");
+	if (error.code === "23505") return new HttpProblem(409, "conflict", "Conflict", "A record with the same unique value already exists");
+	if (error.code === "23503") return new HttpProblem(409, "conflict", "Conflict", "The record points at, or is pointed at by, another record");
+	if (error.code === "23502") return new HttpProblem(400, "invalid-record", "Bad Request", "A required column has no value");
+	if (error.code === "23514") return new HttpProblem(400, "invalid-record", "Bad Request", "A check constraint rejected the record");
+	if (error.code.startsWith("22")) return new HttpProblem(400, "invalid-value", "Bad Request", "A value has the wrong format for its column");
+};
+/** The problem an error stands for, when it is one the API knows how to report; unknown errors give `undefined`. */
+const problemOf = (error) => error instanceof HttpProblem ? error : error instanceof QueryError ? queryProblem(error) : error instanceof HTTPException ? new HttpProblem(error.status, "http-error", titles[error.status] ?? "Error", error.message) : error instanceof SyntaxError ? new HttpProblem(400, "malformed-json", "Bad Request", "The request body is not valid JSON") : isDatabaseError(error) ? databaseProblem(error) : void 0;
+/** The single place where errors become responses: RFC 9457 problems, never raw error messages for unexpected failures. */
+const createErrorHandler = (onUnhandledError) => (error, c) => {
+	const known = problemOf(error);
+	if (known) return problemResponse(known, c.req.path);
+	onUnhandledError?.(error);
+	return problemResponse(new HttpProblem(500, "internal-error", titles[500], "The server failed to handle the request"), c.req.path);
+};
+//#endregion
+export { createErrorHandler, problemOf };

package/dist/etag.js

@@ -0,0 +1,22 @@
+import { sha256Hex, stableJson } from "./hash.js";
+import { etagAlias } from "./sql-parts.js";
+//#region src/etag.ts
+/**
+* The version of a row. With a version or `updated_at` column it is a hash of that column's exact text (so a hidden column's
+* value is never shown, yet every change moves it); without one it is a hash of the exposed fields, which are only the
+* fields the caller may read, so a change to a hidden field cannot be detected.
+*/
+const etagOf = async (entry, raw, exposed) => {
+	const hash = async (text) => (await sha256Hex(text)).slice(0, 32);
+	if (entry.etag) return `"${entry.etag.kind === "version" ? "v" : "t"}${await hash(String(raw[etagAlias]))}"`;
+	return `"h${await hash(stableJson(exposed))}"`;
+};
+const tags = (header) => header.split(",").map((tag) => tag.trim().replace(/^W\//, ""));
+/** If-Match comparison: `*` or any listed tag equal to the current one. */
+const ifMatchSatisfied = (header, etag) => {
+	const listed = tags(header);
+	return listed.includes("*") || listed.includes(etag);
+};
+const ifNoneMatchSatisfied = (header, etag) => ifMatchSatisfied(header, etag);
+//#endregion
+export { etagOf, ifMatchSatisfied, ifNoneMatchSatisfied };