@protobase/server 0.6.0 → 0.8.0

package/dist/better-auth/staff-checks.js

@@ -51,7 +51,11 @@ const accountChanges = [
 	"/passkey/generate-register-options",
 	"/passkey/verify-registration",
 	"/passkey/update-passkey",
-	"/passkey/delete-passkey"
+	"/passkey/delete-passkey",
+	"/invitation/accept",
+	"/organization/leave",
+	"/organization/transfer-ownership",
+	"/organization/delete"
 ];
 const staffCannotChange = {
 	code: "STAFF_CANNOT_CHANGE_SIGN_IN",

package/dist/better-auth/staff-log.js

@@ -1,52 +1,63 @@
 //#region src/better-auth/staff-log.ts
 /** Better Auth's model for the log of staff sign-ins: one row per session staff started as someone. */
 const staffSignInModel = "staffSignIn";
-const staffSignInSchema = { [staffSignInModel]: { fields: {
-	userId: {
-		type: "string",
-		required: true
-	},
-	userEmail: {
-		type: "string",
-		required: true
-	},
-	staff: {
-		type: "string",
-		required: true
-	},
-	staffName: {
-		type: "string",
-		required: false
-	},
-	staffSubject: {
-		type: "string",
-		required: true
-	},
-	issuer: {
-		type: "string",
-		required: true
-	},
-	reason: {
-		type: "string",
-		required: true
-	},
-	sessionId: {
-		type: "string",
-		required: true
-	},
-	startedAt: {
-		type: "date",
-		required: true
-	},
-	expiresAt: {
-		type: "date",
-		required: true
-	},
-	endedAt: {
-		type: "date",
-		required: false
+const staffSignInSchema = { [staffSignInModel]: {
+	modelName: "staff_sign_in",
+	fields: {
+		userId: {
+			type: "string",
+			required: true,
+			fieldName: "user_id"
+		},
+		userEmail: {
+			type: "string",
+			required: true,
+			fieldName: "user_email"
+		},
+		staff: {
+			type: "string",
+			required: true
+		},
+		staffName: {
+			type: "string",
+			required: false,
+			fieldName: "staff_name"
+		},
+		staffSubject: {
+			type: "string",
+			required: true,
+			fieldName: "staff_subject"
+		},
+		issuer: {
+			type: "string",
+			required: true
+		},
+		reason: {
+			type: "string",
+			required: true
+		},
+		sessionId: {
+			type: "string",
+			required: true,
+			fieldName: "session_id"
+		},
+		startedAt: {
+			type: "date",
+			required: true,
+			fieldName: "started_at"
+		},
+		expiresAt: {
+			type: "date",
+			required: true,
+			fieldName: "expires_at"
+		},
+		endedAt: {
+			type: "date",
+			required: false,
+			fieldName: "ended_at"
+		}
 	}
-} } };
+} };
 const entry = (row) => ({
 	id: row.id,
 	user: row.userEmail,

package/dist/better-auth/staff-sign-in-endpoints.js

@@ -6,8 +6,8 @@ import { policyRefusal, staffSignInPath } from "./sign-in-enforcement.js";
 import { staffSignInEmail } from "./sign-in-mail.js";
 import { logStaffSignIn } from "./staff-log.js";
 import { APIError, createAuthEndpoint } from "better-auth/api";
-import * as z$1 from "zod";
 import { expireCookie, setSessionCookie } from "better-auth/cookies";
+import * as z$1 from "zod";
 //#region src/better-auth/staff-sign-in-endpoints.ts
 const startLifetimeMs = 6e5;
 const stateCookie = "staff_state";

package/dist/better-auth/status-route.js

@@ -1,3 +1,4 @@
+import { membershipRoles } from "./organizations/role-definitions.js";
 import { effectiveSignInPolicy } from "./sign-in-policy.js";
 import { readSignInPolicy } from "./policy-store.js";
 import { hasUsers } from "./users.js";
@@ -8,8 +9,9 @@ import { Hono } from "hono";
 * `signInMethods`, the ways to sign in the sign-in policy leaves on (`password`, `emailCode`, `passkey`), so it offers
 * only those; `passwordReset` when reset mail can be sent and passwords are on, so it offers "Forgot password?" only
 * then; the ids of the `socialProviders` people can sign in with, so it offers "Continue with GitHub" when `github` is
-* one; `platformSignIn`, the id and name of the platform's provider when it is one of them; and `staffSignIn`, the
-* operator provider's name, when staff can sign in as people.
+* one; `platformSignIn`, the id and name of the platform's provider when it is one of them; `staffSignIn`, the
+* operator provider's name, when staff can sign in as people; and with organizations, who may create them and the roles
+* with their labels, `membership` for those a member can hold, and the roles each one's holders may also give.
 */
 const statusRoute = (auth) => {
 	const app = new Hono();
@@ -31,7 +33,16 @@ const statusRoute = (auth) => {
 			passwordReset: auth.passwordReset && policy.password === "allowed",
 			socialProviders,
 			...platformSignIn && { platformSignIn },
-			...staffSignIn && { staffSignIn }
+			...staffSignIn && { staffSignIn },
+			...auth.organizations && { organizations: {
+				create: auth.organizations.create,
+				roles: auth.roleDefinitions.names.map((name) => ({
+					name,
+					label: auth.roleDefinitions.labels[name] ?? name,
+					membership: membershipRoles(auth.roleDefinitions).includes(name),
+					grants: auth.roleDefinitions.grants[name] ?? []
+				}))
+			} }
 		});
 	});
 	return app;

package/dist/better-auth/users.d.ts

@@ -28,7 +28,8 @@ export declare const hasUsers: (auth: AdminAuth) => Promise<boolean>;
  * Creates a user directly in the admin store. Host side only (no HTTP route creates accounts while the store is empty):
  * the first user is always an `admin`, later ones get `role` (default `user`). The address counts as verified, so the
  * user can also sign in with an emailed code. `accounts` link the user to sign-in providers up front, so a provider
- * signs them in by its own id whatever address it reports; one that signs in another user already is refused.
+ * signs them in by its own id whatever address it reports; one that signs in another user already is refused. With
+ * organizations, the first user also owns every organization without members, such as those an app's seed made.
  */
 export declare const createUser: (auth: AdminAuth, input: NewUser) => Promise<{
   id: string;

package/dist/better-auth/users.js

@@ -1,4 +1,5 @@
 import { parseRoles } from "./parse-roles.js";
+import { ownOrganizationsWithoutMembers } from "./organizations/host.js";
 //#region src/better-auth/users.ts
 /** The roles this auth instance allows, `admin` first. */
 const roleChoices = (auth) => [...auth.roles];
@@ -21,7 +22,8 @@ const checkAccounts = async (auth, accounts) => {
 * Creates a user directly in the admin store. Host side only (no HTTP route creates accounts while the store is empty):
 * the first user is always an `admin`, later ones get `role` (default `user`). The address counts as verified, so the
 * user can also sign in with an emailed code. `accounts` link the user to sign-in providers up front, so a provider
-* signs them in by its own id whatever address it reports; one that signs in another user already is refused.
+* signs them in by its own id whatever address it reports; one that signs in another user already is refused. With
+* organizations, the first user also owns every organization without members, such as those an app's seed made.
 */
 const createUser = async (auth, input) => {
 	const first = !await hasUsers(auth);
@@ -41,6 +43,7 @@ const createUser = async (auth, input) => {
 		userId: user.id,
 		...account
 	});
+	if (first && auth.organizations) await ownOrganizationsWithoutMembers(auth, user.id);
 	return {
 		id: user.id,
 		email: user.email,

package/dist/create-admin.d.ts

@@ -1,6 +1,8 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
-import { ResourceSource } from "./resource-source.js";
+import { FilesOptions } from "./files/options.js";
 import { AdminEnv, Authenticator, PageSource, ViewSource } from "./types.js";
+import { ResourceSource } from "./resource-source.js";
+import { FunctionSource } from "./functions/define-function.js";
 import { AdminOptions } from "./admin-options.js";
 import { Hono } from "hono";
 import { UserMenuSource } from "@protobase/schema";
@@ -17,8 +19,12 @@ export type CreateAdminInput = {
   authenticate: Authenticator;
   /** A Better Auth instance (see `createAuth`): its handler is mounted at `/api/auth`. */
   auth?: AdminAuth;
+  /** API functions of the app's own, each served at `<systemPath>/functions/<name>` (see `defineFunction`). */
+  functions?: Record<string, FunctionSource>;
+  /** Where file fields keep their bytes (see `FilesOptions`). */
+  files?: FilesOptions;
   options?: AdminOptions;
 };
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-export declare const createAdmin: ({ resources, views, pages, userMenu, db, authenticate, auth, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
+export declare const createAdmin: ({ resources, views, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
 //#endregion

package/dist/create-admin.js

@@ -4,9 +4,15 @@ import { assistantRecords } from "./assistant/records.js";
 import { builtInAssistant } from "./assistant/built-in-assistant.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { authBasePath } from "./better-auth/create-auth.js";
+import { organizationRoutes } from "./better-auth/organizations/admin-routes.js";
 import { statusRoute } from "./better-auth/status-route.js";
 import { checkShell } from "./check-shell.js";
 import { checkViews } from "./check-views.js";
+import { createFilesRuntime } from "./files/runtime.js";
+import { fileRoutes } from "./files/routes.js";
+import { toApiFunction } from "./functions/define-function.js";
+import { callerRecords } from "./functions/records.js";
+import { functionRoutes } from "./functions/routes.js";
 import { runtimeUrl } from "./runtime/runtime-settings.js";
 import { createMeta } from "./meta.js";
 import { buildRegistry } from "./registry.js";
@@ -20,9 +26,10 @@ import { Hono } from "hono";
 import { checkPages } from "@protobase/layout";
 //#region src/create-admin.ts
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenticate, auth, options = {} }) => {
+const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, options = {} }) => {
 	const basePath = options.basePath ?? "/api/v1";
 	const registry = buildRegistry(resources);
+	const apiFunctions = Object.fromEntries(Object.entries(functions).map(([name, source]) => [name, toApiFunction(name, source)]));
 	const viewModels = views.map((view) => view.toModel());
 	const userMenuModel = userMenu?.toUserMenuModel();
 	const pageModels = pages.map((entry) => entry.toModel());
@@ -35,6 +42,12 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 	const systemPath = basePath.slice(0, basePath.lastIndexOf("/"));
 	const assistant = assistantSettings(options.assistant, globalThis.process?.env ?? {});
 	const runtime = runtimeUrl(options.runtime, globalThis.process?.env ?? {});
+	const files = createFilesRuntime({
+		...filesOptions && { options: filesOptions },
+		env: globalThis.process?.env ?? {},
+		models: registry.entries.map((entry) => entry.model),
+		systemPath
+	});
 	const deps = {
 		db,
 		registry,
@@ -53,7 +66,8 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		},
 		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false,
 		...assistant && { assistant: assistant.kind === "external" ? assistant.url : `${systemPath}/assistant` },
-		...runtime && { runtime }
+		...runtime && { runtime },
+		...files && { files }
 	};
 	const meta = createMeta(deps);
 	const onError = createErrorHandler(options.onUnhandledError);
@@ -83,6 +97,12 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 	app.onError(onError);
 	if (auth) {
 		app.route(authBasePath, statusRoute(auth));
+		if (auth.organizations) app.route(authBasePath, organizationRoutes({
+			auth,
+			audit: deps.audit,
+			registry,
+			db
+		}));
 		app.on(["GET", "POST"], `${authBasePath}/*`, (c) => auth.handler(c.req.raw));
 	}
 	if (assistant?.kind === "built-in") {
@@ -99,7 +119,16 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 			report: options.onUnhandledError
 		}));
 	}
+	app.route("/", functionRoutes({
+		basePath: `${systemPath}/functions`,
+		functions: apiFunctions,
+		authenticate,
+		db,
+		records: (session) => callerRecords(deps, session),
+		onError
+	}));
 	app.route("/", batchRoute(deps, authenticate, meta));
+	app.route("/", fileRoutes(deps, authenticate));
 	app.route(basePath, api);
 	app.route(deps.systemPath || "/", system);
 	return app;

package/dist/deps.d.ts

@@ -1,4 +1,5 @@
 import "./types.js";
+import "./files/runtime.js";
 import "./registry.js";
 import "./scan-guard.js";
 import { PageModel } from "@protobase/layout";

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