@protobase/server 0.7.0 → 0.8.1

package/dist/openapi/schemas.js

@@ -24,6 +24,26 @@ const hoist = (entry, schema) => {
 		hoisted
 	};
 };
+/** How responses carry a file field. */
+const fileSchema = {
+	type: "object",
+	required: ["uri"],
+	description: "A stored file. `url` downloads it: a signed link valid one to two hours for private files, a permanent one for public files. A value that names no configured provider comes as `{ uri, missing: true }`.",
+	properties: {
+		uri: {
+			type: "string",
+			description: "The stored value, `{provider}:{path}?name=…&size=…`; send it back unchanged to keep the file"
+		},
+		name: { type: "string" },
+		type: {
+			type: "string",
+			description: "Detected from the content at upload"
+		},
+		size: { type: "integer" },
+		url: { type: "string" },
+		missing: { type: "boolean" }
+	}
+};
 const only = (schema, names) => ({
 	...schema,
 	properties: Object.fromEntries(names.filter((name) => schema.properties?.[name]).map((name) => [name, schema.properties[name]])),
@@ -40,7 +60,10 @@ const resourceSchemas = (access) => {
 	const output = hoist(entry, convert(entry, "output"));
 	const input = hoist(entry, convert(entry, "input"));
 	const record = only(output.schema, readable);
-	for (const field of Object.values(model.fields)) if (field.readOnly && record.properties?.[field.name]) record.properties[field.name].readOnly = true;
+	for (const field of Object.values(model.fields)) {
+		if (field.file && record.properties?.[field.name]) record.properties[field.name] = field.nullable ? { anyOf: [{ $ref: "#/components/schemas/File" }, { type: "null" }] } : { $ref: "#/components/schemas/File" };
+		if (field.readOnly && record.properties?.[field.name]) record.properties[field.name].readOnly = true;
+	}
 	record.properties.etag = {
 		type: "string",
 		readOnly: true,
@@ -70,6 +93,7 @@ const resourceSchemas = (access) => {
 		for (const field of names) {
 			const fieldModel = writable.fields[field];
 			if (fieldModel?.default && "db" in fieldModel.default && properties[field]) properties[field].description = "Defaults to a value the database generates";
+			if (fieldModel?.file && properties[field]) properties[field].description = `The \`value\` of \`POST /${entry.name}:upload?field=${field}\`, or the stored \`uri\` to keep the file`;
 		}
 		const required = input.schema.required?.filter((field) => names.includes(field) && !optional.has(field)) ?? [];
 		return {
@@ -86,8 +110,9 @@ const resourceSchemas = (access) => {
 		[name]: record,
 		...resolved.operations.create && { [`${name}Create`]: create },
 		...resolved.operations.update && { [`${name}Update`]: update },
-		...output.hoisted
+		...output.hoisted,
+		...Object.values(model.fields).some((field) => field.file) && { File: fileSchema }
 	};
 };
 //#endregion
-export { resourceSchemas };
+export { fileSchema, resourceSchemas };

package/dist/project-config.d.ts

@@ -1,5 +1,8 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
+import { EventsOptions } from "./changes/events-options.js";
+import { FilesOptions } from "./files/options.js";
 import { Authenticator } from "./types.js";
+import { FunctionSource } from "./functions/define-function.js";
 import { AdminOptions } from "./admin-options.js";
 import { Db } from "@protobase/query";
 //#region src/project-config.d.ts
@@ -15,13 +18,19 @@ export type ProjectConfig = {
   authenticate?: Authenticator;
   /** A Better Auth instance; createAdmin mounts its routes under /api/auth. */
   auth?: AdminAuth;
+  /** The API functions, each served at `/api/functions/<name>`; default: one per file in ./functions. */
+  functions?: Record<string, FunctionSource>;
+  /** Where file fields keep their bytes: providers by name, retention and the signing secret (see `FilesOptions`). */
+  files?: FilesOptions;
+  /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
+  events?: EventsOptions;
   options?: AdminOptions;
 };
 /** Typed identity, for `export default defineConfig({ extends: [...], config, auth, ... })` in `protobase.config.ts`. */
 export declare const defineConfig: (config: ProjectConfig) => ProjectConfig;
 /**
  * One config from several, each after the ones it `extends`, the last being the app's own. Named things are all kept:
- * resources, views and pages of the config modules, assistant tools; one name defined by two configs is an error naming
+ * resources, views and pages of the config modules, functions, assistant tools, file providers; one name defined by two configs is an error naming
  * both. Write hooks run in the same order. Every other value is the last config's that sets it, so the app's own wins.
  */
 export declare const mergeConfig: (...configs: ProjectConfig[]) => ProjectConfig;

package/dist/project-config.js

@@ -72,6 +72,38 @@ const mergedAssistant = (named) => {
 		...tools.length > 0 && { tools: tools.map(({ tool }) => tool) }
 	};
 };
+const mergedFunctions = (named) => {
+	const all = named.flatMap(({ config, label }) => Object.entries(config.functions ?? {}).map(([name, value]) => ({
+		name,
+		value,
+		label
+	})));
+	if (all.length === 0) return void 0;
+	checkUnique("The function", all);
+	return Object.fromEntries(all.map(({ name, value }) => [name, value]));
+};
+const mergedFiles = (named) => {
+	const all = named.flatMap(({ config, label }) => config.files ? [{
+		files: config.files,
+		label
+	}] : []);
+	if (all.length === 0) return void 0;
+	const providers = all.flatMap(({ files, label }) => Object.entries(files.providers ?? {}).map(([name, value]) => ({
+		name,
+		value,
+		label
+	})));
+	checkUnique("The file provider", providers);
+	const { retention, secret } = lastSet(all.map(({ files }) => ({
+		retention: files.retention,
+		secret: files.secret
+	})));
+	return {
+		...providers.length > 0 && { providers: Object.fromEntries(providers.map(({ name, value }) => [name, value])) },
+		...retention !== void 0 && { retention },
+		...secret !== void 0 && { secret }
+	};
+};
 const mergedOptions = (named) => {
 	const all = named.flatMap(({ config }) => config.options ? [config.options] : []);
 	if (all.length === 0) return void 0;
@@ -85,17 +117,20 @@ const mergedOptions = (named) => {
 };
 /**
 * One config from several, each after the ones it `extends`, the last being the app's own. Named things are all kept:
-* resources, views and pages of the config modules, assistant tools; one name defined by two configs is an error naming
+* resources, views and pages of the config modules, functions, assistant tools, file providers; one name defined by two configs is an error naming
 * both. Write hooks run in the same order. Every other value is the last config's that sets it, so the app's own wins.
 */
 const mergeConfig = (...configs) => {
 	const named = configs.flatMap((config, index) => flatten(config, config.name ?? `config ${index + 1}`));
-	const { db, authenticate, auth } = lastSet(named.map(({ config }) => ({
+	const { db, authenticate, auth, events } = lastSet(named.map(({ config }) => ({
 		db: config.db,
 		authenticate: config.authenticate,
-		auth: config.auth
+		auth: config.auth,
+		events: config.events
 	})));
 	const module = mergedModule(named);
+	const functions = mergedFunctions(named);
+	const files = mergedFiles(named);
 	const options = mergedOptions(named);
 	const name = configs.at(-1)?.name;
 	return {
@@ -104,6 +139,9 @@ const mergeConfig = (...configs) => {
 		...db && { db },
 		...authenticate && { authenticate },
 		...auth && { auth },
+		...functions && { functions },
+		...files && { files },
+		...events && { events },
 		...options && { options }
 	};
 };

package/dist/read-service.js

@@ -1,4 +1,5 @@
 import { notFound } from "./problem.js";
+import { presentFiles } from "./files/present.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
 import { tenantScope } from "./tenant.js";
@@ -59,7 +60,10 @@ const readRecord = async (deps, entry, session, key, deleted = "hide") => {
 		};
 	});
 	if (!found) throw notFound(`No ${entry.name} with this key`);
-	return found;
+	return {
+		...found,
+		record: (await presentFiles(access, [found.record]))[0]
+	};
 };
 //#endregion
 export { fetchReadable, fieldModes, readRecord };

package/dist/request-access.d.ts

@@ -0,0 +1,5 @@
+import "./types.js";
+import "./registry.js";
+import "./deps.js";
+import { ResourceModel } from "@protobase/schema";
+import "@protobase/query";

package/dist/request-access.js

@@ -3,15 +3,19 @@ import { checkedFilter } from "./filter-input.js";
 import { tenantScope } from "./tenant.js";
 import { checkFilter, resolveAccess, restrictModel } from "@protobase/schema";
 //#region src/request-access.ts
+const organizationOf = (session) => session.organization ? { organization: session.organization } : {};
 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 resolved = await resolveAccess(entry.source, {
+		user: {
+			id: session.user.id,
+			roles: session.user.roles
+		},
+		...organizationOf(session)
+	}, deps.accessOptions);
 	const readable = restrictModel(entry.model, resolved);
 	return {
 		entry,
@@ -86,6 +90,7 @@ const recordDecision = async (access, operation, record, input) => {
 			id: session.user.id,
 			roles: session.user.roles
 		},
+		...organizationOf(session),
 		model: full,
 		operation,
 		record

package/dist/resource-source.d.ts

@@ -1,5 +1,5 @@
 import { PageDefinition } from "@protobase/layout";
-import { AccessSource, UserMenuSource, ViewModel } from "@protobase/schema";
+import { AccessSource, FileProcessor, UserMenuSource, ViewModel } from "@protobase/schema";
 import { z } from "zod";
 //#region src/resource-source.d.ts
 type FieldSource = {
@@ -7,6 +7,9 @@ type FieldSource = {
   meta: {
     readOnly: boolean;
     nullable: boolean;
+    file?: {
+      derive?: Record<string, FileProcessor>;
+    };
   };
 };
 /** What the server needs from a resource builder; every `resource(...)` chain satisfies it. */

package/dist/routes/batch.js

@@ -1,6 +1,6 @@
+import { parseParams } from "../params.js";
 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
 /**

package/dist/routes/collection.js

@@ -1,6 +1,7 @@
 import { runWrite } from "../write-pipeline.js";
-import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
 import { listRecords } from "../list-service.js";
+import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
+import { uploadFile } from "../files/upload.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget, unknownAction } from "./target.js";
 import { Hono } from "hono";
@@ -31,6 +32,7 @@ const collectionRoutes = (deps) => {
 	app.post("/:target", async (c) => {
 		const { entry, action } = resolveTarget(deps, c.req.param("target"));
 		const session = c.get("session");
+		if (action === "upload") return c.json(await uploadFile(deps, entry, session, c.req.raw), 201);
 		const body = await c.req.json();
 		if (action === "search") {
 			const { body: page, warning } = await listRecords(deps, entry, session, body, searchFilterLength);

package/dist/routes/record.js

@@ -3,13 +3,13 @@ import { keyFromPath } from "../key.js";
 import { pickFields } from "../rows.js";
 import { readRecord } from "../read-service.js";
 import { runWrite } from "../write-pipeline.js";
+import { auditOrigin } from "../audit/origin.js";
 import { deletedRows, selectedFields } from "../params.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget } from "./target.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) => {
@@ -31,10 +31,7 @@ const recordRoutes = (deps) => {
 		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"))
-			}
+			origin: auditOrigin(c.req.raw.headers)
 		});
 		return c.json(revealed, 200, { "Cache-Control": "no-store" });
 	};

package/dist/transactions.js

@@ -1,8 +1,15 @@
 import { sql } from "kysely";
 //#region src/transactions.ts
-/** One transaction whose statements Postgres cancels after `timeoutMs` (SET LOCAL statement_timeout). */
-const writeTransaction = (db, timeoutMs, run) => db.transaction().execute(async (trx) => {
-	await sql`select set_config('statement_timeout', ${String(timeoutMs)}, true)`.execute(trx);
+/**
+* One transaction whose statements Postgres cancels after `timeoutMs` (SET LOCAL statement_timeout), with `settings`
+* set for it as well, all in one statement.
+*/
+const writeTransaction = (db, timeoutMs, run, settings = {}) => db.transaction().execute(async (trx) => {
+	const all = Object.entries({
+		statement_timeout: String(timeoutMs),
+		...settings
+	});
+	await sql`select ${sql.join(all.map(([name, value]) => sql`set_config(${name}, ${value}, true)`))}`.execute(trx);
 	return run(trx);
 });
 /** Same, and Postgres refuses any write inside it. */

package/dist/types.d.ts

@@ -8,9 +8,14 @@ export type User = {
   id: string | number;
   roles: string[];
 };
+/** The organization a request works in, with organizations on: the same value as `tenant`. */
+export type SessionOrganization = {
+  id: TenantValue;
+};
 export type Session = {
   user: User;
   tenant?: TenantValue;
+  organization?: SessionOrganization;
 };
 /** Resolves the caller of a request, or throws a 401 problem (see `unauthorized`). */
 export type Authenticator = (request: Request) => Promise<Session> | Session;
@@ -32,8 +37,13 @@ export type WriteEvent = {
 };
 /** Extension point of the write pipeline: a hook that throws rolls the write back. */
 export type PipelineHook = (event: WriteEvent, trx: Db) => Promise<void>;
+/** Where a request came from, as its headers say; proxies set `forwardedFor`, so it is only as trustworthy as they are. */
+export type AuditOrigin = {
+  userAgent?: string;
+  forwardedFor?: string;
+};
 /** What happened, by whom, to which value. It never carries the value itself. */
-export type AuditEvent = {
+export type FieldRevealedEvent = {
   type: 'field.revealed';
   /** ISO 8601, when the server answered. */
   at: string;
@@ -47,12 +57,22 @@ export type AuditEvent = {
   /** The record's key as its URL has it (composite keys joined with a comma). */
   recordKey: string;
   field: string;
-  /** Where the request came from, as its headers say; proxies set `forwardedFor`, so it is only as trustworthy as they are. */
-  origin: {
-    userAgent?: string;
-    forwardedFor?: string;
+  origin: AuditOrigin;
+};
+/** Someone with a global role started working in an organization they are not a member of. */
+export type OrganizationEnteredEvent = {
+  type: 'organization.entered';
+  /** ISO 8601, when the server answered. */
+  at: string;
+  /** Their global roles, which let them in. */
+  actor: {
+    id: string | number;
+    roles: string[];
   };
+  organization: TenantValue;
+  origin: AuditOrigin;
 };
+export type AuditEvent = FieldRevealedEvent | OrganizationEnteredEvent;
 /**
  * Where audit events go. `publish` resolves once the event is accepted; when it rejects, the request that caused the
  * event fails, so nothing is revealed without its event. A real queue replaces the console one through

package/dist/write-pipeline.js

@@ -3,6 +3,8 @@ import { deleteRecord, fetchRecord, insertRecord, restoreRecord } from "./record
 import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
 import { writeTransaction } from "./transactions.js";
+import { attachFiles } from "./files/attach.js";
+import { actorSettings } from "./changes/actor.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
 import { applyUpdate, planUpdate } from "./write-update.js";
@@ -22,7 +24,7 @@ const create = async (trx, deps, access, body) => {
 	const tenantValues = full.tenant && scope ? { [full.tenant]: scope.tenantValue } : {};
 	const preset = typeof body === "object" && body !== null && !Array.isArray(body) && writableFields(access, "create").includes(full.owner ?? "") ? withOwner(access, body) : body;
 	const row = {
-		...withOwner(access, validateBody(access, "create", preset, tenantValues)),
+		...await attachFiles(access, withOwner(access, validateBody(access, "create", preset, tenantValues))),
 		...tenantValues
 	};
 	const filter = await decide(access, "create", void 0, row);
@@ -88,7 +90,7 @@ const writeIn = async (trx, deps, access, request) => {
 const runWrite = async (deps, entry, session, request) => {
 	const access = await requestAccess(deps, entry, session);
 	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
-	return writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request));
+	return writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request), actorSettings(deps, session));
 };
 //#endregion
 export { runWrite, writeIn };

package/dist/write-shared.js

@@ -1,9 +1,11 @@
 import { forbidden, notFound, preconditionFailed, preconditionRequired } from "./problem.js";
+import { presentFiles } from "./files/present.js";
 import { ifMatchSatisfied } from "./etag.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
 import { tenantScope } from "./tenant.js";
 import { andFilters, recordDecision } from "./request-access.js";
+import { scheduleRemovedFiles } from "./files/attach.js";
 //#region src/write-shared.ts
 const missing = (entry) => notFound(`No ${entry.name} with this key`);
 const checkPrecondition = (current, ifMatch, required) => {
@@ -30,9 +32,9 @@ const assertWritten = async (trx, access, written, operation, ...filters) => {
 		fields: [firstKeyField(access)]
 	})) throw denied(access.entry, `leave in that state (${operation})`);
 };
-/** The caller sees the readable fields only; hooks get the whole record. */
-const shown = (access, written) => ({
-	record: pickFields(written.record, Object.keys(access.model.fields)),
+/** The caller sees the readable fields only, files as objects with their URL; hooks get the whole record. */
+const shown = async (access, written) => ({
+	record: (await presentFiles(access, [pickFields(written.record, Object.keys(access.model.fields))]))[0],
 	etag: written.etag
 });
 /** Runs the pipeline hooks for one write, inside the transaction. */
@@ -47,6 +49,7 @@ const notifier = (deps, access) => async (trx, kind, before, after) => {
 		...after && { after }
 	};
 	for (const hook of deps.hooks) await hook(event, trx);
+	await scheduleRemovedFiles(access, kind, before, after);
 };
 //#endregion
 export { assertWritten, checkPrecondition, decide, denied, firstKeyField, keyOf, missing, notifier, shown };

package/dist/write-update.js

@@ -1,6 +1,7 @@
 import { fetchRecord, updateRecord } from "./records.js";
 import { tenantScope } from "./tenant.js";
 import { targetFilter } from "./request-access.js";
+import { attachFiles } from "./files/attach.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier } from "./write-shared.js";
 //#region src/write-update.ts
@@ -20,7 +21,7 @@ const planUpdate = async (trx, access, key, body, ifMatch, required = true) => {
 	});
 	if (!current) throw missing(entry);
 	checkPrecondition(current, ifMatch, required);
-	const values = validateBody(access, "update", body, current.record);
+	const values = await attachFiles(access, validateBody(access, "update", body, current.record), current.record);
 	const filter = Object.keys(values).length === 0 ? void 0 : await decide(access, "update", current.record, values);
 	if (filter && !await fetchRecord(trx, entry, key, tenant, {
 		filter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,13 +30,15 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.7.0",
-    "@protobase/query": "0.7.0",
-    "@protobase/schema": "0.7.0",
+    "@protobase/layout": "0.8.1",
+    "@protobase/query": "0.8.1",
+    "@protobase/schema": "0.8.1",
     "@scalar/hono-api-reference": "^0.12.10",
     "@simplewebauthn/server": "^13.3.1",
     "better-auth": "^1.7.7",
+    "file-type": "^22.1.1",
     "hono": "^4.13.13",
+    "image-size": "^2.0.4",
     "jose": "^6.2.12",
     "kysely": "^0.29.6",
     "nodemailer": "^10.0.16",