emdash 0.7.0 → 0.9.0

package/src/auth/allowed-origins.ts

@@ -0,0 +1,168 @@
+/**
+ * Resolution and validation of multi-origin passkey verification.
+ *
+ * `allowedOrigins` lets one EmDash deployment accept passkey assertions from
+ * several hostnames sharing the same `rpId` (e.g. apex + preview/staging
+ * subdomains under one registrable parent). Origins come from two sources:
+ *
+ *   - `EmDashConfig.allowedOrigins` (declared in `astro.config.mjs`)
+ *   - `EMDASH_ALLOWED_ORIGINS` (comma-separated runtime env var)
+ *
+ * Sources are merged (union of permissions, deduplicated). Each entry is
+ * validated against `siteUrl` to fail loud on dead config the browser would
+ * never honor.
+ */
+
+import { getEnvAllowedOrigins } from "../api/public-url.js";
+import type { EmDashConfig } from "../astro/integration/runtime.js";
+
+export type AllowedOriginSource = "config.allowedOrigins" | "EMDASH_ALLOWED_ORIGINS";
+
+export interface TaggedOrigin {
+	/** Raw entry as declared by the operator. */
+	origin: string;
+	/** Where the entry came from (used for source-attributed errors). */
+	source: AllowedOriginSource;
+}
+
+/**
+ * Collect raw allowedOrigins from config and env, source-tagged.
+ *
+ * Returns raw values — the caller is expected to pass the result through
+ * `validateAllowedOrigins()` before use in passkey verification.
+ */
+export function getConfiguredAllowedOrigins(config?: EmDashConfig): TaggedOrigin[] {
+	const tagged: TaggedOrigin[] = [];
+	if (config?.allowedOrigins) {
+		for (const origin of config.allowedOrigins) {
+			if (origin) tagged.push({ origin, source: "config.allowedOrigins" });
+		}
+	}
+	for (const origin of getEnvAllowedOrigins()) {
+		tagged.push({ origin, source: "EMDASH_ALLOWED_ORIGINS" });
+	}
+	return tagged;
+}
+
+/**
+ * Validate per-entry shape rules (no `siteUrl` needed):
+ *   - parses as `URL`
+ *   - protocol is `http:` or `https:`
+ *   - hostname has no trailing dot (`example.com.` rejected)
+ *   - hostname has no empty labels (`foo..example.com` rejected)
+ *
+ * Returns the deduplicated, normalized origin form (`URL.origin`) of every
+ * input, in input order. Throws on the first violation with a source-tagged
+ * error message.
+ */
+export function validateOriginShape(tagged: TaggedOrigin[]): string[] {
+	const normalized: string[] = [];
+	const seen = new Set<string>();
+	for (const { origin, source } of tagged) {
+		let parsed: URL;
+		try {
+			parsed = new URL(origin);
+		} catch (e) {
+			throw configError(source, `invalid URL: "${origin}"`, e);
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+			throw configError(
+				source,
+				`origin must be http or https: "${origin}" (got ${parsed.protocol})`,
+			);
+		}
+		if (parsed.hostname.endsWith(".")) {
+			throw configError(
+				source,
+				`hostname has a trailing dot: "${origin}". Remove the trailing dot — assertion origins from the browser do not include it.`,
+			);
+		}
+		if (parsed.hostname.split(".").includes("")) {
+			throw configError(source, `hostname has empty labels: "${origin}"`);
+		}
+		if (!seen.has(parsed.origin)) {
+			seen.add(parsed.origin);
+			normalized.push(parsed.origin);
+		}
+	}
+	return normalized;
+}
+
+/**
+ * Validate the effective merged allowedOrigins set against `siteUrl`.
+ *
+ * Performs `validateOriginShape()` plus the siteUrl-dependent rules:
+ *   - Rule A: non-empty origins ⇒ `siteUrl` is set
+ *   - `siteUrl` hostname is not an IP literal (multi-origin requires a domain)
+ *   - `siteUrl` hostname has no trailing dot (cannot match assertion origins)
+ *   - Rule B: each origin's hostname is `siteHost` exactly or a subdomain
+ *
+ * Throws on first violation. Returns the deduplicated normalized origins.
+ *
+ * Use this at the runtime chokepoint (where config + env are merged into the
+ * effective set). At Astro integration init, prefer `validateOriginShape()`
+ * for shape-only checks on `config.allowedOrigins`, since `siteUrl` may be
+ * supplied at runtime via `EMDASH_SITE_URL`.
+ */
+export function validateAllowedOrigins(
+	siteUrl: string | undefined,
+	tagged: TaggedOrigin[],
+): string[] {
+	const normalized = validateOriginShape(tagged);
+	if (normalized.length === 0) return normalized;
+
+	if (!siteUrl) {
+		throw new Error(
+			`EmDash config error: allowedOrigins is set (${normalized.length} ${
+				normalized.length === 1 ? "entry" : "entries"
+			}) but siteUrl is not. Without a canonical siteUrl, rpId is derived from the request hostname, defeating multi-origin passkeys. Set siteUrl in astro.config.mjs or via EMDASH_SITE_URL.`,
+		);
+	}
+
+	let siteHost: string;
+	try {
+		siteHost = new URL(siteUrl).hostname;
+	} catch (e) {
+		throw new Error(`EmDash config error: siteUrl is not a valid URL: "${siteUrl}"`, {
+			cause: e,
+		});
+	}
+
+	if (siteHost.endsWith(".")) {
+		throw new Error(
+			`EmDash config error: siteUrl "${siteUrl}" has a trailing-dot hostname, which cannot match assertion origins. Remove the trailing dot when using allowedOrigins.`,
+		);
+	}
+	if (isIPLiteralHostname(siteHost)) {
+		throw new Error(
+			`EmDash config error: siteUrl "${siteUrl}" uses an IP-literal hostname. Multi-origin passkeys require a domain-based siteUrl — IP addresses cannot have valid subdomains for WebAuthn rpId.`,
+		);
+	}
+
+	for (const { origin, source } of tagged) {
+		const h = new URL(origin).hostname;
+		if (h !== siteHost && !h.endsWith("." + siteHost)) {
+			throw configError(
+				source,
+				`"${origin}" is not a subdomain of siteUrl "${siteUrl}". Allowed origins must be the same hostname as siteUrl or a subdomain of it.`,
+			);
+		}
+	}
+
+	return normalized;
+}
+
+function configError(source: AllowedOriginSource, detail: string, cause?: unknown): Error {
+	const err = new Error(`EmDash config error in ${source}: ${detail}`);
+	if (cause !== undefined) (err as Error & { cause?: unknown }).cause = cause;
+	return err;
+}
+
+const IPV4_DOTTED_DECIMAL_RE = /^\d+(\.\d+){3}$/;
+
+function isIPLiteralHostname(h: string): boolean {
+	// IPv6 hostnames are bracketed by URL.hostname, e.g. "[::1]"
+	if (h.startsWith("[")) return true;
+	// IPv4 dotted-decimal
+	return IPV4_DOTTED_DECIMAL_RE.test(h);
+}

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/passkey-config.ts

@@ -9,7 +9,12 @@
 export interface PasskeyConfig {
 	rpName: string;
 	rpId: string;
-	origin: string;
+	/**
+	 * Accepted client-data origins. First entry is the canonical/preferred origin;
+	 * additional entries support multi-origin deployments (e.g. apex + preview
+	 * subdomain sharing the same `rpId`). See `allowedOrigins` parameter.
+	 */
+	origins: string[];
 }
 
 /**
@@ -18,10 +23,22 @@ export interface PasskeyConfig {
  * @param url The request URL (typically `new URL(Astro.request.url)` or `new URL(request.url)`)
  * @param siteName Optional site name for rpName (defaults to hostname from `url` or public origin)
  * @param siteUrl Optional browser-facing origin (see `EmDashConfig.siteUrl`).
- *        When set, **origin** and **rpId** are taken from this URL so they match WebAuthn `clientData.origin`.
+ *        When set, the canonical **origin** and **rpId** are taken from this URL.
+ * @param allowedOrigins Optional list of additional accepted origins for verification.
+ *        Each must share `rpId` with the canonical origin (WebAuthn requirement).
+ *        Typical use: apex + preview subdomain on the same registrable domain.
  * @throws If `siteUrl` is non-empty but not parseable by `new URL()`.
  */
-export function getPasskeyConfig(url: URL, siteName?: string, siteUrl?: string): PasskeyConfig {
+export function getPasskeyConfig(
+	url: URL,
+	siteName?: string,
+	siteUrl?: string,
+	allowedOrigins?: string[],
+): PasskeyConfig {
+	let rpName: string;
+	let rpId: string;
+	let canonicalOrigin: string;
+
 	if (siteUrl) {
 		let publicUrl: URL;
 		try {
@@ -29,16 +46,21 @@ export function getPasskeyConfig(url: URL, siteName?: string, siteUrl?: string):
 		} catch (e) {
 			throw new Error(`Invalid siteUrl: "${siteUrl}"`, { cause: e });
 		}
-		return {
-			rpName: siteName || publicUrl.hostname,
-			rpId: publicUrl.hostname,
-			origin: publicUrl.origin,
-		};
+		rpName = siteName || publicUrl.hostname;
+		rpId = publicUrl.hostname;
+		canonicalOrigin = publicUrl.origin;
+	} else {
+		rpName = siteName || url.hostname;
+		rpId = url.hostname;
+		canonicalOrigin = url.origin;
+	}
+
+	const origins = [canonicalOrigin];
+	if (allowedOrigins) {
+		for (const extra of allowedOrigins) {
+			if (extra && !origins.includes(extra)) origins.push(extra);
+		}
 	}
 
-	return {
-		rpName: siteName || url.hostname,
-		rpId: url.hostname,
-		origin: url.origin,
-	};
+	return { rpName, rpId, origins };
 }

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/types.ts

@@ -2,7 +2,13 @@
  * Auth Provider Types
  *
  * Defines the interfaces for pluggable authentication providers.
- * Providers like Cloudflare Access implement these interfaces.
+ *
+ * Two systems coexist:
+ * - `AuthDescriptor` — transparent auth (Cloudflare Access) that authenticates
+ *   every request via headers/cookies. No login UI needed.
+ * - `AuthProviderDescriptor` — pluggable login methods (GitHub, Google,
+ *   AT Protocol, etc.) that appear as options on the login page and setup
+ *   wizard. Passkey is built-in; providers are additive.
  */
 
 /**
@@ -22,10 +28,10 @@ export interface AuthResult {
 }
 
 /**
- * Auth descriptor - returned by auth adapter functions (e.g., access())
+ * Auth descriptor — transparent auth providers (e.g., Cloudflare Access).
  *
- * Similar to DatabaseDescriptor and StorageDescriptor, this allows
- * auth providers to be configured at build time and loaded at runtime.
+ * These authenticate every request via headers/cookies. No login UI needed.
+ * The module's `authenticate()` function is called by middleware on each request.
  */
 export interface AuthDescriptor {
 	/**
@@ -64,6 +70,110 @@ export interface AuthProviderModule {
 	authenticate(request: Request, config: unknown): Promise<AuthResult>;
 }
 
+// ---------------------------------------------------------------------------
+// Pluggable Auth Providers (additive login methods)
+// ---------------------------------------------------------------------------
+
+/**
+ * Descriptor for a pluggable auth provider.
+ *
+ * Auth providers appear as login options on the login page and setup wizard.
+ * They coexist with passkey (which is built-in) and with each other.
+ * Any provider can be used to create the initial admin account.
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * import { atproto } from "@emdash-cms/auth-atproto";
+ *
+ * emdash({
+ *   authProviders: [atproto(), github(), google()],
+ * })
+ * ```
+ */
+export interface AuthProviderDescriptor {
+	/** Unique provider ID (e.g., "github", "atproto") */
+	id: string;
+
+	/** Human-readable label for UI (e.g., "GitHub", "AT Protocol") */
+	label: string;
+
+	/** Provider-specific config (JSON-serializable) */
+	config?: unknown;
+
+	/**
+	 * Module exporting React components for the admin UI.
+	 * Statically imported at build time via virtual module.
+	 *
+	 * The module should export components matching `AuthProviderAdminExports`.
+	 */
+	adminEntry?: string;
+
+	/**
+	 * Astro route handlers this provider needs injected at build time.
+	 * Used for login initiation, OAuth callbacks, well-known endpoints, etc.
+	 */
+	routes?: AuthRouteDescriptor[];
+
+	/**
+	 * URL prefixes/paths that should bypass auth middleware.
+	 * Added to the public routes set so login/callback endpoints work
+	 * for unauthenticated users.
+	 */
+	publicRoutes?: string[];
+
+	/**
+	 * Storage collections for persistent auth state (e.g., OAuth sessions).
+	 * Same format as plugin storage — collections are stored in the shared
+	 * `_plugin_storage` table namespaced under `auth:<providerId>`.
+	 *
+	 * Access via `getAuthProviderStorage()` from `emdash/api/route-utils`.
+	 */
+	storage?: Record<
+		string,
+		{ indexes?: Array<string | string[]>; uniqueIndexes?: Array<string | string[]> }
+	>;
+}
+
+/**
+ * A route that an auth provider needs injected into the Astro app.
+ */
+export interface AuthRouteDescriptor {
+	/** URL pattern (e.g., "/_emdash/api/auth/atproto/login") */
+	pattern: string;
+	/** Module specifier for the Astro route handler */
+	entrypoint: string;
+}
+
+/**
+ * Expected exports from an auth provider's `adminEntry` module.
+ *
+ * All exports are optional. Providers export whichever components
+ * make sense for their auth flow.
+ */
+export interface AuthProviderAdminExports {
+	/**
+	 * Compact button for the login page (icon + label).
+	 * Used for providers with a simple redirect flow (GitHub, Google).
+	 * Rendered in the "Or continue with" section.
+	 */
+	LoginButton?: import("react").ComponentType;
+
+	/**
+	 * Full login form for providers that need custom input.
+	 * Used for providers like AT Protocol that need a handle field.
+	 * Rendered as an expandable section on the login page.
+	 */
+	LoginForm?: import("react").ComponentType;
+
+	/**
+	 * Setup wizard step for creating the admin account via this provider.
+	 * When present, this provider appears as an option in the setup wizard's
+	 * "Create admin account" step.
+	 */
+	SetupStep?: import("react").ComponentType<{ onComplete: () => void }>;
+}
+
 /**
  * Configuration options common to external auth providers
  */