@protobase/server 0.7.0 → 0.8.0

package/dist/files/attach.js

@@ -0,0 +1,80 @@
+import { badRequest } from "../problem.js";
+import { baseOf, parseUri } from "./uri.js";
+import { tenantScope } from "../tenant.js";
+import { readTicket } from "./ticket.js";
+//#region src/files/attach.ts
+/** The ticket scope of a caller's upload for one field. */
+const ticketScope = (access, field) => ({
+	tenant: String(tenantScope(access.entry, access.session)?.tenantValue ?? ""),
+	resource: access.entry.name,
+	field,
+	user: String(access.session.user.id)
+});
+const fileFields = (access) => Object.values(access.full.fields).filter((field) => field.file);
+/**
+* File values of a validated create or update body, made ready to store: a ticket from `:upload` becomes its clean URI
+* plus the derived fields it carries, `null` clears the field and its derived fields, and the stored value itself is a
+* no-op. Anything else is refused, so a row can only point at a file its writer uploaded for that field.
+*/
+const attachFiles = async (access, values, current) => {
+	const names = Object.keys(values).filter((name) => access.full.fields[name]?.file);
+	const files = access.deps.files;
+	if (names.length === 0 || !files) return values;
+	const result = { ...values };
+	const errors = [];
+	const now = Math.floor(Date.now() / 1e3);
+	for (const name of names) {
+		const field = access.full.fields[name];
+		const derive = field.file.derive ?? [];
+		const value = values[name];
+		if (value === null) {
+			for (const target of derive) result[target] = null;
+			continue;
+		}
+		if (current && value === current[name]) {
+			delete result[name];
+			continue;
+		}
+		const ticket = await readTicket(files.signer, String(value), ticketScope(access, name), now);
+		if (!ticket.ok || ticket.ref.provider !== field.file.provider) {
+			const expired = !ticket.ok && ticket.reason === "expired";
+			errors.push({
+				field: name,
+				code: "invalid-value",
+				message: expired ? "The upload expired; upload the file again" : "Not a file uploaded for this field; upload it with :upload first"
+			});
+			continue;
+		}
+		result[name] = ticket.uri;
+		for (const target of derive) result[target] = Object.hasOwn(ticket.derived, target) ? ticket.derived[target] : null;
+	}
+	if (errors.length > 0) throw badRequest("invalid-record", `The request body is invalid: ${errors[0].field}: ${errors[0].message}`, { errors });
+	return result;
+};
+/**
+* Schedules the delete of every file a write took out of its row: a replaced or cleared value, or all of a hard-deleted
+* row's files, each due after its provider's retention. It runs inside the write transaction, before the commit: if
+* the write rolls back, the file is still referenced when the entry is due, and stays.
+*/
+const scheduleRemovedFiles = async (access, operation, before, after) => {
+	const files = access.deps.files;
+	if (!files || !before || operation === "create" || operation === "undelete") return;
+	if (operation === "delete" && access.full.softDelete) return;
+	const now = Date.now();
+	const removed = fileFields(access).flatMap((field) => {
+		const old = before[field.name];
+		if (typeof old !== "string") return [];
+		const next = after?.[field.name];
+		if (typeof next === "string" && baseOf(next) === baseOf(old)) return [];
+		const ref = parseUri(old);
+		if (!ref || !files.providers[ref.provider]) return [];
+		return [{
+			provider: ref.provider,
+			path: ref.path,
+			due: new Date(now + files.retention(ref.provider))
+		}];
+	});
+	if (removed.length > 0) await files.schedule.add(removed);
+};
+//#endregion
+export { attachFiles, scheduleRemovedFiles, ticketScope };

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

@@ -0,0 +1,8 @@
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/files/cleanup-runner.d.ts
+export type CleanupReport = {
+  deleted: string[];
+  kept: string[];
+};
+//#endregion

package/dist/files/cleanup-runner.js

@@ -0,0 +1,58 @@
+import { sql } from "kysely";
+//#region src/files/cleanup-runner.ts
+/** Every declared file column, once per table and column even when two resources share them. */
+const fileColumns = (models) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const model of models) for (const field of Object.values(model.fields)) {
+		if (field.type !== "file") continue;
+		seen.set(JSON.stringify([
+			model.table.schema ?? "",
+			model.table.name,
+			field.column
+		]), {
+			table: model.table,
+			column: field.column
+		});
+	}
+	return [...seen.values()];
+};
+const chunk = (items, size) => Array.from({ length: Math.ceil(items.length / size) }, (_, i) => items.slice(i * size, (i + 1) * size));
+/** The identities (`provider:path`) among `uris` that some row still holds. */
+const referenced = async (db, columns, uris) => {
+	const found = /* @__PURE__ */ new Set();
+	for (const { table, column } of columns) {
+		const value = sql`split_part(${sql.id(column)}, '?', 1)`;
+		const name = table.schema ? sql.id(table.schema, table.name) : sql.id(table.name);
+		const rows = await sql`select distinct ${value} as uri from ${name} where ${value} = any(${uris})`.execute(db);
+		for (const row of rows.rows) found.add(row.uri);
+	}
+	return found;
+};
+/**
+* Handles every scheduled delete that is due: right before deleting, it checks that no declared file column holds the
+* file; one that is referenced again (a rolled-back write, a restore, a shared value) is kept and its entry dropped.
+* Uploads never attached are deleted here too, after their ticket expired. Running it twice at once is harmless.
+*/
+const runCleanup = async ({ db, columns, providers, schedule, now = /* @__PURE__ */ new Date() }) => {
+	const deleted = /* @__PURE__ */ new Set();
+	const kept = /* @__PURE__ */ new Set();
+	for (const entries of chunk(await schedule.due(now), 500)) {
+		const uris = [...new Set(entries.map((entry) => `${entry.provider}:${entry.path}`))];
+		const inUse = await referenced(db, columns, uris);
+		for (const entry of entries) {
+			const uri = `${entry.provider}:${entry.path}`;
+			if (inUse.has(uri)) kept.add(uri);
+			else if (!deleted.has(uri)) {
+				await providers[entry.provider].store.delete(entry.path);
+				deleted.add(uri);
+			}
+			await schedule.done(entry);
+		}
+	}
+	return {
+		deleted: [...deleted],
+		kept: [...kept]
+	};
+};
+//#endregion
+export { fileColumns, runCleanup };

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

@@ -0,0 +1,28 @@
+import { FileProvider } from "./store.js";
+//#region src/files/cleanup-schedule.d.ts
+/** A file to delete once `due`, unless a row references it again by then. */
+export type ScheduledDelete = {
+  provider: string;
+  path: string;
+  due: Date;
+};
+export type CleanupEntry = ScheduledDelete & {
+  id: string;
+};
+/**
+ * Where scheduled deletes wait. The default keeps them in each provider's own storage (`storageCleanupSchedule`); a
+ * table in a schema of its own, written by a migration at update time, can take its place behind the same three calls.
+ */
+export type CleanupSchedule = {
+  add(deletes: ScheduledDelete[]): Promise<void>;
+  /** Every entry due at `now`. */
+  due(now: Date): Promise<CleanupEntry[]>;
+  /** Drops an entry once it is handled. */
+  done(entry: CleanupEntry): Promise<void>;
+};
+/**
+ * Scheduled deletes as a to-do folder in each provider's storage: one JSON object per delete in `.cleanup/`, named after
+ * its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete.
+ */
+export declare const storageCleanupSchedule: (providers: Record<string, FileProvider>) => CleanupSchedule;
+//#endregion

package/dist/files/cleanup-schedule.js

@@ -0,0 +1,48 @@
+//#region src/files/cleanup-schedule.ts
+const cleanupFolder = ".cleanup/";
+const stamp = (date) => date.toISOString().slice(0, 19).replaceAll(":", "-") + "Z";
+const entryPattern = /^\.cleanup\/(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)-[0-9a-f-]{36}\.json$/;
+const isScheduledDelete = (value) => typeof value === "object" && value !== null && typeof value.provider === "string" && typeof value.path === "string" && typeof value.due === "string";
+/**
+* Scheduled deletes as a to-do folder in each provider's storage: one JSON object per delete in `.cleanup/`, named after
+* its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete.
+*/
+const storageCleanupSchedule = (providers) => {
+	const storeOf = (provider) => {
+		const found = providers[provider];
+		if (!found) throw new Error(`No file provider "${provider}" is configured`);
+		return found.store;
+	};
+	return {
+		add: async (deletes) => {
+			for (const { provider, path, due } of deletes) {
+				const body = new Blob([JSON.stringify({
+					provider,
+					path,
+					due: due.toISOString()
+				})]).stream();
+				await storeOf(provider).put(`${cleanupFolder}${stamp(due)}-${crypto.randomUUID()}.json`, body);
+			}
+		},
+		due: async (now) => {
+			const entries = [];
+			for (const [provider, { store }] of Object.entries(providers)) for (const object of await store.list(cleanupFolder)) {
+				const match = entryPattern.exec(object.path);
+				if (!match) throw new Error(`"${object.path}" in file provider "${provider}" is not a scheduled delete; remove it`);
+				if (match[1] > stamp(now)) continue;
+				const content = JSON.parse(await new Response(await store.read(object.path)).text());
+				if (!isScheduledDelete(content) || content.provider !== provider) throw new Error(`"${object.path}" in file provider "${provider}" is not a scheduled delete of it; remove it`);
+				entries.push({
+					id: object.path,
+					provider,
+					path: content.path,
+					due: new Date(content.due)
+				});
+			}
+			return entries;
+		},
+		done: (entry) => storeOf(entry.provider).delete(entry.id)
+	};
+};
+//#endregion
+export { cleanupFolder, storageCleanupSchedule };

package/dist/files/detect.js

@@ -0,0 +1,51 @@
+import { canonicalExtension, isKnownType, octetStream, textTypes, typeOfExtension } from "./media-types.js";
+import { fileTypeFromBuffer } from "file-type";
+//#region src/files/detect.ts
+const isText = (head, complete) => {
+	if (head.includes(0)) return false;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(head, { stream: !complete });
+		return true;
+	} catch (error) {
+		if (error instanceof TypeError) return false;
+		throw error;
+	}
+};
+const declaredType = (declared) => {
+	const type = declared?.split(";", 1)[0].trim().toLowerCase();
+	return type && type !== "application/octet-stream" ? type : void 0;
+};
+const decided = (type, hints) => {
+	const from = hints.find((hint) => hint !== void 0 && hint !== type);
+	return {
+		type,
+		extension: canonicalExtension(type),
+		...from && { corrected: {
+			from,
+			to: type
+		} }
+	};
+};
+/**
+* The type of an upload, decided once from three signals: the content's magic bytes (C), the name's extension (E) and the
+* client's declared type (H). A recognized C always wins. Unrecognized text takes E when it is a text type, H when there
+* is no extension, otherwise text/plain. Unrecognized binary takes E only when the field lists it exactly and H does not
+* disagree; anything else is application/octet-stream. H never decides on its own.
+*/
+const decideType = async ({ head, complete, name, declared, accept }) => {
+	const fromName = name === void 0 ? void 0 : typeOfExtension(name);
+	const hasExtension = name !== void 0 && /\.[^.]+$/.test(name);
+	const header = declaredType(declared);
+	const hints = [fromName, header];
+	const detected = await fileTypeFromBuffer(head);
+	if (detected) return decided(isKnownType(detected.mime) ? detected.mime : octetStream, hints);
+	if (isText(head, complete)) {
+		if (fromName && textTypes.has(fromName)) return decided(fromName, hints);
+		if (!hasExtension && header && textTypes.has(header)) return decided(header, hints);
+		return decided("text/plain", hints);
+	}
+	if (fromName !== void 0 && fromName !== "application/octet-stream" && accept.includes(fromName) && (header === void 0 || header === fromName)) return decided(fromName, hints);
+	return decided(octetStream, hints);
+};
+//#endregion
+export { decideType };

package/dist/files/download-url.js

@@ -0,0 +1,43 @@
+//#region src/files/download-url.ts
+/** Download URLs stay valid one to two hours and repeat within the hour, so browsers can cache them. */
+const downloadExpiry = (now = Date.now()) => (Math.ceil(now / 36e5) + 1) * 3600;
+const parts = (grant) => [
+	grant.provider,
+	grant.path,
+	grant.resource,
+	grant.key,
+	grant.field,
+	grant.expires
+];
+/** `<base>/<provider>/<path>?r=<resource>&k=<key>&f=<field>&exp=<seconds>&sig=<signature>` */
+const signedDownloadUrl = async (signer, base, grant) => {
+	const query = new URLSearchParams({
+		r: grant.resource,
+		k: grant.key,
+		f: grant.field,
+		exp: String(grant.expires),
+		sig: await signer.sign("download", parts(grant))
+	});
+	return `${base}/${grant.provider}/${grant.path}?${query}`;
+};
+/** The grant of a download URL whose signature checks out; `expired` once it is past its time. */
+const readDownloadUrl = async (signer, provider, path, query, now = Date.now()) => {
+	const expires = Number(query.get("exp"));
+	const grant = {
+		provider,
+		path,
+		resource: query.get("r") ?? "",
+		key: query.get("k") ?? "",
+		field: query.get("f") ?? "",
+		expires
+	};
+	const signature = query.get("sig") ?? "";
+	if (!Number.isSafeInteger(expires) || !await signer.verify("download", parts(grant), signature)) return { status: "invalid" };
+	if (expires * 1e3 < now) return { status: "expired" };
+	return {
+		status: "ok",
+		grant
+	};
+};
+//#endregion
+export { downloadExpiry, readDownloadUrl, signedDownloadUrl };

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