emdash 0.5.0 → 0.7.0

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();
+}

package/src/bylines/index.ts

@@ -13,47 +13,19 @@ import type { BylineSummary, ContentBylineCredit } from "../database/repositorie
 import { validateIdentifier } from "../database/validate.js";
 import { getDb } from "../loader.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
+import { isMissingTableError } from "../utils/db-errors.js";
 
 /**
- * Cached result of "does any byline exist in the database?"
- * null = not yet checked, true/false = cached result.
- * Invalidated when bylines are created or deleted.
- */
-let hasBylines: boolean | null = null;
-
-/**
- * Invalidate the cached "has any bylines" check.
- * Call this when bylines are created, updated, or deleted.
+ * No-op — kept for API compatibility.
+ *
+ * Used to invalidate a worker-lifetime "has any byline?" probe. That
+ * probe added a query on every cold isolate to save one query on sites
+ * with zero bylines (i.e. the wrong tradeoff), so we dropped it. The
+ * batch byline join below returns an empty map for empty sites at the
+ * same cost as the probe, without the pre-check.
  */
 export function invalidateBylineCache(): void {
-	hasBylines = null;
-}
-
-/**
- * Check if any bylines exist in the database. Result is cached
- * for the lifetime of the worker/process and invalidated on writes.
- */
-async function hasAnyBylines(): Promise<boolean> {
-	if (hasBylines !== null) return hasBylines;
-
-	try {
-		const db = await getDb();
-		const result = await sql<{ id: string }>`
-			SELECT id FROM _emdash_bylines LIMIT 1
-		`.execute(db);
-		hasBylines = result.rows.length > 0;
-	} catch (error: unknown) {
-		// Only treat "no such table" as a safe false -- anything else should
-		// not be cached so the next request retries.
-		const message = error instanceof Error ? error.message : "";
-		if (message.includes("no such table")) {
-			hasBylines = false;
-		} else {
-			return false;
-		}
-	}
-
-	return hasBylines;
+	// Intentionally empty.
 }
 
 /**
@@ -176,17 +148,22 @@ export async function getBylinesForEntries(
 		return result;
 	}
 
-	// Skip DB queries entirely when no bylines have been created.
-	// The cache is invalidated when bylines are created/deleted.
-	if (!(await hasAnyBylines())) {
-		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);
+	// 1. Batch fetch all explicit byline credits. Sites with no bylines
+	// get an empty map back for one query — the previous "has any bylines"
+	// probe traded an extra round-trip on every request to save that one
+	// query on empty sites, which is exactly backwards for the common case.
+	// Pre-migration databases (bylines table missing) fall through to the
+	// `isMissingTableError` catch below and return empty results.
+	let bylinesMap;
+	try {
+		bylinesMap = await repo.getContentBylinesMany(collection, entryIds);
+	} catch (error) {
+		if (isMissingTableError(error)) return result;
+		throw error;
+	}
 
 	// 2. Collect entry IDs that need fallback lookup
 	const fallbackEntryIds: string[] = [];

package/src/components/EmDashHead.astro

@@ -16,8 +16,12 @@
 import type { PublicPageContext, PageMetadataContribution } from "../plugins/types.js";
 import { resolvePageMetadata, renderPageMetadata } from "../page/metadata.js";
 import { renderFragments } from "../page/fragments.js";
-import { generateBaseSeoContributions } from "../page/seo-contributions.js";
+import {
+	generateBaseSeoContributions,
+	generateSiteSeoContributions,
+} from "../page/seo-contributions.js";
 import { getPageRuntime } from "../page/index.js";
+import { getSiteSetting } from "../settings/index.js";
 
 interface Props {
 	page: PublicPageContext;
@@ -33,14 +37,26 @@ let metadataHtml = "";
 let fragmentsHtml = "";
 
 if (runtime) {
-	// Plugin contributions come BEFORE base, so resolvePageMetadata's
-	// first-wins dedup lets plugins override base SEO defaults
-	const pluginContributions = await runtime.collectPageMetadata(page);
-	const allContributions = [...pluginContributions, ...baseContributions];
+	// Run independent async loads in parallel: site SEO settings (for
+	// search engine verification meta tags) and plugin page-metadata
+	// contributions. Plugin contributions come BEFORE site/base in the
+	// array, so resolvePageMetadata's first-wins dedup lets plugins
+	// override defaults.
+	//
+	// `getSiteSetting("seo")` is request-cached and — crucially — reads
+	// from `getSiteSettings()`'s cached batch when a parent template has
+	// already called it. So this is either a single-key query or free,
+	// not a second round-trip.
+	const [seoSettings, pluginContributions, fragments] = await Promise.all([
+		getSiteSetting("seo"),
+		runtime.collectPageMetadata(page),
+		runtime.collectPageFragments(page),
+	]);
+
+	const siteContributions = generateSiteSeoContributions(seoSettings);
+	const allContributions = [...pluginContributions, ...siteContributions, ...baseContributions];
 	const resolved = resolvePageMetadata(allContributions);
 	metadataHtml = renderPageMetadata(resolved);
-
-	const fragments = await runtime.collectPageFragments(page);
 	fragmentsHtml = renderFragments(fragments, "head");
 } else {
 	// No runtime (EmDash not initialized) — still render base SEO

package/src/database/connection.ts

@@ -1,6 +1,7 @@
 import BetterSqlite3 from "better-sqlite3";
 import { Kysely, SqliteDialect } from "kysely";
 
+import { kyselyLogOption } from "./instrumentation.js";
 import type { Database } from "./types.js";
 
 export interface DatabaseConfig {
@@ -18,6 +19,23 @@ export class EmDashDatabaseError extends Error {
 	}
 }
 
+/**
+ * Returns a helpful, actionable message when better-sqlite3's native binary
+ * was compiled against a different Node.js version than the one running. This
+ * happens after upgrading Node without rebuilding native deps.
+ *
+ * Returns null if the error is not a NODE_MODULE_VERSION mismatch.
+ */
+export function formatNativeModuleVersionError(error: unknown): string | null {
+	const message = error instanceof Error ? error.message : String(error);
+	if (!message.includes("NODE_MODULE_VERSION")) return null;
+	return (
+		"better-sqlite3's native binary was compiled against a different Node.js version. " +
+		"Rebuild it with `pnpm rebuild better-sqlite3` (or `npm rebuild better-sqlite3`), " +
+		"or reinstall dependencies with your current Node.js version."
+	);
+}
+
 /**
  * Creates a Kysely database instance
  * Supports:
@@ -45,7 +63,7 @@ export function createDatabase(config: DatabaseConfig): Kysely<Database> {
 				database: sqlite,
 			});
 
-			return new Kysely<Database>({ dialect });
+			return new Kysely<Database>({ dialect, log: kyselyLogOption() });
 		}
 
 		// Handle libSQL (Turso)
@@ -62,6 +80,10 @@ export function createDatabase(config: DatabaseConfig): Kysely<Database> {
 		if (error instanceof EmDashDatabaseError) {
 			throw error;
 		}
+		const nativeVersionHint = formatNativeModuleVersionError(error);
+		if (nativeVersionHint) {
+			throw new EmDashDatabaseError(nativeVersionHint, error);
+		}
 		throw new EmDashDatabaseError("Failed to create database", error);
 	}
 }

package/src/database/instrumentation.ts

@@ -0,0 +1,98 @@
+/**
+ * Query instrumentation
+ *
+ * Dev/test-only: captures every Kysely query executed inside a request,
+ * tagged with the route, method, and a caller-supplied phase (e.g. "cold"
+ * or "warm"). Events are emitted as prefixed NDJSON on stdout so the
+ * harness can capture them from both Node and workerd — workerd has no
+ * filesystem access, but `console.log` is portable.
+ *
+ * The recorder lives on the request context (AsyncLocalStorage). The
+ * Kysely `log` hook reads the recorder at query time and appends an
+ * event. When no recorder is attached, the hook is a null check.
+ */
+
+import type { LogEvent, Logger } from "kysely";
+
+import { getRequestContext } from "../request-context.js";
+
+export const QUERY_LOG_ENV = "EMDASH_QUERY_LOG";
+export const QUERY_LOG_PREFIX = "[emdash-query-log]";
+
+export interface QueryEvent {
+	sql: string;
+	params: readonly unknown[];
+	durationMs: number;
+	route: string;
+	method: string;
+	phase: string;
+}
+
+export interface QueryRecorder {
+	events: QueryEvent[];
+	route: string;
+	method: string;
+	phase: string;
+}
+
+export function createRecorder(route: string, method: string, phase: string): QueryRecorder {
+	return { events: [], route, method, phase };
+}
+
+export function recordEvent(
+	rec: QueryRecorder,
+	sql: string,
+	params: readonly unknown[],
+	durationMs: number,
+): void {
+	rec.events.push({
+		sql,
+		params,
+		durationMs,
+		route: rec.route,
+		method: rec.method,
+		phase: rec.phase,
+	});
+}
+
+/**
+ * Emit all events from a recorder as prefixed NDJSON on stdout. The
+ * harness pipes the child's stdout, filters lines beginning with
+ * QUERY_LOG_PREFIX, and writes them to its own file. Using stdout means
+ * the sink works uniformly in Node and in workerd (which has no fs).
+ */
+export function flushRecorder(rec: QueryRecorder): void {
+	if (rec.events.length === 0) return;
+	for (const e of rec.events) {
+		console.log(`${QUERY_LOG_PREFIX} ${JSON.stringify(e)}`);
+	}
+}
+
+/**
+ * Whether query instrumentation is enabled. Read at Kysely construction
+ * time and middleware entry — the env var is a process-lifetime flag, not
+ * per-request. Gated via `process.env` so adapters that ship env through
+ * to the worker (e.g. Miniflare via wrangler.jsonc `vars` or host env
+ * pass-through) can enable it at runtime.
+ */
+export function isInstrumentationEnabled(): boolean {
+	return Boolean(
+		typeof process !== "undefined" && process.env && process.env[QUERY_LOG_ENV] === "1",
+	);
+}
+
+function kyselyLog(event: LogEvent): void {
+	if (event.level !== "query") return;
+	const rec = getRequestContext()?.queryRecorder;
+	if (!rec) return;
+	recordEvent(rec, event.query.sql, event.query.parameters, event.queryDurationMillis);
+}
+
+/**
+ * Returns a Kysely `log` option when instrumentation is enabled, or undefined.
+ * Pass as `new Kysely({ dialect, log: kyselyLogOption() })` so disabled mode
+ * has zero overhead — Kysely skips query timing entirely when `log` is absent.
+ */
+export function kyselyLogOption(): Logger | undefined {
+	return isInstrumentationEnabled() ? kyselyLog : undefined;
+}

package/src/database/migrations/035_bounded_404_log.ts

@@ -0,0 +1,112 @@
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+/**
+ * Migration: Bounded 404 logging
+ *
+ * Hardens `_emdash_404_log` against unauthenticated DoS. Previously every 404
+ * inserted a new row, so an attacker could grow the table without bound.
+ *
+ * Changes:
+ *   - Adds `hits` (default 1, NOT NULL)
+ *   - Adds `last_seen_at` (nullable; SQLite can't add NOT NULL with a
+ *     non-constant default to a populated table, so the column is nullable
+ *     at the schema level and backfilled from `created_at` for existing rows;
+ *     new inserts via `log404` always set it)
+ *   - Deduplicates existing rows by path, keeping the most recent row per
+ *     path and summing hits
+ *   - Adds a UNIQUE index on `path` so upsert semantics work
+ */
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+	// 1. Add columns.
+	await db.schema
+		.alterTable("_emdash_404_log")
+		.addColumn("hits", "integer", (col) => col.notNull().defaultTo(1))
+		.execute();
+
+	// SQLite won't accept a non-constant default when adding a NOT NULL column
+	// to a table with existing rows, so backfill in two steps: add nullable,
+	// populate, then rely on the application layer / future inserts to set it.
+	await db.schema.alterTable("_emdash_404_log").addColumn("last_seen_at", "text").execute();
+
+	// Backfill last_seen_at from created_at for existing rows.
+	await sql`
+		UPDATE _emdash_404_log
+		SET last_seen_at = created_at
+		WHERE last_seen_at IS NULL
+	`.execute(db);
+
+	// 2. Deduplicate existing rows by path.
+	//    For each path, roll up hits and pick the freshest last_seen_at onto
+	//    a single keeper row, then delete the non-keepers. Uses window
+	//    functions (ROW_NUMBER) so the dedup SQL is valid on both SQLite
+	//    (3.25+, 2018) and Postgres. The previous GROUP BY approach was
+	//    accepted by SQLite but invalid on Postgres because `id` wasn't in
+	//    the GROUP BY or wrapped in an aggregate.
+	await sql`
+		WITH ranked AS (
+			SELECT
+				id,
+				path,
+				ROW_NUMBER() OVER (
+					PARTITION BY path
+					ORDER BY created_at DESC, id DESC
+				) AS rn,
+				COUNT(*) OVER (PARTITION BY path) AS path_count,
+				MAX(created_at) OVER (PARTITION BY path) AS latest_created_at
+			FROM _emdash_404_log
+		)
+		UPDATE _emdash_404_log
+		SET
+			hits = (SELECT path_count FROM ranked WHERE ranked.id = _emdash_404_log.id),
+			last_seen_at = (SELECT latest_created_at FROM ranked WHERE ranked.id = _emdash_404_log.id)
+		WHERE id IN (SELECT id FROM ranked WHERE rn = 1)
+	`.execute(db);
+
+	// Delete the non-keepers (every row except the freshest per path).
+	await sql`
+		DELETE FROM _emdash_404_log
+		WHERE id IN (
+			SELECT id FROM (
+				SELECT
+					id,
+					ROW_NUMBER() OVER (
+						PARTITION BY path
+						ORDER BY created_at DESC, id DESC
+					) AS rn
+				FROM _emdash_404_log
+			) AS ranked
+			WHERE rn > 1
+		)
+	`.execute(db);
+
+	// 3. Add unique index on path for upsert semantics.
+	await db.schema
+		.createIndex("idx_404_log_path_unique")
+		.on("_emdash_404_log")
+		.column("path")
+		.unique()
+		.execute();
+
+	// Drop the old non-unique index; the unique one covers the same lookups.
+	await db.schema.dropIndex("idx_404_log_path").execute();
+
+	// 4. Index on last_seen_at for eviction ordering.
+	await db.schema
+		.createIndex("idx_404_log_last_seen")
+		.on("_emdash_404_log")
+		.column("last_seen_at")
+		.execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await db.schema.dropIndex("idx_404_log_last_seen").execute();
+	await db.schema.dropIndex("idx_404_log_path_unique").execute();
+
+	// Restore the original non-unique path index.
+	await db.schema.createIndex("idx_404_log_path").on("_emdash_404_log").column("path").execute();
+
+	await db.schema.alterTable("_emdash_404_log").dropColumn("last_seen_at").execute();
+	await db.schema.alterTable("_emdash_404_log").dropColumn("hits").execute();
+}

package/src/database/migrations/runner.ts

@@ -35,6 +35,7 @@ import * as m031 from "./031_bylines.js";
 import * as m032 from "./032_rate_limits.js";
 import * as m033 from "./033_optimize_content_indexes.js";
 import * as m034 from "./034_published_at_index.js";
+import * as m035 from "./035_bounded_404_log.js";
 
 const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"001_initial": m001,
@@ -70,6 +71,7 @@ const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"032_rate_limits": m032,
 	"033_optimize_content_indexes": m033,
 	"034_published_at_index": m034,
+	"035_bounded_404_log": m035,
 });
 
 /** Total number of registered migrations. Exported for use in tests. */

package/src/database/repositories/content.ts

@@ -1031,6 +1031,45 @@ export class ContentRepository {
 		return updated;
 	}
 
+	/**
+	 * Set the draft revision pointer for a content item.
+	 *
+	 * Used by seed/import paths that stage a new revision's data before
+	 * promoting it to live via `publish()`.
+	 *
+	 * Validates that the content item exists and is not soft-deleted, that
+	 * the revision exists, and that the revision belongs to the same
+	 * collection and entry. Without these checks, a caller could leave the
+	 * content row pointing at a missing or unrelated revision.
+	 */
+	async setDraftRevision(type: string, id: string, revisionId: string): Promise<void> {
+		const tableName = getTableName(type);
+		const now = new Date().toISOString();
+
+		const existing = await this.findById(type, id);
+		if (!existing) {
+			throw new EmDashValidationError("Content item not found");
+		}
+
+		const revisionRepo = new RevisionRepository(this.db);
+		const revision = await revisionRepo.findById(revisionId);
+		if (!revision) {
+			throw new EmDashValidationError("Revision not found");
+		}
+
+		if (revision.collection !== type || revision.entryId !== id) {
+			throw new EmDashValidationError("Revision does not belong to the specified content item");
+		}
+
+		await sql`
+			UPDATE ${sql.ref(tableName)}
+			SET draft_revision_id = ${revisionId},
+				updated_at = ${now}
+			WHERE id = ${id}
+			AND deleted_at IS NULL
+		`.execute(this.db);
+	}
+
 	/**
 	 * Discard pending draft changes
 	 *

package/src/database/repositories/options.ts

@@ -55,6 +55,31 @@ export class OptionsRepository {
 			.execute();
 	}
 
+	/**
+	 * Set an option value only if no row with that name exists. Atomic at the
+	 * database level via INSERT ... ON CONFLICT DO NOTHING, so concurrent
+	 * callers can't race past the check.
+	 *
+	 * Returns true when the row was inserted, false when a row already
+	 * existed (regardless of its value — even an empty string or null).
+	 */
+	async setIfAbsent<T = unknown>(name: string, value: T): Promise<boolean> {
+		const row: OptionTable = {
+			name,
+			value: JSON.stringify(value),
+		};
+
+		const result = await this.db
+			.insertInto("options")
+			.values(row)
+			.onConflict((oc) => oc.column("name").doNothing())
+			.executeTakeFirst();
+
+		// SQLite reports numInsertedOrUpdatedRows; Postgres reports the same.
+		// When the ON CONFLICT branch fires and does nothing, the count is 0.
+		return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
+	}
+
 	/**
 	 * Delete an option
 	 */