emdash 0.6.0 → 1.0.0

package/src/astro/routes/api/setup/admin.ts

@@ -8,6 +8,7 @@ import type { APIRoute } from "astro";
 
 export const prerender = false;
 
+import { generateToken } from "@emdash-cms/auth";
 import { createKyselyAdapter } from "@emdash-cms/auth/adapters/kysely";
 import { generateRegistrationOptions } from "@emdash-cms/auth/passkey";
 
@@ -17,9 +18,10 @@ import { getPublicOrigin } from "#api/public-url.js";
 import { setupAdminBody } from "#api/schemas.js";
 import { createChallengeStore } from "#auth/challenge-store.js";
 import { getPasskeyConfig } from "#auth/passkey-config.js";
+import { SETUP_NONCE_COOKIE, SETUP_NONCE_MAX_AGE_SECONDS } from "#auth/setup-nonce.js";
 import { OptionsRepository } from "#db/repositories/options.js";
 
-export const POST: APIRoute = async ({ request, locals }) => {
+export const POST: APIRoute = async ({ cookies, request, locals }) => {
 	const { emdash } = locals;
 
 	if (!emdash?.db) {
@@ -47,12 +49,17 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		const body = await parseBody(request, setupAdminBody);
 		if (isParseError(body)) return body;
 
-		// Store admin info in setup state for later
-		await options.set("emdash:setup_state", {
-			step: "admin",
-			email: body.email.toLowerCase(),
-			name: body.name || null,
-		});
+		// Preserve title/tagline from step 1 by reading existing setup state
+		// before we overwrite it below.
+		const existingState = await options.get<Record<string, unknown>>("emdash:setup_state");
+
+		// Mint a fresh session nonce. This binds the follow-up
+		// /setup/admin/verify call to the same browser that made this
+		// request, so an unauthenticated attacker on another host cannot
+		// substitute their own email into the setup state during the
+		// setup window. Rotates on every call so a legitimate retry
+		// always gets a working session.
+		const nonce = generateToken();
 
 		// Get passkey config
 		const url = new URL(request.url);
@@ -78,12 +85,35 @@ export const POST: APIRoute = async ({ request, locals }) => {
 			challengeStore,
 		);
 
-		// Store the temp user ID with the setup state
+		// Store the nonce alongside the rest of the setup state, preserving
+		// title/tagline from step 1. The verify endpoint will constant-time
+		// compare the nonce with the incoming cookie.
 		await options.set("emdash:setup_state", {
+			...existingState,
 			step: "admin",
 			email: body.email.toLowerCase(),
 			name: body.name || null,
 			tempUserId: tempUser.id,
+			nonce,
+		});
+
+		// HttpOnly + SameSite=Strict + path-scoped. The cookie must not be
+		// accessible to JS (nothing in the admin UI needs to read it) and
+		// must not be sent on cross-site navigations. The /_emdash/ path
+		// scope keeps it away from user-authored frontend code.
+		//
+		// Derive `secure` from the public origin, not the internal request
+		// URL. Behind a TLS-terminating reverse proxy the internal hop is
+		// often `http:` while the browser-facing origin is `https:` —
+		// using `url.protocol` there would drop the Secure flag on a
+		// sensitive cookie over the public HTTPS connection.
+		const publicOrigin = new URL(siteUrl);
+		cookies.set(SETUP_NONCE_COOKIE, nonce, {
+			path: "/_emdash/",
+			httpOnly: true,
+			sameSite: "strict",
+			secure: publicOrigin.protocol === "https:",
+			maxAge: SETUP_NONCE_MAX_AGE_SECONDS,
 		});
 
 		return apiSuccess({

package/src/astro/routes/api/setup/index.ts

@@ -81,7 +81,7 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 
 		// 5. Store setup state
 		// In external auth mode, mark setup complete immediately (first user to login becomes admin)
-		// In passkey mode, setup_complete is set after admin user is created
+		// Otherwise, setup_complete is set after admin user is created (passkey or auth provider)
 		const authMode = getAuthMode(emdash.config);
 		const useExternalAuth = authMode.type === "external";
 
@@ -89,9 +89,12 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 			const options = new OptionsRepository(emdash.db);
 
 			// Store the canonical site URL from the setup request.
-			// This is trusted because setup runs on the real domain.
+			// Write-once at the DB level so concurrent setup POSTs can't both
+			// observe an empty value and race to write. A spoofed Host header
+			// on a later call during the wizard window must not be able to
+			// replace the first value.
 			const siteUrl = getPublicOrigin(url, emdash.config);
-			await options.set("emdash:site_url", siteUrl);
+			await options.setIfAbsent("emdash:site_url", siteUrl);
 
 			if (useExternalAuth) {
 				// External auth mode: mark setup complete now
@@ -102,7 +105,7 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 					await options.set("emdash:site_tagline", body.tagline);
 				}
 			} else {
-				// Passkey mode: store state for next step (admin creation)
+				// Passkey/provider mode: store state for next step (admin creation)
 				await options.set("emdash:setup_state", {
 					step: "site_complete",
 					title: body.title,

package/src/astro/routes/api/setup/status.ts

@@ -91,7 +91,7 @@ export const GET: APIRoute = async ({ locals }) => {
 		const authMode = getAuthMode(emdash.config);
 		const useExternalAuth = authMode.type === "external";
 
-		// In external auth mode, setup is complete if flag is set (no users required initially)
+		// In external auth mode (not atproto), setup is complete if flag is set (no users required initially)
 		if (useExternalAuth && isComplete) {
 			return apiSuccess({
 				needsSetup: false,
@@ -106,6 +106,8 @@ export const GET: APIRoute = async ({ locals }) => {
 					description: seed.meta?.description || "",
 					collections: seed.collections?.length || 0,
 					hasContent: !!(seed.content && Object.keys(seed.content).length > 0),
+					title: seed.settings?.title,
+					tagline: seed.settings?.tagline,
 				}
 			: null;
 

package/src/astro/routes/api/widget-areas/[name]/widgets/[id].ts

@@ -11,6 +11,8 @@ import { requirePerm } from "#api/authorize.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { updateWidgetBody } from "#api/schemas.js";
+import { rowToWidget } from "#widgets/index.js";
+import type { WidgetRow } from "#widgets/types.js";
 
 export const prerender = false;
 
@@ -73,10 +75,11 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 		const widget = await db
 			.selectFrom("_emdash_widgets")
 			.selectAll()
+			.$castTo<WidgetRow>()
 			.where("id", "=", id)
 			.executeTakeFirstOrThrow();
 
-		return apiSuccess(widget);
+		return apiSuccess(rowToWidget(widget));
 	} catch (error) {
 		return handleError(error, "Failed to update widget", "WIDGET_UPDATE_ERROR");
 	}

package/src/astro/routes/api/widget-areas/[name]/widgets.ts

@@ -11,6 +11,8 @@ import { requirePerm } from "#api/authorize.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { createWidgetBody } from "#api/schemas.js";
+import { rowToWidget } from "#widgets/index.js";
+import type { WidgetRow } from "#widgets/types.js";
 
 export const prerender = false;
 
@@ -70,10 +72,11 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		const widget = await db
 			.selectFrom("_emdash_widgets")
 			.selectAll()
+			.$castTo<WidgetRow>()
 			.where("id", "=", id)
 			.executeTakeFirstOrThrow();
 
-		return apiSuccess(widget, 201);
+		return apiSuccess(rowToWidget(widget), 201);
 	} catch (error) {
 		return handleError(error, "Failed to create widget", "WIDGET_CREATE_ERROR");
 	}

package/src/astro/routes/api/widget-areas/[name].ts

@@ -9,6 +9,8 @@ import type { APIRoute } from "astro";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
+import { rowToWidget } from "#widgets/index.js";
+import type { WidgetRow } from "#widgets/types.js";
 
 export const prerender = false;
 
@@ -40,13 +42,14 @@ export const GET: APIRoute = async ({ params, locals }) => {
 		const widgets = await db
 			.selectFrom("_emdash_widgets")
 			.selectAll()
+			.$castTo<WidgetRow>()
 			.where("area_id", "=", area.id)
 			.orderBy("sort_order", "asc")
 			.execute();
 
 		return apiSuccess({
 			...area,
-			widgets,
+			widgets: widgets.map((row) => rowToWidget(row)),
 		});
 	} catch (error) {
 		return handleError(error, "Failed to fetch widget area", "WIDGET_AREA_GET_ERROR");

package/src/astro/routes/api/widget-areas/index.ts

@@ -12,6 +12,8 @@ import { requirePerm } from "#api/authorize.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { createWidgetAreaBody } from "#api/schemas.js";
+import { rowToWidget } from "#widgets/index.js";
+import type { WidgetRow } from "#widgets/types.js";
 
 export const prerender = false;
 
@@ -35,13 +37,14 @@ export const GET: APIRoute = async ({ locals }) => {
 				const widgets = await db
 					.selectFrom("_emdash_widgets")
 					.selectAll()
+					.$castTo<WidgetRow>()
 					.where("area_id", "=", area.id)
 					.orderBy("sort_order", "asc")
 					.execute();
 
 				return {
 					...area,
-					widgets,
+					widgets: widgets.map((row) => rowToWidget(row)),
 					widgetCount: widgets.length,
 				};
 			}),

package/src/astro/types.ts

@@ -142,6 +142,15 @@ export interface EmDashManifest {
 	 * When true, the admin UI can show marketplace browse/install features.
 	 */
 	marketplace?: boolean;
+	/**
+	 * Admin branding overrides for white-labeling.
+	 * Set via the `admin` config in `astro.config.mjs`.
+	 */
+	admin?: {
+		logo?: string;
+		siteName?: string;
+		favicon?: string;
+	};
 }
 
 /**
@@ -339,6 +348,7 @@ export interface EmDashHandlers {
 	// Direct access to storage and database for advanced use cases
 	storage: import("../index.js").Storage | null;
 	db: Kysely<import("../index.js").Database>;
+	getPublicMediaUrl?: (storageKey: string) => string;
 
 	// Hook pipeline for plugin integrations
 	hooks: import("../plugins/hooks.js").HookPipeline;
@@ -371,4 +381,12 @@ export interface EmDashHandlers {
 	collectPageFragments: (
 		page: import("../plugins/types.js").PublicPageContext,
 	) => Promise<import("../plugins/types.js").PageFragmentContribution[]>;
+
+	/**
+	 * Lazy search index health check. Search routes call this before
+	 * querying so a crash-corrupted index gets repaired on first use
+	 * rather than stalling cold start. Optional because it's only
+	 * meaningful when an FTS5-capable runtime is wired in.
+	 */
+	ensureSearchHealthy?: () => Promise<void>;
 }

package/src/auth/mode.ts

@@ -6,9 +6,21 @@
  */
 
 import type { EmDashConfig } from "../astro/integration/runtime.js";
-import type { AuthDescriptor, AuthResult, ExternalAuthConfig } from "./types.js";
+import type {
+	AuthDescriptor,
+	AuthProviderDescriptor,
+	AuthRouteDescriptor,
+	AuthResult,
+	ExternalAuthConfig,
+} from "./types.js";
 
-export type { AuthDescriptor, AuthResult, ExternalAuthConfig };
+export type {
+	AuthDescriptor,
+	AuthProviderDescriptor,
+	AuthRouteDescriptor,
+	AuthResult,
+	ExternalAuthConfig,
+};
 
 /**
  * Passkey auth mode (default)
@@ -59,7 +71,7 @@ export function getAuthMode(
 ): AuthMode {
 	const auth = config?.auth;
 
-	// Check for AuthDescriptor (new style)
+	// Check for AuthDescriptor (transparent external auth like Cloudflare Access)
 	if (auth && "entrypoint" in auth && auth.entrypoint) {
 		return {
 			type: "external",

package/src/auth/providers/github-admin.tsx

@@ -0,0 +1,29 @@
+/**
+ * GitHub OAuth Admin Components
+ *
+ * LoginButton for the login page, rendered via the auth provider virtual module.
+ */
+
+import { LinkButton } from "@cloudflare/kumo";
+import * as React from "react";
+
+function GitHubIcon({ className }: { className?: string }) {
+	return (
+		<svg className={className} viewBox="0 0 24 24" fill="currentColor">
+			<path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
+		</svg>
+	);
+}
+
+export function LoginButton() {
+	return (
+		<LinkButton
+			href="/_emdash/api/auth/oauth/github"
+			variant="outline"
+			className="w-full justify-center"
+		>
+			<GitHubIcon className="h-5 w-5" />
+			<span>GitHub</span>
+		</LinkButton>
+	);
+}

package/src/auth/providers/github.ts

@@ -0,0 +1,31 @@
+/**
+ * GitHub OAuth Auth Provider
+ *
+ * Returns an AuthProviderDescriptor for GitHub OAuth login.
+ * Credentials are read from environment variables at runtime.
+ *
+ * @example
+ * ```ts
+ * import { github } from "emdash/auth/providers/github";
+ *
+ * emdash({
+ *   authProviders: [github()],
+ * })
+ * ```
+ */
+
+import type { AuthProviderDescriptor } from "../types.js";
+
+/**
+ * Configure GitHub OAuth as an auth provider.
+ *
+ * Requires `EMDASH_OAUTH_GITHUB_CLIENT_ID` and `EMDASH_OAUTH_GITHUB_CLIENT_SECRET`
+ * (or `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`) environment variables.
+ */
+export function github(): AuthProviderDescriptor {
+	return {
+		id: "github",
+		label: "GitHub",
+		adminEntry: "emdash/auth/providers/github-admin",
+	};
+}

package/src/auth/providers/google-admin.tsx

@@ -0,0 +1,44 @@
+/**
+ * Google OAuth Admin Components
+ *
+ * LoginButton for the login page, rendered via the auth provider virtual module.
+ */
+
+import { LinkButton } from "@cloudflare/kumo";
+import * as React from "react";
+
+function GoogleIcon({ className }: { className?: string }) {
+	return (
+		<svg className={className} viewBox="0 0 24 24">
+			<path
+				fill="#4285F4"
+				d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
+			/>
+			<path
+				fill="#34A853"
+				d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
+			/>
+			<path
+				fill="#FBBC05"
+				d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
+			/>
+			<path
+				fill="#EA4335"
+				d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
+			/>
+		</svg>
+	);
+}
+
+export function LoginButton() {
+	return (
+		<LinkButton
+			href="/_emdash/api/auth/oauth/google"
+			variant="outline"
+			className="w-full justify-center"
+		>
+			<GoogleIcon className="h-5 w-5" />
+			<span>Google</span>
+		</LinkButton>
+	);
+}

package/src/auth/providers/google.ts

@@ -0,0 +1,31 @@
+/**
+ * Google OAuth Auth Provider
+ *
+ * Returns an AuthProviderDescriptor for Google OAuth login.
+ * Credentials are read from environment variables at runtime.
+ *
+ * @example
+ * ```ts
+ * import { google } from "emdash/auth/providers/google";
+ *
+ * emdash({
+ *   authProviders: [google()],
+ * })
+ * ```
+ */
+
+import type { AuthProviderDescriptor } from "../types.js";
+
+/**
+ * Configure Google OAuth as an auth provider.
+ *
+ * Requires `EMDASH_OAUTH_GOOGLE_CLIENT_ID` and `EMDASH_OAUTH_GOOGLE_CLIENT_SECRET`
+ * (or `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`) environment variables.
+ */
+export function google(): AuthProviderDescriptor {
+	return {
+		id: "google",
+		label: "Google",
+		adminEntry: "emdash/auth/providers/google-admin",
+	};
+}

package/src/auth/rate-limit.ts

@@ -100,44 +100,72 @@ export function rateLimitResponse(retryAfterSeconds: number): Response {
  *
  * Resolution order:
  * 1. `CF-Connecting-IP` — trusted only when the Cloudflare `cf` object is
- *    present (proving the request traversed Cloudflare's edge, which
- *    strips/overwrites client-supplied values).
- * 2. `X-Forwarded-For` (first entry) — also trusted only on Cloudflare.
- *    Without a trusted reverse proxy the header is trivially spoofable,
- *    so we don't use it for standalone deployments.
- * 3. `null` — no trusted IP available. Callers must handle this gracefully
+ *    present. CF edge overwrites any client-supplied value, so this is the
+ *    cryptographically trustworthy path on Workers. Operator-declared
+ *    trusted headers cannot override it.
+ * 2. `X-Forwarded-For` (first entry) — trusted only when the `cf` object
+ *    is present (CF sets this reliably).
+ * 3. Operator-declared trusted proxy headers (ordered list) — used as a
+ *    fallback for non-CF deployments behind a reverse proxy the operator
+ *    controls. Also applies as a fill-in on CF when the CF headers are
+ *    absent (e.g. internal cron handlers).
+ * 4. `null` — no trusted IP available. Callers must handle this gracefully
  *    (e.g. skip rate limiting).
  *
+ * Pass `trustedHeaders` from `getTrustedProxyHeaders(emdash.config)` so
+ * self-hosted non-CF deployments can opt into reading a specific header.
+ *
  * Aligned with `extractRequestMeta` in `plugins/request-meta.ts`.
  */
-export function getClientIp(request: Request): string | null {
+export function getClientIp(request: Request, trustedHeaders: string[] = []): string | null {
 	const headers = request.headers;
 	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- CF Workers runtime shape
 	const cf = (request as unknown as { cf?: Record<string, unknown> }).cf;
 
-	if (!cf) {
-		// Not on Cloudflare — no trusted source of client IP
-		return null;
-	}
+	// On Cloudflare, prefer the cryptographically trustworthy headers. An
+	// attacker can't spoof these — the CF edge strips/overwrites them.
+	if (cf) {
+		const cfIp = headers.get("cf-connecting-ip")?.trim();
+		if (cfIp && IP_PATTERN.test(cfIp)) {
+			return cfIp;
+		}
 
-	// Trust CF-Connecting-IP when the cf object confirms Cloudflare
-	const cfIp = headers.get("cf-connecting-ip")?.trim();
-	if (cfIp && IP_PATTERN.test(cfIp)) {
-		return cfIp;
+		const xff = headers.get("x-forwarded-for");
+		if (xff) {
+			const first = xff.split(",")[0]?.trim();
+			if (first && IP_PATTERN.test(first)) {
+				return first;
+			}
+		}
 	}
 
-	// Fallback to XFF on Cloudflare (CF sets this reliably)
-	const xff = headers.get("x-forwarded-for");
-	if (xff) {
-		const first = xff.split(",")[0]?.trim();
-		if (first && IP_PATTERN.test(first)) {
-			return first;
-		}
+	// Fall through to operator-declared trusted headers. On CF this fills
+	// in when the CF headers are absent; off-CF it's the primary source.
+	for (const name of trustedHeaders) {
+		const value = readIpFromHeader(headers, name);
+		if (value) return value;
 	}
 
 	return null;
 }
 
+/**
+ * Read an IP from an operator-declared trusted header. XFF-style headers
+ * are parsed as comma-separated lists and the first entry is used.
+ */
+function readIpFromHeader(headers: Headers, name: string): string | null {
+	const value = headers.get(name);
+	if (!value) return null;
+	if (name.toLowerCase().endsWith("forwarded-for")) {
+		const first = value.split(",")[0]?.trim();
+		if (!first) return null;
+		return IP_PATTERN.test(first) ? first : null;
+	}
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	return IP_PATTERN.test(trimmed) ? trimmed : null;
+}
+
 /**
  * Delete expired rate limit entries.
  *

package/src/auth/setup-nonce.ts

@@ -0,0 +1,22 @@
+/**
+ * Session binding for the first-setup admin-creation flow.
+ *
+ * Shared constants for the nonce cookie that ties /_emdash/api/setup/admin
+ * and /_emdash/api/setup/admin/verify to the same browser. Without this
+ * binding, any unauthenticated caller could POST /setup/admin during the
+ * setup window and substitute their own email into the stored setup state
+ * before the legitimate admin completes passkey verification.
+ *
+ * Implementation lives in the two route handlers; this module is just
+ * the name / lifetime so both ends agree.
+ */
+
+/** Cookie name carrying the setup-admin session nonce. */
+export const SETUP_NONCE_COOKIE = "emdash_setup_nonce";
+
+/**
+ * Cookie max-age in seconds. One hour is plenty of time to complete
+ * a passkey registration; if the user lingers longer the admin step
+ * can simply be retried.
+ */
+export const SETUP_NONCE_MAX_AGE_SECONDS = 60 * 60;

package/src/auth/trusted-proxy.ts

@@ -0,0 +1,92 @@
+/**
+ * Resolve the list of client-IP headers the operator trusts.
+ *
+ * Resolution order:
+ *   1. `config.trustedProxyHeaders` — explicit opt-in via astro.config.mjs.
+ *      An empty array is respected (means "trust nothing, ignore env").
+ *   2. `EMDASH_TRUSTED_PROXY_HEADERS` env var — comma-separated header names.
+ *   3. `[]` — default, no trusted headers.
+ *
+ * Operators must only set this when they control the reverse proxy.
+ * Untrusted clients can set any header they like; trusting headers from
+ * an open network defeats rate limiting.
+ *
+ * Header names are returned lowercased because HTTP header lookups are
+ * case-insensitive.
+ */
+
+import type { EmDashConfig } from "../astro/integration/runtime.js";
+
+/**
+ * RFC 7230 token — valid characters for an HTTP header name. Invalid names
+ * passed to `Headers.get()` throw a TypeError at runtime, which would
+ * otherwise surface as a 500 from every auth route.
+ */
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/;
+
+/**
+ * Normalise a list of header names the way both the config path and any
+ * caller passing a pre-resolved list should do: trim, lowercase, drop
+ * empty, drop anything that isn't a valid RFC 7230 token. Invalid names
+ * would crash `Headers.get()` at runtime.
+ */
+export function normalizeTrustedHeaders(names: readonly string[]): string[] {
+	return names
+		.map((h) => h.trim().toLowerCase())
+		.filter((h) => h.length > 0 && HEADER_NAME_PATTERN.test(h));
+}
+
+function isValidHeaderName(name: string): boolean {
+	return HEADER_NAME_PATTERN.test(name);
+}
+
+/** Cache for the env-derived value. `null` means "not yet parsed". */
+let _envCache: string[] | null = null;
+
+/** Test-only: clear the env cache so a fresh value is read on next call. */
+export function _resetTrustedProxyHeadersCache(): void {
+	_envCache = null;
+}
+
+function getEnvTrustedHeaders(): string[] {
+	if (_envCache !== null) return _envCache;
+	let raw: string | undefined;
+	try {
+		// Prefer process.env so SSR/container deployments can override this
+		// value at runtime (Vite/Astro inline import.meta.env at build time,
+		// which locks the value into the bundle). Fall back to import.meta.env
+		// for bundler-managed environments where process.env isn't populated.
+		// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- import.meta.env shape varies by bundler
+		const importMetaEnv = (import.meta as unknown as { env?: Record<string, string | undefined> })
+			.env;
+		raw =
+			(typeof process !== "undefined" ? process.env?.EMDASH_TRUSTED_PROXY_HEADERS : undefined) ||
+			importMetaEnv?.EMDASH_TRUSTED_PROXY_HEADERS;
+	} catch {
+		raw = undefined;
+	}
+	if (!raw) {
+		_envCache = [];
+		return _envCache;
+	}
+	_envCache = raw
+		.split(",")
+		.map((s) => s.trim().toLowerCase())
+		.filter((s) => s.length > 0 && isValidHeaderName(s));
+	return _envCache;
+}
+
+/**
+ * Return the lowercased list of headers to trust for client-IP resolution.
+ *
+ * When `config?.trustedProxyHeaders` is explicitly set (even to `[]`), it
+ * wins. Otherwise fall through to the env var, then to `[]`.
+ */
+export function getTrustedProxyHeaders(config: EmDashConfig | null | undefined): string[] {
+	if (config && config.trustedProxyHeaders !== undefined) {
+		return config.trustedProxyHeaders
+			.map((h) => h.trim().toLowerCase())
+			.filter((h) => h.length > 0 && isValidHeaderName(h));
+	}
+	return getEnvTrustedHeaders();
+}