@emdash-cms/auth 0.0.1

package/src/config.ts

@@ -0,0 +1,214 @@
+/**
+ * Configuration schema for @emdash-cms/auth
+ */
+
+import { z } from "zod";
+
+import type { RoleName } from "./types.js";
+
+/** Matches http(s) scheme at start of URL */
+const HTTP_SCHEME_RE = /^https?:\/\//i;
+
+/** Validates that a URL string uses http or https scheme. Rejects javascript:/data: URI XSS vectors. */
+const httpUrl = z
+	.string()
+	.url()
+	.refine((url) => HTTP_SCHEME_RE.test(url), "URL must use http or https");
+
+/**
+ * OAuth provider configuration
+ */
+const oauthProviderSchema = z.object({
+	clientId: z.string(),
+	clientSecret: z.string(),
+});
+
+/**
+ * Full auth configuration schema
+ */
+export const authConfigSchema = z.object({
+	/**
+	 * Secret key for encrypting tokens and session data.
+	 * Generate with: `emdash auth secret`
+	 */
+	secret: z.string().min(32, "Auth secret must be at least 32 characters"),
+
+	/**
+	 * Passkey (WebAuthn) configuration
+	 */
+	passkeys: z
+		.object({
+			/**
+			 * Relying party name shown to users during passkey registration
+			 */
+			rpName: z.string(),
+			/**
+			 * Relying party ID (domain). Defaults to the hostname from baseUrl.
+			 */
+			rpId: z.string().optional(),
+		})
+		.optional(),
+
+	/**
+	 * Self-signup configuration
+	 */
+	selfSignup: z
+		.object({
+			/**
+			 * Email domains allowed to self-register
+			 */
+			domains: z.array(z.string()),
+			/**
+			 * Default role for self-registered users
+			 */
+			defaultRole: z.enum(["subscriber", "contributor", "author"] as const).default("contributor"),
+		})
+		.optional(),
+
+	/**
+	 * OAuth provider configurations (for "Login with X")
+	 */
+	oauth: z
+		.object({
+			github: oauthProviderSchema.optional(),
+			google: oauthProviderSchema.optional(),
+		})
+		.optional(),
+
+	/**
+	 * Configure EmDash as an OAuth provider
+	 */
+	provider: z
+		.object({
+			enabled: z.boolean(),
+			/**
+			 * Issuer URL for OIDC. Defaults to site URL.
+			 */
+			issuer: httpUrl.optional(),
+		})
+		.optional(),
+
+	/**
+	 * Enterprise SSO configuration
+	 */
+	sso: z
+		.object({
+			enabled: z.boolean(),
+		})
+		.optional(),
+
+	/**
+	 * Session configuration
+	 */
+	session: z
+		.object({
+			/**
+			 * Session max age in seconds. Default: 30 days
+			 */
+			maxAge: z.number().default(30 * 24 * 60 * 60),
+			/**
+			 * Extend session on activity. Default: true
+			 */
+			sliding: z.boolean().default(true),
+		})
+		.optional(),
+});
+
+export type AuthConfig = z.infer<typeof authConfigSchema>;
+
+/**
+ * Validated and resolved auth configuration
+ */
+export interface ResolvedAuthConfig {
+	secret: string;
+	baseUrl: string;
+	siteName: string;
+
+	passkeys: {
+		rpName: string;
+		rpId: string;
+		origin: string;
+	};
+
+	selfSignup?: {
+		domains: string[];
+		defaultRole: RoleName;
+	};
+
+	oauth?: {
+		github?: {
+			clientId: string;
+			clientSecret: string;
+		};
+		google?: {
+			clientId: string;
+			clientSecret: string;
+		};
+	};
+
+	provider?: {
+		enabled: boolean;
+		issuer: string;
+	};
+
+	sso?: {
+		enabled: boolean;
+	};
+
+	session: {
+		maxAge: number;
+		sliding: boolean;
+	};
+}
+
+const selfSignupRoleMap: Record<"subscriber" | "contributor" | "author", RoleName> = {
+	subscriber: "SUBSCRIBER",
+	contributor: "CONTRIBUTOR",
+	author: "AUTHOR",
+};
+
+/**
+ * Resolve auth configuration with defaults
+ */
+export function resolveConfig(
+	config: AuthConfig,
+	baseUrl: string,
+	siteName: string,
+): ResolvedAuthConfig {
+	const url = new URL(baseUrl);
+
+	return {
+		secret: config.secret,
+		baseUrl,
+		siteName,
+
+		passkeys: {
+			rpName: config.passkeys?.rpName ?? siteName,
+			rpId: config.passkeys?.rpId ?? url.hostname,
+			origin: url.origin,
+		},
+
+		selfSignup: config.selfSignup
+			? {
+					domains: config.selfSignup.domains.map((d) => d.toLowerCase()),
+					defaultRole: selfSignupRoleMap[config.selfSignup.defaultRole],
+				}
+			: undefined,
+
+		oauth: config.oauth,
+
+		provider: config.provider
+			? {
+					enabled: config.provider.enabled,
+					issuer: config.provider.issuer ?? baseUrl,
+				}
+			: undefined,
+
+		sso: config.sso,
+
+		session: {
+			maxAge: config.session?.maxAge ?? 30 * 24 * 60 * 60,
+			sliding: config.session?.sliding ?? true,
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * @emdash-cms/auth - Passkey-first authentication for EmDash
+ *
+ * Email is now handled by the plugin email pipeline (see PLUGIN-EMAIL.md).
+ * Auth functions accept an optional `email` send function instead of a
+ * hardcoded adapter. The route layer bridges `emdash.email.send()` from
+ * the pipeline into the auth functions.
+ *
+ * @example
+ * ```ts
+ * import { auth } from '@emdash-cms/auth'
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     emdash({
+ *       auth: auth({
+ *         secret: import.meta.env.EMDASH_AUTH_SECRET,
+ *         passkeys: { rpName: 'My Site' },
+ *       }),
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+
+// Types
+export * from "./types.js";
+
+// Config
+import { authConfigSchema as _authConfigSchema } from "./config.js";
+export {
+	authConfigSchema,
+	resolveConfig,
+	type AuthConfig,
+	type ResolvedAuthConfig,
+} from "./config.js";
+
+// RBAC
+export {
+	Permissions,
+	hasPermission,
+	requirePermission,
+	canActOnOwn,
+	requirePermissionOnResource,
+	PermissionError,
+	scopesForRole,
+	clampScopes,
+	type Permission,
+} from "./rbac.js";
+
+// Tokens
+export {
+	generateToken,
+	hashToken,
+	generateTokenWithHash,
+	generateSessionId,
+	generateAuthSecret,
+	secureCompare,
+	encrypt,
+	decrypt,
+	// Prefixed API tokens (ec_pat_, ec_oat_, ec_ort_)
+	TOKEN_PREFIXES,
+	generatePrefixedToken,
+	hashPrefixedToken,
+	// Scopes
+	VALID_SCOPES,
+	validateScopes,
+	hasScope,
+	type ApiTokenScope,
+	// PKCE
+	computeS256Challenge,
+} from "./tokens.js";
+
+// Passkey
+export * from "./passkey/index.js";
+
+// Magic Link
+export {
+	sendMagicLink,
+	verifyMagicLink,
+	MagicLinkError,
+	type MagicLinkConfig,
+} from "./magic-link/index.js";
+
+// Invite
+export {
+	createInvite,
+	createInviteToken,
+	validateInvite,
+	completeInvite,
+	InviteError,
+	escapeHtml,
+	type InviteConfig,
+	type InviteTokenResult,
+	type EmailSendFn,
+} from "./invite.js";
+
+// Signup
+export {
+	canSignup,
+	requestSignup,
+	validateSignupToken,
+	completeSignup,
+	SignupError,
+	type SignupConfig,
+} from "./signup.js";
+
+// OAuth
+export {
+	createAuthorizationUrl,
+	handleOAuthCallback,
+	OAuthError,
+	github,
+	google,
+	type StateStore,
+	type OAuthConsumerConfig,
+} from "./oauth/consumer.js";
+export type { OAuthProvider, OAuthConfig, OAuthProfile, OAuthState } from "./oauth/types.js";
+
+// Email types (implementations moved to plugin email pipeline)
+export type { EmailAdapter, EmailMessage } from "./types.js";
+
+/**
+ * Create an auth configuration
+ *
+ * This is a helper function that validates the config at runtime.
+ */
+export function auth(config: import("./config.js").AuthConfig): import("./config.js").AuthConfig {
+	// Validate config
+	const result = _authConfigSchema.safeParse(config);
+	if (!result.success) {
+		throw new Error(`Invalid auth config: ${result.error.message}`);
+	}
+	return result.data;
+}

package/src/invite.ts

@@ -0,0 +1,205 @@
+/**
+ * Invite system for new users
+ */
+
+import { generateTokenWithHash, hashToken } from "./tokens.js";
+import type { AuthAdapter, RoleLevel, EmailMessage, User } from "./types.js";
+
+/** Escape HTML special characters to prevent injection in email templates */
+export function escapeHtml(s: string): string {
+	return s
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+}
+
+const TOKEN_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/** Function that sends an email (matches the EmailPipeline.send signature) */
+export type EmailSendFn = (message: EmailMessage) => Promise<void>;
+
+export interface InviteConfig {
+	baseUrl: string;
+	siteName: string;
+	/** Optional email sender. When omitted, invite URL is returned without sending. */
+	email?: EmailSendFn;
+}
+
+/** Result of creating an invite token (without sending email) */
+export interface InviteTokenResult {
+	/** The complete invite URL */
+	url: string;
+	/** The invite email address */
+	email: string;
+}
+
+/**
+ * Create an invite token and URL without sending email.
+ *
+ * Validates the user doesn't already exist, generates a token, stores it,
+ * and returns the invite URL. Callers decide whether to send email or
+ * display the URL as a copy-link fallback.
+ */
+export async function createInviteToken(
+	config: Pick<InviteConfig, "baseUrl">,
+	adapter: AuthAdapter,
+	email: string,
+	role: RoleLevel,
+	invitedBy: string,
+): Promise<InviteTokenResult> {
+	// Check if user already exists
+	const existing = await adapter.getUserByEmail(email);
+	if (existing) {
+		throw new InviteError("user_exists", "A user with this email already exists");
+	}
+
+	// Generate token
+	const { token, hash } = generateTokenWithHash();
+
+	// Store token
+	await adapter.createToken({
+		hash,
+		email,
+		type: "invite",
+		role,
+		invitedBy,
+		expiresAt: new Date(Date.now() + TOKEN_EXPIRY_MS),
+	});
+
+	// Build invite URL
+	const url = new URL("/api/auth/invite/accept", config.baseUrl);
+	url.searchParams.set("token", token);
+
+	return { url: url.toString(), email };
+}
+
+/**
+ * Build the invite email message.
+ */
+function buildInviteEmail(inviteUrl: string, email: string, siteName: string): EmailMessage {
+	const safeName = escapeHtml(siteName);
+	return {
+		to: email,
+		subject: `You've been invited to ${siteName}`,
+		text: `You've been invited to join ${siteName}.\n\nClick this link to create your account:\n${inviteUrl}\n\nThis link expires in 7 days.`,
+		html: `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.5; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+  <h1 style="font-size: 24px; margin-bottom: 20px;">You've been invited to ${safeName}</h1>
+  <p>Click the button below to create your account:</p>
+  <p style="margin: 30px 0;">
+    <a href="${inviteUrl}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">Accept Invite</a>
+  </p>
+  <p style="color: #666; font-size: 14px;">This link expires in 7 days.</p>
+</body>
+</html>`,
+	};
+}
+
+/**
+ * Create and send an invite to a new user.
+ *
+ * When `config.email` is provided, sends the invite email.
+ * When omitted, creates the token and returns the invite URL
+ * without sending (for the copy-link fallback).
+ */
+export async function createInvite(
+	config: InviteConfig,
+	adapter: AuthAdapter,
+	email: string,
+	role: RoleLevel,
+	invitedBy: string,
+): Promise<InviteTokenResult> {
+	const result = await createInviteToken(config, adapter, email, role, invitedBy);
+
+	// Send email if a sender is configured
+	if (config.email) {
+		const message = buildInviteEmail(result.url, email, config.siteName);
+		await config.email(message);
+	}
+
+	return result;
+}
+
+/**
+ * Validate an invite token and return the invite data
+ */
+export async function validateInvite(
+	adapter: AuthAdapter,
+	token: string,
+): Promise<{ email: string; role: RoleLevel }> {
+	const hash = hashToken(token);
+
+	const authToken = await adapter.getToken(hash, "invite");
+	if (!authToken) {
+		throw new InviteError("invalid_token", "Invalid or expired invite link");
+	}
+
+	if (authToken.expiresAt < new Date()) {
+		await adapter.deleteToken(hash);
+		throw new InviteError("token_expired", "This invite has expired");
+	}
+
+	if (!authToken.email || authToken.role === null) {
+		throw new InviteError("invalid_token", "Invalid invite data");
+	}
+
+	return {
+		email: authToken.email,
+		role: authToken.role,
+	};
+}
+
+/**
+ * Complete the invite process (after passkey registration)
+ */
+export async function completeInvite(
+	adapter: AuthAdapter,
+	token: string,
+	userData: {
+		name?: string;
+		avatarUrl?: string;
+	},
+): Promise<User> {
+	const hash = hashToken(token);
+
+	// Validate token one more time
+	const authToken = await adapter.getToken(hash, "invite");
+	if (!authToken || authToken.expiresAt < new Date()) {
+		throw new InviteError("invalid_token", "Invalid or expired invite");
+	}
+
+	if (!authToken.email || authToken.role === null) {
+		throw new InviteError("invalid_token", "Invalid invite data");
+	}
+
+	// Delete token (single-use)
+	await adapter.deleteToken(hash);
+
+	// Create user
+	const user = await adapter.createUser({
+		email: authToken.email,
+		name: userData.name,
+		avatarUrl: userData.avatarUrl,
+		role: authToken.role,
+		emailVerified: true, // Email verified by accepting invite
+	});
+
+	return user;
+}
+
+export class InviteError extends Error {
+	constructor(
+		public code: "invalid_token" | "token_expired" | "user_exists",
+		message: string,
+	) {
+		super(message);
+		this.name = "InviteError";
+	}
+}

package/src/magic-link/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Magic link authentication
+ */
+
+import { escapeHtml } from "../invite.js";
+import { generateTokenWithHash, hashToken } from "../tokens.js";
+import type { AuthAdapter, User, EmailMessage } from "../types.js";
+
+const TOKEN_EXPIRY_MS = 15 * 60 * 1000; // 15 minutes
+
+/** Function that sends an email (matches the EmailPipeline.send signature) */
+export type EmailSendFn = (message: EmailMessage) => Promise<void>;
+
+export interface MagicLinkConfig {
+	baseUrl: string;
+	siteName: string;
+	/** Optional email sender. When omitted, magic links cannot be sent. */
+	email?: EmailSendFn;
+}
+
+/**
+ * Add artificial delay with jitter to prevent timing attacks.
+ * Range approximates the time for token creation + email send.
+ */
+async function timingDelay(): Promise<void> {
+	const delay = 100 + Math.random() * 150; // 100-250ms
+	await new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+/**
+ * Send a magic link to a user's email.
+ *
+ * Requires `config.email` to be set. Throws if no email sender is configured.
+ */
+export async function sendMagicLink(
+	config: MagicLinkConfig,
+	adapter: AuthAdapter,
+	email: string,
+	type: "magic_link" | "recovery" = "magic_link",
+): Promise<void> {
+	if (!config.email) {
+		throw new MagicLinkError("email_not_configured", "Email is not configured");
+	}
+
+	// Find user
+	const user = await adapter.getUserByEmail(email);
+	if (!user) {
+		// Don't reveal whether user exists - add delay to match successful path timing
+		await timingDelay();
+		return;
+	}
+
+	// Generate token
+	const { token, hash } = generateTokenWithHash();
+
+	// Store token hash
+	await adapter.createToken({
+		hash,
+		userId: user.id,
+		email: user.email,
+		type,
+		expiresAt: new Date(Date.now() + TOKEN_EXPIRY_MS),
+	});
+
+	// Build magic link URL
+	const url = new URL("/api/auth/magic-link/verify", config.baseUrl);
+	url.searchParams.set("token", token);
+
+	// Send email
+	const safeName = escapeHtml(config.siteName);
+	await config.email({
+		to: user.email,
+		subject: `Sign in to ${config.siteName}`,
+		text: `Click this link to sign in to ${config.siteName}:\n\n${url.toString()}\n\nThis link expires in 15 minutes.\n\nIf you didn't request this, you can safely ignore this email.`,
+		html: `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.5; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+  <h1 style="font-size: 24px; margin-bottom: 20px;">Sign in to ${safeName}</h1>
+  <p>Click the button below to sign in:</p>
+  <p style="margin: 30px 0;">
+    <a href="${url.toString()}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">Sign in</a>
+  </p>
+  <p style="color: #666; font-size: 14px;">This link expires in 15 minutes.</p>
+  <p style="color: #666; font-size: 14px;">If you didn't request this, you can safely ignore this email.</p>
+</body>
+</html>`,
+	});
+}
+
+/**
+ * Verify a magic link token and return the user
+ */
+export async function verifyMagicLink(adapter: AuthAdapter, token: string): Promise<User> {
+	const hash = hashToken(token);
+
+	// Find and validate token
+	const authToken = await adapter.getToken(hash, "magic_link");
+	if (!authToken) {
+		// Also check for recovery tokens
+		const recoveryToken = await adapter.getToken(hash, "recovery");
+		if (!recoveryToken) {
+			throw new MagicLinkError("invalid_token", "Invalid or expired link");
+		}
+		return verifyTokenAndGetUser(adapter, recoveryToken, hash);
+	}
+
+	return verifyTokenAndGetUser(adapter, authToken, hash);
+}
+
+async function verifyTokenAndGetUser(
+	adapter: AuthAdapter,
+	authToken: { userId: string | null; expiresAt: Date },
+	hash: string,
+): Promise<User> {
+	// Check expiry
+	if (authToken.expiresAt < new Date()) {
+		await adapter.deleteToken(hash);
+		throw new MagicLinkError("token_expired", "This link has expired");
+	}
+
+	// Delete token (single-use)
+	await adapter.deleteToken(hash);
+
+	// Get user
+	if (!authToken.userId) {
+		throw new MagicLinkError("invalid_token", "Invalid token");
+	}
+
+	const user = await adapter.getUserById(authToken.userId);
+	if (!user) {
+		throw new MagicLinkError("user_not_found", "User not found");
+	}
+
+	return user;
+}
+
+export class MagicLinkError extends Error {
+	constructor(
+		public code: "invalid_token" | "token_expired" | "user_not_found" | "email_not_configured",
+		message: string,
+	) {
+		super(message);
+		this.name = "MagicLinkError";
+	}
+}