@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/files/r2-rules.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Run: node --test src/files/*.test.ts
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// @ts-expect-error -- Node's type stripping needs the real .ts extension.
+import { parseDownloadPath } from "./format.ts";
+// @ts-expect-error -- Node's type stripping needs the real .ts extension.
+import { MAX_THROUGH_SITE, PART_SIZE, partSizeFor } from "./r2-rules.ts";
+
+const MiB = 1024 * 1024;
+
+test("parts are 6 MiB: above R2's 5 MiB minimum, under EmDash's 8 MiB route body cap", () => {
+	assert.equal(PART_SIZE, 6 * MiB);
+	assert.equal(partSizeFor(1), PART_SIZE);
+	assert.equal(partSizeFor(40 * 1024 * MiB), PART_SIZE);
+	assert.equal(MAX_THROUGH_SITE, 10_000 * PART_SIZE);
+	assert.ok(MAX_THROUGH_SITE >= 50 * 1024 ** 3, "the 50 GB setting fits");
+});
+
+test("download paths", () => {
+	assert.deepEqual(parseDownloadPath("/download/fabcdefghijklmno/report.pdf", "download"), { id: "fabcdefghijklmno", filename: "report.pdf" });
+	assert.deepEqual(parseDownloadPath("/download/01J9ZQ3W4X5Y6Z7A8B9C0D1E2F", "download"), { id: "01J9ZQ3W4X5Y6Z7A8B9C0D1E2F", filename: null });
+	assert.equal(parseDownloadPath("/download/", "download"), null);
+	assert.equal(parseDownloadPath("/download/not-an-id/x.pdf", "download"), null);
+	assert.equal(parseDownloadPath("/download/fabcdefghijklmno/a/b", "download"), null);
+	assert.equal(parseDownloadPath("/downloads/fabcdefghijklmno/x", "download"), null);
+	assert.equal(parseDownloadPath("/download/%E0%A4%A/x", "download"), null);
+});

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.test.ts

@@ -0,0 +1,64 @@
+/**
+ * SigV4 against the examples AWS publishes in the S3 API reference
+ * ("Signature Calculations for the Authorization Header" and "Authenticating
+ * Requests: Using Query Parameters").
+ * Run: node --test src/files/*.test.ts
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// @ts-expect-error -- Node's type stripping needs the real .ts extension.
+import { canonicalQuery, presignUrl, sha256Hex, signRequest, uriEncode } from "./sigv4.ts";
+
+const creds = { accessKeyId: "AKIAIOSFODNN7EXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" };
+const date = new Date("2013-05-24T00:00:00Z");
+const host = "examplebucket.s3.amazonaws.com";
+const base = { host, region: "us-east-1", date };
+
+test("GET object (Range header)", async () => {
+	const { signature, headers } = await signRequest({ ...base, method: "GET", path: "/test.txt", headers: { range: "bytes=0-9" } }, creds);
+	assert.equal(signature, "f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41");
+	assert.match(headers.authorization, /^AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE\/20130524\/us-east-1\/s3\/aws4_request,SignedHeaders=host;range;x-amz-content-sha256;x-amz-date,Signature=f0e8/);
+});
+
+test("PUT object (encoded key, signed body)", async () => {
+	const body = "Welcome to Amazon S3.";
+	const payload = await sha256Hex(body);
+	assert.equal(payload, "44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072");
+	const { signature } = await signRequest(
+		{
+			...base,
+			method: "PUT",
+			path: "/test$file.text",
+			headers: { date: "Fri, 24 May 2013 00:00:00 GMT", "x-amz-storage-class": "REDUCED_REDUNDANCY" },
+		},
+		creds,
+		payload,
+	);
+	assert.equal(signature, "98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd");
+});
+
+test("GET bucket lifecycle (valueless query parameter)", async () => {
+	const { signature } = await signRequest({ ...base, method: "GET", path: "/", query: { lifecycle: "" } }, creds);
+	assert.equal(signature, "fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543");
+});
+
+test("GET bucket list (sorted query)", async () => {
+	const { signature } = await signRequest({ ...base, method: "GET", path: "/", query: { prefix: "J", "max-keys": "2" } }, creds);
+	assert.equal(signature, "34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7");
+});
+
+test("presigned GET URL", async () => {
+	const { url, signature } = await presignUrl({ ...base, method: "GET", path: "/test.txt" }, creds, 86400);
+	assert.equal(signature, "aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404");
+	assert.equal(
+		url,
+		"https://examplebucket.s3.amazonaws.com/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404",
+	);
+});
+
+test("URI encoding and query order", () => {
+	assert.equal(uriEncode("a b/ü~*", false), "a%20b/%C3%BC~%2A");
+	assert.equal(uriEncode("a/b"), "a%2Fb");
+	assert.equal(canonicalQuery({ uploadId: "x y", partNumber: "2" }), "partNumber=2&uploadId=x%20y");
+});

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