@protobase/server 0.6.0 → 0.8.0

package/dist/files/download.js

@@ -0,0 +1,90 @@
+import { HttpProblem, forbidden, notFound } from "../problem.js";
+import { decodeKeyText } from "../key.js";
+import { readDownloadUrl } from "./download-url.js";
+import { downloadName, isInline, servedType } from "./media-types.js";
+import { baseOf, isFilePath, parseUri, tenantSegment } from "./uri.js";
+import { fetchRecord } from "../records.js";
+import { readTransaction } from "../transactions.js";
+//#region src/files/download.ts
+const gone = () => notFound("There is no such file");
+const rangeOf = (header, size) => {
+	if (!header) return void 0;
+	const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+	if (!match || match[1] === "" && match[2] === "") return false;
+	const start = match[1] === "" ? Math.max(size - Number(match[2]), 0) : Number(match[1]);
+	const end = match[1] === "" || match[2] === "" ? size - 1 : Math.min(Number(match[2]), size - 1);
+	return start <= end && start < size ? {
+		start,
+		end
+	} : false;
+};
+const disposition = (name, type) => {
+	const ascii = name.replace(/[^\x20-\x7e]|["\\]/g, "_");
+	return `${isInline(type) ? "inline" : "attachment"}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+};
+const grantedName = async (deps, provider, path, query) => {
+	const read = await readDownloadUrl(deps.files.signer, provider, path, query);
+	if (read.status === "invalid") throw forbidden("invalid-signature", "This file link is not valid");
+	if (read.status === "expired") throw forbidden("link-expired", "This file link expired; load the record again for a new one");
+	const { grant } = read;
+	const entry = deps.registry.find(grant.resource);
+	const field = entry?.model.fields[grant.field];
+	if (!entry || field?.type !== "file") throw gone();
+	const tenantField = entry.model.tenant ? entry.model.fields[entry.model.tenant] : void 0;
+	const fields = tenantField ? [field, tenantField] : [field];
+	const row = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchRecord(trx, entry, decodeKeyText(entry, grant.key), void 0, {
+		deleted: "show",
+		fields
+	}));
+	const value = row?.record[field.name];
+	if (typeof value !== "string" || baseOf(value) !== `${provider}:${path}`) throw gone();
+	if (tenantField && path.split("/")[0] !== await tenantSegment(row.record[tenantField.name])) throw gone();
+	return {
+		name: parseUri(value)?.name ?? path,
+		expires: grant.expires
+	};
+};
+/**
+* `GET <systemPath>/files/<provider>/<path>`: a public provider's file for anyone; a private one's only through a signed
+* URL whose row still holds it. The Content-Type comes from the path's extension, never from what was uploaded, and
+* nothing renders: `nosniff`, a sandboxing CSP, and `inline` only for images, PDF, audio and video.
+*/
+const serveFile = async (deps, request, provider, path) => {
+	const configured = deps.files?.providers[provider];
+	if (!configured || !isFilePath(path)) throw gone();
+	const granted = configured.public ? void 0 : await grantedName(deps, provider, path, new URL(request.url).searchParams);
+	const object = await configured.store.head(path);
+	if (!object) throw gone();
+	const type = servedType(path);
+	const name = downloadName(granted?.name ?? path.slice(path.lastIndexOf("/") + 1), type);
+	const caching = granted ? `private, max-age=${Math.max(granted.expires - Math.floor(Date.now() / 1e3), 0)}` : "public, max-age=31536000, immutable";
+	const headers = {
+		"content-type": type,
+		"content-disposition": disposition(name, type),
+		"x-content-type-options": "nosniff",
+		"content-security-policy": "sandbox; default-src 'none'",
+		"cache-control": caching,
+		"accept-ranges": "bytes"
+	};
+	const range = rangeOf(request.headers.get("range"), object.size);
+	if (range === false) throw new HttpProblem(416, "range-not-satisfiable", "Range Not Satisfiable", "The requested range is outside the file", {}, { "content-range": `bytes */${object.size}` });
+	const body = await configured.store.read(path, range);
+	if (!body) throw gone();
+	if (!range) return new Response(body, {
+		status: 200,
+		headers: {
+			...headers,
+			"content-length": String(object.size)
+		}
+	});
+	return new Response(body, {
+		status: 206,
+		headers: {
+			...headers,
+			"content-length": String(range.end - range.start + 1),
+			"content-range": `bytes ${range.start}-${range.end}/${object.size}`
+		}
+	});
+};
+//#endregion
+export { serveFile };

package/dist/files/duration.js

@@ -0,0 +1,35 @@
+//#region src/files/duration.ts
+const units = {
+	s: 1e3,
+	second: 1e3,
+	m: 6e4,
+	min: 6e4,
+	minute: 6e4,
+	h: 36e5,
+	hour: 36e5,
+	d: 864e5,
+	day: 864e5,
+	w: 6048e5,
+	week: 6048e5
+};
+/** Milliseconds from a number of them or text such as `1 day`, `14d`, `12 hours` or `0`. */
+const parseDuration = (value, label) => {
+	if (typeof value === "number") {
+		if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a whole number of milliseconds, not ${value}`);
+		return value;
+	}
+	const invalid = /* @__PURE__ */ new Error(`${label} is "${value}"; write it like "1 day", "14d" or "12 hours"`);
+	const match = /^\s*(\d+)\s*([a-z]*)\s*$/i.exec(value);
+	if (!match) throw invalid;
+	const amount = Number(match[1]);
+	const word = match[2].toLowerCase();
+	if (word === "") {
+		if (amount === 0) return 0;
+		throw invalid;
+	}
+	const unit = units[word] ?? units[word.replace(/s$/, "")];
+	if (unit === void 0) throw invalid;
+	return amount * unit;
+};
+//#endregion
+export { parseDuration };

package/dist/files/file-cleanup.d.ts

@@ -0,0 +1,18 @@
+import { FilesOptions } from "./options.js";
+import { CleanupReport } from "./cleanup-runner.js";
+import { ResourceSource } from "../resource-source.js";
+import { Db } from "@protobase/query";
+//#region src/files/file-cleanup.d.ts
+export type FileCleanupInput = {
+  resources: ResourceSource[];
+  db: Db;
+  files?: FilesOptions;
+};
+/**
+ * The scheduled deletes of a project's files, for a runner outside a request: `protobase files cleanup`, or an interval
+ * in `protobase serve`. `undefined` when the project has no file fields.
+ */
+export declare const createFileCleanup: ({ resources, db, files }: FileCleanupInput) => {
+  run: (now?: Date) => Promise<CleanupReport>;
+} | undefined;
+//#endregion

package/dist/files/file-cleanup.js

@@ -0,0 +1,17 @@
+import { cleanupFiles, createFilesRuntime } from "./runtime.js";
+//#region src/files/file-cleanup.ts
+/**
+* The scheduled deletes of a project's files, for a runner outside a request: `protobase files cleanup`, or an interval
+* in `protobase serve`. `undefined` when the project has no file fields.
+*/
+const createFileCleanup = ({ resources, db, files }) => {
+	const runtime = createFilesRuntime({
+		...files && { options: files },
+		env: globalThis.process?.env ?? {},
+		models: resources.map((source) => source.toModel()),
+		systemPath: ""
+	});
+	return runtime && { run: (now) => cleanupFiles(runtime, db, now) };
+};
+//#endregion
+export { createFileCleanup };

package/dist/files/local-files.d.ts

@@ -0,0 +1,17 @@
+import { FileProvider, FileStore } from "./store.js";
+//#region src/files/local-files.d.ts
+export type LocalFilesOptions = {
+  /** The folder the files live in, created when missing; relative to the working directory. */
+  dir: string;
+  /** Files anyone with the link may open, served without a signature. */
+  public?: boolean;
+  /** Where public files are linked from instead of the app's own `/api/files/<provider>`, such as a CDN in front of it. */
+  publicUrl?: string;
+  /** How long bytes outlive their last reference; default `files.retention`, or 0 for a public provider. */
+  retention?: number | string;
+};
+/** A store in a folder on local disk. Writes go to `.tmp/` first and are renamed into place, so they are atomic. */
+export declare const localFileStore: (dir: string) => FileStore;
+/** A provider on local disk: `localFiles({ dir: './data/files/private' })`. */
+export declare const localFiles: ({ dir, public: isPublic, publicUrl, retention }: LocalFilesOptions) => FileProvider;
+//#endregion

package/dist/files/local-files.js

@@ -0,0 +1,101 @@
+import { HttpProblem } from "../problem.js";
+import { parseDuration } from "./duration.js";
+//#region src/files/local-files.ts
+const node = async () => ({
+	fs: await import("node:fs/promises"),
+	streams: await import("node:fs"),
+	path: await import("node:path"),
+	stream: await import("node:stream"),
+	pipeline: (await import("node:stream/promises")).pipeline,
+	crypto: await import("node:crypto")
+});
+const codeOf = (error) => error instanceof Error ? error.code : void 0;
+const storageFull = () => new HttpProblem(507, "storage-full", "Insufficient Storage", "There is no room left to store this file");
+/** A store in a folder on local disk. Writes go to `.tmp/` first and are renamed into place, so they are atomic. */
+const localFileStore = (dir) => {
+	const resolve = async (relative) => {
+		const { path } = await node();
+		const root = path.resolve(dir);
+		const full = path.resolve(root, relative);
+		if (!full.startsWith(`${root}${path.sep}`)) throw new Error(`"${relative}" is outside the file store`);
+		return full;
+	};
+	const head = async (relative) => {
+		const { fs } = await node();
+		try {
+			const stat = await fs.stat(await resolve(relative));
+			return stat.isFile() ? {
+				path: relative,
+				size: stat.size,
+				modified: stat.mtime
+			} : void 0;
+		} catch (error) {
+			if (codeOf(error) === "ENOENT" || codeOf(error) === "ENOTDIR") return void 0;
+			throw error;
+		}
+	};
+	const put = async (relative, body) => {
+		const { fs, streams, path, stream, pipeline, crypto } = await node();
+		const full = await resolve(relative);
+		const temporary = await resolve(`.tmp/${crypto.randomUUID()}`);
+		await fs.mkdir(path.dirname(temporary), { recursive: true });
+		await fs.mkdir(path.dirname(full), { recursive: true });
+		try {
+			await pipeline(stream.Readable.fromWeb(body), streams.createWriteStream(temporary, { flags: "wx" }));
+			await fs.rename(temporary, full);
+		} catch (error) {
+			await fs.rm(temporary, { force: true });
+			if (codeOf(error) === "ENOSPC" || codeOf(error) === "EDQUOT") throw storageFull();
+			throw error;
+		}
+		return { size: (await fs.stat(full)).size };
+	};
+	const read = async (relative, range) => {
+		const { streams, stream } = await node();
+		if (!await head(relative)) return void 0;
+		const reader = streams.createReadStream(await resolve(relative), range ? {
+			start: range.start,
+			end: range.end
+		} : {});
+		return stream.Readable.toWeb(reader);
+	};
+	const remove = async (relative) => {
+		const { fs } = await node();
+		await fs.rm(await resolve(relative), { force: true });
+	};
+	const list = async (prefix) => {
+		const { fs, path } = await node();
+		const root = path.resolve(dir);
+		const folder = await resolve(prefix.replace(/\/$/, ""));
+		let names;
+		try {
+			names = await fs.readdir(folder, { recursive: true });
+		} catch (error) {
+			if (codeOf(error) === "ENOENT") return [];
+			throw error;
+		}
+		const found = [];
+		for (const name of names) {
+			const relative = path.relative(root, path.join(folder, name)).split(path.sep).join("/");
+			const object = await head(relative);
+			if (object) found.push(object);
+		}
+		return found.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	};
+	return {
+		put,
+		head,
+		read,
+		delete: remove,
+		list
+	};
+};
+/** A provider on local disk: `localFiles({ dir: './data/files/private' })`. */
+const localFiles = ({ dir, public: isPublic = false, publicUrl, retention }) => ({
+	store: localFileStore(dir),
+	public: isPublic || publicUrl !== void 0,
+	...publicUrl !== void 0 && { publicUrl: publicUrl.replace(/\/$/, "") },
+	...retention !== void 0 && { retention: parseDuration(retention, "retention") }
+});
+//#endregion
+export { localFileStore, localFiles };

package/dist/files/media-types.js

@@ -0,0 +1,99 @@
+//#region src/files/media-types.ts
+/**
+* The one table between types and extensions. An upload's decided type picks its path's extension, and every download's
+* Content-Type is looked up from that extension here, so what is served never comes from a client's header.
+*/
+const table = [
+	["image/png", ["png"]],
+	["image/jpeg", ["jpg", "jpeg"]],
+	["image/gif", ["gif"]],
+	["image/webp", ["webp"]],
+	["image/avif", ["avif"]],
+	["image/heic", ["heic"]],
+	["image/bmp", ["bmp"]],
+	["image/tiff", ["tif", "tiff"]],
+	["image/x-icon", ["ico"]],
+	["image/svg+xml", ["svg"]],
+	["application/pdf", ["pdf"]],
+	["application/zip", ["zip"]],
+	["application/gzip", ["gz"]],
+	["application/x-tar", ["tar"]],
+	["application/x-7z-compressed", ["7z"]],
+	["application/vnd.rar", ["rar"]],
+	["application/vnd.openxmlformats-officedocument.wordprocessingml.document", ["docx"]],
+	["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ["xlsx"]],
+	["application/vnd.openxmlformats-officedocument.presentationml.presentation", ["pptx"]],
+	["application/vnd.oasis.opendocument.text", ["odt"]],
+	["application/vnd.oasis.opendocument.spreadsheet", ["ods"]],
+	["application/vnd.oasis.opendocument.presentation", ["odp"]],
+	["application/msword", ["doc"]],
+	["application/vnd.ms-excel", ["xls"]],
+	["application/vnd.ms-powerpoint", ["ppt"]],
+	["application/rtf", ["rtf"]],
+	["application/epub+zip", ["epub"]],
+	["application/x-msdownload", ["exe"]],
+	["application/x-sqlite3", ["sqlite"]],
+	["audio/mpeg", ["mp3"]],
+	["audio/wav", ["wav"]],
+	["audio/ogg", ["ogg"]],
+	["audio/mp4", ["m4a"]],
+	["audio/flac", ["flac"]],
+	["video/mp4", ["mp4"]],
+	["video/webm", ["webm"]],
+	["video/quicktime", ["mov"]],
+	["video/x-matroska", ["mkv"]],
+	["text/csv", ["csv"]],
+	["text/tab-separated-values", ["tsv"]],
+	["text/plain", ["txt"]],
+	["text/markdown", ["md"]],
+	["application/json", ["json"]],
+	["application/octet-stream", ["bin"]]
+];
+const octetStream = "application/octet-stream";
+const byExtension = new Map(table.flatMap(([type, extensions]) => extensions.map((extension) => [extension, type])));
+const byType = new Map(table.map(([type, extensions]) => [type, extensions[0]]));
+/** Text formats a name's extension may give text content, which magic bytes cannot tell apart. */
+const textTypes = /* @__PURE__ */ new Set([
+	"text/csv",
+	"text/tab-separated-values",
+	"text/plain",
+	"text/markdown",
+	"application/json"
+]);
+const inlineTypes = /* @__PURE__ */ new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp",
+	"image/avif",
+	"image/bmp",
+	"application/pdf"
+]);
+const extensionOf = (name) => {
+	const dot = name.lastIndexOf(".");
+	return dot <= 0 || dot === name.length - 1 ? void 0 : name.slice(dot + 1).toLowerCase();
+};
+/** The type of a name or path, from its extension; `undefined` for an extension the table does not know. */
+const typeOfExtension = (name) => {
+	const extension = extensionOf(name);
+	return extension === void 0 ? void 0 : byExtension.get(extension);
+};
+/** The type a stored path is served as. */
+const servedType = (path) => typeOfExtension(path) ?? "application/octet-stream";
+/** The canonical extension of a type the table knows. */
+const canonicalExtension = (type) => byType.get(type);
+const isKnownType = (type) => byType.has(type);
+const isInline = (type) => inlineTypes.has(type) || type.startsWith("audio/") || type.startsWith("video/");
+/** Whether `type` passes a field's allowed list: exact types, `type/*` wildcards, `*\/*`; an empty list allows any. */
+const accepts = (allowed, type) => allowed.length === 0 || allowed.some((entry) => entry === "*/*" || entry === type || entry.endsWith("/*") && type.startsWith(entry.slice(0, -1)));
+/** The uploader's name with its extension made to match the stored type: `photo.png` holding a JPEG downloads as `photo.jpg`. */
+const downloadName = (name, type) => {
+	const canonical = canonicalExtension(type);
+	if (!canonical || type === "application/octet-stream") return name;
+	const known = typeOfExtension(name);
+	if (known === type) return name;
+	const extension = extensionOf(name);
+	return `${extension !== void 0 && known !== void 0 ? name.slice(0, -extension.length - 1) : name}.${canonical}`;
+};
+//#endregion
+export { accepts, canonicalExtension, downloadName, extensionOf, isInline, isKnownType, octetStream, servedType, textTypes, typeOfExtension };

package/dist/files/options.d.ts

@@ -0,0 +1,15 @@
+import { FileProvider } from "./store.js";
+//#region src/files/options.d.ts
+/** `files` in `protobase.config.ts`. Environment variables override it (see `resolveProviders`). */
+export type FilesOptions = {
+  /**
+   * Providers by name, such as `private: localFiles({ dir: './data/files' })`. A name is part of every stored value, so
+   * name the role (`archive`), not the vendor. Without config, `private` and `public` are folders under `data/files`.
+   */
+  providers?: Record<string, FileProvider>;
+  /** How long bytes outlive their last reference, for restores; default `1 day`. Public providers default to 0. */
+  retention?: number | string;
+  /** Signs upload tickets and download URLs; default `PROTOBASE_FILES_SECRET`, then `BETTER_AUTH_SECRET`. */
+  secret?: string;
+};
+//#endregion

package/dist/files/present.d.ts

@@ -0,0 +1,15 @@
+import "../types.js";
+import "../request-access.js";
+//#region src/files/present.d.ts
+/** A file field as responses carry it; `missing` when the value does not parse or names a provider the config lacks. */
+export type FileObject = {
+  uri: string;
+  name: string;
+  type: string;
+  size?: number;
+  url?: string;
+} | {
+  uri: string;
+  missing: true;
+};
+//#endregion

package/dist/files/present.js

@@ -0,0 +1,59 @@
+import { downloadExpiry, signedDownloadUrl } from "./download-url.js";
+import { servedType } from "./media-types.js";
+import { parseUri } from "./uri.js";
+import { encodeKey } from "@protobase/schema";
+//#region src/files/present.ts
+const fileObject = async (files, access, row, field, value, expires) => {
+	const ref = parseUri(value);
+	const provider = ref && files.providers[ref.provider];
+	if (!ref || !provider) return {
+		uri: value,
+		missing: true
+	};
+	const described = {
+		uri: value,
+		name: ref.name,
+		type: servedType(ref.path),
+		...ref.size !== void 0 && { size: ref.size }
+	};
+	if (provider.public) return {
+		...described,
+		url: `${provider.publicUrl ?? `${files.path}/${ref.provider}`}/${ref.path}`
+	};
+	const key = access.full.primaryKey.map((name) => row[name]);
+	if (key.some((part) => typeof part !== "string" && typeof part !== "number")) return described;
+	const keyText = encodeKey(key);
+	const url = await signedDownloadUrl(files.signer, files.path, {
+		provider: ref.provider,
+		path: ref.path,
+		resource: access.entry.name,
+		key: keyText,
+		field,
+		expires
+	});
+	return {
+		...described,
+		url
+	};
+};
+/**
+* Records as responses carry them: each readable file field as `{ uri, name, type, size, url }`. The URL is minted here,
+* after the ETag, for a caller who may already see the row: private files get a signed link to this row's field, public
+* ones their permanent address. Stored values, hooks and ETags only ever see the URI.
+*/
+const presentFiles = async (access, rows) => {
+	const files = access.deps.files;
+	const fields = Object.values(access.model.fields).filter((field) => field.type === "file");
+	if (!files || fields.length === 0) return rows;
+	const expires = downloadExpiry();
+	return Promise.all(rows.map(async (row) => {
+		const shown = { ...row };
+		for (const field of fields) {
+			const value = row[field.name];
+			if (typeof value === "string") shown[field.name] = await fileObject(files, access, row, field.name, value, expires);
+		}
+		return shown;
+	}));
+};
+//#endregion
+export { presentFiles };

package/dist/files/processors.d.ts

@@ -0,0 +1,15 @@
+import { FileProcessor } from "@protobase/schema";
+//#region src/files/processors.d.ts
+/** A processor of the project's own: `processor({ accepts: ['image/*'], run: async (file) => … })`. */
+export declare const processor: (definition: FileProcessor) => FileProcessor;
+/** An image's width or height in pixels, as shown (EXIF rotation applied), for an integer field. Null for other files. */
+export declare const imageSize: (dimension: "width" | "height") => FileProcessor;
+/** An image's width divided by its height, as decimal text with `decimals` places (default 4), for a decimal field. */
+export declare const aspectRatio: ({ decimals }?: {
+  decimals?: number;
+}) => FileProcessor;
+/** The file's size in bytes, for an integer field to filter or sort on. */
+export declare const fileSize: () => FileProcessor;
+/** The file's detected type, for a text field to filter or sort on. */
+export declare const fileType: () => FileProcessor;
+//#endregion

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";