emdash 0.0.0-a → 0.0.1

package/src/auth/rate-limit.ts

@@ -0,0 +1,158 @@
+/**
+ * Database-backed rate limiter for unauthenticated endpoints.
+ *
+ * Uses a `_emdash_rate_limits` table with composite primary key (key, window).
+ * Each call to `checkRateLimit` atomically upserts a counter and returns
+ * whether the request is within the allowed limit.
+ *
+ * Key format: `{ip}:{endpoint}` — limits are per-IP, per-endpoint.
+ * Window format: ISO timestamp truncated to the window size.
+ */
+
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import { apiError } from "../api/error.js";
+import type { Database } from "../database/types.js";
+
+/** Loose validation for IPv4 and IPv6 addresses. */
+const IP_PATTERN = /^[\da-fA-F.:]+$/;
+
+/**
+ * Result of a rate limit check.
+ */
+export interface RateLimitResult {
+	/** Whether the request is allowed (within limit). */
+	allowed: boolean;
+	/** Current request count in this window. */
+	count: number;
+	/** Maximum requests allowed in this window. */
+	limit: number;
+}
+
+/**
+ * Check (and increment) the rate limit for a given IP + endpoint.
+ *
+ * If `ip` is null (no trusted IP available), rate limiting is skipped
+ * and the request is allowed. There's no meaningful key to rate limit
+ * on when the IP is unknown.
+ *
+ * Returns whether the request is allowed. The counter is always
+ * incremented — even when the limit is exceeded — so that repeated
+ * abuse doesn't reset the window.
+ *
+ * Piggybacks cleanup of expired entries with a 1% probability
+ * to prevent unbounded table growth.
+ */
+export async function checkRateLimit(
+	db: Kysely<Database>,
+	ip: string | null,
+	endpoint: string,
+	maxRequests: number,
+	windowSeconds: number,
+): Promise<RateLimitResult> {
+	// No trusted IP — skip rate limiting entirely
+	if (!ip) {
+		return { allowed: true, count: 0, limit: maxRequests };
+	}
+
+	const windowStart = new Date(
+		Math.floor(Date.now() / (windowSeconds * 1000)) * windowSeconds * 1000,
+	).toISOString();
+	const key = `${ip}:${endpoint}`;
+
+	// Atomic upsert: insert or increment, return current count
+	const result = await sql<{ count: number }>`
+		INSERT INTO _emdash_rate_limits (key, window, count)
+		VALUES (${key}, ${windowStart}, 1)
+		ON CONFLICT (key, window)
+		DO UPDATE SET count = _emdash_rate_limits.count + 1
+		RETURNING count
+	`.execute(db);
+
+	const count = result.rows[0]?.count ?? 1;
+
+	// Piggyback cleanup: 1% chance per request to clean expired entries
+	if (Math.random() < 0.01) {
+		cleanupExpiredRateLimits(db).catch(() => {
+			// Swallow errors — cleanup is best-effort
+		});
+	}
+
+	return {
+		allowed: count <= maxRequests,
+		count,
+		limit: maxRequests,
+	};
+}
+
+/**
+ * Build a 429 Too Many Requests response with standard headers.
+ */
+export function rateLimitResponse(retryAfterSeconds: number): Response {
+	const response = apiError("RATE_LIMITED", "Too many requests. Please try again later.", 429);
+	response.headers.set("Retry-After", String(retryAfterSeconds));
+	return response;
+}
+
+/**
+ * Extract client IP from a Request.
+ *
+ * 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
+ *    (e.g. skip rate limiting).
+ *
+ * Aligned with `extractRequestMeta` in `plugins/request-meta.ts`.
+ */
+export function getClientIp(request: Request): 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;
+	}
+
+	// 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;
+	}
+
+	// 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;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Delete expired rate limit entries.
+ *
+ * Entries with a window timestamp older than `maxAgeSeconds` are removed.
+ * Safe to call periodically (e.g., from cron cleanup or on-request piggyback).
+ */
+export async function cleanupExpiredRateLimits(
+	db: Kysely<Database>,
+	maxAgeSeconds = 3600,
+): Promise<number> {
+	const cutoff = new Date(Date.now() - maxAgeSeconds * 1000).toISOString();
+
+	const result = await sql`
+		DELETE FROM _emdash_rate_limits WHERE window < ${cutoff}
+	`.execute(db);
+
+	return Number(result.numAffectedRows ?? 0);
+}

package/src/auth/scopes.ts

@@ -0,0 +1,33 @@
+/**
+ * Scope enforcement for API token authentication.
+ *
+ * Routes call `requireScope(locals, "content:write")` alongside role checks.
+ * Session-authenticated requests have no scope restrictions (implicit full access).
+ * Token-authenticated requests must have the required scope (or "admin").
+ */
+
+import { hasScope } from "./api-tokens.js";
+
+/**
+ * Check if the request has a required scope.
+ * Returns a 403 Response if the scope is missing, or null if OK.
+ *
+ * For session-authenticated users (no tokenScopes), always returns null
+ * since session auth has implicit full scope.
+ */
+export function requireScope(locals: { tokenScopes?: string[] }, scope: string): Response | null {
+	// Session auth = no scope restrictions
+	if (!locals.tokenScopes) return null;
+
+	if (hasScope(locals.tokenScopes, scope)) return null;
+
+	return new Response(
+		JSON.stringify({
+			error: {
+				code: "INSUFFICIENT_SCOPE",
+				message: `Token lacks required scope: ${scope}`,
+			},
+		}),
+		{ status: 403, headers: { "Content-Type": "application/json" } },
+	);
+}

package/src/auth/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Auth Provider Types
+ *
+ * Defines the interfaces for pluggable authentication providers.
+ * Providers like Cloudflare Access implement these interfaces.
+ */
+
+/**
+ * Result of authenticating a request via an external auth provider
+ */
+export interface AuthResult {
+	/** User's email address */
+	email: string;
+	/** User's display name */
+	name: string;
+	/** Resolved role level (e.g., 50 for Admin, 30 for Editor) */
+	role: number;
+	/** Provider-specific subject ID */
+	subject?: string;
+	/** Additional provider-specific data */
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Auth descriptor - returned by auth adapter functions (e.g., access())
+ *
+ * Similar to DatabaseDescriptor and StorageDescriptor, this allows
+ * auth providers to be configured at build time and loaded at runtime.
+ */
+export interface AuthDescriptor {
+	/**
+	 * Auth provider type identifier
+	 * @example "cloudflare-access", "okta", "auth0"
+	 */
+	type: string;
+
+	/**
+	 * Module specifier to import at runtime
+	 * The module must export an `authenticate` function.
+	 * @example "@emdash-cms/cloudflare/auth"
+	 */
+	entrypoint: string;
+
+	/**
+	 * Provider-specific configuration (JSON-serializable)
+	 */
+	config: unknown;
+}
+
+/**
+ * Auth provider module interface
+ *
+ * Modules specified by AuthDescriptor.entrypoint must export
+ * an `authenticate` function matching this signature.
+ */
+export interface AuthProviderModule {
+	/**
+	 * Authenticate a request using the provider
+	 *
+	 * @param request - The incoming HTTP request
+	 * @param config - Provider-specific configuration from AuthDescriptor
+	 * @returns Authentication result if valid, throws if invalid
+	 */
+	authenticate(request: Request, config: unknown): Promise<AuthResult>;
+}
+
+/**
+ * Configuration options common to external auth providers
+ */
+export interface ExternalAuthConfig {
+	/**
+	 * Automatically create EmDash users on first login
+	 * @default true
+	 */
+	autoProvision?: boolean;
+
+	/**
+	 * Role level for users not matching any group in roleMapping
+	 * @default 30 (Editor)
+	 */
+	defaultRole?: number;
+
+	/**
+	 * Update user's role on each login based on current IdP groups
+	 * When false, role is only set on first provisioning
+	 * @default false
+	 */
+	syncRoles?: boolean;
+
+	/**
+	 * Map IdP group names to EmDash role levels
+	 * First match wins if user is in multiple groups
+	 *
+	 * @example
+	 * ```ts
+	 * roleMapping: {
+	 *   "Admins": 50,        // Admin
+	 *   "Developers": 40,    // Developer
+	 *   "Content Team": 30,  // Editor
+	 * }
+	 * ```
+	 */
+	roleMapping?: Record<string, number>;
+}

package/src/aws-sdk.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Type declarations for optional AWS SDK dependencies
+ *
+ * The AWS SDK is only required when using S3-compatible storage.
+ * This file provides minimal type declarations to satisfy TypeScript
+ * without requiring the SDK to be installed.
+ */
+
+declare module "@aws-sdk/client-s3" {
+	export interface S3ClientConfig {
+		endpoint: string;
+		region: string;
+		credentials: {
+			accessKeyId: string;
+			secretAccessKey: string;
+		};
+		forcePathStyle?: boolean;
+	}
+
+	export interface SdkStreamMixin {
+		transformToWebStream(): ReadableStream;
+	}
+
+	export interface GetObjectResponse {
+		Body?: SdkStreamMixin;
+		ContentType?: string;
+		ContentLength?: number;
+		ETag?: string;
+		LastModified?: Date;
+	}
+
+	export interface HeadObjectResponse {
+		ContentType?: string;
+		ContentLength?: number;
+		ETag?: string;
+		LastModified?: Date;
+	}
+
+	export interface ListObjectsV2Response {
+		Contents?: Array<{
+			Key?: string;
+			Size?: number;
+			LastModified?: Date;
+			ETag?: string;
+		}>;
+		NextContinuationToken?: string;
+	}
+
+	export class S3Client {
+		constructor(config: S3ClientConfig);
+		send(command: GetObjectCommand): Promise<GetObjectResponse>;
+		send(command: HeadObjectCommand): Promise<HeadObjectResponse>;
+		send(command: ListObjectsV2Command): Promise<ListObjectsV2Response>;
+		send(command: PutObjectCommand): Promise<void>;
+		send(command: DeleteObjectCommand): Promise<void>;
+		// Generic fallback
+		send(command: unknown): Promise<unknown>;
+	}
+
+	export class PutObjectCommand {
+		constructor(input: {
+			Bucket: string;
+			Key: string;
+			Body?: unknown;
+			ContentType?: string;
+			ContentLength?: number;
+		});
+	}
+
+	export class GetObjectCommand {
+		constructor(input: { Bucket: string; Key: string });
+	}
+
+	export class DeleteObjectCommand {
+		constructor(input: { Bucket: string; Key: string });
+	}
+
+	export class HeadObjectCommand {
+		constructor(input: { Bucket: string; Key: string });
+	}
+
+	export class ListObjectsV2Command {
+		constructor(input: {
+			Bucket: string;
+			Prefix?: string;
+			MaxKeys?: number;
+			ContinuationToken?: string;
+		});
+	}
+}
+
+declare module "@aws-sdk/s3-request-presigner" {
+	import type { S3Client } from "@aws-sdk/client-s3";
+
+	export function getSignedUrl(
+		client: S3Client,
+		command: unknown,
+		options: { expiresIn: number },
+	): Promise<string>;
+}

package/src/bylines/index.ts

@@ -0,0 +1,237 @@
+/**
+ * Runtime API for bylines
+ *
+ * Provides functions to query byline profiles and byline credits
+ * associated with content entries. Follows the same pattern as
+ * the taxonomies runtime API.
+ */
+
+import { sql } from "kysely";
+
+import { BylineRepository } from "../database/repositories/byline.js";
+import type { BylineSummary, ContentBylineCredit } from "../database/repositories/types.js";
+import { validateIdentifier } from "../database/validate.js";
+import { getDb } from "../loader.js";
+
+/**
+ * Get a byline by ID.
+ *
+ * @example
+ * ```ts
+ * import { getByline } from "emdash";
+ *
+ * const byline = await getByline("01HXYZ...");
+ * if (byline) {
+ *   console.log(byline.displayName);
+ * }
+ * ```
+ */
+export async function getByline(id: string): Promise<BylineSummary | null> {
+	const db = await getDb();
+	const repo = new BylineRepository(db);
+	return repo.findById(id);
+}
+
+/**
+ * Get a byline by slug.
+ *
+ * @example
+ * ```ts
+ * import { getBylineBySlug } from "emdash";
+ *
+ * const byline = await getBylineBySlug("jane-doe");
+ * if (byline) {
+ *   console.log(byline.displayName); // "Jane Doe"
+ * }
+ * ```
+ */
+export async function getBylineBySlug(slug: string): Promise<BylineSummary | null> {
+	const db = await getDb();
+	const repo = new BylineRepository(db);
+	return repo.findBySlug(slug);
+}
+
+/**
+ * Get byline credits for a single content entry.
+ *
+ * Returns explicit byline credits from the junction table. If none exist
+ * but the entry has an `authorId`, falls back to the user-linked byline
+ * (marked as source: "inferred").
+ *
+ * @example
+ * ```ts
+ * import { getEntryBylines } from "emdash";
+ *
+ * const bylines = await getEntryBylines("posts", post.data.id);
+ * for (const credit of bylines) {
+ *   console.log(credit.byline.displayName, credit.roleLabel);
+ * }
+ * ```
+ */
+export async function getEntryBylines(
+	collection: string,
+	entryId: string,
+): Promise<ContentBylineCredit[]> {
+	validateIdentifier(collection, "collection");
+	const db = await getDb();
+	const repo = new BylineRepository(db);
+
+	const explicit = await repo.getContentBylines(collection, entryId);
+	if (explicit.length > 0) {
+		return explicit.map((c) => ({ ...c, source: "explicit" as const }));
+	}
+
+	// Fallback: look up user-linked byline from author_id
+	const authorId = await getAuthorId(db, collection, entryId);
+	if (authorId) {
+		const fallback = await repo.findByUserId(authorId);
+		if (fallback) {
+			return [{ byline: fallback, sortOrder: 0, roleLabel: null, source: "inferred" }];
+		}
+	}
+
+	return [];
+}
+
+/**
+ * Batch-fetch byline credits for multiple content entries in a single query.
+ *
+ * This is more efficient than calling getEntryBylines for each entry
+ * when you need bylines for a list of entries (e.g., a blog index page).
+ *
+ * @param collection - The collection slug (e.g., "posts")
+ * @param entryIds - Array of entry IDs
+ * @returns Map from entry ID to array of byline credits
+ *
+ * @example
+ * ```ts
+ * import { getBylinesForEntries, getEmDashCollection } from "emdash";
+ *
+ * const { entries } = await getEmDashCollection("posts");
+ * const ids = entries.map(e => e.data.id);
+ * const bylinesMap = await getBylinesForEntries("posts", ids);
+ *
+ * for (const entry of entries) {
+ *   const bylines = bylinesMap.get(entry.data.id) ?? [];
+ *   // render bylines
+ * }
+ * ```
+ */
+export async function getBylinesForEntries(
+	collection: string,
+	entryIds: string[],
+): Promise<Map<string, ContentBylineCredit[]>> {
+	validateIdentifier(collection, "collection");
+	const result = new Map<string, ContentBylineCredit[]>();
+
+	// Initialize all entry IDs with empty arrays
+	for (const id of entryIds) {
+		result.set(id, []);
+	}
+
+	if (entryIds.length === 0) {
+		return result;
+	}
+
+	const db = await getDb();
+	const repo = new BylineRepository(db);
+
+	// 1. Batch fetch all explicit byline credits
+	const bylinesMap = await repo.getContentBylinesMany(collection, entryIds);
+
+	// 2. Collect entry IDs that need fallback lookup
+	const fallbackEntryIds: string[] = [];
+	const needsFallback: Map<string, string> = new Map(); // entryId -> authorId
+
+	for (const id of entryIds) {
+		if (!bylinesMap.has(id)) {
+			// Need to check author_id for this entry — but we only have the IDs,
+			// so batch-fetch them from the content table
+			fallbackEntryIds.push(id);
+		}
+	}
+
+	// Batch-fetch author_ids for entries that need fallback
+	if (fallbackEntryIds.length > 0) {
+		const authorMap = await getAuthorIds(db, collection, fallbackEntryIds);
+		for (const [entryId, authorId] of authorMap) {
+			needsFallback.set(entryId, authorId);
+		}
+	}
+
+	// 3. Batch fetch user-linked bylines for fallback
+	const uniqueAuthorIds = [...new Set(needsFallback.values())];
+	const authorBylineMap = await repo.findByUserIds(uniqueAuthorIds);
+
+	// 4. Assign results
+	for (const id of entryIds) {
+		const explicit = bylinesMap.get(id);
+		if (explicit && explicit.length > 0) {
+			result.set(
+				id,
+				explicit.map((c) => ({ ...c, source: "explicit" as const })),
+			);
+			continue;
+		}
+
+		const authorId = needsFallback.get(id);
+		if (authorId) {
+			const fallback = authorBylineMap.get(authorId);
+			if (fallback) {
+				result.set(id, [{ byline: fallback, sortOrder: 0, roleLabel: null, source: "inferred" }]);
+				continue;
+			}
+		}
+
+		// Already initialized with empty array
+	}
+
+	return result;
+}
+
+/**
+ * Look up the author_id for a single content entry.
+ * Uses raw SQL since we need dynamic table names.
+ */
+async function getAuthorId(
+	db: Awaited<ReturnType<typeof getDb>>,
+	collection: string,
+	entryId: string,
+): Promise<string | null> {
+	const tableName = `ec_${collection}`;
+	validateIdentifier(tableName, "content table");
+
+	const result = await sql<{ author_id: string | null }>`
+		SELECT author_id FROM ${sql.ref(tableName)}
+		WHERE id = ${entryId}
+		LIMIT 1
+	`.execute(db);
+
+	return result.rows[0]?.author_id ?? null;
+}
+
+/**
+ * Batch-fetch author_ids for multiple content entries.
+ * Returns Map<entryId, authorId> (only entries with non-null author_id).
+ */
+async function getAuthorIds(
+	db: Awaited<ReturnType<typeof getDb>>,
+	collection: string,
+	entryIds: string[],
+): Promise<Map<string, string>> {
+	const tableName = `ec_${collection}`;
+	validateIdentifier(tableName, "content table");
+
+	const result = await sql<{ id: string; author_id: string | null }>`
+		SELECT id, author_id FROM ${sql.ref(tableName)}
+		WHERE id IN (${sql.join(entryIds.map((id) => sql`${id}`))})
+	`.execute(db);
+
+	const map = new Map<string, string>();
+	for (const row of result.rows) {
+		if (row.author_id) {
+			map.set(row.id, row.author_id);
+		}
+	}
+	return map;
+}