emdash 0.5.0 → 0.7.0

package/src/astro/routes/api/oauth/register.ts

@@ -0,0 +1,178 @@
+/**
+ * POST /_emdash/api/oauth/register
+ *
+ * RFC 7591 Dynamic Client Registration. Public, unauthenticated.
+ * MCP clients (e.g. Claude Code) call this to register themselves
+ * before starting the OAuth authorization flow.
+ */
+
+import type { APIRoute } from "astro";
+
+import { apiError, handleError } from "#api/error.js";
+import { handleOAuthClientCreate } from "#api/handlers/oauth-clients.js";
+
+export const prerender = false;
+
+const OAUTH_REGISTRATION_HEADERS: HeadersInit = {
+	"Cache-Control": "no-store",
+	Pragma: "no-cache",
+	// RFC 7591 dynamic client registration is called cross-origin by MCP clients,
+	// CLIs, and native apps. The endpoint is anonymous and carries no ambient
+	// credentials, so CORS `*` is safe.
+	"Access-Control-Allow-Origin": "*",
+};
+
+const OAUTH_PREFLIGHT_HEADERS: HeadersInit = {
+	"Access-Control-Allow-Origin": "*",
+	"Access-Control-Allow-Methods": "POST, OPTIONS",
+	"Access-Control-Allow-Headers": "Content-Type",
+	"Access-Control-Max-Age": "86400",
+};
+
+const SUPPORTED_GRANT_TYPES = new Set([
+	"authorization_code",
+	"refresh_token",
+	"urn:ietf:params:oauth:grant-type:device_code",
+]);
+const SUPPORTED_RESPONSE_TYPES = new Set(["code"]);
+
+function registrationError(description: string, status = 400): Response {
+	return Response.json(
+		{
+			error: "invalid_client_metadata",
+			error_description: description,
+		},
+		{ status, headers: OAUTH_REGISTRATION_HEADERS },
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function parseScope(value: unknown): string[] | Response | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "string") {
+		const scopes = value.split(" ").filter(Boolean);
+		return scopes.length > 0 ? scopes : undefined;
+	}
+	if (isStringArray(value)) {
+		const scopes = value.filter(Boolean);
+		return scopes.length > 0 ? scopes : undefined;
+	}
+	return registrationError("scope must be a string or array of strings");
+}
+
+function parseSupportedStringArray(
+	value: unknown,
+	field: string,
+	supported: ReadonlySet<string>,
+): string[] | Response | undefined {
+	if (value === undefined) return undefined;
+	if (!isStringArray(value)) {
+		return registrationError(`${field} must be an array of strings`);
+	}
+	const invalidValue = value.find((item) => !supported.has(item));
+	if (invalidValue) {
+		return registrationError(`${field} contains unsupported value: ${invalidValue}`);
+	}
+	return value;
+}
+
+export const OPTIONS: APIRoute = () => {
+	return new Response(null, { status: 204, headers: OAUTH_PREFLIGHT_HEADERS });
+};
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const { emdash } = locals;
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	try {
+		let body: unknown;
+		try {
+			body = await request.json();
+		} catch {
+			return registrationError("Request body must be valid JSON");
+		}
+
+		if (!isRecord(body)) {
+			return registrationError("Request body must be a JSON object");
+		}
+
+		// redirect_uris is the only required field per RFC 7591 §2
+		if (!isStringArray(body.redirect_uris) || body.redirect_uris.length === 0) {
+			return registrationError("redirect_uris must be a non-empty array of strings");
+		}
+
+		if (
+			body.token_endpoint_auth_method !== undefined &&
+			body.token_endpoint_auth_method !== "none"
+		) {
+			return registrationError("Only token_endpoint_auth_method=none is supported");
+		}
+
+		const grantTypes = parseSupportedStringArray(
+			body.grant_types,
+			"grant_types",
+			SUPPORTED_GRANT_TYPES,
+		);
+		if (grantTypes instanceof Response) {
+			return grantTypes;
+		}
+
+		const responseTypes = parseSupportedStringArray(
+			body.response_types,
+			"response_types",
+			SUPPORTED_RESPONSE_TYPES,
+		);
+		if (responseTypes instanceof Response) {
+			return responseTypes;
+		}
+
+		const scopes = parseScope(body.scope);
+		if (scopes instanceof Response) {
+			return scopes;
+		}
+
+		const clientId = crypto.randomUUID();
+		const clientName =
+			typeof body.client_name === "string" && body.client_name
+				? body.client_name
+				: `dynamic-${clientId.slice(0, 8)}`;
+
+		const result = await handleOAuthClientCreate(emdash.db, {
+			id: clientId,
+			name: clientName,
+			redirectUris: body.redirect_uris,
+			scopes,
+		});
+
+		if (!result.success) {
+			return registrationError(result.error.message);
+		}
+
+		// RFC 7591 §3.2.1 response
+		return Response.json(
+			{
+				client_id: result.data.id,
+				client_id_issued_at: Math.floor(new Date(result.data.createdAt).getTime() / 1000),
+				redirect_uris: result.data.redirectUris,
+				client_name: result.data.name,
+				grant_types: grantTypes ?? ["authorization_code", "refresh_token"],
+				response_types: responseTypes ?? ["code"],
+				token_endpoint_auth_method: "none",
+				scope: result.data.scopes ? result.data.scopes.join(" ") : undefined,
+			},
+			{ status: 201, headers: OAUTH_REGISTRATION_HEADERS },
+		);
+	} catch (error) {
+		return handleError(error, "Failed to register OAuth client", "CLIENT_REGISTER_ERROR");
+	}
+};

package/src/astro/routes/api/oauth/token.ts

@@ -87,6 +87,10 @@ const refreshSchema = z.object({
 // Handler
 // ---------------------------------------------------------------------------
 
+export const OPTIONS: APIRoute = () => {
+	return new Response(null, { status: 204, headers: OAUTH_PREFLIGHT_HEADERS });
+};
+
 export const POST: APIRoute = async ({ request, locals }) => {
 	const { emdash } = locals;
 
@@ -166,6 +170,17 @@ const OAUTH_TOKEN_HEADERS: HeadersInit = {
 	"Content-Type": "application/json",
 	"Cache-Control": "no-store",
 	Pragma: "no-cache",
+	// OAuth 2.1 token endpoint is called cross-origin by external clients. Caller
+	// must present PKCE code_verifier / device_code / refresh_token on each request,
+	// so there is no ambient credential for CSRF to exploit.
+	"Access-Control-Allow-Origin": "*",
+};
+
+const OAUTH_PREFLIGHT_HEADERS: HeadersInit = {
+	"Access-Control-Allow-Origin": "*",
+	"Access-Control-Allow-Methods": "POST, OPTIONS",
+	"Access-Control-Allow-Headers": "Content-Type",
+	"Access-Control-Max-Age": "86400",
 };
 
 function oauthSuccess(data: unknown): Response {

package/src/astro/routes/api/openapi.json.ts

@@ -15,13 +15,23 @@ export const prerender = false;
 
 let cachedSpec: string | null = null;
 
-export const GET: APIRoute = async () => {
-	if (!cachedSpec) {
-		const doc = generateOpenApiDocument();
-		cachedSpec = JSON.stringify(doc);
+export const GET: APIRoute = async ({ locals }) => {
+	const { emdash } = locals;
+	if (!cachedSpec && emdash) {
+		try {
+			const doc = generateOpenApiDocument({ maxUploadSize: emdash.config.maxUploadSize });
+			cachedSpec = JSON.stringify(doc);
+		} catch {
+			return new Response(
+				JSON.stringify({ error: "Failed to generate OpenAPI document: invalid configuration" }),
+				{ status: 500, headers: { "Content-Type": "application/json" } },
+			);
+		}
 	}
 
-	return new Response(cachedSpec, {
+	const spec = cachedSpec ?? JSON.stringify(generateOpenApiDocument());
+
+	return new Response(spec, {
 		status: 200,
 		headers: {
 			"Content-Type": "application/json",

package/src/astro/routes/api/schema/collections/[slug]/fields/[fieldSlug].ts

@@ -57,6 +57,7 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 		fieldSlug,
 		body as UpdateFieldInput,
 	);
+	if (result.success) emdash!.invalidateManifest();
 	return unwrapResult(result);
 };
 
@@ -72,5 +73,6 @@ export const DELETE: APIRoute = async ({ params, locals }) => {
 	if (denied) return denied;
 
 	const result = await handleSchemaFieldDelete(emdash!.db, collectionSlug, fieldSlug);
+	if (result.success) emdash!.invalidateManifest();
 	return unwrapResult(result);
 };

package/src/astro/routes/api/schema/collections/[slug]/fields/index.ts

@@ -48,5 +48,6 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		collectionSlug,
 		body as CreateFieldInput,
 	);
+	if (result.success) emdash!.invalidateManifest();
 	return unwrapResult(result, 201);
 };

package/src/astro/routes/api/schema/collections/[slug]/fields/reorder.ts

@@ -28,5 +28,6 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 	if (isParseError(body)) return body;
 
 	const result = await handleSchemaFieldReorder(emdash!.db, collectionSlug, body.fieldSlugs);
+	if (result.success) emdash!.invalidateManifest();
 	return unwrapResult(result);
 };

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

@@ -37,6 +37,11 @@ export const GET: APIRoute = async ({ url, locals }) => {
 		: undefined;
 
 	try {
+		// Verify FTS indexes are healthy on first use. At most once per worker
+		// lifetime; no-op after that. Moved off the cold-start hot path to
+		// keep anonymous public reads fast.
+		await emdash.ensureSearchHealthy?.();
+
 		const result = await searchWithDb(emdash.db, query.q, {
 			collections,
 			status: query.status,

package/src/astro/routes/api/search/suggest.ts

@@ -36,6 +36,9 @@ export const GET: APIRoute = async ({ url, locals }) => {
 		: undefined;
 
 	try {
+		// Verify FTS indexes are healthy on first use. See search/index.ts.
+		await emdash.ensureSearchHealthy?.();
+
 		const suggestions = await getSuggestions(emdash.db, query.q, {
 			collections,
 			locale: query.locale,

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

@@ -8,7 +8,7 @@ import type { APIRoute } from "astro";
 
 export const prerender = false;
 
-import { Role } from "@emdash-cms/auth";
+import { Role, secureCompare } from "@emdash-cms/auth";
 import { createKyselyAdapter } from "@emdash-cms/auth/adapters/kysely";
 import { verifyRegistrationResponse, registerPasskey } from "@emdash-cms/auth/passkey";
 
@@ -18,9 +18,10 @@ import { getPublicOrigin } from "#api/public-url.js";
 import { setupAdminVerifyBody } from "#api/schemas.js";
 import { createChallengeStore } from "#auth/challenge-store.js";
 import { getPasskeyConfig } from "#auth/passkey-config.js";
+import { SETUP_NONCE_COOKIE } 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) {
@@ -45,12 +46,35 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		}
 
 		// Get setup state
-		const setupState = await options.get("emdash:setup_state");
+		const setupState = await options.get<{
+			step?: string;
+			email?: string;
+			name?: string | null;
+			nonce?: string;
+		}>("emdash:setup_state");
 
 		if (!setupState || setupState.step !== "admin") {
 			return apiError("INVALID_STATE", "Invalid setup state. Please restart setup.", 400);
 		}
 
+		// Verify the session nonce. The cookie was minted by POST /setup/admin
+		// and stored alongside setup_state; presenting a matching cookie is
+		// proof that this verify call comes from the same browser that
+		// started the admin step. Constant-time compare to avoid leaking the
+		// stored value through timing.
+		const cookieNonce = cookies.get(SETUP_NONCE_COOKIE)?.value;
+		if (!setupState.nonce || !cookieNonce || !secureCompare(cookieNonce, setupState.nonce)) {
+			return apiError(
+				"INVALID_STATE",
+				"Setup session expired or tampered with. Please restart the admin step.",
+				400,
+			);
+		}
+
+		if (!setupState.email) {
+			return apiError("INVALID_STATE", "Invalid setup state. Please restart setup.", 400);
+		}
+
 		// Parse request body
 		const body = await parseBody(request, setupAdminVerifyBody);
 		if (isParseError(body)) return body;
@@ -73,7 +97,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		// Create the admin user
 		const user = await adapter.createUser({
 			email: setupState.email,
-			name: setupState.name,
+			name: setupState.name ?? null,
 			role: Role.ADMIN,
 			emailVerified: false, // No email verification for first user
 		});
@@ -84,8 +108,9 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		// Mark setup as complete
 		await options.set("emdash:setup_complete", true);
 
-		// Clean up setup state
+		// Clean up setup state and the session nonce cookie
 		await options.delete("emdash:setup_state");
+		cookies.delete(SETUP_NONCE_COOKIE, { path: "/_emdash/" });
 
 		return apiSuccess({
 			success: true,

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,13 @@ 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,
-		});
+		// 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 +81,33 @@ 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. The verify
+		// endpoint will constant-time compare this with the incoming cookie.
 		await options.set("emdash:setup_state", {
 			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

@@ -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

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

@@ -52,6 +52,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		if (isParseError(body)) return body;
 
 		const result = await handleTaxonomyCreate(emdash.db, body);
+		if (result.success) emdash.invalidateManifest();
 		return unwrapResult(result, 201);
 	} catch (error) {
 		return handleError(error, "Failed to create taxonomy", "TAXONOMY_CREATE_ERROR");

package/src/astro/routes/api/well-known/oauth-authorization-server.ts

@@ -33,8 +33,8 @@ export const GET: APIRoute = async ({ url, locals }) => {
 				"urn:ietf:params:oauth:grant-type:device_code",
 			],
 			code_challenge_methods_supported: ["S256"],
+			registration_endpoint: `${origin}/_emdash/api/oauth/register`,
 			token_endpoint_auth_methods_supported: ["none"],
-			client_id_metadata_document_supported: true,
 			device_authorization_endpoint: `${origin}/_emdash/api/oauth/device/code`,
 		},
 		{

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

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;