@protobase/server 0.12.16 → 0.12.18

package/dist/files/download.js

@@ -1,7 +1,7 @@
 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 { downloadExpiry, readDownloadUrl } from "./download-url.js";
+import { contentDisposition, downloadName, servedType } from "./media-types.js";
 import { baseOf, isFilePath, parseUri, tenantSegment } from "./uri.js";
 import { fetchRecord } from "../records.js";
 import { readTransaction } from "../transactions.js";
@@ -18,10 +18,6 @@ const rangeOf = (header, size) => {
 		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");
@@ -44,23 +40,40 @@ const grantedName = async (deps, provider, path, query) => {
 		expires: grant.expires
 	};
 };
+const redirectToStore = async (store, path, type, name, expires) => {
+	const location = await store.downloadUrl(path, {
+		expires,
+		type,
+		disposition: contentDisposition(name, type)
+	});
+	const seconds = Math.max(expires - Math.floor(Date.now() / 1e3), 0);
+	return new Response(null, {
+		status: 302,
+		headers: {
+			location,
+			"cache-control": `private, max-age=${seconds}`
+		}
+	});
+};
 /**
 * `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.
+* nothing renders: `nosniff`, a sandboxing CSP, and `inline` only for images, PDF, audio and video. A store with its own
+* download links gets a redirect to one instead, with the same type and disposition.
 */
 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);
+	if (configured.store.downloadUrl) return redirectToStore(configured.store, path, type, name, granted?.expires ?? downloadExpiry());
+	const object = await configured.store.head(path);
+	if (!object) throw gone();
 	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),
+		"content-disposition": contentDisposition(name, type),
 		"x-content-type-options": "nosniff",
 		"content-security-policy": "sandbox; default-src 'none'",
 		"cache-control": caching,

package/dist/files/limits.d.ts

@@ -0,0 +1,15 @@
+import { FileStore } from "./store.js";
+//#region src/files/limits.d.ts
+/** The most a provider may hold, in bytes and in files; a bucket has no quota of its own. */
+export type FileLimits = {
+  maxBytes?: number | string;
+  maxFiles?: number;
+};
+/**
+ * `store` refusing a file with `507` once it would hold more than `maxBytes` or `maxFiles`. Only files count, not the
+ * store's own `.cleanup/` entries. What the store holds is counted with `list` on the first upload and again when the
+ * count is older than `recountMs`, and in between follows this instance's own writes: several instances, or a delete
+ * made elsewhere, can be off by what happened since the last count.
+ */
+export declare const limitedFileStore: (store: FileStore, limits: FileLimits, now?: () => number) => FileStore;
+//#endregion

package/dist/files/limits.js

@@ -0,0 +1,79 @@
+import { HttpProblem } from "../problem.js";
+import { isFilePath } from "./uri.js";
+import { parseSize } from "@protobase/schema";
+//#region src/files/limits.ts
+/** How long a count of what a store holds is trusted before it is taken again. */
+const recountMs = 3e5;
+const limitReached = () => new HttpProblem(507, "storage-full", "Insufficient Storage", "The file storage is full; delete files to make room");
+var LimitReached = class extends Error {};
+const checkedFiles = (value) => {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`maxFiles must be a positive whole number, not ${value}`);
+	return value;
+};
+/**
+* `store` refusing a file with `507` once it would hold more than `maxBytes` or `maxFiles`. Only files count, not the
+* store's own `.cleanup/` entries. What the store holds is counted with `list` on the first upload and again when the
+* count is older than `recountMs`, and in between follows this instance's own writes: several instances, or a delete
+* made elsewhere, can be off by what happened since the last count.
+*/
+const limitedFileStore = (store, limits, now = Date.now) => {
+	if (limits.maxBytes === void 0 && limits.maxFiles === void 0) return store;
+	const maxBytes = limits.maxBytes === void 0 ? Infinity : parseSize(limits.maxBytes);
+	const maxFiles = limits.maxFiles === void 0 ? Infinity : checkedFiles(limits.maxFiles);
+	let counted;
+	const pending = {
+		bytes: 0,
+		files: 0
+	};
+	const usage = async () => {
+		if (counted && now() - counted.at < 3e5) return counted;
+		const files = (await store.list("")).filter((object) => isFilePath(object.path));
+		counted = {
+			bytes: files.reduce((sum, object) => sum + object.size, 0),
+			files: files.length,
+			at: now()
+		};
+		return counted;
+	};
+	const put = async (path, body) => {
+		if (!isFilePath(path)) return store.put(path, body);
+		const stored = await usage();
+		if (stored.files + pending.files + 1 > maxFiles) {
+			await body.cancel();
+			throw limitReached();
+		}
+		let size = 0;
+		const counting = new TransformStream({ transform: (chunk, controller) => {
+			size += chunk.length;
+			pending.bytes += chunk.length;
+			if (stored.bytes + pending.bytes > maxBytes) throw new LimitReached();
+			controller.enqueue(chunk);
+		} });
+		pending.files += 1;
+		try {
+			const written = await store.put(path, body.pipeThrough(counting));
+			if (counted) {
+				counted.bytes += written.size;
+				counted.files += 1;
+			}
+			return written;
+		} catch (error) {
+			if (error instanceof LimitReached) throw limitReached();
+			throw error;
+		} finally {
+			pending.files -= 1;
+			pending.bytes -= size;
+		}
+	};
+	const remove = async (path) => {
+		await store.delete(path);
+		if (isFilePath(path)) counted = void 0;
+	};
+	return {
+		...store,
+		put,
+		delete: remove
+	};
+};
+//#endregion
+export { limitedFileStore, recountMs };

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

@@ -1,6 +1,7 @@
 import { FileProvider, FileStore } from "./store.js";
+import { FileLimits } from "./limits.js";
 //#region src/files/local-files.d.ts
-export type LocalFilesOptions = {
+export type LocalFilesOptions = FileLimits & {
   /** 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. */
@@ -13,5 +14,5 @@ export type LocalFilesOptions = {
 /** 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;
+export declare const localFiles: ({ dir, public: isPublic, publicUrl, retention, maxBytes, maxFiles }: LocalFilesOptions) => FileProvider;
 //#endregion

package/dist/files/local-files.js

@@ -1,5 +1,6 @@
 import { HttpProblem } from "../problem.js";
 import { parseDuration } from "./duration.js";
+import { limitedFileStore } from "./limits.js";
 //#region src/files/local-files.ts
 const node = async () => ({
 	fs: await import("node:fs/promises"),
@@ -66,7 +67,7 @@ const localFileStore = (dir) => {
 	const list = async (prefix) => {
 		const { fs, path } = await node();
 		const root = path.resolve(dir);
-		const folder = await resolve(prefix.replace(/\/$/, ""));
+		const folder = prefix === "" ? root : await resolve(prefix.replace(/\/$/, ""));
 		let names;
 		try {
 			names = await fs.readdir(folder, { recursive: true });
@@ -91,8 +92,11 @@ const localFileStore = (dir) => {
 	};
 };
 /** A provider on local disk: `localFiles({ dir: './data/files/private' })`. */
-const localFiles = ({ dir, public: isPublic = false, publicUrl, retention }) => ({
-	store: localFileStore(dir),
+const localFiles = ({ dir, public: isPublic = false, publicUrl, retention, maxBytes, maxFiles }) => ({
+	store: limitedFileStore(localFileStore(dir), {
+		maxBytes,
+		maxFiles
+	}),
 	public: isPublic || publicUrl !== void 0,
 	...publicUrl !== void 0 && { publicUrl: publicUrl.replace(/\/$/, "") },
 	...retention !== void 0 && { retention: parseDuration(retention, "retention") }

package/dist/files/media-types.js

@@ -84,6 +84,11 @@ const servedType = (path) => typeOfExtension(path) ?? "application/octet-stream"
 const canonicalExtension = (type) => byType.get(type);
 const isKnownType = (type) => byType.has(type);
 const isInline = (type) => inlineTypes.has(type) || type.startsWith("audio/") || type.startsWith("video/");
+/** `inline` for types shown in the browser, else `attachment`, named `name` in ASCII and in UTF-8. */
+const contentDisposition = (name, type) => {
+	const ascii = name.replace(/[^\x20-\x7e]|["\\]/g, "_");
+	return `${isInline(type) ? "inline" : "attachment"}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+};
 /** 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`. */
@@ -96,4 +101,4 @@ const downloadName = (name, type) => {
 	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 };
+export { accepts, canonicalExtension, contentDisposition, downloadName, extensionOf, isInline, isKnownType, octetStream, servedType, textTypes, typeOfExtension };

package/dist/files/providers.js

@@ -1,5 +1,6 @@
 import { parseDuration } from "./duration.js";
 import { localFiles } from "./local-files.js";
+import { s3Files } from "./s3-files.js";
 import { checkedProvider } from "@protobase/schema";
 //#region src/files/providers.ts
 const prefix = "PROTOBASE_FILES_";
@@ -10,14 +11,54 @@ const settingVariables = [
 	"CLEANUP_MINUTES"
 ];
 const reservedNames = new Set(settingVariables.map((name) => name.toLowerCase().replaceAll("_", "-")));
+const credentialSuffixes = ["_ACCESS_KEY_ID", "_SECRET_ACCESS_KEY"];
 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`);
+	const suffix = credentialSuffixes.find((ending) => name.endsWith(ending.toLowerCase().replaceAll("_", "-")));
+	if (suffix) throw new Error(`"${name}" cannot name a file provider: variables ending in ${suffix} hold credentials`);
 	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) => {
+const credentialsOf = (variable, env) => {
+	for (const owner of [
+		`${variable}_`,
+		"S3_",
+		"AWS_"
+	]) {
+		const accessKeyId = env[`${owner}ACCESS_KEY_ID`];
+		const secretAccessKey = env[`${owner}SECRET_ACCESS_KEY`];
+		if (!accessKeyId && !secretAccessKey) continue;
+		if (!accessKeyId || !secretAccessKey) throw new Error(`Set both ${owner}ACCESS_KEY_ID and ${owner}SECRET_ACCESS_KEY, or neither`);
+		return {
+			accessKeyId,
+			secretAccessKey
+		};
+	}
+	throw new Error(`${variable} needs credentials: set ${variable}_ACCESS_KEY_ID and ${variable}_SECRET_ACCESS_KEY`);
+};
+const sharedOptions = (url, variable) => {
+	const flag = url.searchParams.get("public");
+	const publicUrl = url.searchParams.get("public_url") ?? void 0;
+	const retention = url.searchParams.get("retention") ?? void 0;
+	const maxBytes = url.searchParams.get("max_bytes") ?? void 0;
+	const maxFiles = url.searchParams.get("max_files") ?? void 0;
+	if (maxFiles !== void 0 && !/^\d+$/.test(maxFiles)) throw new Error(`${variable} has max_files=${maxFiles}; write a whole number of files`);
+	return {
+		public: flag === "1" || flag === "true",
+		...publicUrl && { publicUrl },
+		...retention && { retention },
+		...maxBytes && { maxBytes },
+		...maxFiles && { maxFiles: Number(maxFiles) }
+	};
+};
+/**
+* A provider from a URL: `file:///data/files/private` (a relative `file:data/files` works too) or
+* `s3://<bucket>/<prefix>?endpoint=…&region=…`, both taking `public=1`, `public_url=…`, `retention=14d`,
+* `max_bytes=1GB` and `max_files=20000`. An s3: provider's credentials come from `<variable>_ACCESS_KEY_ID` and
+* `<variable>_SECRET_ACCESS_KEY`, else `S3_…`, else `AWS_…`.
+*/
+const providerFromUrl = (text, variable, env = {}) => {
 	let url;
 	try {
 		url = new URL(text);
@@ -25,15 +66,22 @@ const providerFromUrl = (text, variable) => {
 		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({
+	if (url.protocol === "file:") return localFiles({
 		dir: decodeURIComponent(url.pathname),
-		public: flag === "1" || flag === "true",
-		...publicUrl && { publicUrl },
-		...retention && { retention }
+		...sharedOptions(url, variable)
+	});
+	if (url.protocol !== "s3:") throw new Error(`${variable} uses ${url.protocol}; not implemented: only file: (local disk) and s3: (S3-compatible buckets) providers are supported`);
+	if (url.username || url.password) throw new Error(`${variable} must not hold credentials; set ${variable}_ACCESS_KEY_ID and ${variable}_SECRET_ACCESS_KEY instead`);
+	if (!url.hostname) throw new Error(`${variable} names no bucket; write it like s3://bucket/prefix?endpoint=https://…`);
+	const endpoint = url.searchParams.get("endpoint") ?? void 0;
+	const region = url.searchParams.get("region") ?? void 0;
+	return s3Files({
+		bucket: url.hostname,
+		prefix: decodeURIComponent(url.pathname),
+		...endpoint && { endpoint },
+		...region && { region },
+		...credentialsOf(variable, env),
+		...sharedOptions(url, variable)
 	});
 };
 /**
@@ -47,8 +95,9 @@ const resolveProviders = (options, env, used) => {
 		if (!variable.startsWith(prefix) || !value) continue;
 		const suffix = variable.slice(16);
 		if (settingVariables.includes(suffix)) continue;
+		if (credentialSuffixes.some((ending) => suffix.endsWith(ending))) continue;
 		const name = checkedName(suffix.toLowerCase().replaceAll("_", "-"));
-		providers[name] = providerFromUrl(value, variable);
+		providers[name] = providerFromUrl(value, variable, env);
 	}
 	for (const name of used) {
 		if (providers[name]) continue;

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

@@ -0,0 +1,67 @@
+import { FileProvider, FileStore } from "./store.js";
+import { FileLimits } from "./limits.js";
+//#region src/files/s3-files.d.ts
+/** The part of Bun's `S3Client` the store uses, so tests can pass their own. */
+export type S3Bucket = {
+  file(key: string): S3Object;
+  list(input: {
+    prefix: string;
+    continuationToken?: string;
+  }): Promise<S3ListPage>;
+};
+export type S3Object = {
+  /** Bytes written. A streamed body goes up in parts, and an upload that fails leaves no object. */
+  write(body: Response, options: {
+    type: string;
+    contentDisposition: string;
+  }): Promise<number>;
+  stat(): Promise<{
+    size: number;
+    lastModified: Date;
+  }>;
+  /** The bytes from `start` up to, not including, `end`. */
+  slice(start: number, end: number): {
+    stream(): ReadableStream<Uint8Array>;
+  };
+  stream(): ReadableStream<Uint8Array>;
+  delete(): Promise<void>;
+  /** A GET link, served with the given Content-Type and Content-Disposition. */
+  presign(options: {
+    expiresIn: number;
+    type: string;
+    contentDisposition: string;
+  }): string;
+};
+export type S3ListPage = {
+  contents?: Array<{
+    key: string;
+    size?: number;
+    lastModified?: string;
+  }>;
+  isTruncated?: boolean;
+  nextContinuationToken?: string;
+};
+export type S3FilesOptions = FileLimits & {
+  bucket: string;
+  /** The folder in the bucket that holds this provider's files, such as `acme/private`; default the bucket's root. */
+  prefix?: string;
+  /** The S3 API's address, such as `https://<account>.eu.r2.cloudflarestorage.com`; default AWS. */
+  endpoint?: string;
+  /** `auto` for R2, `fr-par` for Scaleway in Paris. */
+  region?: string;
+  /** Default `S3_ACCESS_KEY_ID`, then `AWS_ACCESS_KEY_ID`, from the environment. */
+  accessKeyId?: string;
+  /** Default `S3_SECRET_ACCESS_KEY`, then `AWS_SECRET_ACCESS_KEY`, from the environment. */
+  secretAccessKey?: string;
+  /** Files anyone with the link may open. */
+  public?: boolean;
+  /** The bucket's public address, such as an R2 custom domain; public files are linked from there, under `prefix`. */
+  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 bucket, under `prefix`. Downloads get presigned links, so their bytes never pass through the app. */
+export declare const s3FileStore: (bucket: S3Bucket, prefix?: string) => FileStore;
+/** A provider in an S3-compatible bucket, such as Cloudflare R2 or Scaleway: `s3Files({ bucket: 'acme-files', ... })`. */
+export declare const s3Files: (options: S3FilesOptions) => FileProvider;
+//#endregion

package/dist/files/s3-files.js

@@ -0,0 +1,113 @@
+import { contentDisposition, servedType } from "./media-types.js";
+import { parseDuration } from "./duration.js";
+import { limitedFileStore } from "./limits.js";
+//#region src/files/s3-files.ts
+const codeOf = (error) => error instanceof Error ? error.code : void 0;
+/** A store in a bucket, under `prefix`. Downloads get presigned links, so their bytes never pass through the app. */
+const s3FileStore = (bucket, prefix = "") => {
+	const trimmed = prefix.replace(/^\/+|\/+$/g, "");
+	const root = trimmed === "" ? "" : `${trimmed}/`;
+	const keyOf = (path) => `${root}${path}`;
+	const head = async (path) => {
+		try {
+			const stat = await bucket.file(keyOf(path)).stat();
+			return {
+				path,
+				size: stat.size,
+				modified: stat.lastModified
+			};
+		} catch (error) {
+			if (codeOf(error) === "NoSuchKey" || codeOf(error) === "NotFound") return void 0;
+			throw error;
+		}
+	};
+	const put = async (path, body) => {
+		const type = servedType(path);
+		const name = path.slice(path.lastIndexOf("/") + 1);
+		return { size: await bucket.file(keyOf(path)).write(new Response(body), {
+			type,
+			contentDisposition: contentDisposition(name, type)
+		}) };
+	};
+	const read = async (path, range) => {
+		if (!await head(path)) return void 0;
+		const file = bucket.file(keyOf(path));
+		return range ? file.slice(range.start, range.end + 1).stream() : file.stream();
+	};
+	const remove = (path) => bucket.file(keyOf(path)).delete();
+	const list = async (folder) => {
+		const found = [];
+		let continuationToken;
+		do {
+			const page = await bucket.list({
+				prefix: keyOf(folder),
+				...continuationToken !== void 0 && { continuationToken }
+			});
+			for (const item of page.contents ?? []) {
+				if (item.key.endsWith("/")) continue;
+				found.push({
+					path: item.key.slice(root.length),
+					size: item.size ?? 0,
+					modified: new Date(item.lastModified ?? 0)
+				});
+			}
+			if (page.isTruncated && !page.nextContinuationToken) throw new Error(`Listing "${keyOf(folder)}" stopped without a continuation token`);
+			continuationToken = page.isTruncated ? page.nextContinuationToken : void 0;
+		} while (continuationToken !== void 0);
+		return found.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	};
+	const downloadUrl = async (path, options) => {
+		const expiresIn = Math.max(options.expires - Math.floor(Date.now() / 1e3), 1);
+		return bucket.file(keyOf(path)).presign({
+			expiresIn,
+			type: options.type,
+			contentDisposition: options.disposition
+		});
+	};
+	return {
+		put,
+		head,
+		read,
+		delete: remove,
+		list,
+		downloadUrl
+	};
+};
+const bunBucket = (options) => {
+	let client;
+	const connect = () => {
+		if (client) return client;
+		const bun = globalThis.Bun;
+		if (!bun) throw new Error("Not implemented: S3 file providers need Bun; serve the app with protobase-serve.js or the protobase image");
+		client = new bun.S3Client(options);
+		return client;
+	};
+	return {
+		file: (key) => connect().file(key),
+		list: (input) => connect().list(input)
+	};
+};
+/** A provider in an S3-compatible bucket, such as Cloudflare R2 or Scaleway: `s3Files({ bucket: 'acme-files', ... })`. */
+const s3Files = (options) => {
+	const { bucket, prefix = "", endpoint, region, accessKeyId, secretAccessKey, public: isPublic = false, publicUrl, retention, maxBytes, maxFiles } = options;
+	if (!bucket) throw new Error("s3Files needs a bucket");
+	const client = bunBucket({
+		bucket,
+		...endpoint !== void 0 && { endpoint },
+		...region !== void 0 && { region },
+		...accessKeyId !== void 0 && { accessKeyId },
+		...secretAccessKey !== void 0 && { secretAccessKey }
+	});
+	const folder = prefix.replace(/^\/+|\/+$/g, "");
+	return {
+		store: limitedFileStore(s3FileStore(client, folder), {
+			maxBytes,
+			maxFiles
+		}),
+		public: isPublic || publicUrl !== void 0,
+		...publicUrl !== void 0 && { publicUrl: `${publicUrl.replace(/\/$/, "")}${folder === "" ? "" : `/${folder}`}` },
+		...retention !== void 0 && { retention: parseDuration(retention, "retention") }
+	};
+};
+//#endregion
+export { s3FileStore, s3Files };

package/dist/files/store.d.ts

@@ -6,7 +6,7 @@ export type StoredObject = {
   modified: Date;
 };
 /**
- * Where a provider keeps bytes: local disk now, an S3-compatible bucket later. Paths are relative and use `/`. Every
+ * Where a provider keeps bytes: a folder on local disk or an S3-compatible bucket. 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 = {
@@ -21,8 +21,17 @@ export type FileStore = {
     end: number;
   }): Promise<ReadableStream<Uint8Array> | undefined>;
   delete(path: string): Promise<void>;
-  /** Every object under `prefix` (a folder such as `.cleanup/`), sorted by path. */
+  /** Every object under `prefix` (a folder such as `.cleanup/`, or `''` for all), sorted by path. */
   list(prefix: string): Promise<StoredObject[]>;
+  /**
+   * A link that serves the bytes straight from storage until `expires` (seconds since the epoch), as `type` with the
+   * given Content-Disposition. Downloads redirect to it after their checks; without it the app serves the bytes itself.
+   */
+  downloadUrl?(path: string, options: {
+    expires: number;
+    type: string;
+    disposition: string;
+  }): Promise<string>;
 };
 /** A configured provider: its store, whether its files are public, and how long bytes outlive their last reference. */
 export type FileProvider = {

package/dist/index.d.ts

@@ -66,7 +66,9 @@ import { startErrorReporting } from "./error-reporting/error-reporter.js";
 import { FunctionEnv, PublicFunctionEnv, functionApp } from "./functions/function-app.js";
 import { SignatureOptions, StandardWebhookOptions, verifySignature, verifyStandardWebhook } from "./functions/verify-signature.js";
 import { requireEnv } from "./functions/require-env.js";
+import { FileLimits, limitedFileStore } from "./files/limits.js";
 import { LocalFilesOptions, localFileStore, localFiles } from "./files/local-files.js";
+import { S3Bucket, S3FilesOptions, S3ListPage, S3Object, s3FileStore, s3Files } from "./files/s3-files.js";
 import { FileCleanupInput, createFileCleanup } from "./files/file-cleanup.js";
 import { FileObject } from "./files/present.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
@@ -75,4 +77,4 @@ import { FatalJobError } from "./jobs/run-job.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileObject, type FileProvider, type FileStore, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileStore, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/index.js

@@ -31,7 +31,9 @@ import { newWebhookSecret } from "./webhooks/standard-webhooks.js";
 import { subscription } from "./webhooks/subscription.js";
 import { errorReportingSettings, errorReportingVariable } from "./error-reporting/error-reporting-settings.js";
 import { storageCleanupSchedule } from "./files/cleanup-schedule.js";
+import { limitedFileStore } from "./files/limits.js";
 import { localFileStore, localFiles } from "./files/local-files.js";
+import { s3FileStore, s3Files } from "./files/s3-files.js";
 import { pluginOptions, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { checkSourceNames, sourceOptions, sourcesFor, sourcesVariable } from "./sources/source-settings.js";
@@ -56,4 +58,4 @@ import { createFileCleanup } from "./files/file-cleanup.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.12.16",
+  "version": "0.12.18",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.12.16",
-    "@protobase/query": "0.12.16",
-    "@protobase/schema": "0.12.16",
+    "@protobase/layout": "0.12.18",
+    "@protobase/query": "0.12.18",
+    "@protobase/schema": "0.12.18",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
     "@simplewebauthn/server": "^13.3.1",