@protobase/server 0.0.0-stage → 0.1.0

package/dist/problem.js

@@ -0,0 +1,43 @@
+//#region src/problem.ts
+/** An RFC 9457 problem. Throw it anywhere below a route; the central error handler renders it. */
+var HttpProblem = class extends Error {
+	status;
+	slug;
+	title;
+	extras;
+	headers;
+	constructor(status, slug, title, detail, extras = {}, headers = {}) {
+		super(detail);
+		this.status = status;
+		this.slug = slug;
+		this.title = title;
+		this.extras = extras;
+		this.headers = headers;
+	}
+	get detail() {
+		return this.message;
+	}
+};
+const problemType = (slug) => `urn:protobase:problem:${slug}`;
+const problemResponse = (problem, instance) => new Response(JSON.stringify({
+	type: problemType(problem.slug),
+	title: problem.title,
+	status: problem.status,
+	detail: problem.detail,
+	instance,
+	...problem.extras
+}), {
+	status: problem.status,
+	headers: {
+		"content-type": "application/problem+json",
+		...problem.headers
+	}
+});
+const badRequest = (slug, detail, extras) => new HttpProblem(400, slug, "Bad Request", detail, extras);
+const unauthorized = (detail) => new HttpProblem(401, "unauthenticated", "Unauthorized", detail, {}, { "www-authenticate": "Bearer" });
+const forbidden = (slug, detail) => new HttpProblem(403, slug, "Forbidden", detail);
+const notFound = (detail) => new HttpProblem(404, "not-found", "Not Found", detail);
+const preconditionFailed = (detail) => new HttpProblem(412, "precondition-failed", "Precondition Failed", detail);
+const preconditionRequired = (detail) => new HttpProblem(428, "precondition-required", "Precondition Required", detail);
+//#endregion
+export { HttpProblem, badRequest, forbidden, notFound, preconditionFailed, preconditionRequired, problemResponse, problemType, unauthorized };

package/dist/read-service.js

@@ -0,0 +1,65 @@
+import { notFound } from "./problem.js";
+import { tenantScope } from "./tenant.js";
+import { recordDecision, requestAccess, requireOperation, targetFilter, visibleFields, writableFields } from "./request-access.js";
+import { readTransaction } from "./transactions.js";
+import { pickFields } from "./rows.js";
+import { fetchRecord } from "./records.js";
+import { rowPermissions } from "./row-permissions.js";
+//#region src/read-service.ts
+/** `edit` for fields the caller may change on this record, `read` for the rest (sensitive ones included); hidden fields are not listed at all. */
+const fieldModes = (access, canUpdate) => Object.fromEntries(Object.keys(access.readable.fields).map((name) => [name, canUpdate && writableFields(access, "update").includes(name) ? "edit" : "read"]));
+/**
+* The row with this key if the caller may read it: inside their tenant and row filter, and passing a record-level read
+* rule. Such a rule may look at fields the caller cannot see, so then the whole row is read; the caller cuts it down.
+*/
+const fetchReadable = async (trx, access, key, deleted, { fields, ...shape }) => {
+	const { entry } = access;
+	const tenant = tenantScope(entry, access.session)?.tenantValue;
+	const recordRule = access.resolved.recordChecks.includes("read");
+	const filter = targetFilter(access, "read");
+	const current = await fetchRecord(trx, entry, key, tenant, {
+		deleted,
+		...filter && { filter },
+		...shape,
+		...!recordRule && fields && { fields }
+	});
+	if (!current || !recordRule) return current;
+	const decision = await recordDecision(access, "read", current.record);
+	if (decision === false) return void 0;
+	if (decision !== true && !await fetchRecord(trx, entry, key, tenant, {
+		deleted,
+		filter: decision,
+		fields: [access.full.fields[access.full.primaryKey[0]]]
+	})) return void 0;
+	return current;
+};
+/**
+* The record with this key as the caller may see it: readable fields only, inside the caller's tenant and row filter.
+* A key outside the tenant, outside the row filter, or failing a record-level read rule is a plain 404.
+*/
+const readRecord = async (deps, entry, session, key, deleted = "hide") => {
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "read");
+	const names = Object.keys(access.model.fields);
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		const current = await fetchReadable(trx, access, key, deleted, {
+			etagFields: names,
+			fields: visibleFields(access)
+		});
+		if (!current) return void 0;
+		const record = pickFields(current.record, names);
+		const [row] = await rowPermissions(trx, access, [record]);
+		return {
+			record,
+			etag: current.etag,
+			permissions: {
+				...row,
+				fields: fieldModes(access, row.update)
+			}
+		};
+	});
+	if (!found) throw notFound(`No ${entry.name} with this key`);
+	return found;
+};
+//#endregion
+export { fetchReadable, fieldModes, readRecord };

package/dist/records.js

@@ -0,0 +1,66 @@
+import { columnId, filterCondition, keyConditions, returningList, scopeConditions, tableId, whereClause } from "./sql-parts.js";
+import { etagOf } from "./etag.js";
+import { exposeRow, pickFields } from "./rows.js";
+import { sql } from "kysely";
+//#region src/records.ts
+const stored = async (entry, raw, shape = {}) => {
+	if (!raw) return void 0;
+	const record = exposeRow(entry.model, raw);
+	return {
+		record,
+		etag: await etagOf(entry, raw, shape.etagFields ? pickFields(record, shape.etagFields) : record)
+	};
+};
+const rowsOf = async (db, query) => (await query.execute(db)).rows;
+/** The row of the caller's tenant with this key (live unless `deleted` says otherwise), optionally narrowed by a filter. */
+const fetchRecord = async (db, entry, key, tenant, options = {}) => {
+	const { filter, deleted, lock = false, ...shape } = options;
+	const conditions = [
+		...scopeConditions(entry.model, tenant, deleted),
+		...keyConditions(entry.model, key),
+		...filterCondition(entry.model, filter)
+	];
+	const query = sql`select ${returningList(entry, shape.fields)} from ${tableId(entry.model)} as t${whereClause(conditions)} limit 1${lock ? sql` for update` : sql``}`;
+	return stored(entry, (await rowsOf(db, query))[0], shape);
+};
+const writeValue = (field, value) => field.type === "json" && value !== null ? JSON.stringify(value) : value;
+const insertRecord = async (db, entry, values, shape = {}) => {
+	const fields = Object.keys(values).map((name) => entry.model.fields[name]);
+	const body = fields.length === 0 ? sql`default values` : sql`(${sql.join(fields.map(columnId))}) values (${sql.join(fields.map((field) => writeValue(field, values[field.name])))})`;
+	const query = sql`insert into ${tableId(entry.model)} ${body} returning ${returningList(entry, shape.fields)}`;
+	return await stored(entry, (await rowsOf(db, query))[0], shape);
+};
+const etagBump = (entry) => {
+	if (!entry.etag) return [];
+	const column = columnId(entry.etag.field);
+	return [entry.etag.kind === "version" ? sql`${column} = ${column} + 1` : sql`${column} = clock_timestamp()`];
+};
+const updateRecord = async (db, entry, key, tenant, values, shape = {}) => {
+	const assignments = [...Object.entries(values).map(([name, value]) => {
+		const field = entry.model.fields[name];
+		return sql`${columnId(field)} = ${writeValue(field, value)}`;
+	}), ...etagBump(entry)];
+	const conditions = [...scopeConditions(entry.model, tenant), ...keyConditions(entry.model, key)];
+	const query = sql`update ${tableId(entry.model)} as t set ${sql.join(assignments)}${whereClause(conditions)} returning ${returningList(entry, shape.fields)}`;
+	return await stored(entry, (await rowsOf(db, query))[0], shape);
+};
+const deleteRecord = async (db, entry, key, tenant, shape = {}) => {
+	const { model } = entry;
+	const conditions = [...scopeConditions(model, tenant), ...keyConditions(model, key)];
+	const softField = model.softDelete ? model.fields[model.softDelete] : void 0;
+	if (model.softDelete && !softField) throw new Error(`Soft delete field "${model.softDelete}" is not a field of "${model.name}"`);
+	const query = softField ? sql`update ${tableId(model)} as t set ${columnId(softField)} = clock_timestamp()${whereClause(conditions)} returning ${returningList(entry, shape.fields)}` : sql`delete from ${tableId(model)} as t${whereClause(conditions)} returning ${returningList(entry, shape.fields)}`;
+	return await stored(entry, (await rowsOf(db, query))[0], shape);
+};
+/** Clears the soft delete column of a deleted row. */
+const restoreRecord = async (db, entry, key, tenant, shape = {}) => {
+	const { model } = entry;
+	const softField = model.softDelete ? model.fields[model.softDelete] : void 0;
+	if (!softField) throw new Error(`Resource "${model.name}" has no soft delete field to clear`);
+	const conditions = [...scopeConditions(model, tenant, "only"), ...keyConditions(model, key)];
+	const assignments = [sql`${columnId(softField)} = null`, ...etagBump(entry)];
+	const query = sql`update ${tableId(model)} as t set ${sql.join(assignments)}${whereClause(conditions)} returning ${returningList(entry, shape.fields)}`;
+	return await stored(entry, (await rowsOf(db, query))[0], shape);
+};
+//#endregion
+export { deleteRecord, fetchRecord, insertRecord, restoreRecord, updateRecord };

package/dist/registry.js

@@ -0,0 +1,44 @@
+import { keyTypes } from "@protobase/schema";
+//#region src/registry.ts
+const etagSource = (model) => {
+	const fields = Object.values(model.fields).filter((field) => field.readOnly);
+	const version = fields.find((field) => field.column === "version" && (field.type === "integer" || field.type === "bigint"));
+	if (version) return {
+		field: version,
+		kind: "version"
+	};
+	const updated = fields.find((field) => field.column === "updated_at" && field.type === "timestamp");
+	return updated && {
+		field: updated,
+		kind: "timestamp"
+	};
+};
+const buildRegistry = (resources) => {
+	const built = resources.map((source) => ({
+		source,
+		model: source.toModel()
+	}));
+	const models = new Map(built.map(({ model }) => [model.name, model]));
+	const entries = built.map(({ source, model }) => {
+		if (/[/:?#]/.test(model.name)) throw new Error(`Resource name "${model.name}" cannot be used in a URL path`);
+		if (Object.hasOwn(model.fields, "etag")) throw new Error(`Resource "${model.name}" has a field named "etag", which the API uses for the record version`);
+		const types = keyTypes(model, (name) => models.get(name));
+		if (types.length !== model.primaryKey.length) throw new Error(`Not implemented: resource "${model.name}" has a primary key field that points at a composite-key resource; the server maps one key part per key field`);
+		const etag = etagSource(model);
+		return {
+			name: model.name,
+			source,
+			model,
+			keyTypes: types,
+			...etag && { etag }
+		};
+	});
+	const byName = new Map(entries.map((entry) => [entry.name, entry]));
+	if (byName.size !== entries.length) throw new Error("Resource names must be unique");
+	return {
+		entries,
+		find: (name) => byName.get(name)
+	};
+};
+//#endregion
+export { buildRegistry };

package/dist/request-access.js

@@ -0,0 +1,97 @@
+import { forbidden, notFound } from "./problem.js";
+import { checkedFilter } from "./filter-input.js";
+import { tenantScope } from "./tenant.js";
+import { checkFilter, resolveAccess, restrictModel } from "@protobase/schema";
+//#region src/request-access.ts
+const withoutSensitive = (model) => ({
+	...model,
+	fields: Object.fromEntries(Object.entries(model.fields).filter(([, field]) => !field.sensitive))
+});
+const requestAccess = async (deps, entry, session) => {
+	const resolved = await resolveAccess(entry.source, { user: {
+		id: session.user.id,
+		roles: session.user.roles
+	} }, deps.accessOptions);
+	const readable = restrictModel(entry.model, resolved);
+	return {
+		entry,
+		session,
+		resolved,
+		full: entry.model,
+		readable,
+		model: withoutSensitive(readable),
+		deps
+	};
+};
+const hasNoAccess = (resolved) => !Object.values(resolved.operations).some(Boolean);
+/** 403 when the operation is denied; a resource the user can do nothing with does not exist for them. */
+const requireOperation = (access, operation) => {
+	if (access.resolved.operations[operation]) return;
+	if (hasNoAccess(access.resolved)) throw notFound(`There is no resource "${access.entry.name}"`);
+	throw forbidden("access-denied", `You may not ${operation} ${access.entry.name}`);
+};
+/**
+* Fields the caller may write on create or update. A field they cannot read is never writable, even when its write rule
+* allows it (nobody writes blind; a sensitive field counts as readable); the tenant column is always set by the server.
+*/
+const writableFields = (access, mode) => access.resolved.writableFields[mode].filter((name) => Object.hasOwn(access.readable.fields, name) && name !== access.full.tenant);
+const visibleFields = (access) => Object.values(access.model.fields);
+const andFilters = (filters) => {
+	const present = filters.filter((filter) => filter !== void 0);
+	if (present.length < 2) return present[0];
+	return {
+		kind: "and",
+		args: present,
+		span: {
+			start: 0,
+			end: 0
+		}
+	};
+};
+/** The row filter that narrows which rows an operation may target: the read filter, plus the operation's own. */
+const targetFilter = (access, operation) => operation === "read" ? access.resolved.rowFilter.read : andFilters([access.resolved.rowFilter.read, access.resolved.rowFilter[operation]]);
+/** The query-layer scope for reads: tenant, the access row filter against the full model, soft delete from the full model. */
+const readScope = (access, fullModel = access.full) => {
+	const tenant = tenantScope(access.entry, access.session);
+	const rowFilter = access.resolved.rowFilter.read;
+	return {
+		...tenant && { tenantValue: tenant.tenantValue },
+		...rowFilter && { rowFilter },
+		fullModel
+	};
+};
+const trusted = (model) => ({
+	...model,
+	fields: Object.fromEntries(Object.entries(model.fields).map(([name, field]) => [name, {
+		...field,
+		filterable: true
+	}]))
+});
+const asFilter = (access, expr, operation) => {
+	if (typeof expr === "string") return checkedFilter(trusted(access.full), expr);
+	const result = checkFilter(trusted(access.full), expr);
+	if (!result.ok) throw new Error(`The ${operation} access rule of "${access.entry.name}" returned an invalid filter: ${result.errors[0].message}`);
+	return result.filter;
+};
+/**
+* The record-level rule of an operation, run with the stored record (and the input of a write). Returns a verdict, or a
+* filter that the caller checks in the database, so its semantics match reads exactly.
+*/
+const recordDecision = async (access, operation, record, input) => {
+	const { entry, deps, full, session } = access;
+	const explicit = entry.source.accessRules[operation] ?? (operation === "list" ? entry.source.accessRules.read : void 0);
+	const fallback = deps.accessOptions.defaultAccess ? () => deps.accessOptions.defaultAccess === "allow" : deps.accessOptions.roles ? deps.accessOptions.roles.can(`${entry.name}.${operation === "list" ? "read" : operation}`) : () => true;
+	const result = await (explicit ?? fallback)({
+		user: {
+			id: session.user.id,
+			roles: session.user.roles
+		},
+		model: full,
+		operation,
+		record
+	}, record, input);
+	if (typeof result === "boolean") return result;
+	return asFilter(access, result, operation);
+};
+//#endregion
+export { andFilters, readScope, recordDecision, requestAccess, requireOperation, targetFilter, visibleFields, writableFields };

package/dist/resource-source.d.ts

@@ -0,0 +1,35 @@
+import { PageDefinition } from "@protobase/layout";
+import { AccessSource, UserMenuSource, ViewModel } from "@protobase/schema";
+import { z } from "zod";
+//#region src/resource-source.d.ts
+type FieldSource = {
+  schema: z.ZodType;
+  meta: {
+    readOnly: boolean;
+    nullable: boolean;
+  };
+};
+/** What the server needs from a resource builder; every `resource(...)` chain satisfies it. */
+export type ResourceSource = AccessSource & {
+  readonly state: {
+    fields?: Record<string, FieldSource | null>;
+  };
+  readonly validators: readonly ((record: any) => Array<{
+    field: string;
+    message: string;
+  }> | undefined)[];
+  recordSchema(): z.ZodType;
+};
+/**
+ * Splits a config module (`import * as config from './config'`) into its resources, views, pages and, when it exports
+ * one `userMenu(...)`, the user menu.
+ */
+export declare const configExports: (module: Record<string, unknown>) => {
+  userMenu?: UserMenuSource | undefined;
+  resources: ResourceSource[];
+  views: Array<{
+    toModel(): ViewModel;
+  }>;
+  pages: PageDefinition[];
+};
+//#endregion

package/dist/resource-source.js

@@ -0,0 +1,22 @@
+import { isPageDefinition } from "@protobase/layout";
+//#region src/resource-source.ts
+/**
+* Splits a config module (`import * as config from './config'`) into its resources, views, pages and, when it exports
+* one `userMenu(...)`, the user menu.
+*/
+const configExports = (module) => {
+	const values = Object.values(module);
+	const pages = values.filter(isPageDefinition);
+	const others = values.filter((value) => !isPageDefinition(value));
+	const buildable = others.filter((value) => typeof value?.toModel === "function");
+	const menus = others.filter((value) => typeof value?.toUserMenuModel === "function");
+	if (menus.length > 1) throw new Error(`The config module exports ${menus.length} user menus; export one userMenu(...)`);
+	return {
+		resources: buildable.filter((value) => typeof value.recordSchema === "function"),
+		views: buildable.filter((value) => typeof value.recordSchema !== "function"),
+		pages,
+		...menus[0] && { userMenu: menus[0] }
+	};
+};
+//#endregion
+export { configExports };

package/dist/reveal-service.js

@@ -0,0 +1,43 @@
+import { badRequest, notFound } from "./problem.js";
+import { tenantScope } from "./tenant.js";
+import { requestAccess, requireOperation } from "./request-access.js";
+import { readTransaction } from "./transactions.js";
+import { fetchReadable } from "./read-service.js";
+import { encodeKey } from "@protobase/schema";
+//#region src/reveal-service.ts
+/**
+* The value of one sensitive field of one record, for a caller who may read the record and the field: the same tenant,
+* row filter and record-level rule as a get. The reveal is published to the audit queue before the value is returned;
+* when publishing fails, so does the reveal.
+*/
+const revealField = async (deps, entry, session, request) => {
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "read");
+	const name = typeof request.field === "string" ? request.field : "";
+	const field = Object.hasOwn(access.readable.fields, name) ? access.readable.fields[name] : void 0;
+	if (!field) throw badRequest("invalid-parameter", `Unknown field "${name}"`);
+	if (!field.sensitive) throw badRequest("invalid-parameter", `"${name}" is not sensitive; it comes with the record`);
+	const keyFields = access.full.primaryKey.map((part) => access.full.fields[part]);
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchReadable(trx, access, request.key, "hide", { fields: [...keyFields, access.full.fields[name]] }));
+	if (!found) throw notFound(`No ${entry.name} with this key`);
+	const tenant = tenantScope(entry, session)?.tenantValue;
+	await deps.audit.publish({
+		type: "field.revealed",
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		actor: {
+			id: session.user.id,
+			roles: [...session.user.roles]
+		},
+		...tenant !== void 0 && { tenant },
+		resource: entry.name,
+		recordKey: encodeKey(request.key),
+		field: name,
+		origin: request.origin
+	});
+	return {
+		field: name,
+		value: found.record[name] ?? null
+	};
+};
+//#endregion
+export { revealField };

package/dist/routes/batch.js

@@ -0,0 +1,21 @@
+import { batchBody } from "../batch/schema.js";
+import { runBatch } from "../batch/run-batch.js";
+import { parseParams } from "../params.js";
+import { Hono } from "hono";
+//#region src/routes/batch.ts
+/**
+* `POST /api/v1:batchWrite`. It sits beside the API's own app, not inside it: the method name is glued to the version
+* segment, so the route is registered on the root with the full path and authenticates itself.
+*/
+const batchRoute = (deps, authenticate, meta) => {
+	const app = new Hono();
+	app.post(`${deps.basePath}:batchWrite`, async (c) => {
+		const session = await authenticate(c.req.raw);
+		const { ops } = parseParams(batchBody, await c.req.json());
+		const results = await runBatch(deps, session, ops);
+		return c.json({ results }, 200, { "X-Meta-Version": await meta.version(session.user.roles) });
+	});
+	return app;
+};
+//#endregion
+export { batchRoute };

package/dist/routes/collection.js

@@ -0,0 +1,63 @@
+import { runWrite } from "../write-pipeline.js";
+import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
+import { listRecords } from "../list-service.js";
+import { returnPreference } from "./preferences.js";
+import { resolveTarget, unknownAction } from "./target.js";
+import { Hono } from "hono";
+import { encodeKey } from "@protobase/schema";
+//#region src/routes/collection.ts
+/** Filters in a JSON body may be much longer than in a URL. */
+const searchFilterLength = 2e5;
+const warningHeader = (warning) => warning ? { "X-Protobase-Warning": warning } : {};
+const collectionRoutes = (deps) => {
+	const app = new Hono();
+	app.get("/:target", async (c) => {
+		const { entry, action } = resolveTarget(deps, c.req.param("target"));
+		const session = c.get("session");
+		const query = c.req.query();
+		if (action === "") {
+			const { body, warning } = await listRecords(deps, entry, session, query);
+			return c.json(body, 200, warningHeader(warning));
+		}
+		if (action === "facets") return c.json(await facets(deps, entry, session, query));
+		if (action === "series") return c.json(await timeSeries(deps, entry, session, query));
+		if (action === "histogram") return c.json(await numericHistogram(deps, entry, session, query));
+		if (action === "seek") {
+			const { body, warning } = await listRecords(deps, entry, session, query, void 0, true);
+			return c.json(body, 200, warningHeader(warning));
+		}
+		return unknownAction(action);
+	});
+	app.post("/:target", async (c) => {
+		const { entry, action } = resolveTarget(deps, c.req.param("target"));
+		const session = c.get("session");
+		const body = await c.req.json();
+		if (action === "search") {
+			const { body: page, warning } = await listRecords(deps, entry, session, body, searchFilterLength);
+			return c.json(page, 200, warningHeader(warning));
+		}
+		if (action !== "") return unknownAction(action);
+		const created = await runWrite(deps, entry, session, {
+			operation: "create",
+			body
+		});
+		const key = entry.model.primaryKey.map((name) => created.record[name]);
+		const location = `${deps.basePath}/${entry.name}/${key.length === 1 ? encodeURIComponent(String(key[0])) : encodeKey(key)}`;
+		const { minimal, applied } = returnPreference(c);
+		const headers = {
+			Location: location,
+			ETag: created.etag,
+			...applied
+		};
+		return minimal ? new Response(null, {
+			status: 201,
+			headers
+		}) : c.json({
+			...created.record,
+			etag: created.etag
+		}, 201, headers);
+	});
+	return app;
+};
+//#endregion
+export { collectionRoutes };

package/dist/routes/docs.js

@@ -0,0 +1,20 @@
+import { requestAccess } from "../request-access.js";
+import { openApiDocument } from "../openapi/document.js";
+import { Hono } from "hono";
+import { Scalar } from "@scalar/hono-api-reference";
+//#region src/routes/docs.ts
+/** The OpenAPI document and the Scalar reference. Both need a token: the document lists what the caller may see and do. */
+const docsRoutes = (deps) => {
+	const app = new Hono();
+	app.get("/openapi.json", async (c) => {
+		const visible = (await Promise.all(deps.registry.entries.map((entry) => requestAccess(deps, entry, c.get("session"))))).filter((access) => Object.values(access.resolved.operations).some(Boolean));
+		return c.json(openApiDocument(visible, deps.basePath, deps.systemPath));
+	});
+	app.get("/docs", Scalar({
+		url: `${deps.systemPath}/openapi.json`,
+		pageTitle: "Protobase API"
+	}));
+	return app;
+};
+//#endregion
+export { docsRoutes };

package/dist/routes/meta.js

@@ -0,0 +1,22 @@
+import { ifNoneMatchSatisfied } from "../etag.js";
+import { Hono } from "hono";
+//#region src/routes/meta.ts
+const metaRoutes = (meta) => {
+	const app = new Hono();
+	app.get("/meta", async (c) => {
+		const { body, etag } = await meta.forCaller(c.get("session"));
+		const headers = {
+			ETag: etag,
+			"Cache-Control": "no-cache"
+		};
+		const given = c.req.header("if-none-match");
+		if (given && ifNoneMatchSatisfied(given, etag)) return new Response(null, {
+			status: 304,
+			headers
+		});
+		return c.json(body, 200, headers);
+	});
+	return app;
+};
+//#endregion
+export { metaRoutes };

package/dist/routes/preferences.js

@@ -0,0 +1,12 @@
+//#region src/routes/preferences.ts
+/** RFC 7240 `Prefer: return=minimal | representation`; the representation is the default. */
+const returnPreference = (c) => {
+	const match = /return=(minimal|representation)/.exec(c.req.header("prefer") ?? "");
+	const applied = match ? { "Preference-Applied": match[0] } : {};
+	return {
+		minimal: match?.[1] === "minimal",
+		applied
+	};
+};
+//#endregion
+export { returnPreference };

package/dist/routes/record.js

@@ -0,0 +1,97 @@
+import { notFound } from "../problem.js";
+import { pickFields } from "../rows.js";
+import { runWrite } from "../write-pipeline.js";
+import { keyFromPath } from "../key.js";
+import { deletedRows, selectedFields } from "../params.js";
+import { returnPreference } from "./preferences.js";
+import { resolveTarget } from "./target.js";
+import { readRecord } from "../read-service.js";
+import { revealField } from "../reveal-service.js";
+import { Hono } from "hono";
+//#region src/routes/record.ts
+const headerValue = (name, value) => value === void 0 ? {} : { [name]: value };
+const recordRoutes = (deps) => {
+	const app = new Hono();
+	app.get("/:resource/:key", async (c) => {
+		const { entry } = resolveTarget(deps, c.req.param("resource"));
+		const deleted = deletedRows(entry.model, c.req.query("show_deleted") === "true");
+		const found = await readRecord(deps, entry, c.get("session"), keyFromPath(c, entry), deleted);
+		const columns = selectedFields({
+			...entry.model,
+			fields: Object.fromEntries(Object.keys(found.record).map((name) => [name, entry.model.fields[name]]))
+		}, c.req.query("fields"));
+		return c.json({
+			...pickFields(found.record, columns),
+			etag: found.etag,
+			permissions: found.permissions
+		}, 200, { ETag: found.etag });
+	});
+	const reveal = async (c, entry) => {
+		const body = await c.req.json();
+		const revealed = await revealField(deps, entry, c.get("session"), {
+			key: keyFromPath(c, entry, ":reveal"),
+			field: typeof body === "object" && body !== null ? body.field : void 0,
+			origin: {
+				...headerValue("userAgent", c.req.header("user-agent")),
+				...headerValue("forwardedFor", c.req.header("x-forwarded-for"))
+			}
+		});
+		return c.json(revealed, 200, { "Cache-Control": "no-store" });
+	};
+	app.post("/:resource/:key", async (c) => {
+		const { entry } = resolveTarget(deps, c.req.param("resource"));
+		if (c.req.param("key").endsWith(":reveal")) return reveal(c, entry);
+		if (!c.req.param("key").endsWith(":undelete")) throw notFound("There is no such method");
+		const restored = await runWrite(deps, entry, c.get("session"), {
+			operation: "undelete",
+			key: keyFromPath(c, entry, ":undelete"),
+			ifMatch: c.req.header("if-match") ?? null
+		});
+		const { minimal, applied } = returnPreference(c);
+		const headers = {
+			ETag: restored.etag,
+			...applied
+		};
+		return minimal ? new Response(null, {
+			status: 204,
+			headers
+		}) : c.json({
+			...restored.record,
+			etag: restored.etag
+		}, 200, headers);
+	});
+	app.patch("/:resource/:key", async (c) => {
+		const { entry } = resolveTarget(deps, c.req.param("resource"));
+		const updated = await runWrite(deps, entry, c.get("session"), {
+			operation: "update",
+			key: keyFromPath(c, entry),
+			body: await c.req.json(),
+			ifMatch: c.req.header("if-match") ?? null
+		});
+		const { minimal, applied } = returnPreference(c);
+		const headers = {
+			ETag: updated.etag,
+			...applied
+		};
+		return minimal ? new Response(null, {
+			status: 204,
+			headers
+		}) : c.json({
+			...updated.record,
+			etag: updated.etag
+		}, 200, headers);
+	});
+	app.delete("/:resource/:key", async (c) => {
+		const { entry } = resolveTarget(deps, c.req.param("resource"));
+		const deleted = await runWrite(deps, entry, c.get("session"), {
+			operation: "delete",
+			key: keyFromPath(c, entry),
+			ifMatch: c.req.header("if-match") ?? null
+		});
+		const preference = c.req.header("prefer") ?? "";
+		return /return=representation/.test(preference) ? c.json(deleted.record, 200, { "Preference-Applied": "return=representation" }) : new Response(null, { status: 204 });
+	});
+	return app;
+};
+//#endregion
+export { recordRoutes };