@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/files/r2-rules.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure R2 helpers: multipart part sizing and minimal XML reading. No imports, so
+ * `node --test` can load this file.
+ */
+
+/**
+ * Every part goes through the site (files/upload-part; EmDash's admin CSP blocks the
+ * browser from reaching R2), so parts must fit a plugin route body (8 MiB). 6 MiB is
+ * above R2's 5 MiB minimum and leaves headroom.
+ */
+export const PART_SIZE = 6 * 1024 * 1024;
+const MAX_PARTS = 10_000;
+/** The largest file that fits in 10,000 parts of PART_SIZE (just under 60 GB). */
+export const MAX_THROUGH_SITE = PART_SIZE * MAX_PARTS;
+
+/** Equal-sized parts (R2 requires every part but the last to be the same size). */
+export function partSizeFor(_size: number): number {
+	return PART_SIZE;
+}
+
+export function xmlValue(xml: string, tag: string): string | undefined {
+	const match = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(xml);
+	return match ? decodeXml(match[1]) : undefined;
+}
+
+export function xmlValues(xml: string, tag: string): string[] {
+	return [...xml.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g"))].map((m) => decodeXml(m[1]));
+}
+
+function decodeXml(value: string): string {
+	return value
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&apos;/g, "'")
+		.replace(/&amp;/g, "&");
+}
+
+export function encodeXml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/src/files/range.ts

@@ -0,0 +1,50 @@
+/**
+ * HTTP byte ranges for downloads (RFC 9110 §14). Only single ranges are
+ * served; multiple ranges, malformed headers and a mismatched If-Range fall
+ * back to the full file (200). No imports, so `node --test` can load this file.
+ */
+
+export type ByteRange = { offset: number; end?: number } | { suffix: number };
+
+/** Parse a Range header. Null means "ignore it and send the whole file". */
+export function parseRange(header: string | null | undefined): ByteRange | null {
+	if (!header) return null;
+	const match = /^\s*bytes\s*=\s*(\d*)\s*-\s*(\d*)\s*$/i.exec(header);
+	if (!match) return null; // Malformed, another unit, or several ranges.
+	const [, first, last] = match;
+	if (first === "" && last === "") return null;
+	if (first === "") {
+		const suffix = Number(last);
+		return suffix > 0 ? { suffix } : null;
+	}
+	const offset = Number(first);
+	if (last === "") return { offset };
+	const end = Number(last);
+	return end >= offset ? { offset, end } : null;
+}
+
+/** The bytes a range covers in a file of `size`, clamped; null when unsatisfiable. */
+export function resolveRange(range: ByteRange, size: number): { offset: number; length: number } | null {
+	if ("suffix" in range) {
+		if (size === 0) return null;
+		const length = Math.min(range.suffix, size);
+		return { offset: size - length, length };
+	}
+	if (range.offset >= size) return null;
+	const end = Math.min(range.end ?? size - 1, size - 1);
+	return { offset: range.offset, length: end - range.offset + 1 };
+}
+
+/**
+ * Whether an If-Range validator still matches the file. A strong ETag must
+ * match exactly; a date must equal Last-Modified (to the second). Weak ETags
+ * never match.
+ */
+export function ifRangeMatches(ifRange: string | null | undefined, etag: string, lastModified: Date): boolean {
+	if (!ifRange) return true;
+	const value = ifRange.trim();
+	if (value.startsWith("W/")) return false;
+	if (value.startsWith('"')) return value === etag;
+	const date = Date.parse(value);
+	return !Number.isNaN(date) && Math.floor(date / 1000) === Math.floor(lastModified.getTime() / 1000);
+}

package/src/files/s3.ts

@@ -0,0 +1,114 @@
+/**
+ * The few R2 S3-API calls large uploads need: start, upload a part of, complete and
+ * abort a multipart upload, and delete an object. Requests are signed with ./sigv4.ts.
+ */
+import { encodeXml, xmlValue } from "./r2-rules.js";
+import { EMPTY_SHA256, type SigV4Credentials, UNSIGNED_PAYLOAD, sha256Hex, signRequest } from "./sigv4.js";
+
+export { MAX_THROUGH_SITE, PART_SIZE, partSizeFor } from "./r2-rules.js";
+
+export interface R2Config extends SigV4Credentials {
+	accountId: string;
+	bucket: string;
+}
+
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+export function r2Host(accountId: string): string {
+	return `${accountId}.r2.cloudflarestorage.com`;
+}
+
+export class S3Error extends Error {
+	readonly status: number;
+	readonly code?: string;
+	constructor(message: string, status: number, code?: string) {
+		super(message);
+		this.status = status;
+		this.code = code;
+	}
+}
+
+export function r2Client(config: R2Config, fetchImpl: Fetch) {
+	const host = r2Host(config.accountId);
+	const objectPath = (key: string) => `/${config.bucket}/${key}`;
+
+	async function call(
+		method: string,
+		path: string,
+		options: { query?: Record<string, string>; headers?: Record<string, string>; body?: string | Uint8Array } = {},
+	): Promise<{ status: number; text: string; headers: Headers }> {
+		// A part's bytes go unsigned (TLS protects them; hashing megabytes per request costs CPU).
+		const payloadHash = options.body instanceof Uint8Array ? UNSIGNED_PAYLOAD : options.body ? await sha256Hex(options.body) : EMPTY_SHA256;
+		const signed = await signRequest(
+			{ method, host, path, query: options.query, headers: options.headers, region: "auto" },
+			config,
+			payloadHash,
+		);
+		const response = await fetchImpl(signed.url, { method, headers: signed.headers, body: options.body instanceof Uint8Array ? new Uint8Array(options.body) : options.body });
+		const text = await response.text();
+		if (!response.ok) {
+			const code = xmlValue(text, "Code");
+			const message = xmlValue(text, "Message") ?? `R2 answered ${response.status}`;
+			throw new S3Error(code ? `${code}: ${message}` : message, response.status, code);
+		}
+		return { status: response.status, text, headers: response.headers };
+	}
+
+	return {
+		async createMultipart(key: string, contentType: string): Promise<string> {
+			const { text } = await call("POST", objectPath(key), {
+				query: { uploads: "" },
+				headers: { "content-type": contentType || "application/octet-stream" },
+			});
+			const uploadId = xmlValue(text, "UploadId");
+			if (!uploadId) throw new S3Error("R2 didn't return an upload ID.", 502);
+			return uploadId;
+		},
+
+		/** Uploads one part; returns its ETag (for completeMultipart). */
+		async uploadPart(key: string, uploadId: string, partNumber: number, bytes: Uint8Array): Promise<string> {
+			const { headers } = await call("PUT", objectPath(key), { query: { partNumber: String(partNumber), uploadId }, body: bytes });
+			const etag = headers.get("etag");
+			if (!etag) throw new S3Error("R2 didn't return an ETag for the part.", 502);
+			return etag;
+		},
+
+		async completeMultipart(key: string, uploadId: string, parts: Array<{ partNumber: number; etag: string }>): Promise<string | undefined> {
+			const sorted = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+			const body = `<CompleteMultipartUpload>${sorted
+				.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${encodeXml(p.etag)}</ETag></Part>`)
+				.join("")}</CompleteMultipartUpload>`;
+			const { text } = await call("POST", objectPath(key), {
+				query: { uploadId },
+				headers: { "content-type": "application/xml" },
+				body,
+			});
+			// S3 can answer 200 with an <Error> body.
+			if (text.includes("<Error>")) throw new S3Error(xmlValue(text, "Message") ?? "Completing the upload failed.", 500, xmlValue(text, "Code"));
+			return xmlValue(text, "ETag");
+		},
+
+		async abortMultipart(key: string, uploadId: string): Promise<void> {
+			try {
+				await call("DELETE", objectPath(key), { query: { uploadId } });
+			} catch (error) {
+				if (!(error instanceof S3Error && error.status === 404)) throw error;
+			}
+		},
+
+		async headObject(key: string): Promise<{ size: number; etag: string | null } | null> {
+			try {
+				const { headers } = await call("HEAD", objectPath(key));
+				return { size: Number(headers.get("content-length") ?? 0), etag: headers.get("etag") };
+			} catch (error) {
+				if (error instanceof S3Error && error.status === 404) return null;
+				throw error;
+			}
+		},
+
+		async deleteObject(key: string): Promise<void> {
+			await call("DELETE", objectPath(key));
+		},
+	};
+}
+

package/src/files/serve.ts

@@ -0,0 +1,141 @@
+/**
+ * Serves stable download URLs, /<base>/<id>/<filename>, through the pack
+ * middleware. The file streams from R2 with Content-Disposition: attachment
+ * (or redirects to a public bucket / CDN URL), with ETag, conditional
+ * requests and byte ranges. Downloads are counted after the response.
+ */
+import { contentDisposition, downloadPath, parseDownloadPath } from "./format.js";
+import { type ByteRange, ifRangeMatches, parseRange, resolveRange } from "./range.js";
+import { type FileRecord, countDownload, readSiteSettings, resolveFile } from "./site.js";
+
+export interface FilesSiteOptions {
+	/** D1 binding of the site database. Default "DB". */
+	database?: string;
+	/** R2 binding of the media bucket. Default "MEDIA". */
+	media?: string;
+	/** R2 binding of the bucket large uploads go to. Default: FILES when bound, else the media bucket. */
+	uploads?: string;
+	/** Count downloads (the files.counts feature). */
+	count?: boolean;
+}
+
+/** The R2 binding large uploads live in. */
+export function uploadsBindingName(env: Record<string, unknown>, options: { media?: string; uploads?: string }): string {
+	return options.uploads ?? (env.FILES ? "FILES" : (options.media ?? "MEDIA"));
+}
+
+const NOT_FOUND = () =>
+	new Response("File not found", { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" } });
+
+/** Whether a request should count as a download (not HEAD, not a later range chunk, not a 304). */
+function countsAsDownload(request: Request, range: ByteRange | null): boolean {
+	return request.method === "GET" && (!range || ("offset" in range && range.offset === 0));
+}
+
+export async function serveDownload(
+	request: Request,
+	url: URL,
+	env: Record<string, unknown>,
+	waitUntil: (p: Promise<unknown>) => void,
+	options: FilesSiteOptions = {},
+): Promise<Response | undefined> {
+	if (request.method !== "GET" && request.method !== "HEAD") return undefined;
+	if (url.pathname.startsWith("/_")) return undefined;
+	const db = env[options.database ?? "DB"] as D1Database | undefined;
+	if (!db) return undefined;
+
+	const settings = await readSiteSettings(db);
+	const parsed = parseDownloadPath(url.pathname, settings.base);
+	if (!parsed) return undefined;
+
+	const file = await resolveFile(db, parsed.id);
+	if (!file) return NOT_FOUND();
+
+	const canonical = downloadPath(settings.base, file.id, file.name);
+	if (!parsed.filename) return Response.redirect(new URL(canonical, url).href, 301);
+
+	if (settings.publicBaseUrl) {
+		if (options.count && countsAsDownload(request, parseRange(request.headers.get("Range")))) countDownload(db, file.id, waitUntil);
+		const target = `${settings.publicBaseUrl}/${file.key.split("/").map(encodeURIComponent).join("/")}`;
+		return new Response(null, { status: 302, headers: { Location: target, "Cache-Control": "no-store" } });
+	}
+
+	const bucketName = file.source === "upload" ? uploadsBindingName(env, options) : (options.media ?? "MEDIA");
+	const bucket = env[bucketName] as R2Bucket | undefined;
+	if (!bucket) {
+		console.error(`coywolf-pack files: R2 binding ${bucketName} is missing`);
+		return NOT_FOUND();
+	}
+	const count = options.count ? () => countDownload(db, file.id, waitUntil) : () => undefined;
+	return streamObject(request, bucket, file, count);
+}
+
+async function streamObject(request: Request, bucket: R2Bucket, file: FileRecord, count: () => void) {
+	const headers = new Headers({
+		"Content-Type": file.type || "application/octet-stream",
+		"Content-Disposition": contentDisposition(file.name),
+		"Accept-Ranges": "bytes",
+		"Cache-Control": "public, max-age=0, must-revalidate",
+		"X-Content-Type-Options": "nosniff",
+	});
+
+	if (request.method === "HEAD") {
+		const head = await bucket.head(file.key);
+		if (!head) return NOT_FOUND();
+		headers.set("ETag", head.httpEtag);
+		headers.set("Content-Length", String(head.size));
+		headers.set("Last-Modified", head.uploaded.toUTCString());
+		return new Response(null, { status: 200, headers });
+	}
+
+	// One range at most; several ranges or a malformed header get the whole file.
+	let range = parseRange(request.headers.get("Range"));
+	if (range && request.headers.has("If-Range")) {
+		const head = await bucket.head(file.key);
+		if (!head) return NOT_FOUND();
+		if (!ifRangeMatches(request.headers.get("If-Range"), head.httpEtag, head.uploaded)) range = null;
+	}
+
+	let object: R2Object | R2ObjectBody | null;
+	try {
+		object = await bucket.get(file.key, {
+			onlyIf: request.headers,
+			...(range ? { range: "suffix" in range ? { suffix: range.suffix } : { offset: range.offset, ...(range.end !== undefined ? { length: range.end - range.offset + 1 } : {}) } } : {}),
+		});
+	} catch (error) {
+		if (!range) throw error;
+		if ("suffix" in range) {
+			// A suffix longer than the file means the whole file (sent as a 206 of every byte).
+			object = await bucket.get(file.key, { onlyIf: request.headers });
+		} else {
+			// R2 rejects a range that starts past the end.
+			const head = await bucket.head(file.key);
+			return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${head?.size ?? 0}` } });
+		}
+	}
+	if (!object) return NOT_FOUND();
+	headers.set("ETag", object.httpEtag);
+	headers.set("Last-Modified", object.uploaded.toUTCString());
+
+	// A precondition failed (If-None-Match matched, or If-Match didn't): R2 returns the object without a body.
+	if (!("body" in object) || !object.body) {
+		const matched = request.headers.has("If-None-Match") || request.headers.has("If-Modified-Since");
+		return new Response(null, { status: matched ? 304 : 412, headers });
+	}
+
+	if (countsAsDownload(request, range)) count();
+
+	const body = object as R2ObjectBody;
+	if (range) {
+		const bytes = resolveRange(range, body.size);
+		if (!bytes) {
+			await body.body.cancel();
+			return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${body.size}` } });
+		}
+		headers.set("Content-Range", `bytes ${bytes.offset}-${bytes.offset + bytes.length - 1}/${body.size}`);
+		headers.set("Content-Length", String(bytes.length));
+		return new Response(body.body, { status: 206, headers });
+	}
+	headers.set("Content-Length", String(body.size));
+	return new Response(body.body, { status: 200, headers });
+}

package/src/files/sigv4.ts

@@ -0,0 +1,160 @@
+/**
+ * AWS Signature Version 4 for the S3 API (Cloudflare R2), with Web Crypto
+ * only, so the Worker bundle doesn't need the AWS SDK. Two forms:
+ * header-signed requests (the Worker calling R2) and presigned URLs (the
+ * browser uploading parts straight to R2). No imports, so `node --test` can
+ * load this file directly.
+ */
+
+export interface SigV4Credentials {
+	accessKeyId: string;
+	secretAccessKey: string;
+}
+
+export interface SigV4Request {
+	method: string;
+	/** Host, e.g. "<account>.r2.cloudflarestorage.com". */
+	host: string;
+	/** Unencoded path, e.g. "/bucket/files/abc/report.pdf". Each segment is encoded here. */
+	path: string;
+	/** Query parameters (unencoded). Use "" for valueless ones such as `uploads` or `cors`. */
+	query?: Record<string, string>;
+	/** Extra headers to sign (host is added). */
+	headers?: Record<string, string>;
+	region: string;
+	service?: string;
+	/** Defaults to now. */
+	date?: Date;
+}
+
+const encoder = new TextEncoder();
+export const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+
+function hex(buffer: ArrayBuffer): string {
+	return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export async function sha256Hex(data: string | Uint8Array): Promise<string> {
+	const bytes = typeof data === "string" ? encoder.encode(data) : data;
+	return hex(await crypto.subtle.digest("SHA-256", bytes as Uint8Array<ArrayBuffer>));
+}
+
+async function hmac(key: ArrayBuffer | Uint8Array, data: string): Promise<ArrayBuffer> {
+	const cryptoKey = await crypto.subtle.importKey("raw", key as Uint8Array<ArrayBuffer>, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+	return crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(data));
+}
+
+/** S3's URI encoding: everything but A-Z a-z 0-9 - . _ ~ (and "/" when encoding a path). */
+export function uriEncode(value: string, encodeSlash = true): string {
+	let out = "";
+	for (const byte of encoder.encode(value)) {
+		const c = String.fromCharCode(byte);
+		if (/[A-Za-z0-9\-._~]/.test(c) || (c === "/" && !encodeSlash)) out += c;
+		else out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	}
+	return out;
+}
+
+export function canonicalQuery(query: Record<string, string> = {}): string {
+	return Object.entries(query)
+		.map(([k, v]) => [uriEncode(k), uriEncode(v)] as const)
+		.sort(([a, av], [b, bv]) => (a < b ? -1 : a > b ? 1 : av < bv ? -1 : av > bv ? 1 : 0))
+		.map(([k, v]) => `${k}=${v}`)
+		.join("&");
+}
+
+/** "20130524T000000Z" */
+export function amzDate(date: Date): string {
+	return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+async function signingKey(secret: string, day: string, region: string, service: string): Promise<ArrayBuffer> {
+	const kDate = await hmac(encoder.encode(`AWS4${secret}`), day);
+	const kRegion = await hmac(kDate, region);
+	const kService = await hmac(kRegion, service);
+	return hmac(kService, "aws4_request");
+}
+
+interface Prepared {
+	canonicalRequest: string;
+	stringToSign: string;
+	signature: string;
+	signedHeaders: string;
+	scope: string;
+	datetime: string;
+}
+
+async function prepare(
+	req: SigV4Request,
+	creds: SigV4Credentials,
+	headers: Record<string, string>,
+	query: Record<string, string>,
+	payloadHash: string,
+	datetime: string,
+): Promise<Prepared> {
+	const service = req.service ?? "s3";
+	const day = datetime.slice(0, 8);
+	const scope = `${day}/${req.region}/${service}/aws4_request`;
+	const lower = Object.entries(headers).map(([k, v]) => [k.toLowerCase(), String(v).trim().replace(/\s+/g, " ")] as const);
+	lower.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	const signedHeaders = lower.map(([k]) => k).join(";");
+	const canonicalRequest = [
+		req.method.toUpperCase(),
+		uriEncode(req.path, false),
+		canonicalQuery(query),
+		lower.map(([k, v]) => `${k}:${v}\n`).join(""),
+		signedHeaders,
+		payloadHash,
+	].join("\n");
+	const stringToSign = ["AWS4-HMAC-SHA256", datetime, scope, await sha256Hex(canonicalRequest)].join("\n");
+	const signature = hex(await hmac(await signingKey(creds.secretAccessKey, day, req.region, service), stringToSign));
+	return { canonicalRequest, stringToSign, signature, signedHeaders, scope, datetime };
+}
+
+/**
+ * Sign a request with an Authorization header. Returns the headers to send
+ * (including host, x-amz-date and x-amz-content-sha256) and the full URL.
+ */
+export async function signRequest(
+	req: SigV4Request,
+	creds: SigV4Credentials,
+	payloadHash: string = EMPTY_SHA256,
+): Promise<{ url: string; headers: Record<string, string>; signature: string }> {
+	const datetime = amzDate(req.date ?? new Date());
+	const headers: Record<string, string> = {
+		...req.headers,
+		host: req.host,
+		"x-amz-date": datetime,
+		"x-amz-content-sha256": payloadHash,
+	};
+	const query = req.query ?? {};
+	const p = await prepare(req, creds, headers, query, payloadHash, datetime);
+	const out = { ...headers };
+	delete out.host; // fetch sets Host itself.
+	out.authorization = `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${p.scope},SignedHeaders=${p.signedHeaders},Signature=${p.signature}`;
+	const qs = canonicalQuery(query);
+	return { url: `https://${req.host}${uriEncode(req.path, false)}${qs ? `?${qs}` : ""}`, headers: out, signature: p.signature };
+}
+
+/** A presigned URL (query-string auth, unsigned payload). Only `host` is signed unless `headers` adds more. */
+export async function presignUrl(req: SigV4Request, creds: SigV4Credentials, expiresSeconds: number): Promise<{ url: string; signature: string }> {
+	const datetime = amzDate(req.date ?? new Date());
+	const service = req.service ?? "s3";
+	const headers: Record<string, string> = { ...req.headers, host: req.host };
+	const signedHeaders = Object.keys(headers)
+		.map((k) => k.toLowerCase())
+		.sort()
+		.join(";");
+	const query: Record<string, string> = {
+		...req.query,
+		"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+		"X-Amz-Credential": `${creds.accessKeyId}/${datetime.slice(0, 8)}/${req.region}/${service}/aws4_request`,
+		"X-Amz-Date": datetime,
+		"X-Amz-Expires": String(Math.max(1, Math.min(604800, Math.floor(expiresSeconds)))),
+		"X-Amz-SignedHeaders": signedHeaders,
+	};
+	const p = await prepare(req, creds, headers, query, UNSIGNED_PAYLOAD, datetime);
+	const qs = `${canonicalQuery(query)}&X-Amz-Signature=${p.signature}`;
+	return { url: `https://${req.host}${uriEncode(req.path, false)}?${qs}`, signature: p.signature };
+}

package/src/files/site.ts

@@ -0,0 +1,137 @@
+/**
+ * Site-side reads and writes for File Downloads, outside the plugin context
+ * (the download middleware and the Astro download card). They go straight to
+ * D1: plugin settings live in `options` (read with the feature switches),
+ * large uploads and download counts in `_plugin_storage`, media library files
+ * in `media`. Reads are cached per isolate; download counts are batched and written after the response.
+ */
+import { PLUGIN_ID, invalidateFeatures, readSiteSetting, registerSiteSetting } from "../core/features.js";
+import { createDownloadCounter } from "./counts.js";
+import { isUploadId, normalizeBase, safeColor } from "./format.js";
+
+export const COLLECTIONS = {
+	uploads: "files_uploads",
+	usage: "files_usage",
+	counts: "files_counts",
+} as const;
+
+/** Site settings the card and downloads need (never the S3 credentials). */
+export interface SiteSettings {
+	base: string;
+	publicBaseUrl: string;
+	scheme: "auto" | "light" | "dark";
+	accent: string;
+}
+
+/** A downloadable file, from either store. */
+export interface FileRecord {
+	id: string;
+	source: "upload" | "media";
+	name: string;
+	type: string;
+	size: number;
+	uploadedAt: string;
+	key: string;
+}
+
+/** Large-upload metadata in plugin storage. */
+export interface UploadDoc {
+	id: string;
+	key: string;
+	name: string;
+	size: number;
+	type: string;
+	uploadedAt: string;
+	status: "uploading" | "ready";
+	uploadId?: string;
+	partSize?: number;
+}
+
+const SETTING_KEYS = ["filesBase", "filesPublicBaseUrl", "filesScheme", "filesAccent"] as const;
+for (const key of SETTING_KEYS) registerSiteSetting(key);
+const FILE_TTL = 60_000;
+const FILE_CACHE_MAX = 500;
+
+/** The last stored values and the settings made from them, so a cache hit doesn't rebuild them. */
+let settingsMemo: { raw: unknown[]; value: SiteSettings } | null = null;
+const fileCache = new Map<string, { value: FileRecord | null; at: number }>();
+
+/** Forget cached settings and files (after admin changes in this isolate). */
+export function invalidateSiteCache(id?: string): void {
+	if (id) fileCache.delete(id);
+	else {
+		invalidateFeatures();
+		fileCache.clear();
+	}
+}
+
+export function settingsFrom(raw: Record<string, unknown>): SiteSettings {
+	const scheme = raw.filesScheme === "light" || raw.filesScheme === "dark" ? raw.filesScheme : "auto";
+	const publicBase = typeof raw.filesPublicBaseUrl === "string" ? raw.filesPublicBaseUrl.trim().replace(/\/+$/, "") : "";
+	return {
+		base: normalizeBase(raw.filesBase),
+		publicBaseUrl: /^https:\/\/[^\s"'<>]+$/i.test(publicBase) ? publicBase : "",
+		scheme,
+		accent: safeColor(raw.filesAccent),
+	};
+}
+
+/** The settings from D1, in the feature switches' query and per-isolate cache (defaults if it can't be read). */
+export async function readSiteSettings(db: D1Database): Promise<SiteSettings> {
+	const reads = await Promise.all(SETTING_KEYS.map((key) => readSiteSetting(key, db)));
+	if (reads.some((r) => !r)) console.error("coywolf-pack files: could not read settings");
+	const raw = reads.map((r) => r?.value ?? null);
+	const memo = settingsMemo;
+	if (memo && raw.every((v, i) => v === memo.raw[i])) return memo.value;
+	const value = settingsFrom(Object.fromEntries(SETTING_KEYS.map((key, i) => [key, raw[i] ?? undefined])));
+	settingsMemo = { raw, value };
+	return value;
+}
+
+export function uploadToRecord(doc: UploadDoc): FileRecord {
+	return { id: doc.id, source: "upload", name: doc.name, type: doc.type, size: doc.size, uploadedAt: doc.uploadedAt, key: doc.key };
+}
+
+/** Look up a file by id: a ready large upload, or a ready media library item. Null when missing. */
+export async function resolveFile(db: D1Database, id: string): Promise<FileRecord | null> {
+	const hit = fileCache.get(id);
+	if (hit && Date.now() - hit.at < FILE_TTL) return hit.value;
+	let value: FileRecord | null = null;
+	if (isUploadId(id)) {
+		const row = await db
+			.prepare("SELECT data FROM _plugin_storage WHERE plugin_id = ? AND collection = ? AND id = ?")
+			.bind(PLUGIN_ID, COLLECTIONS.uploads, id)
+			.first<{ data: string }>();
+		const doc = row ? (JSON.parse(row.data) as UploadDoc) : null;
+		value = doc && doc.status === "ready" ? uploadToRecord(doc) : null;
+	} else {
+		const row = await db
+			.prepare("SELECT id, filename, mime_type, size, storage_key, created_at, status FROM media WHERE id = ?")
+			.bind(id)
+			.first<{ id: string; filename: string; mime_type: string; size: number | null; storage_key: string; created_at: string; status: string | null }>();
+		value =
+			row && (row.status ?? "ready") === "ready"
+				? {
+						id: row.id,
+						source: "media",
+						name: row.filename,
+						type: row.mime_type,
+						size: row.size ?? 0,
+						uploadedAt: row.created_at,
+						key: row.storage_key,
+					}
+				: null;
+	}
+	if (fileCache.size >= FILE_CACHE_MAX) fileCache.delete(fileCache.keys().next().value as string);
+	fileCache.set(id, { value, at: Date.now() });
+	return value;
+}
+
+// ── Download counts ──────────────────────────────────────────────
+
+const counter = createDownloadCounter(PLUGIN_ID, COLLECTIONS.counts);
+
+/** Count a download; counts within a second in this isolate are written together after the response. */
+export function countDownload(db: D1Database, id: string, waitUntil: (p: Promise<unknown>) => void): void {
+	counter.count(db, id, waitUntil);
+}