emdash 0.40.1 → 0.41.0

package/dist/transport-DhlZlf4D.d.mts

@@ -0,0 +1,42 @@
+//#region src/client/transport.d.ts
+/**
+ * Transport layer for the EmDash client.
+ *
+ * Implements a composable interceptor pipeline that modifies requests
+ * and responses. The client calls `transport.fetch(request)` — everything
+ * else (auth, CSRF, retry) is handled by interceptors.
+ */
+/**
+ * An interceptor can modify the request, call next(), inspect
+ * the response, and optionally retry.
+ */
+type Interceptor = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+interface TransportOptions {
+  interceptors?: Interceptor[];
+}
+/**
+ * Creates a fetch function that runs requests through an interceptor pipeline.
+ */
+declare function createTransport(options?: TransportOptions): {
+  fetch: (request: Request) => Promise<Response>;
+};
+/**
+ * Adds X-EmDash-Request: 1 and Origin headers to mutation requests
+ * (POST, PUT, DELETE). The custom header satisfies EmDash's CSRF check;
+ * the Origin header satisfies Astro's built-in origin verification which
+ * rejects server-side POST requests that lack a matching Origin.
+ */
+declare function csrfInterceptor(): Interceptor;
+/**
+ * Adds Authorization: Bearer header from a static token.
+ */
+declare function tokenInterceptor(token: string): Interceptor;
+/**
+ * Dev bypass interceptor. Calls the dev-bypass endpoint on first request
+ * to establish a session, then forwards the session cookie on subsequent
+ * requests.
+ */
+declare function devBypassInterceptor(baseUrl: string): Interceptor;
+//#endregion
+export { tokenInterceptor as a, devBypassInterceptor as i, createTransport as n, csrfInterceptor as r, Interceptor as t };
+//# sourceMappingURL=transport-DhlZlf4D.d.mts.map

package/dist/transport-DhlZlf4D.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-DhlZlf4D.d.mts","names":[],"sources":["../src/client/transport.ts"],"mappings":";;AAeA;;;;;;;;;;KAAY,WAAA,IACX,OAAA,EAAS,OAAA,EACT,IAAA,GAAO,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA,MAChC,OAAA,CAAQ,QAAA;AAAA,UAEI,gBAAA;EAChB,YAAA,GAAe,WAAA;AAAA;;;;iBAUA,eAAA,CAAgB,OAAA,GAAS,gBAAA;EACxC,KAAA,GAAQ,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;AAAA;;;AAZtC;;;;iBAqCgB,eAAA,CAAA,GAAmB,WAAA;AA1BnC;;;AAAA,iBA8CgB,gBAAA,CAAiB,KAAA,WAAgB,WAAA;;;;;;iBAajC,oBAAA,CAAqB,OAAA,WAAkB,WAAA"}

package/dist/trusted-proxy-B6ECOZJc.mjs

@@ -0,0 +1,51 @@
+//#region src/auth/trusted-proxy.ts
+/**
+* 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.
+*/
+function normalizeTrustedHeaders(names) {
+	return names.map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && HEADER_NAME_PATTERN.test(h));
+}
+function isValidHeaderName(name) {
+	return HEADER_NAME_PATTERN.test(name);
+}
+/** Cache for the env-derived value. `null` means "not yet parsed". */
+let _envCache = null;
+function getEnvTrustedHeaders() {
+	if (_envCache !== null) return _envCache;
+	let raw;
+	try {
+		const importMetaEnv = import.meta.env;
+		raw = (typeof process !== "undefined" ? process.env?.EMDASH_TRUSTED_PROXY_HEADERS : void 0) || importMetaEnv?.EMDASH_TRUSTED_PROXY_HEADERS;
+	} catch {
+		raw = void 0;
+	}
+	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 `[]`.
+*/
+function getTrustedProxyHeaders(config) {
+	if (config && config.trustedProxyHeaders !== void 0) return config.trustedProxyHeaders.map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && isValidHeaderName(h));
+	return getEnvTrustedHeaders();
+}
+
+//#endregion
+export { normalizeTrustedHeaders as n, getTrustedProxyHeaders as t };
+//# sourceMappingURL=trusted-proxy-B6ECOZJc.mjs.map

package/dist/trusted-proxy-B6ECOZJc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-proxy-B6ECOZJc.mjs","names":[],"sources":["../src/auth/trusted-proxy.ts"],"sourcesContent":["/**\n * Resolve the list of client-IP headers the operator trusts.\n *\n * Resolution order:\n *   1. `config.trustedProxyHeaders` — explicit opt-in via astro.config.mjs.\n *      An empty array is respected (means \"trust nothing, ignore env\").\n *   2. `EMDASH_TRUSTED_PROXY_HEADERS` env var — comma-separated header names.\n *   3. `[]` — default, no trusted headers.\n *\n * Operators must only set this when they control the reverse proxy.\n * Untrusted clients can set any header they like; trusting headers from\n * an open network defeats rate limiting.\n *\n * Header names are returned lowercased because HTTP header lookups are\n * case-insensitive.\n */\n\nimport type { EmDashConfig } from \"../astro/integration/runtime.js\";\n\n/**\n * RFC 7230 token — valid characters for an HTTP header name. Invalid names\n * passed to `Headers.get()` throw a TypeError at runtime, which would\n * otherwise surface as a 500 from every auth route.\n */\nconst HEADER_NAME_PATTERN = /^[!#$%&'*+\\-.^_`|~0-9a-z]+$/;\n\n/**\n * Normalise a list of header names the way both the config path and any\n * caller passing a pre-resolved list should do: trim, lowercase, drop\n * empty, drop anything that isn't a valid RFC 7230 token. Invalid names\n * would crash `Headers.get()` at runtime.\n */\nexport function normalizeTrustedHeaders(names: readonly string[]): string[] {\n\treturn names\n\t\t.map((h) => h.trim().toLowerCase())\n\t\t.filter((h) => h.length > 0 && HEADER_NAME_PATTERN.test(h));\n}\n\nfunction isValidHeaderName(name: string): boolean {\n\treturn HEADER_NAME_PATTERN.test(name);\n}\n\n/** Cache for the env-derived value. `null` means \"not yet parsed\". */\nlet _envCache: string[] | null = null;\n\n/** Test-only: clear the env cache so a fresh value is read on next call. */\nexport function _resetTrustedProxyHeadersCache(): void {\n\t_envCache = null;\n}\n\nfunction getEnvTrustedHeaders(): string[] {\n\tif (_envCache !== null) return _envCache;\n\tlet raw: string | undefined;\n\ttry {\n\t\t// Prefer process.env so SSR/container deployments can override this\n\t\t// value at runtime (Vite/Astro inline import.meta.env at build time,\n\t\t// which locks the value into the bundle). Fall back to import.meta.env\n\t\t// for bundler-managed environments where process.env isn't populated.\n\t\t// eslint-disable-next-line typescript/no-unsafe-type-assertion -- import.meta.env shape varies by bundler\n\t\tconst importMetaEnv = (import.meta as unknown as { env?: Record<string, string | undefined> })\n\t\t\t.env;\n\t\traw =\n\t\t\t(typeof process !== \"undefined\" ? process.env?.EMDASH_TRUSTED_PROXY_HEADERS : undefined) ||\n\t\t\timportMetaEnv?.EMDASH_TRUSTED_PROXY_HEADERS;\n\t} catch {\n\t\traw = undefined;\n\t}\n\tif (!raw) {\n\t\t_envCache = [];\n\t\treturn _envCache;\n\t}\n\t_envCache = raw\n\t\t.split(\",\")\n\t\t.map((s) => s.trim().toLowerCase())\n\t\t.filter((s) => s.length > 0 && isValidHeaderName(s));\n\treturn _envCache;\n}\n\n/**\n * Return the lowercased list of headers to trust for client-IP resolution.\n *\n * When `config?.trustedProxyHeaders` is explicitly set (even to `[]`), it\n * wins. Otherwise fall through to the env var, then to `[]`.\n */\nexport function getTrustedProxyHeaders(config: EmDashConfig | null | undefined): string[] {\n\tif (config && config.trustedProxyHeaders !== undefined) {\n\t\treturn config.trustedProxyHeaders\n\t\t\t.map((h) => h.trim().toLowerCase())\n\t\t\t.filter((h) => h.length > 0 && isValidHeaderName(h));\n\t}\n\treturn getEnvTrustedHeaders();\n}\n"],"mappings":";;;;;;AAwBA,MAAM,sBAAsB;;;;;;;AAQ5B,SAAgB,wBAAwB,OAAoC;AAC3E,QAAO,MACL,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,oBAAoB,KAAK,EAAE,CAAC;;AAG7D,SAAS,kBAAkB,MAAuB;AACjD,QAAO,oBAAoB,KAAK,KAAK;;;AAItC,IAAI,YAA6B;AAOjC,SAAS,uBAAiC;AACzC,KAAI,cAAc,KAAM,QAAO;CAC/B,IAAI;AACJ,KAAI;EAMH,MAAM,gBAAiB,OAAO,KAC5B;AACF,SACE,OAAO,YAAY,cAAc,QAAQ,KAAK,+BAA+B,WAC9E,eAAe;SACT;AACP,QAAM;;AAEP,KAAI,CAAC,KAAK;AACT,cAAY,EAAE;AACd,SAAO;;AAER,aAAY,IACV,MAAM,IAAI,CACV,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,kBAAkB,EAAE,CAAC;AACrD,QAAO;;;;;;;;AASR,SAAgB,uBAAuB,QAAmD;AACzF,KAAI,UAAU,OAAO,wBAAwB,OAC5C,QAAO,OAAO,oBACZ,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,kBAAkB,EAAE,CAAC;AAEtD,QAAO,sBAAsB"}

package/dist/turnstile-lqUiY7lP.mjs

@@ -0,0 +1,53 @@
+//#region src/comments/turnstile.ts
+/**
+* Server-side Turnstile verification for public comment submissions.
+*
+* The comment form widget (`CommentForm.astro`) submits a `turnstileToken`;
+* this verifies it against Cloudflare's siteverify API. Enforcement is
+* opt-in: it only runs when the operator configures the Turnstile secret
+* key (`EMDASH_TURNSTILE_SECRET_KEY` or `TURNSTILE_SECRET_KEY`), so
+* existing non-Turnstile sites are unaffected.
+*
+* Mirrors `verifyTurnstile` in `@emdash-cms/plugin-forms` (not imported —
+* core doesn't depend on plugin packages).
+*/
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/**
+* Resolve the configured Turnstile secret key, or `""` when Turnstile
+* enforcement is not configured.
+*/
+function getTurnstileSecretKey() {
+	return import.meta.env.EMDASH_TURNSTILE_SECRET_KEY || import.meta.env.TURNSTILE_SECRET_KEY || "";
+}
+/**
+* Verify a Turnstile response token via siteverify.
+*
+* Fails closed: a missing token, a failed verification, and a siteverify
+* transport error all return `false` — when the operator has configured a
+* secret, an unverifiable submission must not be persisted.
+*/
+async function verifyTurnstileToken(token, secretKey, remoteIp) {
+	if (!token) return false;
+	const body = {
+		secret: secretKey,
+		response: token
+	};
+	if (remoteIp) body.remoteip = remoteIp;
+	try {
+		const data = await (await fetch(SITEVERIFY_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(1e4)
+		})).json();
+		if (!data.success) console.warn("[comments] Turnstile verification failed:", data["error-codes"] ?? []);
+		return data.success === true;
+	} catch (error) {
+		console.error("[comments] Turnstile siteverify request failed:", error instanceof Error ? error.message : error);
+		return false;
+	}
+}
+
+//#endregion
+export { getTurnstileSecretKey, verifyTurnstileToken };
+//# sourceMappingURL=turnstile-lqUiY7lP.mjs.map

package/dist/turnstile-lqUiY7lP.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile-lqUiY7lP.mjs","names":[],"sources":["../src/comments/turnstile.ts"],"sourcesContent":["/**\n * Server-side Turnstile verification for public comment submissions.\n *\n * The comment form widget (`CommentForm.astro`) submits a `turnstileToken`;\n * this verifies it against Cloudflare's siteverify API. Enforcement is\n * opt-in: it only runs when the operator configures the Turnstile secret\n * key (`EMDASH_TURNSTILE_SECRET_KEY` or `TURNSTILE_SECRET_KEY`), so\n * existing non-Turnstile sites are unaffected.\n *\n * Mirrors `verifyTurnstile` in `@emdash-cms/plugin-forms` (not imported —\n * core doesn't depend on plugin packages).\n */\n\nconst SITEVERIFY_URL = \"https://challenges.cloudflare.com/turnstile/v0/siteverify\";\n\n/**\n * Resolve the configured Turnstile secret key, or `\"\"` when Turnstile\n * enforcement is not configured.\n */\nexport function getTurnstileSecretKey(): string {\n\treturn import.meta.env.EMDASH_TURNSTILE_SECRET_KEY || import.meta.env.TURNSTILE_SECRET_KEY || \"\";\n}\n\n/**\n * Verify a Turnstile response token via siteverify.\n *\n * Fails closed: a missing token, a failed verification, and a siteverify\n * transport error all return `false` — when the operator has configured a\n * secret, an unverifiable submission must not be persisted.\n */\nexport async function verifyTurnstileToken(\n\ttoken: string | undefined,\n\tsecretKey: string,\n\tremoteIp?: string | null,\n): Promise<boolean> {\n\tif (!token) return false;\n\n\tconst body: Record<string, string> = { secret: secretKey, response: token };\n\tif (remoteIp) {\n\t\tbody.remoteip = remoteIp;\n\t}\n\n\ttry {\n\t\tconst res = await fetch(SITEVERIFY_URL, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"Content-Type\": \"application/json\" },\n\t\t\tbody: JSON.stringify(body),\n\t\t\t// Fail closed *quickly* if siteverify is slow — without a timeout\n\t\t\t// the comment POST would hang until the runtime kills it\n\t\t\tsignal: AbortSignal.timeout(10_000),\n\t\t});\n\t\tconst data: { success?: boolean; \"error-codes\"?: string[] } = await res.json();\n\t\tif (!data.success) {\n\t\t\tconsole.warn(\"[comments] Turnstile verification failed:\", data[\"error-codes\"] ?? []);\n\t\t}\n\t\treturn data.success === true;\n\t} catch (error) {\n\t\tconsole.error(\n\t\t\t\"[comments] Turnstile siteverify request failed:\",\n\t\t\terror instanceof Error ? error.message : error,\n\t\t);\n\t\treturn false;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAM,iBAAiB;;;;;AAMvB,SAAgB,wBAAgC;AAC/C,QAAO,OAAO,KAAK,IAAI,+BAA+B,OAAO,KAAK,IAAI,wBAAwB;;;;;;;;;AAU/F,eAAsB,qBACrB,OACA,WACA,UACmB;AACnB,KAAI,CAAC,MAAO,QAAO;CAEnB,MAAM,OAA+B;EAAE,QAAQ;EAAW,UAAU;EAAO;AAC3E,KAAI,SACH,MAAK,WAAW;AAGjB,KAAI;EASH,MAAM,OAAwD,OARlD,MAAM,MAAM,gBAAgB;GACvC,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAC/C,MAAM,KAAK,UAAU,KAAK;GAG1B,QAAQ,YAAY,QAAQ,IAAO;GACnC,CAAC,EACsE,MAAM;AAC9E,MAAI,CAAC,KAAK,QACT,SAAQ,KAAK,6CAA6C,KAAK,kBAAkB,EAAE,CAAC;AAErF,SAAO,KAAK,YAAY;UAChB,OAAO;AACf,UAAQ,MACP,mDACA,iBAAiB,QAAQ,MAAM,UAAU,MACzC;AACD,SAAO"}

package/dist/types-4Dn9bZhu.mjs

@@ -0,0 +1,77 @@
+//#region src/plugins/sandbox/types.ts
+const SANDBOX_ROUTE_ERROR_DEFINITIONS = {
+	MEDIA_USAGE_ACTIVATION_IN_PROGRESS: {
+		message: "Media usage activation is in progress",
+		status: 503
+	},
+	MEDIA_USAGE_ACTIVATION_CHECK_FAILED: {
+		message: "Unable to verify media usage activation state",
+		status: 503
+	},
+	TRANSFER_IMPORT_IN_PROGRESS: {
+		message: "A site import is in progress or incomplete; writes are disabled",
+		status: 503
+	},
+	TRANSFER_FENCE_CHECK_FAILED: {
+		message: "Unable to verify whether site writes are allowed",
+		status: 503
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isSandboxRouteErrorCode(value) {
+	return typeof value === "string" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;
+}
+function getSandboxRouteErrorDetails(error) {
+	if (!isRecord(error)) return null;
+	const propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;
+	const nameCode = error instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;
+	if (propertyCode && nameCode && propertyCode !== nameCode) return null;
+	const code = propertyCode ?? nameCode;
+	if (!code || error.status !== void 0 && error.status !== 503) return null;
+	return {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code]
+	};
+}
+function createSandboxRouteError(code) {
+	const details = {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code]
+	};
+	return Object.assign(new Error(details.message), details, { name: code });
+}
+function createSandboxRouteErrorEnvelope(error) {
+	const details = getSandboxRouteErrorDetails(error);
+	return details ? {
+		__emdashSandboxRouteError: true,
+		error: details
+	} : null;
+}
+function getSandboxRouteErrorEnvelope(value) {
+	if (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;
+	const details = getSandboxRouteErrorDetails(value.error);
+	return details ? {
+		__emdashSandboxRouteError: true,
+		error: details
+	} : null;
+}
+function withUnavailableReason(message, runner) {
+	const reason = runner?.unavailableReason?.();
+	return reason ? `${message}: ${reason}` : message;
+}
+/**
+* Error thrown when the sandbox runtime is unavailable.
+* This happens when the sidecar process has crashed or hasn't started.
+*/
+var SandboxUnavailableError = class extends Error {
+	constructor(pluginId, reason) {
+		super(`Plugin sandbox unavailable for ${pluginId}: ${reason}`);
+		this.name = "SandboxUnavailableError";
+	}
+};
+
+//#endregion
+export { getSandboxRouteErrorEnvelope as a, getSandboxRouteErrorDetails as i, createSandboxRouteError as n, withUnavailableReason as o, createSandboxRouteErrorEnvelope as r, SandboxUnavailableError as t };
+//# sourceMappingURL=types-4Dn9bZhu.mjs.map

package/dist/types-4Dn9bZhu.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-4Dn9bZhu.mjs","names":[],"sources":["../src/plugins/sandbox/types.ts"],"sourcesContent":["/**\n * Plugin Sandbox Types\n *\n * Defines interfaces for running plugins in sandboxed V8 isolates.\n * The SandboxRunner interface is implemented by platform adapters\n * (e.g., Cloudflare Worker Loader) to provide isolation.\n *\n */\n\nimport type { PluginUiContext } from \"@emdash-cms/blocks/server\";\nimport type { Kysely } from \"kysely\";\n\nimport type { Database } from \"../../database/types.js\";\nimport type { ContentActionCallbacks } from \"../context.js\";\nimport type {\n\tContentCreateOptions,\n\tContentItem,\n\tContentWriteInput,\n\tPluginComment,\n\tPluginCommentStatus,\n\tPluginManifest,\n\tRequestMeta,\n\tTaxonomyAccessWithWrite,\n\tUserInfo,\n} from \"../types.js\";\n\n/**\n * Resource limits for sandboxed plugins.\n * Enforced by the sandbox runtime (e.g., Worker Loader).\n */\nexport interface ResourceLimits {\n\t/** CPU time per invocation in milliseconds (default: 50ms) */\n\tcpuMs?: number;\n\t/** Memory limit in MB (default: 128MB) */\n\tmemoryMb?: number;\n\t/** Maximum subrequests per invocation (default: 10) */\n\tsubrequests?: number;\n\t/** Wall-clock time limit in milliseconds (default: 30000ms) */\n\twallTimeMs?: number;\n}\n\n/**\n * Storage interface for loading plugin code.\n * Could be R2, local filesystem, or any other storage backend.\n */\nexport interface PluginCodeStorage {\n\t/** Get plugin bundle code by path */\n\tget(path: string): Promise<string | null>;\n\t/** Check if a bundle exists */\n\texists(path: string): Promise<boolean>;\n}\n\n/**\n * Serialized email message for sandbox RPC transport.\n * Matches the core EmailMessage type but uses only serializable fields.\n */\nexport interface SandboxEmailMessage {\n\tto: string;\n\tcc?: string[];\n\treplyTo?: string;\n\tsubject: string;\n\ttext: string;\n\thtml?: string;\n}\n\n/**\n * Callback for sending email from a sandboxed plugin.\n * The sandbox runner wires this up from the EmailPipeline.\n *\n * @param message - The email message to send\n * @param pluginId - The sending plugin's ID (used as source)\n */\nexport type SandboxEmailSendCallback = (\n\tmessage: SandboxEmailMessage,\n\tpluginId: string,\n) => Promise<void>;\n\nexport type SandboxCommentModerateCallback = (\n\tpluginId: string,\n\tid: string,\n\tstatus: PluginCommentStatus,\n\texpectedStatus: PluginCommentStatus,\n) => Promise<PluginComment>;\n\nexport type SandboxContentCreateCallback = (\n\tpluginId: string,\n\tcollection: string,\n\tdata: ContentWriteInput,\n\toptions?: ContentCreateOptions & {\n\t\toriginHook?: \"content:beforeSave\" | \"content:afterSave\";\n\t\tsandboxOrigin?: true;\n\t},\n) => Promise<ContentItem>;\n\nexport type SandboxHttpFetchCallback = typeof fetch;\n\n/**\n * Options for creating a sandbox runner\n */\nexport interface SandboxOptions {\n\t/** Storage interface for loading plugin code */\n\tstorage?: PluginCodeStorage;\n\t/** Database for bridge operations */\n\tdb: Kysely<Database>;\n\t/**\n\t * Called immediately before a sandboxed plugin content mutation; it throws\n\t * to refuse the write. When it returns a function, the bridge calls that\n\t * function once the write has succeeded.\n\t */\n\tbeforeContentWrite?: () => Promise<void | (() => Promise<void>)>;\n\t/** Runtime-owned taxonomy mutation surface used by sandbox bridges. */\n\ttaxonomyWrite?: TaxonomyAccessWithWrite;\n\tcontentActions?: ContentActionCallbacks;\n\t/** Clock used to calculate recurring plugin task schedules. */\n\tnow?: () => Date;\n\t/** Default resource limits */\n\tlimits?: ResourceLimits;\n\t/** Site info for plugin context (injected into wrapper at generation time) */\n\tsiteInfo?: {\n\t\tname: string;\n\t\turl: string;\n\t\tlocale: string;\n\t\ttrailingSlash?: \"always\" | \"never\" | \"ignore\";\n\t};\n\t/** Email send callback, wired from the EmailPipeline by the runtime */\n\temailSend?: SandboxEmailSendCallback;\n\tcommentModerate?: SandboxCommentModerateCallback;\n\t/** Optional host HTTP transport used by test hosts and custom runtimes. */\n\thttpFetch?: SandboxHttpFetchCallback;\n\t/**\n\t * Media storage adapter for sandboxed plugin byte reads, uploads, and deletes.\n\t * Each operation remains gated by its own media capability.\n\t */\n\tmediaStorage?: {\n\t\tupload(options: { key: string; body: Uint8Array; contentType: string }): Promise<unknown>;\n\t\tdownload(key: string): Promise<{\n\t\t\tbody: ReadableStream<Uint8Array>;\n\t\t\tcontentType: string;\n\t\t\tsize: number;\n\t\t}>;\n\t\tdelete(key: string): Promise<unknown>;\n\t};\n\t/** Worker Loader name suffix. The plugin's logical ID remains unchanged. */\n\tisolateKey?: string;\n}\n\n/**\n * Handle to a sandboxed plugin running inside an isolate. Returned\n * by `SandboxRunner.load` and held by the runtime's cache so hooks /\n * routes can be invoked across the isolate boundary. Distinct from\n * the author-facing `SandboxedPlugin` type in `emdash/plugin`, which\n * describes the source-level shape of a plugin's default export.\n */\nexport interface SandboxedPluginInstance {\n\t/** Unique identifier: `${manifest.id}:${manifest.version}` */\n\treadonly id: string;\n\n\t/**\n\t * Invoke a hook in the sandboxed plugin.\n\t *\n\t * @param hookName - Name of the hook (e.g., \"content:beforeSave\")\n\t * @param event - Event data to pass to the hook\n\t * @returns Hook result (transformed content, void, etc.)\n\t */\n\tinvokeHook(hookName: string, event: unknown): Promise<unknown>;\n\n\t/**\n\t * Invoke an API route in the sandboxed plugin.\n\t *\n\t * @param routeName - Name of the route\n\t * @param input - Validated input data\n\t * @param request - Serialized request info for context\n\t * @returns Route response data\n\t */\n\tinvokeRoute(\n\t\trouteName: string,\n\t\tinput: unknown,\n\t\trequest: SerializedRequest,\n\t\toptions?: SandboxInvocationOptions,\n\t): Promise<unknown>;\n\n\t/**\n\t * Change whether the plugin may access host services.\n\t * Deactivation revokes credentials synchronously; reactivation issues fresh credentials.\n\t */\n\tsetActive?(active: boolean): void;\n\n\t/**\n\t * Terminate the sandboxed plugin.\n\t * Releases resources and prevents further invocations.\n\t */\n\tterminate(): Promise<void>;\n}\n\nexport interface SandboxInvocationOptions {\n\tinvalidateContentCache?: (tags: string[]) => Promise<void>;\n}\n\n/**\n * Serialized request for RPC transport.\n * Worker Loader can't pass Request objects directly.\n */\nexport interface SerializedRequest {\n\turl: string;\n\tmethod: string;\n\theaders: Record<string, string>;\n\t/** Normalized request metadata extracted before RPC serialization */\n\tmeta: RequestMeta;\n\t/** Host-attested context for a validated Block Kit request. */\n\tui?: PluginUiContext;\n\t/**\n\t * Authenticated caller for private routes, resolved by the host before\n\t * dispatch. Undefined for public routes and unbound machine tokens.\n\t */\n\tuser?: UserInfo;\n}\n\nconst SANDBOX_ROUTE_ERROR_DEFINITIONS = {\n\tMEDIA_USAGE_ACTIVATION_IN_PROGRESS: {\n\t\tmessage: \"Media usage activation is in progress\",\n\t\tstatus: 503,\n\t},\n\tMEDIA_USAGE_ACTIVATION_CHECK_FAILED: {\n\t\tmessage: \"Unable to verify media usage activation state\",\n\t\tstatus: 503,\n\t},\n\tTRANSFER_IMPORT_IN_PROGRESS: {\n\t\tmessage: \"A site import is in progress or incomplete; writes are disabled\",\n\t\tstatus: 503,\n\t},\n\tTRANSFER_FENCE_CHECK_FAILED: {\n\t\tmessage: \"Unable to verify whether site writes are allowed\",\n\t\tstatus: 503,\n\t},\n} as const;\n\nexport type SandboxRouteErrorCode = keyof typeof SANDBOX_ROUTE_ERROR_DEFINITIONS;\n\nexport interface SandboxRouteErrorDetails {\n\tcode: SandboxRouteErrorCode;\n\tmessage: string;\n\tstatus: 503;\n}\n\nexport interface SandboxRouteErrorEnvelope {\n\t__emdashSandboxRouteError: true;\n\terror: SandboxRouteErrorDetails;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nfunction isSandboxRouteErrorCode(value: unknown): value is SandboxRouteErrorCode {\n\treturn typeof value === \"string\" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;\n}\n\nexport function getSandboxRouteErrorDetails(error: unknown): SandboxRouteErrorDetails | null {\n\tif (!isRecord(error)) return null;\n\n\tconst propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;\n\tconst nameCode =\n\t\terror instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;\n\tif (propertyCode && nameCode && propertyCode !== nameCode) return null;\n\n\tconst code = propertyCode ?? nameCode;\n\tif (!code || (error.status !== undefined && error.status !== 503)) return null;\n\n\treturn {\n\t\tcode,\n\t\t...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],\n\t};\n}\n\nexport function createSandboxRouteError(\n\tcode: SandboxRouteErrorCode,\n): Error & SandboxRouteErrorDetails {\n\tconst details: SandboxRouteErrorDetails = {\n\t\tcode,\n\t\t...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],\n\t};\n\treturn Object.assign(new Error(details.message), details, { name: code });\n}\n\nexport function createSandboxRouteErrorEnvelope(error: unknown): SandboxRouteErrorEnvelope | null {\n\tconst details = getSandboxRouteErrorDetails(error);\n\treturn details ? { __emdashSandboxRouteError: true, error: details } : null;\n}\n\nexport function getSandboxRouteErrorEnvelope(value: unknown): SandboxRouteErrorEnvelope | null {\n\tif (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;\n\tconst details = getSandboxRouteErrorDetails(value.error);\n\treturn details ? { __emdashSandboxRouteError: true, error: details } : null;\n}\n\n/**\n * Sandbox runner interface.\n * Platform adapters implement this to provide plugin isolation.\n */\nexport interface SandboxRunner {\n\t/**\n\t * Check if sandboxing is available on this platform.\n\t * Returns false for platforms that don't support isolation.\n\t */\n\tisAvailable(): boolean;\n\n\t/**\n\t * Check if the sandbox runtime is currently healthy.\n\t * For in-process runners this always returns true.\n\t * For sidecar-based runners (workerd), returns false if the\n\t * child process has crashed and hasn't been restarted yet.\n\t */\n\tisHealthy(): boolean;\n\n\t/**\n\t * Why the runner cannot run plugins, once isAvailable() or isHealthy()\n\t * has returned false. A lowercase clause without a final period: callers\n\t * append it to their own message after a colon.\n\t *\n\t * Making this required breaks runners implemented outside this repository.\n\t */\n\tunavailableReason?(): string;\n\n\t/**\n\t * Load a sandboxed plugin from code.\n\t *\n\t * @param manifest - Plugin manifest with metadata and capabilities\n\t * @param code - The bundled plugin JavaScript code\n\t * @returns A sandboxed plugin instance\n\t * @throws If sandboxing is not available or plugin can't be loaded\n\t */\n\tload(manifest: PluginManifest, code: string): Promise<SandboxedPluginInstance>;\n\n\t/**\n\t * Set the email send callback for sandboxed plugins.\n\t * Called after the EmailPipeline is created, since the pipeline\n\t * doesn't exist when the sandbox runner is constructed.\n\t */\n\tsetEmailSend(callback: SandboxEmailSendCallback | null): void;\n\tsetCommentModerate?(callback: SandboxCommentModerateCallback | null): void;\n\tsetContentCreate?(callback: SandboxContentCreateCallback | null): void;\n\tsetContentActions?(callback: ContentActionCallbacks | null): void;\n\n\t/** Wake a long-lived scheduler after a sandboxed plugin changes its tasks. */\n\tsetCronReschedule?(callback: (() => void) | null): void;\n\n\t/**\n\t * Terminate all loaded sandboxed plugins.\n\t * Called during shutdown or when reconfiguring.\n\t */\n\tterminateAll(): Promise<void>;\n}\n\nexport function withUnavailableReason(message: string, runner: SandboxRunner | null): string {\n\tconst reason = runner?.unavailableReason?.();\n\treturn reason ? `${message}: ${reason}` : message;\n}\n\n/**\n * Error thrown when the sandbox runtime is unavailable.\n * This happens when the sidecar process has crashed or hasn't started.\n */\nexport class SandboxUnavailableError extends Error {\n\tconstructor(pluginId: string, reason: string) {\n\t\tsuper(`Plugin sandbox unavailable for ${pluginId}: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Factory function type for creating sandbox runners.\n * Exported by platform adapters (e.g., @emdash-cms/cloudflare/sandbox).\n *\n * @example\n * ```typescript\n * // In @emdash-cms/cloudflare/sandbox\n * export const createSandboxRunner: SandboxRunnerFactory = (options) => {\n *   return new CloudflareSandboxRunner(options);\n * };\n * ```\n */\nexport type SandboxRunnerFactory = (options: SandboxOptions) => SandboxRunner;\n"],"mappings":";AAyNA,MAAM,kCAAkC;CACvC,oCAAoC;EACnC,SAAS;EACT,QAAQ;EACR;CACD,qCAAqC;EACpC,SAAS;EACT,QAAQ;EACR;CACD,6BAA6B;EAC5B,SAAS;EACT,QAAQ;EACR;CACD,6BAA6B;EAC5B,SAAS;EACT,QAAQ;EACR;CACD;AAeD,SAAS,SAAS,OAAkD;AACnE,QAAO,OAAO,UAAU,YAAY,UAAU;;AAG/C,SAAS,wBAAwB,OAAgD;AAChF,QAAO,OAAO,UAAU,YAAY,SAAS;;AAG9C,SAAgB,4BAA4B,OAAiD;AAC5F,KAAI,CAAC,SAAS,MAAM,CAAE,QAAO;CAE7B,MAAM,eAAe,wBAAwB,MAAM,KAAK,GAAG,MAAM,OAAO;CACxE,MAAM,WACL,iBAAiB,SAAS,wBAAwB,MAAM,KAAK,GAAG,MAAM,OAAO;AAC9E,KAAI,gBAAgB,YAAY,iBAAiB,SAAU,QAAO;CAElE,MAAM,OAAO,gBAAgB;AAC7B,KAAI,CAAC,QAAS,MAAM,WAAW,UAAa,MAAM,WAAW,IAAM,QAAO;AAE1E,QAAO;EACN;EACA,GAAG,gCAAgC;EACnC;;AAGF,SAAgB,wBACf,MACmC;CACnC,MAAM,UAAoC;EACzC;EACA,GAAG,gCAAgC;EACnC;AACD,QAAO,OAAO,OAAO,IAAI,MAAM,QAAQ,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;;AAG1E,SAAgB,gCAAgC,OAAkD;CACjG,MAAM,UAAU,4BAA4B,MAAM;AAClD,QAAO,UAAU;EAAE,2BAA2B;EAAM,OAAO;EAAS,GAAG;;AAGxE,SAAgB,6BAA6B,OAAkD;AAC9F,KAAI,CAAC,SAAS,MAAM,IAAI,MAAM,8BAA8B,KAAM,QAAO;CACzE,MAAM,UAAU,4BAA4B,MAAM,MAAM;AACxD,QAAO,UAAU;EAAE,2BAA2B;EAAM,OAAO;EAAS,GAAG;;AA6DxE,SAAgB,sBAAsB,SAAiB,QAAsC;CAC5F,MAAM,SAAS,QAAQ,qBAAqB;AAC5C,QAAO,SAAS,GAAG,QAAQ,IAAI,WAAW;;;;;;AAO3C,IAAa,0BAAb,cAA6C,MAAM;CAClD,YAAY,UAAkB,QAAgB;AAC7C,QAAM,kCAAkC,SAAS,IAAI,SAAS;AAC9D,OAAK,OAAO"}

package/dist/types-5LSo7PPx.d.mts

@@ -0,0 +1,85 @@
+//#region src/settings/types.d.ts
+/**
+ * Site Settings Types
+ *
+ * Global configuration for the site (title, logo, social links, etc.)
+ */
+/**
+ * Media reference for logo/favicon/seo.defaultOgImage.
+ *
+ * Stored shape is just `{ mediaId, alt? }`. The remaining fields are
+ * populated by `resolveMediaReference` on read so templates can emit
+ * correct head tags without a second round-trip to the media table.
+ *
+ * The Zod schemas at the REST/MCP boundary are split:
+ *  - `mediaReferenceInput` (used by `settingsUpdateBody`) defines only
+ *    `mediaId` and `alt`. Default strip-mode parsing discards any
+ *    resolved fields a client posts back, so they never reach storage.
+ *  - `mediaReferenceResponse` (used by `siteSettingsSchema`) includes
+ *    the resolved fields so generated OpenAPI clients see them.
+ *
+ * If you ever switch `mediaReferenceInput` to `passthrough`, you must
+ * also strip the resolved fields explicitly in `setSiteSettings`, or
+ * stored options will accumulate stale `url` / `contentType` / `width`
+ * / `height` snapshots.
+ */
+interface MediaReference {
+  mediaId: string;
+  alt?: string;
+  /** Resolved URL. Populated by `resolveMediaReference`; absent on raw stored values. */
+  url?: string;
+  /** Stored MIME type (e.g. `image/svg+xml`). Populated alongside `url`. */
+  contentType?: string;
+  /** Pixel width if known. Populated alongside `url`. */
+  width?: number;
+  /** Pixel height if known. Populated alongside `url`. */
+  height?: number;
+}
+/** Site-level SEO settings */
+interface SeoSettings {
+  /** Separator between page title and site title (e.g., " | ", " — ") */
+  titleSeparator?: string;
+  /** Default OG image when content has no seo_image */
+  defaultOgImage?: MediaReference;
+  /** Custom robots.txt content. If unset, a default is generated. */
+  robotsTxt?: string;
+  /** Google Search Console verification meta tag content */
+  googleVerification?: string;
+  /** Bing Webmaster Tools verification meta tag content */
+  bingVerification?: string;
+}
+/** Site settings schema */
+interface SiteSettings {
+  title: string;
+  tagline?: string;
+  logo?: MediaReference;
+  favicon?: MediaReference;
+  url?: string;
+  postsPerPage: number;
+  dateFormat: string;
+  timezone: string;
+  social?: {
+    twitter?: string;
+    github?: string;
+    facebook?: string;
+    instagram?: string;
+    linkedin?: string;
+    youtube?: string;
+  };
+  seo?: SeoSettings;
+}
+/** Partial SEO update. `null` removes the configured default image. */
+interface SeoSettingsUpdate extends Omit<SeoSettings, "defaultOgImage"> {
+  defaultOgImage?: MediaReference | null;
+}
+/** Site-settings write shape. `null` removes media references; omitted fields are unchanged. */
+interface SiteSettingsUpdate extends Omit<Partial<SiteSettings>, "logo" | "favicon" | "seo"> {
+  logo?: MediaReference | null;
+  favicon?: MediaReference | null;
+  seo?: SeoSettingsUpdate;
+}
+/** Keys that are valid site settings */
+type SiteSettingKey = keyof SiteSettings;
+//#endregion
+export { SiteSettings as a, SiteSettingKey as i, SeoSettings as n, SiteSettingsUpdate as o, SeoSettingsUpdate as r, MediaReference as t };
+//# sourceMappingURL=types-5LSo7PPx.d.mts.map

package/dist/types-5LSo7PPx.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-5LSo7PPx.d.mts","names":[],"sources":["../src/settings/types.ts"],"mappings":";;AAyBA;;;;;;;;;;;;AAcA;;;;;;;;;;;UAdiB,cAAA;EAChB,OAAA;EACA,GAAA;;EAEA,GAAA;EA6BU;EA3BV,WAAA;EAgDiB;EA9CjB,KAAA;EAsBA;EApBA,MAAA;AAAA;;UAIgB,WAAA;EAmBN;EAjBV,cAAA;EAuBA;EArBA,cAAA,GAAiB,cAAA;EAuBjB;EArBA,SAAA;EAyBC;EAvBD,kBAAA;EAyBC;EAvBD,gBAAA;AAAA;;UAIgB,YAAA;EAEhB,KAAA;EACA,OAAA;EACA,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EAGV,GAAA;EAGA,YAAA;EACA,UAAA;EACA,QAAA;EAGA,MAAA;IACC,OAAA;IACA,MAAA;IACA,QAAA;IACA,SAAA;IACA,QAAA;IACA,OAAA;EAAA;EAID,GAAA,GAAM,WAAA;AAAA;;UAIU,iBAAA,SAA0B,IAAA,CAAK,WAAA;EAC/C,cAAA,GAAiB,cAAA;AAAA;;UAID,kBAAA,SAA2B,IAAA,CAC3C,OAAA,CAAQ,YAAA;EAGR,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EACV,GAAA,GAAM,iBAAA;AAAA;;KAIK,cAAA,SAAuB,YAAA"}