emdash 0.2.0 → 0.3.0

package/src/database/repositories/content.ts

@@ -3,6 +3,7 @@ import { ulid } from "ulidx";
 
 import { slugify } from "../../utils/slugify.js";
 import type { Database } from "../types.js";
+import { validateIdentifier } from "../validate.js";
 import { RevisionRepository } from "./revision.js";
 import type {
 	CreateContentInput,
@@ -41,6 +42,7 @@ const SYSTEM_COLUMNS = new Set([
  * Get the table name for a collection type
  */
 function getTableName(type: string): string {
+	validateIdentifier(type, "collection type");
 	return `ec_${type}`;
 }
 
@@ -168,6 +170,7 @@ export class ContentRepository {
 		if (data && typeof data === "object") {
 			for (const [key, value] of Object.entries(data)) {
 				if (!SYSTEM_COLUMNS.has(key)) {
+					validateIdentifier(key, "content field name");
 					columns.push(key);
 					values.push(serializeValue(value));
 				}
@@ -578,6 +581,7 @@ export class ContentRepository {
 		if (input.data !== undefined && typeof input.data === "object") {
 			for (const [key, value] of Object.entries(input.data)) {
 				if (!SYSTEM_COLUMNS.has(key)) {
+					validateIdentifier(key, "content field name");
 					updates[key] = serializeValue(value);
 				}
 			}
@@ -1079,6 +1083,7 @@ export class ContentRepository {
 		for (const [key, value] of Object.entries(data)) {
 			if (SYSTEM_COLUMNS.has(key)) continue;
 			if (key.startsWith("_")) continue; // revision metadata
+			validateIdentifier(key, "content field name");
 			updates[key] = serializeValue(value);
 		}
 

package/src/database/repositories/redirect.ts

@@ -237,6 +237,19 @@ export class RedirectRepository {
 		return BigInt(result.numDeletedRows) > 0n;
 	}
 
+	/**
+	 * Fetch all enabled redirects (for loop detection graph building).
+	 * Not paginated — returns the full set.
+	 */
+	async findAllEnabled(): Promise<Redirect[]> {
+		const rows = await this.db
+			.selectFrom("_emdash_redirects")
+			.selectAll()
+			.where("enabled", "=", 1)
+			.execute();
+		return rows.map(rowToRedirect);
+	}
+
 	// --- Matching -----------------------------------------------------------
 
 	async findExactMatch(path: string): Promise<Redirect | null> {

package/src/database/validate.ts

@@ -79,16 +79,6 @@ export function validateIdentifier(value: string, label = "identifier"): void {
 	}
 }
 
-/**
- * Validate that a string is a safe SQL identifier, allowing hyphens.
- *
- * Like `validateIdentifier` but also permits hyphens, which appear in
- * plugin IDs (e.g., "my-plugin"). Matches `/^[a-z][a-z0-9_-]*$/`.
- *
- * @param value - The string to validate
- * @param label - Human-readable label for error messages
- * @throws {IdentifierError} If the value is not valid
- */
 /**
  * Validate that a string is a safe JSON field name for use in json_extract paths.
  *
@@ -120,6 +110,16 @@ export function validateJsonFieldName(value: string, label = "JSON field name"):
 	}
 }
 
+/**
+ * Validate that a string is a safe SQL identifier, allowing hyphens.
+ *
+ * Like `validateIdentifier` but also permits hyphens, which appear in
+ * plugin IDs (e.g., "my-plugin"). Matches `/^[a-z][a-z0-9_-]*$/`.
+ *
+ * @param value - The string to validate
+ * @param label - Human-readable label for error messages
+ * @throws {IdentifierError} If the value is not valid
+ */
 export function validatePluginIdentifier(value: string, label = "plugin identifier"): void {
 	if (!value || typeof value !== "string") {
 		throw new IdentifierError(`${label} must be a non-empty string`, String(value));

package/src/emdash-runtime.ts

@@ -23,6 +23,7 @@ import { isSqlite } from "./database/dialect-helpers.js";
 import { runMigrations } from "./database/migrations/runner.js";
 import { RevisionRepository } from "./database/repositories/revision.js";
 import type { ContentItem as ContentItemInternal } from "./database/repositories/types.js";
+import { validateIdentifier } from "./database/validate.js";
 import { normalizeMediaValue } from "./media/normalize.js";
 import type { MediaProvider, MediaProviderCapabilities } from "./media/types.js";
 import type { SandboxedPlugin, SandboxRunner } from "./plugins/sandbox/types.js";
@@ -38,6 +39,7 @@ import type {
 } from "./plugins/types.js";
 import type { FieldType } from "./schema/types.js";
 import { hashString } from "./utils/hash.js";
+import { COMMIT, VERSION } from "./version.js";
 
 const LEADING_SLASH_PATTERN = /^\//;
 
@@ -1352,7 +1354,8 @@ export class EmDashRuntime {
 				: undefined;
 
 		return {
-			version: "0.1.0",
+			version: VERSION,
+			commit: COMMIT,
 			hash: manifestHash,
 			collections: manifestCollections,
 			plugins: manifestPlugins,
@@ -1540,6 +1543,7 @@ export class EmDashRuntime {
 							});
 
 							// Update entry to point to new draft (metadata only, not data columns)
+							validateIdentifier(collection, "collection");
 							const tableName = `ec_${collection}`;
 							await sql`
 								UPDATE ${sql.ref(tableName)}

package/src/index.ts

@@ -102,6 +102,7 @@ export type {
 export { ulid } from "ulidx";
 export { computeContentHash, hashString } from "./utils/hash.js";
 export { sanitizeHref, isSafeHref } from "./utils/url.js";
+export { decodeSlug } from "./utils/slugify.js";
 
 // Live Collections query functions (loader is in emdash/runtime)
 export {

package/src/loader.ts

@@ -16,6 +16,7 @@ import { Kysely, sql, type Dialect } from "kysely";
 
 import { currentTimestampValue, isPostgres } from "./database/dialect-helpers.js";
 import { decodeCursor, encodeCursor } from "./database/repositories/types.js";
+import { validateIdentifier } from "./database/validate.js";
 import type { Database } from "./index.js";
 import { getRequestContext } from "./request-context.js";
 
@@ -50,6 +51,7 @@ const SYSTEM_COLUMNS = new Set([
  * Get the table name for a collection type
  */
 function getTableName(type: string): string {
+	validateIdentifier(type, "collection type");
 	return `ec_${type}`;
 }
 

package/src/menus/index.ts

@@ -8,6 +8,7 @@ import type { Kysely } from "kysely";
 import { sql } from "kysely";
 
 import type { Database } from "../database/types.js";
+import { validateIdentifier } from "../database/validate.js";
 import { getDb } from "../loader.js";
 import { sanitizeHref } from "../utils/url.js";
 import type { Menu, MenuItem, MenuItemRow } from "./types.js";
@@ -273,6 +274,9 @@ async function resolveContentUrl(
 	}
 
 	try {
+		// Validate collection name before interpolating into table reference
+		validateIdentifier(collection, "menu item collection");
+
 		// Dynamic content tables (ec_*) aren't in the Database type, so use sql
 		const result = await sql<{ slug: string }>`
 			SELECT slug FROM ${sql.ref(`ec_${collection}`)} WHERE id = ${entryId} LIMIT 1

package/src/redirects/loops.ts

@@ -0,0 +1,318 @@
+/**
+ * Redirect loop and chain detection utilities.
+ *
+ * Builds a directed graph from redirect rules and detects:
+ * - Cycles (loops): /a → /b → /c → /a
+ * - Long chains: /a → /b → /c → /d → /e (exceeding a warning threshold)
+ *
+ * Handles both exact and pattern redirects. When the walker encounters
+ * a path with no exact source match, it tests against compiled pattern
+ * sources and resolves the destination using captured parameters.
+ */
+
+import {
+	compilePattern,
+	matchPattern,
+	interpolateDestination,
+	type CompiledPattern,
+} from "./patterns.js";
+
+export interface RedirectEdge {
+	id: string;
+	source: string;
+	destination: string;
+	enabled: boolean;
+	isPattern: boolean;
+}
+
+interface CompiledPatternRedirect {
+	id: string;
+	compiled: CompiledPattern;
+	destination: string;
+}
+
+/**
+ * Compile all enabled pattern redirects for matching during graph walks.
+ */
+function compilePatterns(edges: RedirectEdge[]): CompiledPatternRedirect[] {
+	const result: CompiledPatternRedirect[] = [];
+	for (const edge of edges) {
+		if (edge.enabled && edge.isPattern) {
+			result.push({
+				id: edge.id,
+				compiled: compilePattern(edge.source),
+				destination: edge.destination,
+			});
+		}
+	}
+	return result;
+}
+
+/** Single-segment dummy value for representative path generation */
+const DUMMY_SEGMENT = "__p__";
+
+/** Splat pattern: [...paramName] */
+const SPLAT_RE = /\[\.\.\.(\w+)\]/g;
+
+/** Param pattern: [paramName] */
+const PARAM_RE = /\[(\w+)\]/g;
+
+/**
+ * Extract the literal prefix from a pattern source (everything before the
+ * first placeholder), stripped of leading segments shared with a base path.
+ * e.g., "/new/docs/[slug]" → "docs/__p__" (the part after "/new/")
+ */
+function extractPatternSuffix(patternSource: string): string {
+	// Replace placeholders with dummy values
+	let result = patternSource.replace(SPLAT_RE, DUMMY_SEGMENT);
+	SPLAT_RE.lastIndex = 0;
+	result = result.replace(PARAM_RE, DUMMY_SEGMENT);
+	// Strip leading slash and first segment (e.g., "/new/docs/__p__" → "docs/__p__")
+	const parts = result.split("/").filter(Boolean);
+	return parts.slice(1).join("/");
+}
+
+/**
+ * Generate representative concrete paths from a template string.
+ * Replaces [param] with a dummy segment and [...rest] with multiple
+ * depth variants. For catch-alls, also generates representatives using
+ * literal prefixes from existing pattern sources to catch cross-pattern loops.
+ */
+function generateRepresentatives(template: string, existingEdges?: RedirectEdge[]): string[] {
+	const hasSplat = SPLAT_RE.test(template);
+	SPLAT_RE.lastIndex = 0;
+
+	if (hasSplat) {
+		// Extract the static prefix before the catch-all (e.g., "/old/" from "/old/[...path]")
+		const splatIndex = template.indexOf("[...");
+		const prefix = template.slice(0, splatIndex);
+
+		const reps = [
+			template.replace(SPLAT_RE, DUMMY_SEGMENT).replace(PARAM_RE, DUMMY_SEGMENT),
+			template
+				.replace(SPLAT_RE, `${DUMMY_SEGMENT}/${DUMMY_SEGMENT}`)
+				.replace(PARAM_RE, DUMMY_SEGMENT),
+			template
+				.replace(SPLAT_RE, `${DUMMY_SEGMENT}/${DUMMY_SEGMENT}/${DUMMY_SEGMENT}`)
+				.replace(PARAM_RE, DUMMY_SEGMENT),
+		];
+
+		// Add representatives derived from existing pattern sources' literal prefixes
+		if (existingEdges) {
+			for (const edge of existingEdges) {
+				if (edge.enabled && edge.isPattern && edge.source !== template) {
+					const suffix = extractPatternSuffix(edge.source);
+					if (suffix) {
+						reps.push(`${prefix}${suffix}`);
+					}
+				}
+			}
+		}
+
+		return reps;
+	}
+
+	return [template.replace(PARAM_RE, DUMMY_SEGMENT)];
+}
+
+/**
+ * Resolve the next hop for a given path. Tries exact match first,
+ * then pattern matching with parameter interpolation for concrete paths,
+ * then representative-based matching for template strings.
+ */
+function resolveNext(
+	path: string,
+	graph: Map<string, { destination: string; id: string }>,
+	patterns: CompiledPatternRedirect[],
+	edges?: RedirectEdge[],
+): { destination: string; id: string } | null {
+	// Exact match (fast) — works for both real paths and template strings
+	const exact = graph.get(path);
+	if (exact) return exact;
+
+	if (!path.includes("[")) {
+		// Concrete path — try pattern matching directly
+		for (const pr of patterns) {
+			const params = matchPattern(pr.compiled, path);
+			if (params) {
+				const resolved = interpolateDestination(pr.destination, params);
+				return { destination: resolved, id: pr.id };
+			}
+		}
+	} else {
+		// Template string — generate representative paths and test against patterns
+		const representatives = generateRepresentatives(path, edges);
+		for (const pr of patterns) {
+			for (const rep of representatives) {
+				const params = matchPattern(pr.compiled, rep);
+				if (params) {
+					const resolved = interpolateDestination(pr.destination, params);
+					return { destination: resolved, id: pr.id };
+				}
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Build an adjacency map from redirect edges.
+ * Includes both exact and pattern redirects — pattern redirects use their
+ * template strings as literal graph edges, which works because EmDash
+ * patterns pass parameters through without transformation.
+ */
+function buildGraph(edges: RedirectEdge[]): Map<string, { destination: string; id: string }> {
+	const graph = new Map<string, { destination: string; id: string }>();
+	for (const edge of edges) {
+		if (edge.enabled) {
+			graph.set(edge.source, { destination: edge.destination, id: edge.id });
+		}
+	}
+	return graph;
+}
+
+/**
+ * Detect all redirect IDs that participate in cycles.
+ * Walks every node in the graph once, collecting IDs from any cycles found.
+ *
+ * @returns Array of redirect IDs that are part of a loop
+ */
+export function detectLoops(edges: RedirectEdge[]): string[] {
+	const graph = buildGraph(edges);
+	const patterns = compilePatterns(edges);
+	const visited = new Set<string>();
+	const loopRedirectIds = new Set<string>();
+
+	for (const [startSource] of graph) {
+		if (visited.has(startSource)) continue;
+
+		const path: string[] = [];
+		const pathSet = new Set<string>();
+		const pathIds: string[] = [];
+		let current: string | undefined = startSource;
+
+		while (current) {
+			if (pathSet.has(current)) {
+				// Found a cycle — collect IDs of redirects in the loop
+				const loopStart = path.indexOf(current);
+				for (const id of pathIds.slice(loopStart)) loopRedirectIds.add(id);
+				break;
+			}
+
+			if (visited.has(current)) {
+				break;
+			}
+
+			const next = resolveNext(current, graph, patterns, edges);
+			if (!next) break;
+
+			path.push(current);
+			pathSet.add(current);
+			pathIds.push(next.id);
+			current = next.destination;
+		}
+
+		for (const node of path) visited.add(node);
+	}
+
+	return [...loopRedirectIds];
+}
+
+/**
+ * Find a compiled pattern redirect whose source matches the given resolved path,
+ * returning the source template string for display purposes.
+ */
+function findMatchingTemplate(
+	resolvedPath: string,
+	patterns: CompiledPatternRedirect[],
+): string | null {
+	for (const pr of patterns) {
+		if (matchPattern(pr.compiled, resolvedPath) !== null) {
+			return pr.compiled.source;
+		}
+	}
+	return null;
+}
+
+/**
+ * Check if adding or updating a redirect would create a loop.
+ *
+ * Walks the chain from `destination` through existing redirects.
+ * If it reaches `source`, a cycle would form.
+ *
+ * @returns The loop path if a cycle would be created, or null if safe
+ */
+export function wouldCreateLoop(
+	source: string,
+	destination: string,
+	existingEdges: RedirectEdge[],
+	excludeId?: string,
+): string[] | null {
+	const filtered = excludeId ? existingEdges.filter((e) => e.id !== excludeId) : existingEdges;
+	const graph = buildGraph(filtered);
+	const patterns = compilePatterns(filtered);
+
+	// If the proposed source is a pattern, compile it so we can check
+	// whether resolved paths would match it (not just string equality)
+	const sourceIsPattern = source.includes("[");
+	const compiledSource = sourceIsPattern ? compilePattern(source) : null;
+
+	// Determine starting points for the walk. If the destination is a
+	// template, generate representative concrete paths AND find existing
+	// exact sources in the graph that match the template.
+	let startingPoints: string[];
+	if (destination.includes("[")) {
+		const reps = generateRepresentatives(destination, filtered);
+		// Also find existing exact graph keys that match this template
+		const compiled = compilePattern(destination);
+		for (const [key] of graph) {
+			if (!key.includes("[") && matchPattern(compiled, key) !== null) {
+				reps.push(key);
+			}
+		}
+		// Always include the destination itself — it may be an exact graph key
+		// (e.g., /a/sub/[...path] exists as a literal source in the graph)
+		reps.push(destination);
+		startingPoints = reps;
+	} else {
+		startingPoints = [destination];
+	}
+
+	for (const start of startingPoints) {
+		const path = [source, destination];
+		let current = start;
+		const seen = new Set<string>([source, destination, start]);
+
+		// Walk the chain until it ends or we revisit a node
+		// eslint-disable-next-line no-constant-condition -- terminates via return/break when chain ends or cycle found
+		while (true) {
+			const next = resolveNext(current, graph, patterns, filtered);
+			if (!next) break; // chain ends, try next starting point
+
+			// Check if we've looped back — either exact match or pattern match
+			const loopsBack =
+				seen.has(next.destination) ||
+				(compiledSource !== null && matchPattern(compiledSource, next.destination) !== null);
+
+			if (loopsBack) {
+				// Show the source template instead of dummy resolved path
+				const displayPath =
+					!seen.has(next.destination) && compiledSource !== null ? source : next.destination;
+				path.push(displayPath);
+				return path; // cycle found
+			}
+
+			// If the resolved path contains dummy segments, try to find the
+			// original pattern template that produced it for cleaner display
+			const cleanDest = next.destination.includes(DUMMY_SEGMENT)
+				? (findMatchingTemplate(next.destination, patterns) ?? next.destination)
+				: next.destination;
+			path.push(cleanDest);
+			seen.add(next.destination);
+			current = next.destination;
+		}
+	}
+
+	return null;
+}

package/src/schema/registry.ts

@@ -6,6 +6,7 @@ import { ulid } from "ulidx";
 import { currentTimestamp, listTablesLike, tableExists } from "../database/dialect-helpers.js";
 import { withTransaction } from "../database/transaction.js";
 import type { CollectionTable, Database, FieldTable } from "../database/types.js";
+import { validateIdentifier } from "../database/validate.js";
 import { FTSManager } from "../search/fts-manager.js";
 import {
 	type Collection,
@@ -684,6 +685,7 @@ export class SchemaRegistry {
 	 * Get table name for a collection
 	 */
 	private getTableName(slug: string): string {
+		validateIdentifier(slug, "collection slug");
 		return `ec_${slug}`;
 	}
 
@@ -691,6 +693,7 @@ export class SchemaRegistry {
 	 * Get column name for a field
 	 */
 	private getColumnName(slug: string): string {
+		validateIdentifier(slug, "field slug");
 		return slug;
 	}
 

package/src/search/fts-manager.ts

@@ -39,6 +39,7 @@ export class FTSManager {
 	 * Uses _emdash_ prefix to clearly mark as internal/system table
 	 */
 	getFtsTableName(collectionSlug: string): string {
+		validateIdentifier(collectionSlug, "collection slug");
 		return `_emdash_fts_${collectionSlug}`;
 	}
 
@@ -46,6 +47,7 @@ export class FTSManager {
 	 * Get the content table name for a collection
 	 */
 	getContentTableName(collectionSlug: string): string {
+		validateIdentifier(collectionSlug, "collection slug");
 		return `ec_${collectionSlug}`;
 	}
 
@@ -101,6 +103,7 @@ export class FTSManager {
 	 * Create triggers to keep FTS table in sync with content table
 	 */
 	private async createTriggers(collectionSlug: string, searchableFields: string[]): Promise<void> {
+		this.validateInputs(collectionSlug, searchableFields);
 		const ftsTable = this.getFtsTableName(collectionSlug);
 		const contentTable = this.getContentTableName(collectionSlug);
 		const fieldList = searchableFields.join(", ");
@@ -147,6 +150,7 @@ export class FTSManager {
 	 * Drop triggers for a collection
 	 */
 	private async dropTriggers(collectionSlug: string): Promise<void> {
+		this.validateInputs(collectionSlug);
 		const ftsTable = this.getFtsTableName(collectionSlug);
 
 		await sql.raw(`DROP TRIGGER IF EXISTS "${ftsTable}_insert"`).execute(this.db);

package/src/storage/s3.ts

@@ -15,6 +15,7 @@ import {
 	type ListObjectsV2Response,
 } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { z } from "zod";
 
 import type {
 	Storage,
@@ -28,6 +29,87 @@ import type {
 } from "./types.js";
 import { EmDashStorageError } from "./types.js";
 
+const ENV_KEYS = {
+	endpoint: "S3_ENDPOINT",
+	bucket: "S3_BUCKET",
+	accessKeyId: "S3_ACCESS_KEY_ID",
+	secretAccessKey: "S3_SECRET_ACCESS_KEY",
+	region: "S3_REGION",
+	publicUrl: "S3_PUBLIC_URL",
+} as const satisfies Record<keyof S3StorageConfig, string>;
+
+function fail(msg: string): never {
+	throw new EmDashStorageError(msg, "MISSING_S3_CONFIG");
+}
+
+const s3ConfigSchema = z.object({
+	endpoint: z.url({ protocol: /^https?$/, error: "is not a valid http/https URL" }).optional(),
+	bucket: z.string().optional(),
+	accessKeyId: z.string().optional(),
+	secretAccessKey: z.string().optional(),
+	region: z.string().optional(),
+	publicUrl: z.string().optional(),
+});
+
+function isConfigKey(key: unknown): key is keyof S3StorageConfig {
+	return typeof key === "string" && key in ENV_KEYS;
+}
+
+/**
+ * Build the merged config: for each field, use the explicit value if present,
+ * otherwise fall back to the corresponding S3_* env var.  Validate once on the
+ * final merged result so a malformed env var never breaks the build when the
+ * caller provides that field explicitly.
+ */
+export function resolveS3Config(partial: Record<string, unknown>): S3StorageConfig {
+	const raw: Record<string, unknown> = {};
+	for (const [field, envKey] of Object.entries(ENV_KEYS)) {
+		const explicit = partial[field];
+		if (explicit !== undefined && explicit !== "") {
+			raw[field] = explicit;
+			continue;
+		}
+		const envVal = typeof process !== "undefined" && process.env ? process.env[envKey] : undefined;
+		if (envVal !== undefined && envVal !== "") {
+			raw[field] = envVal;
+		}
+	}
+
+	const result = s3ConfigSchema.safeParse(raw);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		const pathKey = issue?.path[0];
+		if (!issue || !isConfigKey(pathKey)) fail("S3 config validation failed");
+		const fromExplicit = partial[pathKey] !== undefined && partial[pathKey] !== "";
+		const label = fromExplicit ? `s3({ ${pathKey} })` : ENV_KEYS[pathKey];
+		fail(`${label} ${issue.message}`);
+	}
+	const merged = result.data;
+
+	const endpoint = merged.endpoint;
+	const bucket = merged.bucket;
+	if (!endpoint || !bucket) {
+		const missing: string[] = [];
+		if (!endpoint) missing.push(`endpoint: set ${ENV_KEYS.endpoint} or pass endpoint to s3({...})`);
+		if (!bucket) missing.push(`bucket: set ${ENV_KEYS.bucket} or pass bucket to s3({...})`);
+		fail(`missing required S3 config: ${missing.join("; ")}`);
+	}
+	const accessKeyId = merged.accessKeyId;
+	const secretAccessKey = merged.secretAccessKey;
+	if (accessKeyId && !secretAccessKey) {
+		fail(
+			`S3 credentials incomplete: accessKeyId is set but secretAccessKey is missing (set ${ENV_KEYS.secretAccessKey} or pass secretAccessKey to s3({...}))`,
+		);
+	}
+	if (secretAccessKey && !accessKeyId) {
+		fail(
+			`S3 credentials incomplete: secretAccessKey is set but accessKeyId is missing (set ${ENV_KEYS.accessKeyId} or pass accessKeyId to s3({...}))`,
+		);
+	}
+
+	return { ...merged, endpoint, bucket };
+}
+
 const TRAILING_SLASH_PATTERN = /\/$/;
 
 /** Type guard for AWS SDK errors (have a `name` property) */
@@ -52,13 +134,17 @@ export class S3Storage implements Storage {
 		this.client = new S3Client({
 			endpoint: config.endpoint,
 			region: config.region || "auto",
-			credentials: {
-				accessKeyId: config.accessKeyId,
-				secretAccessKey: config.secretAccessKey,
-			},
+			...(config.accessKeyId && config.secretAccessKey
+				? {
+						credentials: {
+							accessKeyId: config.accessKeyId,
+							secretAccessKey: config.secretAccessKey,
+						},
+					}
+				: {}),
 			// Required for R2 and some S3-compatible services
 			forcePathStyle: true,
-		});
+		} as ConstructorParameters<typeof S3Client>[0]);
 	}
 
 	async upload(options: {
@@ -238,26 +324,9 @@ export class S3Storage implements Storage {
 
 /**
  * Create S3 storage adapter
- * This is the factory function called at runtime
+ * This is the factory function called at runtime.
+ * Config fields are merged with S3_* env vars; env vars fill in any missing fields.
  */
 export function createStorage(config: Record<string, unknown>): Storage {
-	const { endpoint, bucket, accessKeyId, secretAccessKey, region, publicUrl } = config;
-	if (
-		typeof endpoint !== "string" ||
-		typeof bucket !== "string" ||
-		typeof accessKeyId !== "string" ||
-		typeof secretAccessKey !== "string"
-	) {
-		throw new Error(
-			"S3Storage requires 'endpoint', 'bucket', 'accessKeyId', and 'secretAccessKey' string config values",
-		);
-	}
-	return new S3Storage({
-		endpoint,
-		bucket,
-		accessKeyId,
-		secretAccessKey,
-		region: typeof region === "string" ? region : undefined,
-		publicUrl: typeof publicUrl === "string" ? publicUrl : undefined,
-	});
+	return new S3Storage(resolveS3Config(config));
 }