@flowdular/sdk 0.2.4 → 0.3.0

package/packages/server/src/trace/tracer.ts

@@ -0,0 +1,338 @@
+import { serverLogger } from '../log.ts';
+import {
+	currentTrace,
+	newSpanId,
+	newTraceId,
+	parseTraceParent,
+	type TraceContext,
+} from './context.ts';
+
+export type SpanKind =
+	| 'internal'
+	| 'server'
+	| 'client'
+	| 'producer'
+	| 'consumer';
+export type SpanStatus = 'unset' | 'ok' | 'error';
+export type SpanAttributeValue = string | number | boolean;
+
+export interface SpanAttributes {
+	readonly [key: string]: SpanAttributeValue;
+}
+
+/**
+ * A unit of work with a name, a start, an end, a status and bounded
+ * attributes. Ending it is idempotent, so a `finally` may always call it.
+ */
+export interface Span {
+	readonly context: TraceContext;
+	/** Ignored past the attribute ceiling and after the span ended. */
+	setAttribute(key: string, value: SpanAttributeValue): void;
+	/**
+	 * `endedAt` is epoch milliseconds, for a consumer replaying an instant it
+	 * was told about rather than one it observed, such as the job event sink.
+	 * Absent reads the tracer's clock.
+	 */
+	end(status?: SpanStatus, message?: string, endedAt?: number): void;
+}
+
+export interface StartSpanOptions {
+	/**
+	 * Absent takes the ambient trace, so nested work nests without threading a
+	 * context by hand. Null is an explicit new root.
+	 */
+	readonly parent?: TraceContext | null;
+	/** Parsed when `parent` is absent; a header that does not parse is a root. */
+	readonly traceparent?: string | null;
+	readonly kind?: SpanKind;
+	readonly attributes?: SpanAttributes;
+	/** Epoch milliseconds. Defaults to the tracer's clock. */
+	readonly startedAt?: number;
+}
+
+/** What a recorded span carries once it ended. Values only, no references. */
+export interface RecordedSpan {
+	readonly traceId: string;
+	readonly spanId: string;
+	readonly parentSpanId: string | null;
+	readonly name: string;
+	readonly kind: SpanKind;
+	/** Epoch milliseconds. */
+	readonly startedAt: number;
+	readonly endedAt: number;
+	readonly status: SpanStatus;
+	readonly statusMessage: string | null;
+	readonly attributes: SpanAttributes;
+}
+
+export interface TraceStats {
+	/** Spans waiting to be drained. */
+	readonly buffered: number;
+	/** Spans the buffer evicted because it was full. */
+	readonly dropped: number;
+	/** Sampled spans recorded since the process started. */
+	readonly recorded: number;
+}
+
+export interface Tracer {
+	/** 0 to 1. A root outside that ratio still propagates, it is not recorded. */
+	readonly sampleRatio: number;
+	startSpan(name: string, options?: StartSpanOptions): Span;
+	/** Up to `max` spans, oldest first, removed from the buffer. */
+	drain(max?: number): readonly RecordedSpan[];
+	stats(): TraceStats;
+	/**
+	 * One consumer at a time; the returned function detaches it. The listener
+	 * is called with the buffered count after every recorded span, isolated.
+	 */
+	onSpanRecorded(listener: (buffered: number) => void): () => void;
+}
+
+/**
+ * Every bound the in-process trace buffer enforces. A span is a diagnostic,
+ * never a transport: attribute count, attribute length and buffered spans are
+ * all capped so one hostile caller cannot grow the process.
+ */
+export const TRACE_LIMITS = Object.freeze({
+	/** Spans held before the oldest is evicted. */
+	bufferSpans: 4_096,
+	/** Attributes kept per span. */
+	attributes: 16,
+	/** Characters kept per attribute key and per string value. */
+	attributeChars: 256,
+	/** Characters kept of a span name. */
+	nameChars: 256,
+	/** Spans one export batch carries. */
+	batchSpans: 512,
+	/** Milliseconds between export batches. */
+	flushEveryMs: 5_000,
+});
+
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/g;
+const SAMPLE_DENOMINATOR = 0x1_0000_0000;
+
+/* A span name and an attribute both reach an exporter and a log line, so a
+   control character in either would forge a second record downstream. */
+function boundedText(value: string, max: number): string {
+	const cut = value.length <= max ? value : value.slice(0, max);
+	return cut.replace(CONTROL_CHARACTER, ' ');
+}
+
+/* Deterministic on the trace id so the whole trace shares one decision, and so
+   a test that injects ids gets a stable answer instead of a coin flip. */
+function sampledByRatio(traceId: string, ratio: number): boolean {
+	if (ratio >= 1) return true;
+	if (ratio <= 0) return false;
+	return Number.parseInt(traceId.slice(-8), 16) / SAMPLE_DENOMINATOR < ratio;
+}
+
+/* Propagated but never recorded. It still owns a span id, because a downstream
+   service reads the header and must see a parent that exists. */
+class UnsampledSpan implements Span {
+	constructor(readonly context: TraceContext) {}
+	setAttribute(): void {}
+	end(): void {}
+}
+
+class RecordingSpan implements Span {
+	#ended = false;
+	#count = 0;
+	readonly #attributes: Record<string, SpanAttributeValue> = {};
+
+	constructor(
+		readonly context: TraceContext,
+		private readonly parentSpanId: string | null,
+		private readonly name: string,
+		private readonly kind: SpanKind,
+		private readonly startedAt: number,
+		private readonly now: () => number,
+		private readonly record: (span: RecordedSpan) => void,
+	) {}
+
+	setAttribute(key: string, value: SpanAttributeValue): void {
+		if (this.#ended) return;
+		if (typeof value === 'number' && !Number.isFinite(value)) return;
+		const name = boundedText(key, TRACE_LIMITS.attributeChars);
+		if (name.length === 0) return;
+		/* The ceiling bounds distinct keys, so overwriting one the span already
+		   carries is always admitted: it grows nothing. */
+		if (!(name in this.#attributes)) {
+			if (this.#count >= TRACE_LIMITS.attributes) return;
+			this.#count += 1;
+		}
+		this.#attributes[name] =
+			typeof value === 'string'
+				? boundedText(value, TRACE_LIMITS.attributeChars)
+				: value;
+	}
+
+	end(status: SpanStatus = 'unset', message?: string, endedAt?: number): void {
+		if (this.#ended) return;
+		this.#ended = true;
+		this.record({
+			traceId: this.context.traceId,
+			spanId: this.context.spanId,
+			parentSpanId: this.parentSpanId,
+			name: this.name,
+			kind: this.kind,
+			startedAt: this.startedAt,
+			endedAt: endedAt ?? this.now(),
+			status,
+			statusMessage:
+				message === undefined
+					? null
+					: boundedText(message, TRACE_LIMITS.attributeChars),
+			attributes: this.#attributes,
+		});
+	}
+}
+
+export interface TracerOptions {
+	/** 0 to 1. Anything outside that, or not a number, is 1. */
+	readonly sampleRatio?: number;
+	/** Epoch milliseconds. Defaults to `Date.now`. */
+	readonly now?: () => number;
+	/** Hex id source, for a test that needs a stable sampling decision. */
+	readonly newTraceId?: () => string;
+	readonly newSpanId?: () => string;
+	/** Buffered spans before the oldest is evicted. Defaults to the limit. */
+	readonly bufferSpans?: number;
+}
+
+/**
+ * Collects spans into one bounded ring. It sends nothing and opens no handle:
+ * an exporter drains it, and a deployment that composes none still pays only
+ * the ring, which evicts its oldest span rather than growing.
+ */
+export function createTracer(options: TracerOptions = {}): Tracer {
+	const ratio =
+		typeof options.sampleRatio === 'number' &&
+		Number.isFinite(options.sampleRatio) &&
+		options.sampleRatio >= 0 &&
+		options.sampleRatio <= 1
+			? options.sampleRatio
+			: 1;
+	const now = options.now ?? (() => Date.now());
+	const traceId = options.newTraceId ?? newTraceId;
+	const spanId = options.newSpanId ?? newSpanId;
+	const capacity = Math.max(
+		1,
+		Math.trunc(options.bufferSpans ?? TRACE_LIMITS.bufferSpans),
+	);
+	const ring = new Array<RecordedSpan | undefined>(capacity);
+	let head = 0;
+	let size = 0;
+	let dropped = 0;
+	let recorded = 0;
+	let listener: ((buffered: number) => void) | undefined;
+
+	const record = (span: RecordedSpan): void => {
+		if (size === capacity) {
+			/* Drop oldest: the newest span is the one a reader is waiting for, and
+			   an exporter that fell behind must not decide what the process keeps. */
+			ring[head] = span;
+			head = (head + 1) % capacity;
+			dropped += 1;
+		} else {
+			ring[(head + size) % capacity] = span;
+			size += 1;
+		}
+		recorded += 1;
+		if (!listener) return;
+		try {
+			listener(size);
+		} catch {
+			/* An observer that throws is the observer's defect, not the span's. */
+		}
+	};
+
+	return Object.freeze({
+		sampleRatio: ratio,
+		startSpan(name: string, startOptions: StartSpanOptions = {}): Span {
+			const parent =
+				startOptions.parent !== undefined
+					? startOptions.parent
+					: startOptions.traceparent !== undefined
+						? parseTraceParent(startOptions.traceparent)
+						: (currentTrace() ?? null);
+			const id = parent ? parent.traceId : traceId();
+			const context: TraceContext = {
+				traceId: id,
+				spanId: spanId(),
+				sampled: parent ? parent.sampled : sampledByRatio(id, ratio),
+			};
+			if (!context.sampled) return new UnsampledSpan(context);
+			const span = new RecordingSpan(
+				context,
+				parent ? parent.spanId : null,
+				boundedText(name, TRACE_LIMITS.nameChars),
+				startOptions.kind ?? 'internal',
+				startOptions.startedAt ?? now(),
+				now,
+				record,
+			);
+			if (startOptions.attributes) {
+				for (const [key, value] of Object.entries(startOptions.attributes)) {
+					span.setAttribute(key, value);
+				}
+			}
+			return span;
+		},
+		drain(max = capacity): readonly RecordedSpan[] {
+			const take = Math.min(size, Math.max(0, Math.trunc(max)));
+			const batch = new Array<RecordedSpan>(take);
+			for (let index = 0; index < take; index += 1) {
+				batch[index] = ring[head]!;
+				ring[head] = undefined;
+				head = (head + 1) % capacity;
+			}
+			size -= take;
+			return batch;
+		},
+		stats: (): TraceStats => ({ buffered: size, dropped, recorded }),
+		onSpanRecorded(next: (buffered: number) => void): () => void {
+			listener = next;
+			return () => {
+				if (listener === next) listener = undefined;
+			};
+		},
+	});
+}
+
+/**
+ * The sample ratio this process records at, from `FD_TRACE_SAMPLE`. Throws on
+ * a value that is not a ratio, so a deployment that meant to sample never
+ * silently records everything.
+ */
+export function traceSampleRatio(environment: NodeJS.ProcessEnv): number {
+	const raw = environment.FD_TRACE_SAMPLE?.trim();
+	if (!raw) return 1;
+	const value = Number(raw);
+	if (!Number.isFinite(value) || value < 0 || value > 1) {
+		throw new Error('FD_TRACE_SAMPLE must be a ratio between 0 and 1.');
+	}
+	return value;
+}
+
+let processTracer: Tracer | undefined;
+
+/**
+ * The tracer of this process, built from the environment on first use so a
+ * deployment's `.env` is already loaded. Recording is always on and bounded;
+ * exporting is the platform's decision. Tests and libraries that need their
+ * own buffer call `createTracer` instead.
+ */
+export function serverTracer(): Tracer {
+	if (processTracer) return processTracer;
+	let ratio = 1;
+	try {
+		ratio = traceSampleRatio(process.env);
+	} catch {
+		/* The platform refuses the value while it composes, so this arm is only
+		   reached by a process that never composed one. It records everything and
+		   says so, rather than failing a request over a diagnostic. */
+		serverLogger().warn('FD_TRACE_SAMPLE is not a ratio; recording every span');
+	}
+	processTracer = createTracer({ sampleRatio: ratio });
+	return processTracer;
+}

package/packages/server/src/web.ts

@@ -387,7 +387,11 @@ export function createModuleWebRoutes(options: {
 			!surface.pages.some((page) => page.path === '/')
 		)
 			routes.push(fallback(site.path));
-		routes.push(fallback(base + '/*unmatched'));
+		/* A nested mount closes its own subtree. A root mount gets no catch-all:
+		   it would claim the whole origin, and a matched server route pre-empts
+		   the host layers that serve development transforms, built assets and
+		   public files. Unmatched addresses reach those layers and 404 there. */
+		if (base) routes.push(fallback(base + '/*unmatched'));
 	}
 	if (
 		mounts.some((site) => site.path.startsWith('/sites/')) &&

package/packages/storage/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@flowdular/storage",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/kernel": "workspace:*"
+	},
+	"devDependencies": {
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.11"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "packages/storage"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/packages/storage/src/config.ts

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import {
+	createKeyring,
+	parsePreviousKeys,
+	type Keyring,
+} from '@flowdular/sdk/kernel';
+import {
+	flowdularEnvironment,
+	flowdularStateDirectory,
+} from '@flowdular/sdk/kernel/runtime-config';
+
+export type ConfiguredStorageAdapter = 'local' | 's3';
+
+export interface StorageConfig {
+	readonly adapter: ConfiguredStorageAdapter;
+	readonly production: boolean;
+	readonly maxObjectBytes: number;
+	readonly local: { readonly directory: string };
+	readonly s3: {
+		readonly bucket: string;
+		readonly region: string;
+		readonly endpoint: string | undefined;
+		readonly accessKeyId: string;
+		readonly secretAccessKey: string;
+		readonly forcePathStyle: boolean;
+	};
+}
+
+export const DEFAULT_STORAGE_MAX_OBJECT_BYTES = 25 * 1024 * 1024;
+/* The port authenticates a whole object before handing out a byte of it, so the
+   limit also bounds what one request holds in memory. */
+const STORAGE_MAX_OBJECT_BYTES_CEILING = 256 * 1024 * 1024;
+const STORAGE_KEY_VARIABLE = 'FD_STORAGE_ENCRYPTION_KEY';
+
+function adapterOf(
+	environment: NodeJS.ProcessEnv,
+	production: boolean,
+): ConfiguredStorageAdapter {
+	const configured = environment.FD_STORAGE_ADAPTER?.trim();
+	const adapter = configured || (production ? 's3' : 'local');
+	if (adapter !== 'local' && adapter !== 's3') {
+		throw new Error('FD_STORAGE_ADAPTER must be "local" or "s3".');
+	}
+	/* The local adapter writes to the container filesystem, which no replica
+	   shares and no backup covers. Production refuses it exactly as it refuses
+	   the embedded database. */
+	if (production && adapter === 'local') {
+		throw new Error(
+			'FD_STORAGE_ADAPTER=local is refused in production; configure the S3-compatible adapter.',
+		);
+	}
+	return adapter;
+}
+
+function booleanEnvironment(
+	value: string | undefined,
+	fallback: boolean,
+	name: string,
+): boolean {
+	const trimmed = value?.trim();
+	if (trimmed === undefined || trimmed === '') return fallback;
+	if (trimmed === 'true') return true;
+	if (trimmed === 'false') return false;
+	throw new Error(`${name} must be true or false.`);
+}
+
+function required(
+	environment: NodeJS.ProcessEnv,
+	name: string,
+	adapter: string,
+): string {
+	const value = environment[name]?.trim();
+	if (!value)
+		throw new Error(`${name} is required by FD_STORAGE_ADAPTER=${adapter}.`);
+	return value;
+}
+
+export function storageConfigFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+	workspaceRoot = process.cwd(),
+): StorageConfig {
+	environment = flowdularEnvironment(environment);
+	const production = environment.NODE_ENV === 'production';
+	const adapter = adapterOf(environment, production);
+	if (production && !environment[STORAGE_KEY_VARIABLE]?.trim()) {
+		throw new Error(
+			`${STORAGE_KEY_VARIABLE} is required in production. Provide a base64-encoded 32-byte key through deployment secrets.`,
+		);
+	}
+	const configuredLimit = environment.FD_STORAGE_MAX_OBJECT_BYTES?.trim();
+	const maxObjectBytes = configuredLimit
+		? Number(configuredLimit)
+		: DEFAULT_STORAGE_MAX_OBJECT_BYTES;
+	if (
+		!Number.isSafeInteger(maxObjectBytes) ||
+		maxObjectBytes < 1024 ||
+		maxObjectBytes > STORAGE_MAX_OBJECT_BYTES_CEILING
+	) {
+		throw new Error(
+			`FD_STORAGE_MAX_OBJECT_BYTES must be an integer between 1024 and ${STORAGE_MAX_OBJECT_BYTES_CEILING}.`,
+		);
+	}
+	return {
+		adapter,
+		production,
+		maxObjectBytes,
+		local: {
+			directory:
+				environment.FD_STORAGE_LOCAL_DIRECTORY?.trim() ||
+				resolve(flowdularStateDirectory(workspaceRoot), 'data', 'storage'),
+		},
+		s3:
+			adapter === 's3'
+				? {
+						bucket: required(environment, 'FD_STORAGE_S3_BUCKET', adapter),
+						region: required(environment, 'FD_STORAGE_S3_REGION', adapter),
+						endpoint: environment.FD_STORAGE_S3_ENDPOINT?.trim() || undefined,
+						accessKeyId: required(
+							environment,
+							'FD_STORAGE_S3_ACCESS_KEY_ID',
+							adapter,
+						),
+						secretAccessKey: required(
+							environment,
+							'FD_STORAGE_S3_SECRET_ACCESS_KEY',
+							adapter,
+						),
+						forcePathStyle: booleanEnvironment(
+							environment.FD_STORAGE_S3_FORCE_PATH_STYLE,
+							false,
+							'FD_STORAGE_S3_FORCE_PATH_STYLE',
+						),
+					}
+				: {
+						bucket: '',
+						region: '',
+						endpoint: undefined,
+						accessKeyId: '',
+						secretAccessKey: '',
+						forcePathStyle: false,
+					},
+	};
+}
+
+function decodeStorageKey(
+	value: string,
+	variable = STORAGE_KEY_VARIABLE,
+): Buffer {
+	const trimmed = value.trim();
+	const decoded = /^[0-9a-f]{64}$/i.test(trimmed)
+		? Buffer.from(trimmed, 'hex')
+		: Buffer.from(trimmed, 'base64');
+	if (decoded.length !== 32) {
+		throw new Error(`${variable} must encode exactly 32 bytes.`);
+	}
+	return decoded;
+}
+
+/* A local checkout stores objects without a configured key, the way it runs
+   without a database URL. The value is derived from the workspace path, so it
+   is stable across restarts and useless anywhere else. */
+function derivedDevelopmentKey(workspaceRoot: string): Buffer {
+	return createHash('sha256')
+		.update(`flowdular-storage-development\u0000${workspaceRoot}`)
+		.digest();
+}
+
+/**
+ * The ring that seals every stored object and every read token. Rotation adds
+ * the retired key to `FD_STORAGE_ENCRYPTION_KEY_PREVIOUS`, which opens objects
+ * written before the rotation while new writes use the current key.
+ */
+export function createStorageKeyring(
+	environment: NodeJS.ProcessEnv = process.env,
+	workspaceRoot = process.cwd(),
+): Keyring {
+	environment = flowdularEnvironment(environment);
+	const configured = environment[STORAGE_KEY_VARIABLE];
+	return createKeyring({
+		current: configured
+			? decodeStorageKey(configured)
+			: derivedDevelopmentKey(workspaceRoot),
+		previous: parsePreviousKeys(
+			environment[`${STORAGE_KEY_VARIABLE}_PREVIOUS`],
+			(entry) => decodeStorageKey(entry, `${STORAGE_KEY_VARIABLE}_PREVIOUS`),
+		),
+	});
+}

package/packages/storage/src/content-type.ts

@@ -0,0 +1,124 @@
+/* The platform stores content it did not produce, so the declared type is not
+   evidence. Every accepted type is verified against the bytes: a signature, or a
+   structural check for the container formats that share one. Archives and
+   executables are absent by decision, not by oversight. */
+
+const OOXML_ENTRY = '[Content_Types].xml';
+const TEXT_SAMPLE_BYTES = 64 * 1024;
+
+type ContentVerifier = (body: Uint8Array) => boolean;
+
+function signature(...bytes: readonly number[]): ContentVerifier {
+	return (body) => {
+		if (body.byteLength < bytes.length) return false;
+		return bytes.every((value, index) => body[index] === value);
+	};
+}
+
+function at(offset: number, text: string): ContentVerifier {
+	const codes = [...text].map((character) => character.charCodeAt(0));
+	return (body) => {
+		if (body.byteLength < offset + codes.length) return false;
+		return codes.every((value, index) => body[offset + index] === value);
+	};
+}
+
+function either(...verifiers: readonly ContentVerifier[]): ContentVerifier {
+	return (body) => verifiers.some((verify) => verify(body));
+}
+
+function both(...verifiers: readonly ContentVerifier[]): ContentVerifier {
+	return (body) => verifiers.every((verify) => verify(body));
+}
+
+/**
+ * An OOXML document is a ZIP whose first entry is the content type map. A plain
+ * archive renamed to .docx carries a different first entry, so this refuses the
+ * archive the allowlist deliberately leaves out.
+ */
+const ooxml: ContentVerifier = (body) => {
+	if (!signature(0x50, 0x4b, 0x03, 0x04)(body)) return false;
+	if (body.byteLength < 30) return false;
+	const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+	const nameLength = view.getUint16(26, true);
+	if (nameLength !== OOXML_ENTRY.length) return false;
+	if (body.byteLength < 30 + nameLength) return false;
+	return at(30, OOXML_ENTRY)(body);
+};
+
+/* Valid UTF-8 without NUL or stray control bytes. The decoder runs over a
+   bounded prefix in streaming mode, so a multi-byte sequence split by the
+   sample boundary is not read as a failure. */
+const utf8Text: ContentVerifier = (body) => {
+	const sample = body.subarray(0, TEXT_SAMPLE_BYTES);
+	for (const byte of sample) {
+		if (byte === 0) return false;
+		if (byte < 0x09 || (byte > 0x0d && byte < 0x20)) return false;
+	}
+	try {
+		new TextDecoder('utf-8', { fatal: true }).decode(sample, { stream: true });
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/* Documents, images, spreadsheets and PDF. No archive and no executable: a type
+   added here needs a verifier that a renamed file cannot satisfy. */
+const RULES: ReadonlyMap<string, ContentVerifier> = new Map([
+	['application/pdf', signature(0x25, 0x50, 0x44, 0x46, 0x2d)],
+	['image/png', signature(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)],
+	['image/jpeg', signature(0xff, 0xd8, 0xff)],
+	['image/gif', either(at(0, 'GIF87a'), at(0, 'GIF89a'))],
+	['image/webp', both(at(0, 'RIFF'), at(8, 'WEBP'))],
+	['text/plain', utf8Text],
+	['text/csv', utf8Text],
+	[
+		'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+		ooxml,
+	],
+	['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', ooxml],
+	[
+		'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+		ooxml,
+	],
+	[
+		'application/msword',
+		signature(0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1),
+	],
+	[
+		'application/vnd.ms-excel',
+		signature(0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1),
+	],
+]);
+
+/** Every content type an object may be stored under. */
+export const STORAGE_CONTENT_TYPES: readonly string[] = Object.freeze([
+	...RULES.keys(),
+]);
+
+/**
+ * The essence of a media type: lowercased, without parameters and without
+ * surrounding space. `null` when the value is not a media type at all.
+ */
+export function normalizeContentType(value: string): string | null {
+	const essence = value.split(';')[0]?.trim().toLowerCase() ?? '';
+	return /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(
+		essence,
+	)
+		? essence
+		: null;
+}
+
+export function contentTypeAllowed(contentType: string): boolean {
+	return RULES.has(contentType);
+}
+
+/** Whether the bytes carry what the normalized content type claims. */
+export function contentMatchesType(
+	contentType: string,
+	body: Uint8Array,
+): boolean {
+	const verify = RULES.get(contentType);
+	return verify ? verify(body) : false;
+}