@protobase/server 0.7.0 → 0.8.1

package/dist/files/processors.js

@@ -0,0 +1,39 @@
+import { imageSize } from "image-size";
+//#region src/files/processors.ts
+const shownSize = (head) => {
+	let size;
+	try {
+		size = imageSize(head);
+	} catch (error) {
+		if (error instanceof TypeError || error instanceof RangeError) return void 0;
+		throw error;
+	}
+	return (size.orientation ?? 1) >= 5 ? {
+		width: size.height,
+		height: size.width
+	} : {
+		width: size.width,
+		height: size.height
+	};
+};
+/** A processor of the project's own: `processor({ accepts: ['image/*'], run: async (file) => … })`. */
+const processor = (definition) => definition;
+/** An image's width or height in pixels, as shown (EXIF rotation applied), for an integer field. Null for other files. */
+const imageSize$1 = (dimension) => processor({
+	accepts: ["image/*"],
+	run: (file) => shownSize(file.head)?.[dimension] ?? null
+});
+/** An image's width divided by its height, as decimal text with `decimals` places (default 4), for a decimal field. */
+const aspectRatio = ({ decimals = 4 } = {}) => processor({
+	accepts: ["image/*"],
+	run: (file) => {
+		const size = shownSize(file.head);
+		return size && size.height > 0 ? (size.width / size.height).toFixed(decimals) : null;
+	}
+});
+/** The file's size in bytes, for an integer field to filter or sort on. */
+const fileSize = () => processor({ run: (file) => file.size });
+/** The file's detected type, for a text field to filter or sort on. */
+const fileType = () => processor({ run: (file) => file.type });
+//#endregion
+export { aspectRatio, fileSize, fileType, imageSize$1 as imageSize, processor };

package/dist/files/providers.js

@@ -0,0 +1,70 @@
+import { parseDuration } from "./duration.js";
+import { localFiles } from "./local-files.js";
+import { checkedProvider } from "@protobase/schema";
+//#region src/files/providers.ts
+const prefix = "PROTOBASE_FILES_";
+/** `PROTOBASE_FILES_<NAME>` configures a provider, except for these settings. */
+const settingVariables = [
+	"RETENTION",
+	"SECRET",
+	"CLEANUP_MINUTES"
+];
+const reservedNames = new Set(settingVariables.map((name) => name.toLowerCase().replaceAll("_", "-")));
+const checkedName = (name) => {
+	checkedProvider(name);
+	if (reservedNames.has(name)) throw new Error(`"${name}" cannot name a file provider: PROTOBASE_FILES_${name.toUpperCase().replaceAll("-", "_")} is a setting`);
+	return name;
+};
+const variableOf = (name) => `${prefix}${name.toUpperCase().replaceAll("-", "_")}`;
+/** A provider from `file:///data/files/private?public=1&public_url=…&retention=14d` (a relative `file:data/files` works too). */
+const providerFromUrl = (text, variable) => {
+	let url;
+	try {
+		url = new URL(text);
+	} catch (error) {
+		if (error instanceof TypeError) throw new Error(`${variable} is not a URL; write it like file:///data/files/private`);
+		throw error;
+	}
+	if (url.protocol !== "file:") throw new Error(`${variable} uses ${url.protocol}; not implemented: only file: providers (local disk) are supported so far`);
+	const flag = url.searchParams.get("public");
+	const publicUrl = url.searchParams.get("public_url") ?? void 0;
+	const retention = url.searchParams.get("retention") ?? void 0;
+	return localFiles({
+		dir: decodeURIComponent(url.pathname),
+		public: flag === "1" || flag === "true",
+		...publicUrl && { publicUrl },
+		...retention && { retention }
+	});
+};
+/**
+* The providers in effect: the config's, each replaced by `PROTOBASE_FILES_<NAME>` when that is set, plus any the
+* environment adds. `private` and `public` default to `data/files/private` and `data/files/public` when `used` needs them.
+*/
+const resolveProviders = (options, env, used) => {
+	const providers = {};
+	for (const [name, provider] of Object.entries(options.providers ?? {})) providers[checkedName(name)] = provider;
+	for (const [variable, value] of Object.entries(env)) {
+		if (!variable.startsWith(prefix) || !value) continue;
+		const suffix = variable.slice(16);
+		if (settingVariables.includes(suffix)) continue;
+		const name = checkedName(suffix.toLowerCase().replaceAll("_", "-"));
+		providers[name] = providerFromUrl(value, variable);
+	}
+	for (const name of used) {
+		if (providers[name]) continue;
+		if (name !== "private" && name !== "public") throw new Error(`No file provider "${name}": add it to files.providers in protobase.config.ts or set ${variableOf(name)}`);
+		providers[name] = localFiles({
+			dir: `data/files/${name}`,
+			public: name === "public"
+		});
+	}
+	return providers;
+};
+/** How long a provider keeps bytes after their last reference. */
+const retentionOf = (options, env) => {
+	const fallback = env[`${prefix}RETENTION`] ?? options.retention ?? "1 day";
+	const global = parseDuration(fallback, env[`${prefix}RETENTION`] ? `${prefix}RETENTION` : "files.retention");
+	return (provider) => provider.retention ?? (provider.public ? 0 : global);
+};
+//#endregion
+export { providerFromUrl, resolveProviders, retentionOf, settingVariables };

package/dist/files/routes.js

@@ -0,0 +1,26 @@
+import { forbidden } from "../problem.js";
+import { serveFile } from "./download.js";
+import { cleanupFiles } from "./runtime.js";
+import { Hono } from "hono";
+//#region src/files/routes.ts
+/**
+* Beside the API, on the app's own host: `GET <systemPath>/files/<provider>/<path>` serves files, and
+* `POST <systemPath>/files:cleanup` runs the scheduled deletes that are due, for an admin (a platform calls it on a schedule).
+*/
+const fileRoutes = (deps, authenticate) => {
+	const app = new Hono();
+	const files = deps.files;
+	if (!files) return app;
+	app.get(`${files.path}/:provider/*`, (c) => {
+		const provider = c.req.param("provider");
+		const path = decodeURIComponent(new URL(c.req.url).pathname.slice(`${files.path}/${provider}/`.length));
+		return serveFile(deps, c.req.raw, provider, path);
+	});
+	app.post(`${files.path}:cleanup`, async (c) => {
+		if (!(await authenticate(c.req.raw)).user.roles.includes("admin")) throw forbidden("access-denied", "Only an admin may run the file cleanup");
+		return c.json(await cleanupFiles(files, deps.db));
+	});
+	return app;
+};
+//#endregion
+export { fileRoutes };

package/dist/files/runtime.d.ts

@@ -0,0 +1,3 @@
+import "./cleanup-runner.js";
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";

package/dist/files/runtime.js

@@ -0,0 +1,37 @@
+import { fileColumns, runCleanup } from "./cleanup-runner.js";
+import { storageCleanupSchedule } from "./cleanup-schedule.js";
+import { resolveProviders, retentionOf } from "./providers.js";
+import { createSigner } from "./signer.js";
+//#region src/files/runtime.ts
+/** How long an upload ticket stays usable, so a form left open still saves. */
+const ticketSeconds = 86400;
+/**
+* The runtime, when a resource has a file field or the config names providers. It fails at startup when a field's
+* provider is not configured or nothing signs uploads.
+*/
+const createFilesRuntime = ({ options = {}, env, models, systemPath }) => {
+	const used = [...new Set(models.flatMap((model) => Object.values(model.fields).flatMap((field) => field.file ? [field.file.provider] : [])))];
+	if (used.length === 0 && !options.providers) return void 0;
+	const secret = options.secret ?? env.PROTOBASE_FILES_SECRET ?? env.BETTER_AUTH_SECRET;
+	if (!secret) throw new Error("File fields need a secret to sign uploads: set BETTER_AUTH_SECRET, PROTOBASE_FILES_SECRET or files.secret");
+	const providers = resolveProviders(options, env, used);
+	const retention = retentionOf(options, env);
+	return {
+		providers,
+		signer: createSigner(secret),
+		schedule: storageCleanupSchedule(providers),
+		retention: (provider) => retention(providers[provider]),
+		path: `${systemPath}/files`,
+		columns: fileColumns(models)
+	};
+};
+/** Runs the scheduled deletes that are due (see `runCleanup`). */
+const cleanupFiles = (runtime, db, now) => runCleanup({
+	db,
+	columns: runtime.columns,
+	providers: runtime.providers,
+	schedule: runtime.schedule,
+	...now && { now }
+});
+//#endregion
+export { cleanupFiles, createFilesRuntime, ticketSeconds };

package/dist/files/signer.js

@@ -0,0 +1,32 @@
+//#region src/files/signer.ts
+const encoder = new TextEncoder();
+const toBase64Url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes))).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+const fromBase64Url = (text) => {
+	if (!/^[A-Za-z0-9_-]{43}$/.test(text)) return void 0;
+	return Uint8Array.from(atob(text.replaceAll("-", "+").replaceAll("_", "/")), (char) => char.charCodeAt(0));
+};
+const createSigner = (secret) => {
+	const key = (async () => {
+		const material = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveKey"]);
+		return crypto.subtle.deriveKey({
+			name: "HKDF",
+			hash: "SHA-256",
+			salt: /* @__PURE__ */ new Uint8Array(0),
+			info: encoder.encode("protobase files")
+		}, material, {
+			name: "HMAC",
+			hash: "SHA-256",
+			length: 256
+		}, false, ["sign", "verify"]);
+	})();
+	const content = (purpose, parts) => encoder.encode(JSON.stringify([purpose, ...parts]));
+	return {
+		sign: async (purpose, parts) => toBase64Url(await crypto.subtle.sign("HMAC", await key, content(purpose, parts))),
+		verify: async (purpose, parts, signature) => {
+			const bytes = fromBase64Url(signature);
+			return bytes !== void 0 && crypto.subtle.verify("HMAC", await key, bytes, content(purpose, parts));
+		}
+	};
+};
+//#endregion
+export { createSigner };

package/dist/files/store.d.ts

@@ -0,0 +1,37 @@
+//#region src/files/store.d.ts
+/** One stored object. */
+export type StoredObject = {
+  path: string;
+  size: number;
+  modified: Date;
+};
+/**
+ * Where a provider keeps bytes: local disk now, an S3-compatible bucket later. Paths are relative and use `/`. Every
+ * operation on a path that does not exist is harmless: `head` and `read` give `undefined`, `delete` does nothing.
+ */
+export type FileStore = {
+  /** Writes the whole stream, or nothing when it fails: a reader never sees part of an object. */
+  put(path: string, body: ReadableStream<Uint8Array>): Promise<{
+    size: number;
+  }>;
+  head(path: string): Promise<StoredObject | undefined>;
+  /** The bytes, or the inclusive byte range `start`–`end`. */
+  read(path: string, range?: {
+    start: number;
+    end: number;
+  }): Promise<ReadableStream<Uint8Array> | undefined>;
+  delete(path: string): Promise<void>;
+  /** Every object under `prefix` (a folder such as `.cleanup/`), sorted by path. */
+  list(prefix: string): Promise<StoredObject[]>;
+};
+/** A configured provider: its store, whether its files are public, and how long bytes outlive their last reference. */
+export type FileProvider = {
+  store: FileStore;
+  /** Served to anyone at a permanent URL. */
+  public: boolean;
+  /** Where public files are linked from, such as a CDN; default the app's own `/api/files/<provider>`. */
+  publicUrl?: string;
+  /** Milliseconds between a file leaving its row and its bytes being deleted; default `files.retention` (0 when public). */
+  retention?: number;
+};
+//#endregion

package/dist/files/ticket.js

@@ -0,0 +1,87 @@
+import { formatUri, parseUri } from "./uri.js";
+//#region src/files/ticket.ts
+const sortedEntries = (derived) => Object.entries(derived).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+const parts = (uri, derived, scope, expires) => [
+	uri,
+	sortedEntries(derived),
+	scope.tenant,
+	scope.resource,
+	scope.field,
+	scope.user,
+	expires
+];
+/**
+* What `:upload` answers with, and what a write sends back: the file's URI with its derived values, an expiry (Unix
+* seconds) and a signature over them and the scope, so it works only for that uploader, tenant, resource and field.
+*/
+const issueTicket = async (signer, ref, derived, scope, expires) => {
+	const uri = formatUri(ref);
+	return `${uri}&${new URLSearchParams([
+		...sortedEntries(derived).map(([column, value]) => [`d.${column}`, JSON.stringify(value)]),
+		["exp", String(expires)],
+		["sig", await signer.sign("ticket", parts(uri, derived, scope, expires))]
+	])}`;
+};
+const parseJson = (text) => {
+	try {
+		return { value: JSON.parse(text) };
+	} catch (error) {
+		if (error instanceof SyntaxError) return void 0;
+		throw error;
+	}
+};
+/** The clean URI and derived values of a ticket that verifies for `scope` and has not expired at `now` (Unix seconds). */
+const readTicket = async (signer, value, scope, now) => {
+	const query = new URLSearchParams(value.slice(value.indexOf("?") + 1));
+	const signature = query.get("sig");
+	if (!value.includes("?") || signature === null) return {
+		ok: false,
+		reason: "not-a-ticket"
+	};
+	const derived = {};
+	for (const [name, text] of query) {
+		if (!name.startsWith("d.")) continue;
+		const parsed = parseJson(text);
+		if (!parsed) return {
+			ok: false,
+			reason: "invalid"
+		};
+		derived[name.slice(2)] = parsed.value;
+	}
+	const known = /* @__PURE__ */ new Set([
+		"name",
+		"size",
+		"exp",
+		"sig"
+	]);
+	if ([...query.keys()].some((name) => !known.has(name) && !name.startsWith("d."))) return {
+		ok: false,
+		reason: "invalid"
+	};
+	const parsed = parseUri(value.slice(0, value.indexOf("?")) + `?${new URLSearchParams({
+		name: query.get("name") ?? "",
+		size: query.get("size") ?? ""
+	})}`);
+	const expires = Number(query.get("exp"));
+	if (!parsed || parsed.size === void 0 || !Number.isSafeInteger(expires)) return {
+		ok: false,
+		reason: "invalid"
+	};
+	const uri = formatUri(parsed);
+	if (!await signer.verify("ticket", parts(uri, derived, scope, expires), signature)) return {
+		ok: false,
+		reason: "invalid"
+	};
+	if (expires < now) return {
+		ok: false,
+		reason: "expired"
+	};
+	return {
+		ok: true,
+		uri,
+		ref: parsed,
+		derived
+	};
+};
+//#endregion
+export { issueTicket, readTicket };

package/dist/files/upload-body.js

@@ -0,0 +1,85 @@
+import { HttpProblem, badRequest } from "../problem.js";
+//#region src/files/upload-body.ts
+const tooLarge = (maxSize) => new HttpProblem(413, "file-too-large", "Payload Too Large", `The file is larger than this field allows (${maxSize} bytes)`);
+const multipartSlack = 65536;
+/**
+* The file of an upload request: the raw body with `?name=` and its Content-Type, or the one file part of a
+* `multipart/form-data` body with that part's file name and type. A multipart body is read whole, after its size is
+* checked; a raw body streams.
+*/
+const incomingFile = async (request, maxSize) => {
+	const header = request.headers.get("content-length");
+	const length = header === null ? void 0 : Number(header);
+	const contentType = request.headers.get("content-type") ?? void 0;
+	const name = new URL(request.url).searchParams.get("name") ?? void 0;
+	if (!contentType?.toLowerCase().startsWith("multipart/form-data")) {
+		if (length !== void 0 && length > maxSize) throw tooLarge(maxSize);
+		return {
+			body: request.body ?? new Blob([]).stream(),
+			...name !== void 0 && { name },
+			...contentType && { declared: contentType },
+			...length !== void 0 && { length }
+		};
+	}
+	if (length !== void 0 && length > maxSize + multipartSlack) throw tooLarge(maxSize);
+	const files = [...(await request.formData()).values()].filter((value) => typeof value !== "string");
+	if (files.length !== 1) throw badRequest("invalid-upload", `A multipart upload carries exactly one file part, not ${files.length}`);
+	const file = files[0];
+	if (file.size > maxSize) throw tooLarge(maxSize);
+	return {
+		body: file.stream(),
+		name: file.name || name,
+		...file.type && { declared: file.type },
+		length: file.size
+	};
+};
+const concat = (chunks, length) => {
+	const joined = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		joined.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return joined;
+};
+/** The first `want` bytes (or all, when there are fewer), and whether that was the whole stream. */
+const readHead = async (reader, want) => {
+	const chunks = [];
+	let length = 0;
+	while (length < want) {
+		const next = await reader.read();
+		if (next.done) return {
+			head: concat(chunks, length),
+			complete: true
+		};
+		chunks.push(next.value);
+		length += next.value.length;
+	}
+	return {
+		head: concat(chunks, length),
+		complete: false
+	};
+};
+var FileTooLarge = class extends Error {};
+/** The head followed by the rest of the reader, failing with `FileTooLarge` past `maxSize` bytes. */
+const limitedStream = (head, reader, maxSize) => {
+	let size = head.length;
+	return new ReadableStream({
+		start: (controller) => {
+			if (head.length > 0) controller.enqueue(head);
+		},
+		pull: async (controller) => {
+			const next = await reader.read();
+			if (next.done) return controller.close();
+			size += next.value.length;
+			if (size > maxSize) {
+				await reader.cancel();
+				return controller.error(new FileTooLarge());
+			}
+			controller.enqueue(next.value);
+		},
+		cancel: (reason) => reader.cancel(reason)
+	});
+};
+//#endregion
+export { FileTooLarge, incomingFile, limitedStream, readHead, tooLarge };

package/dist/files/upload.js

@@ -0,0 +1,124 @@
+import { HttpProblem, badRequest } from "../problem.js";
+import { accepts } from "./media-types.js";
+import { cleanName, tenantSegment } from "./uri.js";
+import { tenantScope } from "../tenant.js";
+import { requestAccess, requireOperation, writableFields } from "../request-access.js";
+import { issueTicket } from "./ticket.js";
+import { ticketScope } from "./attach.js";
+import { ticketSeconds } from "./runtime.js";
+import { decideType } from "./detect.js";
+import { FileTooLarge, incomingFile, limitedStream, readHead, tooLarge } from "./upload-body.js";
+//#region src/files/upload.ts
+/** How many first bytes processors get as `head`: enough for image headers, EXIF included. */
+const headBytes = 262144;
+const uploadField = (access, name) => {
+	if (!access.resolved.operations.create && !access.resolved.operations.update) requireOperation(access, "update");
+	const field = name !== void 0 && Object.hasOwn(access.readable.fields, name) ? access.full.fields[name] : void 0;
+	if (!field?.file) throw badRequest("invalid-parameter", `"${name ?? ""}" is not a file field of ${access.entry.name}`, { errors: [{
+		parameter: "field",
+		message: "Not a file field"
+	}] });
+	if (!writableFields(access, "create").includes(field.name) && !writableFields(access, "update").includes(field.name)) throw badRequest("invalid-parameter", `"${field.name}" is read-only`, { errors: [{
+		parameter: "field",
+		message: "Read-only"
+	}] });
+	return field;
+};
+const deriveValues = async (entry, field, input) => {
+	const source = entry.source.state.fields?.[field.name];
+	const derived = {};
+	for (const [target, processor] of Object.entries(source?.meta.file?.derive ?? {})) {
+		const value = !processor.accepts || accepts(processor.accepts, input.type) ? await processor.run({
+			name: input.name,
+			type: input.type,
+			size: input.size,
+			head: input.head,
+			read: async () => {
+				const body = await input.store.read(input.path);
+				if (!body) throw new Error(`The upload ${input.path} is gone from its store`);
+				return body;
+			}
+		}) : null;
+		const schema = entry.source.state.fields?.[target]?.schema;
+		const normalized = value === void 0 ? null : value;
+		if (schema && !schema.safeParse(normalized).success) throw new Error(`The processor for "${target}" of ${entry.name} returned ${JSON.stringify(normalized)}, which that field refuses`);
+		derived[target] = normalized;
+	}
+	return derived;
+};
+/**
+* `POST /{resource}:upload?field=<field>`: streams one file to the field's provider and answers with a ticket for a
+* write. The type is decided from the first bytes before anything is stored, a refused type gets 415 and a file over
+* `maxSize` 413. The field's processors then compute its derived values, which the ticket carries signed. An upload no
+* write ever uses is deleted after the ticket expires.
+*/
+const uploadFile = async (deps, entry, session, request) => {
+	const files = deps.files;
+	const access = await requestAccess(deps, entry, session);
+	const field = uploadField(access, new URL(request.url).searchParams.get("field") ?? void 0);
+	if (!files) throw new Error(`Resource "${entry.name}" has file fields but no file runtime`);
+	const { accept, maxSize, provider: providerName } = field.file;
+	const provider = files.providers[providerName];
+	const incoming = await incomingFile(request, maxSize);
+	const reader = incoming.body.getReader();
+	const { head, complete } = await readHead(reader, headBytes);
+	if (head.length > maxSize) {
+		await reader.cancel();
+		throw tooLarge(maxSize);
+	}
+	const name = cleanName(incoming.name);
+	const decision = await decideType({
+		head,
+		complete,
+		name,
+		accept,
+		...incoming.declared && { declared: incoming.declared }
+	});
+	if (!accepts(accept, decision.type)) {
+		await reader.cancel();
+		throw new HttpProblem(415, "unsupported-type", "Unsupported Media Type", `This field takes ${accept.join(", ")}; the file is ${decision.type}`, {
+			detected: decision.type,
+			accept
+		});
+	}
+	const expires = Math.floor(Date.now() / 1e3) + ticketSeconds;
+	const path = `${await tenantSegment(tenantScope(entry, session)?.tenantValue)}/${crypto.randomUUID()}.${decision.extension}`;
+	await files.schedule.add([{
+		provider: providerName,
+		path,
+		due: /* @__PURE__ */ new Date((expires + 3600) * 1e3)
+	}]);
+	let size;
+	try {
+		size = (await provider.store.put(path, limitedStream(head, reader, maxSize))).size;
+	} catch (error) {
+		if (error instanceof FileTooLarge) throw tooLarge(maxSize);
+		throw error;
+	}
+	const derived = await deriveValues(entry, field, {
+		name,
+		type: decision.type,
+		size,
+		head,
+		store: provider.store,
+		path
+	});
+	const ref = {
+		provider: providerName,
+		path,
+		name,
+		size
+	};
+	return {
+		value: await issueTicket(files.signer, ref, derived, ticketScope(access, field.name), expires),
+		file: {
+			name,
+			type: decision.type,
+			size
+		},
+		derived,
+		...decision.corrected && { corrected: decision.corrected }
+	};
+};
+//#endregion
+export { headBytes, uploadFile };

package/dist/files/uri.js

@@ -0,0 +1,47 @@
+import { sha256Hex } from "../hash.js";
+//#region src/files/uri.ts
+const provider = /^[a-z][a-z0-9-]{0,31}$/;
+const segment = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/;
+const maxPath = 512;
+const isFilePath = (path) => path.length <= maxPath && path.split("/").every((part) => segment.test(part));
+/** The identity of a value or ticket: `{provider}:{path}`. */
+const baseOf = (value) => value.split("?", 1)[0];
+const formatUri = (ref) => {
+	const query = new URLSearchParams({
+		name: ref.name,
+		...ref.size !== void 0 && { size: String(ref.size) }
+	});
+	return `${ref.provider}:${ref.path}?${query}`;
+};
+const lastSegment = (path) => path.slice(path.lastIndexOf("/") + 1);
+/** The file a value names, or `undefined` when it does not parse. */
+const parseUri = (value) => {
+	const match = /^([a-z][a-z0-9-]*):([^?#]+)(?:\?([^#]*))?$/.exec(value);
+	if (!match || !provider.test(match[1]) || !isFilePath(match[2])) return void 0;
+	const query = new URLSearchParams(match[3] ?? "");
+	const size = query.get("size");
+	if (size !== null && !/^\d{1,15}$/.test(size)) return void 0;
+	return {
+		provider: match[1],
+		path: match[2],
+		name: query.get("name") || lastSegment(match[2]),
+		...size !== null && { size: Number(size) }
+	};
+};
+const encoder = new TextEncoder();
+/** The uploader's file name without a path or control characters, at most 255 bytes; `file` when nothing is left. */
+const cleanName = (name) => {
+	const text = name ?? "";
+	let clean = text.slice(Math.max(text.lastIndexOf("/"), text.lastIndexOf("\\")) + 1).replace(/[\u0000-\u001f\u007f]/g, "").trim();
+	while (encoder.encode(clean).length > 255) clean = clean.slice(0, -1);
+	return clean || "file";
+};
+const tenantText = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** The first path segment of an upload: the row's tenant as it is when it fits, a hash of it when not, `_` without one. */
+const tenantSegment = async (tenant) => {
+	if (tenant === void 0) return "_";
+	const text = String(tenant);
+	return tenantText.test(text) ? text : `t${(await sha256Hex(text)).slice(0, 32)}`;
+};
+//#endregion
+export { baseOf, cleanName, formatUri, isFilePath, parseUri, tenantSegment };

package/dist/functions/define-function.d.ts

@@ -0,0 +1,71 @@
+import { Session } from "../types.js";
+import { FunctionRecords } from "./records.js";
+import { Db } from "@protobase/query";
+//#region src/functions/define-function.d.ts
+/** What every function gets: its name and the raw database. */
+export type PublicFunctionContext = {
+  /** The function's name, as in `/api/functions/<name>`. */
+  name: string;
+  /** The database itself, with no access rules, row filters or tenant scope: privileged work only. */
+  db: Db;
+  /** The caller, through the app's own `authenticate`: rejects with a 401 problem when the request carries no valid token. */
+  caller: () => Promise<FunctionCaller>;
+};
+/** Who called a function, and the app's resources as them. */
+export type FunctionCaller = {
+  session: Session;
+  /** The app's resources as this caller, under the same access rules, row filters and tenant scope as the REST API. */
+  records: FunctionRecords;
+};
+/** What a function that needs a signed-in caller gets: the caller resolved before it runs. */
+export type FunctionContext = PublicFunctionContext & FunctionCaller;
+/** A Web-standard handler. Its request's path is the part after `/api/functions/<name>`: `/` or `/more/parts`. */
+export type FunctionHandler = (request: Request, context: FunctionContext) => Response | Promise<Response>;
+export type PublicFunctionHandler = (request: Request, context: PublicFunctionContext) => Response | Promise<Response>;
+/** Any app with a Hono-style `fetch`, such as `new Hono()`: its `c.env` is the function's context. */
+export type FunctionApp<Context = FunctionContext> = {
+  fetch: (request: Request, env: Context) => Response | Promise<Response>;
+};
+/** `hono/cors` options: an origin, a list of them, or a function of the request's origin. */
+export type CorsOptions = {
+  origin: string | string[] | ((origin: string) => string | undefined | null);
+  allowMethods?: string[];
+  allowHeaders?: string[];
+  exposeHeaders?: string[];
+  maxAge?: number;
+  credentials?: boolean;
+};
+type SharedOptions = {
+  /** Answers CORS preflights before authentication and adds the CORS headers to every response, problems included. */
+  cors?: CorsOptions;
+};
+/** A function anyone may call, such as a webhook; it can still ask for a caller with `context.caller()`. */
+export type PublicFunctionOptions = SharedOptions & {
+  public: true;
+};
+export type ProtectedFunctionOptions = SharedOptions & {
+  public?: false;
+  /** The caller needs one of these roles, otherwise the call is a 403 problem. */
+  roles?: string[];
+};
+export type FunctionOptions = PublicFunctionOptions | ProtectedFunctionOptions;
+/** A function as `createAdmin` serves it: its options and what answers its requests. */
+export type ApiFunction = {
+  kind: 'function';
+  options: PublicFunctionOptions;
+  handler: PublicFunctionHandler | FunctionApp<PublicFunctionContext>;
+} | {
+  kind: 'function';
+  options: ProtectedFunctionOptions;
+  handler: FunctionHandler | FunctionApp;
+};
+/** What a function file may default-export: `defineFunction(...)`, a bare handler or a Hono app (both protected). */
+export type FunctionSource = ApiFunction | FunctionHandler | FunctionApp;
+/**
+ * A function of your own, served at `/api/functions/<name>`. Without options it needs a signed-in caller, through the
+ * app's `authenticate`; `{ public: true }` opens it to anyone, as for a webhook.
+ */
+export declare function defineFunction(handler: FunctionHandler | FunctionApp): ApiFunction;
+export declare function defineFunction(options: PublicFunctionOptions, handler: PublicFunctionHandler | FunctionApp<PublicFunctionContext>): ApiFunction;
+export declare function defineFunction(options: ProtectedFunctionOptions, handler: FunctionHandler | FunctionApp): ApiFunction;
+//#endregion