emdash 0.34.0 → 0.36.0

package/src/migrations/manifest.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+import type { CoreMigrationIdentity } from "./identity.js";
+import { fingerprintMigrationSet } from "./identity.js";
+
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const MIGRATION_NAME_PATTERN = /^\d{3}_[a-z0-9_]+$/;
+const EXECUTOR_ENTRYPOINT_PATTERN =
+	/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+const ENVIRONMENT_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENVIRONMENT_REFERENCE_KEY_PATTERN = /(?:env|envName|envVar)$/i;
+const URL_SCHEME_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const SECRET_QUERY_KEY_PATTERN = /(?:auth|credential|key|password|secret|signature|token)/i;
+const SECRET_CONFIG_KEY_PATTERN =
+	/(?:accessToken|apiKey|authToken|certificate|connectionString|password|privateKey|secret)/i;
+const SECRET_CONFIG_EXACT_KEY_PATTERN = /^(?:ca|cert|key)$/i;
+const CONNECTION_URL_PROTOCOLS = new Set(["mysql:", "postgres:", "postgresql:"]);
+
+type JsonPrimitive = boolean | number | string | null;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+const i18nConfigSchema = z
+	.object({
+		defaultLocale: z.string().min(1),
+		locales: z.array(z.string().min(1)).min(1),
+		fallback: z.record(z.string(), z.string()).optional(),
+		prefixDefaultLocale: z.boolean().optional(),
+	})
+	.strict();
+
+export const migrationManifestV1Schema = z
+	.object({
+		schemaVersion: z.literal(1),
+		emdashVersion: z.string().min(1),
+		migrationSet: z
+			.object({
+				names: z
+					.array(z.string().regex(MIGRATION_NAME_PATTERN))
+					.min(1)
+					.refine((names) => new Set(names).size === names.length),
+				fingerprint: z.string().regex(FINGERPRINT_PATTERN),
+			})
+			.strict(),
+		i18n: i18nConfigSchema.nullable(),
+		database: z
+			.object({
+				type: z.enum(["sqlite", "postgres"]),
+				executorEntrypoint: z.string().regex(EXECUTOR_ENTRYPOINT_PATTERN),
+				executorConfig: z.unknown(),
+			})
+			.strict(),
+	})
+	.strict();
+
+export type MigrationManifestV1 = z.infer<typeof migrationManifestV1Schema>;
+
+export class MigrationManifestValidationError extends Error {
+	constructor(message: string) {
+		super(`Invalid migration manifest: ${message}`);
+		this.name = "MigrationManifestValidationError";
+	}
+}
+
+function isEnvironmentReferenceKey(key: string): boolean {
+	return ENVIRONMENT_REFERENCE_KEY_PATTERN.test(key);
+}
+
+function assertSafeUrl(value: string, path: string): void {
+	if (!URL_SCHEME_PATTERN.test(value)) return;
+
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new MigrationManifestValidationError(`${path} contains an invalid URL`);
+	}
+
+	if (CONNECTION_URL_PROTOCOLS.has(url.protocol)) {
+		throw new MigrationManifestValidationError(`${path} contains a database connection URL`);
+	}
+	if (url.username || url.password) {
+		throw new MigrationManifestValidationError(`${path} contains URL credentials`);
+	}
+	for (const key of url.searchParams.keys()) {
+		if (SECRET_QUERY_KEY_PATTERN.test(key)) {
+			throw new MigrationManifestValidationError(`${path} contains a credential query parameter`);
+		}
+	}
+}
+
+function cloneSecretFreeJson(value: unknown, path: string, ancestors: Set<object>): JsonValue {
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		assertSafeUrl(value, path);
+		return value;
+	}
+	if (typeof value === "number") {
+		if (Number.isFinite(value)) return value;
+		throw new MigrationManifestValidationError(`${path} contains a non-finite number`);
+	}
+	if (typeof value !== "object") {
+		throw new MigrationManifestValidationError(`${path} is not JSON-serializable`);
+	}
+	if (ancestors.has(value)) {
+		throw new MigrationManifestValidationError(`${path} contains a cycle`);
+	}
+
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			return value.map((item, index) => cloneSecretFreeJson(item, `${path}[${index}]`, ancestors));
+		}
+
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new MigrationManifestValidationError(`${path} contains a non-plain object`);
+		}
+
+		const cloned: Record<string, JsonValue> = {};
+		for (const [key, item] of Object.entries(value)) {
+			const itemPath = `${path}.${key}`;
+			const environmentReference = isEnvironmentReferenceKey(key);
+			if (
+				!environmentReference &&
+				(SECRET_CONFIG_KEY_PATTERN.test(key) || SECRET_CONFIG_EXACT_KEY_PATTERN.test(key))
+			) {
+				throw new MigrationManifestValidationError(`${itemPath} is a credential-bearing field`);
+			}
+			if (environmentReference) {
+				if (typeof item !== "string" || !ENVIRONMENT_VARIABLE_PATTERN.test(item)) {
+					throw new MigrationManifestValidationError(
+						`${itemPath} must contain an environment-variable name`,
+					);
+				}
+			}
+			cloned[key] = cloneSecretFreeJson(item, itemPath, ancestors);
+		}
+		return cloned;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+
+export function validateSecretFreeExecutorConfig(
+	value: unknown,
+	path = "database.executorConfig",
+): unknown {
+	return cloneSecretFreeJson(value, path, new Set());
+}
+
+function identitiesMatch(
+	manifest: MigrationManifestV1,
+	expectedIdentity: CoreMigrationIdentity,
+): boolean {
+	return (
+		manifest.emdashVersion === expectedIdentity.emdashVersion &&
+		manifest.migrationSet.fingerprint === expectedIdentity.fingerprint &&
+		manifest.migrationSet.names.length === expectedIdentity.names.length &&
+		manifest.migrationSet.names.every((name, index) => name === expectedIdentity.names[index])
+	);
+}
+
+export async function validateMigrationManifest(
+	value: unknown,
+	expectedIdentity?: CoreMigrationIdentity,
+): Promise<MigrationManifestV1> {
+	const parsed = migrationManifestV1Schema.safeParse(value);
+	if (!parsed.success) {
+		throw new MigrationManifestValidationError("schema validation failed");
+	}
+
+	const executorConfig = validateSecretFreeExecutorConfig(parsed.data.database.executorConfig);
+	const manifest: MigrationManifestV1 = {
+		...parsed.data,
+		database: { ...parsed.data.database, executorConfig },
+	};
+	const fingerprint = await fingerprintMigrationSet(
+		manifest.emdashVersion,
+		manifest.migrationSet.names,
+	);
+	if (fingerprint !== manifest.migrationSet.fingerprint) {
+		throw new MigrationManifestValidationError(
+			"migrationSet fingerprint does not match its version and ordered names",
+		);
+	}
+	if (expectedIdentity && !identitiesMatch(manifest, expectedIdentity)) {
+		throw new MigrationManifestValidationError(
+			"manifest does not match the loaded EmDash migration identity",
+		);
+	}
+
+	return manifest;
+}
+
+export function serializeMigrationManifest(manifest: MigrationManifestV1): string {
+	return `${JSON.stringify(manifest, null, "\t")}\n`;
+}

package/src/migrations/protocol.ts

@@ -0,0 +1,59 @@
+import type { I18nConfig } from "../i18n/config.js";
+
+export type MigrationAction = "check" | "apply";
+
+export interface MigrationRequest {
+	action: MigrationAction;
+	i18n: I18nConfig | null;
+	artifact: {
+		emdashVersion: string;
+		migrationSetFingerprint: string;
+	};
+}
+
+export interface MigrationTarget {
+	kind: string;
+	label: string;
+	fingerprint: string;
+	accountId?: string;
+	environment?: string;
+	resourceId?: string;
+}
+
+export interface MigrationReport {
+	target: MigrationTarget;
+	knownApplied: string[];
+	pending: string[];
+	unknownApplied: string[];
+	executed: string[];
+}
+
+export interface MigrationExecutor {
+	target: MigrationTarget;
+	execute(request: MigrationRequest): Promise<MigrationReport>;
+	dispose?(): Promise<void>;
+}
+
+export interface MigrationTargetOverrides {
+	database?: string;
+	databaseUrlEnv?: string;
+	d1?: string;
+	accountId?: string;
+	wranglerConfig?: string;
+	wranglerEnv?: string;
+}
+
+export interface MigrationExecutorFactoryContext {
+	projectRoot: string;
+	env: Readonly<Record<string, string | undefined>>;
+	overrides?: Readonly<MigrationTargetOverrides>;
+}
+
+export type MigrationExecutorFactory<ManifestConfig = unknown> = (
+	manifestConfig: ManifestConfig,
+	context: MigrationExecutorFactoryContext,
+) => MigrationExecutor | Promise<MigrationExecutor>;
+
+export interface MigrationExecutorModule<ManifestConfig = unknown> {
+	createMigrationExecutor: MigrationExecutorFactory<ManifestConfig>;
+}

package/src/migrations/target.ts

@@ -0,0 +1,35 @@
+import type { MigrationTarget } from "./protocol.js";
+
+const ENVIRONMENT_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function encodeHex(bytes: Uint8Array): string {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function createMigrationTarget(
+	kind: string,
+	label: string,
+	identity: readonly string[],
+): Promise<MigrationTarget> {
+	const encoded = new TextEncoder().encode(JSON.stringify({ kind, identity }));
+	const digest = await crypto.subtle.digest("SHA-256", encoded);
+	return {
+		kind,
+		label,
+		fingerprint: encodeHex(new Uint8Array(digest)),
+	};
+}
+
+export function requireMigrationEnvironment(
+	name: unknown,
+	env: Readonly<Record<string, string | undefined>>,
+): string {
+	if (typeof name !== "string" || !ENVIRONMENT_VARIABLE_PATTERN.test(name)) {
+		throw new Error("Migration credential environment variable name is invalid.");
+	}
+	const value = env[name];
+	if (!value) {
+		throw new Error(`Migration credential environment variable ${name} is not set.`);
+	}
+	return value;
+}

package/src/plugins/index.ts

@@ -44,6 +44,7 @@ export type { PluginContextFactoryOptions } from "./context.js";
 // Hooks
 export { HookPipeline, createHookPipeline } from "./hooks.js";
 export type { HookResult } from "./hooks.js";
+export { ContentSaveRejectedError, isContentSaveRejection } from "./save-rejection.js";
 
 // Email pipeline
 export { EmailPipeline, EmailNotConfiguredError, EmailRecursionError } from "./email.js";

package/src/plugins/save-rejection.ts

@@ -0,0 +1,20 @@
+/**
+ * Thrown by a `content:beforeSave` hook to reject a save with a message
+ * that is safe to show to the editor. The runtime converts it into a
+ * structured `SAVE_REJECTED` API error; any other exception thrown by the
+ * hook cancels the save with a generic error that hides the exception
+ * message.
+ */
+export class ContentSaveRejectedError extends Error {
+	override readonly name = "ContentSaveRejectedError";
+}
+
+/**
+ * Matches by name as well as by prototype: bundlers can duplicate this
+ * module across SSR chunks, and an `instanceof` against the wrong copy of
+ * the class would misreport a rejection as a plugin crash.
+ */
+export function isContentSaveRejection(error: unknown): error is ContentSaveRejectedError {
+	if (error instanceof ContentSaveRejectedError) return true;
+	return error instanceof Error && error.name === "ContentSaveRejectedError";
+}

package/src/plugins/scheduler/node.ts

@@ -29,7 +29,6 @@ export class NodeCronScheduler implements CronScheduler {
 	private timer: ReturnType<typeof setTimeout> | null = null;
 	private running = false;
 	private systemCleanup: SystemCleanupFn | null = null;
-	private mediaUsageMaintenance: SystemCleanupFn | null = null;
 
 	constructor(private executor: CronExecutor) {}
 
@@ -37,10 +36,6 @@ export class NodeCronScheduler implements CronScheduler {
 		this.systemCleanup = fn;
 	}
 
-	setMediaUsageMaintenance(fn: SystemCleanupFn): void {
-		this.mediaUsageMaintenance = fn;
-	}
-
 	start(): void {
 		this.running = true;
 		this.arm();
@@ -117,19 +112,12 @@ export class NodeCronScheduler implements CronScheduler {
 		}
 
 		void Promise.allSettled(tasks)
-			.then(async (results) => {
+			.then((results) => {
 				for (const r of results) {
 					if (r.status === "rejected") {
 						console.error("[cron:node] Tick task failed:", r.reason);
 					}
 				}
-				if (this.mediaUsageMaintenance) {
-					try {
-						await this.mediaUsageMaintenance();
-					} catch (error) {
-						console.error("[cron:node] Media Usage maintenance failed:", error);
-					}
-				}
 				return undefined;
 			})
 			.finally(() => {

package/src/plugins/scheduler/types.ts

@@ -18,8 +18,6 @@ export interface CronScheduler {
 	reschedule(): void;
 	/** Register a system cleanup function to run alongside each tick. */
 	setSystemCleanup(fn: SystemCleanupFn): void;
-	/** Register bounded Media Usage maintenance to run after the general tick settles. */
-	setMediaUsageMaintenance?(fn: SystemCleanupFn): void;
 }
 
 /**

package/src/plugins/state.ts

@@ -12,6 +12,16 @@ import type { Database } from "../database/types.js";
 export type PluginStatus = "active" | "inactive";
 export type PluginSource = "config" | "marketplace" | "registry";
 
+const TIMEZONE_SUFFIX = /(?:z|[+-]\d{2}(?::?\d{2})?)$/i;
+const HOUR_OFFSET_SUFFIX = /\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?[+-]\d{2}$/i;
+
+function parseDatabaseTimestamp(value: string): Date {
+	let normalized = value.trim().replace(" ", "T");
+	if (HOUR_OFFSET_SUFFIX.test(normalized)) normalized += ":00";
+	else if (!TIMEZONE_SUFFIX.test(normalized)) normalized += "Z";
+	return new Date(normalized);
+}
+
 function toPluginStatus(value: string): PluginStatus {
 	if (value === "active") return "active";
 	return "inactive";
@@ -255,9 +265,9 @@ function rowToPluginState(row: PluginStateRow): PluginState {
 		pluginId: row.plugin_id,
 		status: toPluginStatus(row.status),
 		version: row.version,
-		installedAt: new Date(row.installed_at),
-		activatedAt: row.activated_at ? new Date(row.activated_at) : null,
-		deactivatedAt: row.deactivated_at ? new Date(row.deactivated_at) : null,
+		installedAt: parseDatabaseTimestamp(row.installed_at),
+		activatedAt: row.activated_at ? parseDatabaseTimestamp(row.activated_at) : null,
+		deactivatedAt: row.deactivated_at ? parseDatabaseTimestamp(row.deactivated_at) : null,
 		source: toPluginSource(row.source),
 		marketplaceVersion: row.marketplace_version ?? null,
 		displayName: row.display_name ?? null,