emdash 0.11.1 → 0.13.0

package/src/index.ts

@@ -164,6 +164,7 @@ export type {
 	WxrAttachment,
 	WxrCategory,
 	WxrTag,
+	WxrTerm,
 	WxrAuthor,
 } from "./cli/wxr/parser.js";
 
@@ -188,7 +189,6 @@ export { EmDashStorageError } from "./storage/types.js";
 export {
 	definePlugin,
 	adaptSandboxEntry,
-	isStandardPluginDefinition,
 	pluginManifestSchema,
 	createHookPipeline,
 	HookPipeline,
@@ -243,16 +243,9 @@ export type {
 	CollectionCommentSettings,
 	StoredComment,
 
-	// Standard plugin format
-	StandardPluginDefinition,
-	StandardHookHandler,
-	StandardHookEntry,
-	StandardRouteHandler,
-	StandardRouteEntry,
-
-	// Sandbox types
+	// Sandbox runtime types
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,

package/src/media/local-runtime.ts

@@ -14,6 +14,7 @@ import type { Kysely } from "kysely";
 import { MediaRepository } from "../database/repositories/media.js";
 import type { Database } from "../database/types.js";
 import type { Storage } from "../index.js";
+import { invalidateSiteSettingsCache } from "../settings/index.js";
 import type {
 	CreateMediaProviderFn,
 	MediaProvider,
@@ -120,6 +121,12 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 			}
 
 			await repo.delete(id);
+
+			// If this row was referenced by `logo`, `favicon`, or
+			// `seo.defaultOgImage`, the worker-scoped settings cache now
+			// holds a stale URL. The provider routes (and any future caller)
+			// bypass `handleMediaDelete`, so we invalidate here too.
+			invalidateSiteSettingsCache();
 		},
 
 		getEmbed(value: MediaValue, _options?: EmbedOptions): EmbedResult {

package/src/media/normalize.ts

@@ -20,6 +20,7 @@ const URL_PATTERN = /^https?:\/\//;
  * - `null`/`undefined` → `null`
  * - Bare URL string → `{ provider: "external", id: "", src: url }`
  * - Bare internal media URL → resolved via local provider's `get()`
+ * - Bare local media ID → resolved via local provider's `get()`
  * - Object with `provider` + `id` → enriched with missing fields from provider
  */
 export async function normalizeMediaValue(
@@ -79,7 +80,7 @@ export async function normalizeMediaValue(
 	return mergeProviderData(result, providerItem);
 }
 
-function normalizeStringUrl(
+async function normalizeStringUrl(
 	url: string,
 	getProvider: (id: string) => MediaProvider | undefined,
 ): Promise<MediaValue | null> {
@@ -97,12 +98,15 @@ function normalizeStringUrl(
 		});
 	}
 
-	// Unrecognized string — treat as external
-	return Promise.resolve({
+	const localMedia = await resolveLocalId(url, getProvider);
+	if (localMedia) return localMedia;
+
+	// Unrecognized string — preserve legacy behavior and treat as external
+	return {
 		provider: "external",
 		id: "",
 		src: url,
-	});
+	};
 }
 
 async function resolveInternalUrl(
@@ -139,6 +143,35 @@ async function resolveInternalUrl(
 	};
 }
 
+async function resolveLocalId(
+	id: string,
+	getProvider: (id: string) => MediaProvider | undefined,
+): Promise<MediaValue | null> {
+	const localProvider = getProvider("local");
+
+	if (!localProvider?.get) return null;
+
+	let item: MediaProviderItem | null;
+	try {
+		item = await localProvider.get(id);
+	} catch {
+		return null;
+	}
+
+	if (!item) return null;
+
+	return {
+		provider: "local",
+		id: item.id,
+		filename: item.filename,
+		mimeType: item.mimeType,
+		width: item.width,
+		height: item.height,
+		alt: item.alt,
+		meta: item.meta,
+	};
+}
+
 /**
  * Merge provider data into an existing MediaValue, preserving caller-supplied fields.
  * Caller `alt` takes priority over provider `alt` (per-usage, not per-image).

package/src/page/absolute-url.ts

@@ -0,0 +1,146 @@
+/**
+ * Helpers for resolving relative media URLs to absolute URLs for SEO output.
+ *
+ * Social-card scrapers (Facebook, LinkedIn, Slack, Twitter) and JSON-LD
+ * consumers expect absolute URLs in `og:image`, `twitter:image`, and
+ * structured-data `image` fields. EmDash's media file route returns a
+ * site-relative path (`/_emdash/api/media/file/...`), so anywhere the
+ * resolved URL feeds into crawler-facing markup we have to join it with
+ * the public site origin.
+ */
+
+import type { PublicPageContext } from "../plugins/types.js";
+
+const HTTP_URL_RE = /^https?:\/\//i;
+/**
+ * Protocol-relative URLs (`//cdn.example.com/x.png`) are dropped outright.
+ * They have no legitimate use in `og:image` (scrapers want a full URL) and
+ * are a well-known SSRF vector when reflected through server-side
+ * fetchers. Anything starting with `//` returns `null`.
+ */
+const PROTOCOL_RELATIVE_RE = /^\/\//;
+/**
+ * URL schemes we pass through unchanged because they are legitimately
+ * useful as OG image values. `data:image/*` is sometimes used for inline
+ * social cards (rare, but legal). Everything else with a scheme
+ * (`mailto:`, `tel:`, `file:`, `blob:`, custom protocols) would be garbage
+ * in an `og:image`; we return `null` so the caller can decide whether to
+ * fall back or drop the tag.
+ */
+const PASSTHROUGH_SCHEME_RE = /^data:image\//i;
+/**
+ * Detects URLs that have a scheme other than http/https (and other than
+ * the data:image/ form we pass through). Used to short-circuit garbage
+ * input rather than treating it as a relative path.
+ */
+const OTHER_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+/**
+ * Any ASCII whitespace or C0/C1 control character anywhere in the URL is
+ * an injection signal — legitimate media URLs never contain them. Without
+ * this guard, an input like `"  https://attacker/x"` would slip past the
+ * scheme regexes (which are anchored at offset 0) and get joined as a
+ * relative path with the site origin, producing
+ * `https://site.example/  https://attacker/x` — confusing but not
+ * exploitable, plus more pathological shapes like leading newlines that
+ * could inject across header boundaries downstream.
+ */
+// eslint-disable-next-line eslint(no-control-regex) -- intentional: rejecting control chars is the whole point of this regex
+const WHITESPACE_OR_CONTROL_RE = /[\s\u0000-\u001f\u007f-\u009f]/;
+const TRAILING_SLASH_RE = /\/$/;
+
+/**
+ * `URL.origin` returns the literal string `"null"` (not the `null` value)
+ * for opaque origins like `data:`, `blob:`, and `about:blank`. Treating
+ * that as a valid origin would produce `null/og.png` in the output.
+ */
+function isUsableOrigin(origin: string): boolean {
+	return origin !== "null" && origin !== "";
+}
+
+/**
+ * Resolve the public origin to use when absolutizing a media URL.
+ *
+ * Precedence:
+ *  1. The configured `SiteSettings.url` (admin-controlled, canonical).
+ *  2. `PublicPageContext.siteUrl` (set by themes that override the origin,
+ *     e.g. when running behind a reverse proxy).
+ *  3. The origin parsed from `page.url`, which is the live request URL.
+ *
+ * Only `http:` and `https:` candidates count — anything else (e.g. `file:`,
+ * `data:`, `blob:`) would yield an unusable origin and is skipped. Returns
+ * `null` if no candidate parses to a usable HTTP(S) origin; callers should
+ * treat that as "leave the URL relative" rather than throw.
+ */
+export function resolveSiteOrigin(
+	configuredSiteUrl: string | undefined,
+	page: PublicPageContext,
+): string | null {
+	const candidates = [configuredSiteUrl, page.siteUrl, page.url];
+	for (const candidate of candidates) {
+		if (!candidate || typeof candidate !== "string") continue;
+		try {
+			const parsed = new URL(candidate);
+			if (parsed.protocol !== "http:" && parsed.protocol !== "https:") continue;
+			if (!isUsableOrigin(parsed.origin)) continue;
+			return parsed.origin;
+		} catch {
+			// Fall through to the next candidate. Configured URLs and page
+			// URLs can be malformed (e.g. an admin pasted "example.com"
+			// without a scheme); we don't want a bad config to break head
+			// rendering.
+		}
+	}
+	return null;
+}
+
+/**
+ * Absolutize a media URL using the best available site origin.
+ *
+ * - Returns `null` for missing/empty input.
+ * - Passes through already-absolute `http(s):` URLs unchanged.
+ * - Passes through `data:image/*` URLs unchanged (rare but legal as OG
+ *   image content).
+ * - Returns `null` for protocol-relative URLs (`//cdn.com/x`): no
+ *   legitimate `og:image` use case, and a known SSRF vector when reflected
+ *   through server-side fetchers.
+ * - Returns `null` for any other scheme (`mailto:`, `blob:`, `file:`,
+ *   custom protocols): emitting those into `og:image` is worse than
+ *   omitting the tag.
+ * - Returns the original (relative) URL when no origin can be resolved —
+ *   preferable to dropping `og:image` outright because scrapers that follow
+ *   relative URLs are better off than ones that get nothing.
+ *
+ * @param url - The (possibly relative) media URL, e.g. `/_emdash/api/media/file/abc.jpg`.
+ * @param configuredSiteUrl - `SiteSettings.url` value (admin-controlled).
+ * @param page - The page context providing `siteUrl` and `url` fallbacks.
+ */
+export function absolutizeMediaUrl(
+	url: string | undefined,
+	configuredSiteUrl: string | undefined,
+	page: PublicPageContext,
+): string | null {
+	if (!url) return null;
+
+	// Any whitespace or control character means this isn't a real media URL.
+	// Rejecting up front prevents scheme-regex evasion (`  https://x` would
+	// otherwise fall through to the relative-path join below).
+	if (WHITESPACE_OR_CONTROL_RE.test(url)) return null;
+
+	if (HTTP_URL_RE.test(url)) return url;
+	if (PASSTHROUGH_SCHEME_RE.test(url)) return url;
+
+	// Reject protocol-relative URLs before any other handling. Order
+	// matters: `OTHER_SCHEME_RE` wouldn't match `//x` (no leading scheme),
+	// so a missing check here would fall through to the relative-path
+	// join below and produce `https://site.example//cdn.evil.com/x`.
+	if (PROTOCOL_RELATIVE_RE.test(url)) return null;
+
+	// Any remaining `<scheme>:` form is something we'd silently mangle by
+	// prepending an origin. Drop it.
+	if (OTHER_SCHEME_RE.test(url)) return null;
+
+	const origin = resolveSiteOrigin(configuredSiteUrl, page);
+	if (!origin) return url;
+	const safePath = url.startsWith("/") ? url : `/${url}`;
+	return `${origin.replace(TRAILING_SLASH_RE, "")}${safePath}`;
+}

package/src/page/jsonld.ts

@@ -29,13 +29,21 @@ export function cleanJsonLd(obj: Record<string, unknown>): Record<string, unknow
 /**
  * Build a BlogPosting JSON-LD graph from page context.
  * Used for article-type content pages.
+ *
+ * @param page - Page context for the current request.
+ * @param defaultOgImage - Optional site-wide fallback image URL, used when
+ *   the page has no own OG image. Matches the fallback applied to `og:image`
+ *   in `generateBaseSeoContributions`.
  */
-export function buildBlogPostingJsonLd(page: PublicPageContext): Record<string, unknown> | null {
+export function buildBlogPostingJsonLd(
+	page: PublicPageContext,
+	defaultOgImage?: string | null,
+): Record<string, unknown> | null {
 	if (page.pageType !== "article" || !page.canonical) return null;
 
 	const ogTitle = page.seo?.ogTitle ?? page.pageTitle ?? page.title;
 	const description = page.seo?.ogDescription || page.description;
-	const ogImage = page.seo?.ogImage || page.image;
+	const ogImage = page.seo?.ogImage || page.image || defaultOgImage || null;
 	const publishedTime = page.articleMeta?.publishedTime;
 	const modifiedTime = page.articleMeta?.modifiedTime;
 	const author = page.articleMeta?.author;

package/src/page/seo-contributions.ts

@@ -1,9 +1,11 @@
 /**
  * Generate base SEO metadata contributions from PublicPageContext.
  *
- * These contributions are prepended BEFORE plugin contributions in
- * resolvePageMetadata(), which uses first-wins dedup. This means
- * plugins can override any base SEO tag by contributing the same key.
+ * EmDashHead.astro composes the final contribution list as
+ * `[...plugin, ...site, ...base]` and feeds it to `resolvePageMetadata()`,
+ * which is first-wins. That ordering means plugin contributions override
+ * site-level ones override base ones for any given key — base values are
+ * the fallback, not the source of truth.
  *
  * This replaces the per-template SEO.astro components, eliminating
  * the class of XSS bugs where templates hand-rolled JSON-LD serialization.
@@ -15,15 +17,24 @@ import { buildBlogPostingJsonLd, buildWebSiteJsonLd } from "./jsonld.js";
 
 /**
  * Generate base metadata contributions from a page context's SEO data.
+ *
+ * @param page - Page context produced by the runtime for the current request.
+ * @param defaultOgImage - Optional site-wide fallback OG image URL, used when
+ *   the page has no own OG image (i.e., neither `seo.ogImage` nor `image`).
+ *   Sourced from `SiteSettings.seo.defaultOgImage` by `EmDashHead`.
+ *
  * Returns an empty array if no SEO-relevant data is present.
  */
-export function generateBaseSeoContributions(page: PublicPageContext): PageMetadataContribution[] {
+export function generateBaseSeoContributions(
+	page: PublicPageContext,
+	defaultOgImage?: string | null,
+): PageMetadataContribution[] {
 	const contributions: PageMetadataContribution[] = [];
 
 	const description = page.description;
 	const ogTitle = page.seo?.ogTitle ?? page.pageTitle ?? page.title;
 	const ogDescription = page.seo?.ogDescription || description;
-	const ogImage = page.seo?.ogImage || page.image;
+	const ogImage = page.seo?.ogImage || page.image || defaultOgImage || null;
 	const robots = page.seo?.robots;
 	const canonical = page.canonical;
 	const siteName = page.siteName;
@@ -122,7 +133,7 @@ export function generateBaseSeoContributions(page: PublicPageContext): PageMetad
 	// -- JSON-LD --
 
 	if (page.pageType === "article") {
-		const blogPosting = buildBlogPostingJsonLd(page);
+		const blogPosting = buildBlogPostingJsonLd(page, defaultOgImage ?? null);
 		if (blogPosting) {
 			contributions.push({ kind: "jsonld", id: "primary", graph: blogPosting });
 		}

package/src/plugin-types.ts

@@ -0,0 +1,240 @@
+/**
+ * `emdash/plugin` — types for authoring sandboxed plugins.
+ *
+ * This is a **type-only** subpath. The package.json export map only
+ * declares a `types` condition, so the bundler erases `import type`
+ * statements against this entry and the build never tries to resolve a
+ * JavaScript module. That's how a sandboxed plugin can import these
+ * types without dragging the `emdash` runtime into its bundle.
+ *
+ * Recommended authoring pattern:
+ *
+ * ```ts
+ * import type { SandboxedPlugin } from "emdash/plugin";
+ *
+ * export default {
+ *   hooks: {
+ *     "content:beforeSave": async (event, ctx) => {
+ *       // event: ContentHookEvent, ctx: PluginContext — both inferred.
+ *       return event.content;
+ *     },
+ *   },
+ *   routes: {
+ *     health: async (routeCtx, ctx) => ({ ok: true }),
+ *   },
+ * } satisfies SandboxedPlugin;
+ * ```
+ *
+ * The `satisfies SandboxedPlugin` annotation drives full inference on
+ * every hook handler. Authors should not need to annotate handler
+ * params — TypeScript reads the event type from the hook name. The
+ * runtime probe at build time reads `default.hooks` and `default.routes`
+ * directly; the shape declared here mirrors what the probe consumes.
+ *
+ * Return types matter: `content:beforeSave` may return a mutated
+ * `content` to override the saved fields; `content:beforeDelete` and
+ * `comment:beforeCreate` may return `false` to veto; `page:metadata`
+ * returns the metadata contribution. The mapped type captures these
+ * per-hook return contracts so misuse fails at compile time.
+ */
+
+import type {
+	CommentAfterCreateEvent,
+	CommentAfterCreateHandler,
+	CommentAfterModerateEvent,
+	CommentAfterModerateHandler,
+	CommentBeforeCreateEvent,
+	CommentBeforeCreateHandler,
+	CommentModerateEvent,
+	CommentModerateHandler,
+	ContentAfterDeleteHandler,
+	ContentAfterPublishHandler,
+	ContentAfterSaveHandler,
+	ContentAfterUnpublishHandler,
+	ContentBeforeDeleteHandler,
+	ContentBeforeSaveHandler,
+	ContentDeleteEvent,
+	ContentHookEvent,
+	ContentPublishStateChangeEvent,
+	CronEvent,
+	CronHandler,
+	EmailAfterSendEvent,
+	EmailAfterSendHandler,
+	EmailBeforeSendEvent,
+	EmailBeforeSendHandler,
+	EmailDeliverEvent,
+	EmailDeliverHandler,
+	LifecycleEvent,
+	LifecycleHandler,
+	MediaAfterUploadEvent,
+	MediaAfterUploadHandler,
+	MediaBeforeUploadHandler,
+	MediaUploadEvent,
+	PageFragmentEvent,
+	PageFragmentHandler,
+	PageMetadataEvent,
+	PageMetadataHandler,
+	PluginContext,
+	UninstallEvent,
+	UninstallHandler,
+} from "./plugins/types.js";
+
+/**
+ * Map from hook name to its handler signature. Adding or changing a
+ * hook signature in the runtime means updating this map; the rest of
+ * the type story flows from it. Authors writing
+ * `"content:beforeSave": async (event, ctx) => { ... }` get `event`
+ * typed as `ContentHookEvent` and `ctx` as `PluginContext` for free.
+ */
+export interface HookHandlers {
+	"plugin:install": LifecycleHandler;
+	"plugin:activate": LifecycleHandler;
+	"plugin:deactivate": LifecycleHandler;
+	"plugin:uninstall": UninstallHandler;
+	"content:beforeSave": ContentBeforeSaveHandler;
+	"content:afterSave": ContentAfterSaveHandler;
+	"content:beforeDelete": ContentBeforeDeleteHandler;
+	"content:afterDelete": ContentAfterDeleteHandler;
+	"content:afterPublish": ContentAfterPublishHandler;
+	"content:afterUnpublish": ContentAfterUnpublishHandler;
+	"media:beforeUpload": MediaBeforeUploadHandler;
+	"media:afterUpload": MediaAfterUploadHandler;
+	cron: CronHandler;
+	"email:beforeSend": EmailBeforeSendHandler;
+	"email:deliver": EmailDeliverHandler;
+	"email:afterSend": EmailAfterSendHandler;
+	"comment:beforeCreate": CommentBeforeCreateHandler;
+	"comment:moderate": CommentModerateHandler;
+	"comment:afterCreate": CommentAfterCreateHandler;
+	"comment:afterModerate": CommentAfterModerateHandler;
+	"page:metadata": PageMetadataHandler;
+	"page:fragments": PageFragmentHandler;
+}
+
+/**
+ * Hook-handler config form. The bare-function form is also accepted
+ * (see `HookEntry`) — this is the long form that lets authors override
+ * priority, timeout, exclusivity. `errorPolicy` and `dependencies` are
+ * read by the host but rarely set by authors.
+ */
+export interface HookConfig<K extends keyof HookHandlers> {
+	handler: HookHandlers[K];
+	priority?: number;
+	timeout?: number;
+	dependencies?: string[];
+	errorPolicy?: "continue" | "abort";
+	exclusive?: boolean;
+}
+
+/**
+ * Either a bare handler or the config form. The build probe accepts
+ * both shapes and the runtime normalises to the config form before
+ * dispatch.
+ */
+export type HookEntry<K extends keyof HookHandlers> = HookHandlers[K] | HookConfig<K>;
+
+/**
+ * Request fields a route handler can rely on across both trusted and
+ * sandboxed execution. Trusted handlers receive a real `Request`
+ * (which is structurally compatible — has `url`, `method`, `headers`);
+ * sandboxed handlers receive a serialised `{ url, method, headers }`
+ * record because Worker Loader can't pass `Request` objects across
+ * the boundary. The shared shape is what's actually portable.
+ *
+ * `headers` is intentionally `Record<string, string>` rather than
+ * `Headers` so the sandboxed serialised form (which is a plain
+ * record) typechecks. Trusted handlers receiving a real `Headers`
+ * object can still call `.get(...)`, but reading via this type's
+ * indexing requires the lookup to be lowercased and exact. Authors
+ * iterating headers in a portable way should use `Object.entries`.
+ */
+export interface SandboxedRequest {
+	url: string;
+	method: string;
+	headers: Record<string, string>;
+}
+
+/**
+ * Context passed to a route handler. Routes get an extra `routeCtx`
+ * argument with the call-site input + the originating request, in
+ * addition to the standard `PluginContext`.
+ *
+ * `input` is `unknown` because plugins validate it themselves — no
+ * central schema for route payloads.
+ */
+export interface SandboxedRouteContext {
+	input: unknown;
+	request: SandboxedRequest;
+	requestMeta?: unknown;
+}
+
+/**
+ * Route handler. The two-arg shape (`routeCtx`, `pluginCtx`) matches
+ * how the standard-format runtime invokes routes — distinct from
+ * native plugins, where routes take a single context with the input
+ * merged in.
+ *
+ * Return type is `unknown` because routes serialise their return value
+ * to JSON for the caller; authors define their own response shape.
+ */
+export type RouteHandler = (
+	routeCtx: SandboxedRouteContext,
+	ctx: PluginContext,
+) => Promise<unknown>;
+
+/**
+ * Route entry — either a bare handler or the config form with
+ * `public`, `input` schema, and so on. The build probe accepts both.
+ */
+export type RouteEntry =
+	| RouteHandler
+	| {
+			handler: RouteHandler;
+			public?: boolean;
+			input?: unknown;
+	  };
+
+/**
+ * The shape of a sandboxed plugin's default export.
+ *
+ * Both `hooks` and `routes` are optional — a plugin that only declares
+ * one is valid. Hook keys are constrained to the runtime's hook
+ * vocabulary so a typo (`"content:beforSave"`) is a compile error.
+ * Route keys are open because route names are author-chosen URL path
+ * segments.
+ */
+export interface SandboxedPlugin {
+	hooks?: {
+		[K in keyof HookHandlers]?: HookEntry<K>;
+	};
+	routes?: Record<string, RouteEntry>;
+}
+
+/**
+ * Re-export of event types so plugin authors can reference them
+ * explicitly when needed (helper functions, type predicates). Most
+ * authors won't need these — the mapped type infers them at handler
+ * call sites. But the default-export's inferred type also needs them
+ * publicly nameable so `satisfies SandboxedPlugin` can produce a
+ * portable `.d.mts`.
+ */
+export type {
+	CommentAfterCreateEvent,
+	CommentAfterModerateEvent,
+	CommentBeforeCreateEvent,
+	CommentModerateEvent,
+	ContentDeleteEvent,
+	ContentHookEvent,
+	ContentPublishStateChangeEvent,
+	CronEvent,
+	EmailAfterSendEvent,
+	EmailBeforeSendEvent,
+	EmailDeliverEvent,
+	LifecycleEvent,
+	MediaAfterUploadEvent,
+	MediaUploadEvent,
+	PageFragmentEvent,
+	PageMetadataEvent,
+	PluginContext,
+	UninstallEvent,
+};