emdash 0.15.0 → 0.16.1

package/src/astro/routes/api/admin/plugins/registry/artifact.ts

@@ -0,0 +1,388 @@
+/**
+ * Registry artifact proxy
+ *
+ * GET /_emdash/api/admin/plugins/registry/artifact?did=&slug=&version=&kind=&index=
+ *
+ * Proxies an icon / screenshot / banner image referenced by a registry
+ * release record so the admin UI can display it without cross-origin
+ * requests to arbitrary publisher hosting.
+ *
+ * Trust model (CRITICAL): the proxy never accepts an artifact URL from the
+ * client. The caller addresses an artifact by its coordinates
+ * `(did, slug, version, kind, index)`; the server resolves the *declared*
+ * URL from the validated release record fetched from the configured
+ * aggregator. The proxy can therefore only ever fetch a URL the publisher
+ * declared in their signed release — not an arbitrary caller-supplied URL.
+ *
+ * The publisher-declared URL is still untrusted (an attacker who controls a
+ * publisher record, or the aggregator, can point it anywhere), so the
+ * resolved URL passes through the SSRF defences (`assertSafeArtifactUrl`,
+ * re-validated on every redirect hop) before any fetch, and only allowlisted
+ * image content types are served back.
+ */
+
+import type { Did } from "@atcute/lexicons";
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError } from "#api/error.js";
+import { assertSafeArtifactUrl } from "#api/index.js";
+
+import { coerceRegistryConfig, validateAggregatorUrl } from "../../../../../../registry/config.js";
+
+export const prerender = false;
+
+/**
+ * Image content types the proxy will pass through. Anything else is rejected.
+ *
+ * SVG is deliberately excluded: it is active content (an `<svg><script>`
+ * executes when navigated to as a top-level document), and the publisher
+ * supplies the bytes. Rather than serve it behind mitigations, we refuse it
+ * end-to-end — the publish CLI rejects SVG artifacts too, so a conforming
+ * release never references one. AVIF is included.
+ */
+const ALLOWED_IMAGE_TYPES = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif",
+	"image/avif",
+]);
+
+/** Artifact kinds the proxy can resolve. `screenshot` additionally needs `index`. */
+const ALLOWED_KINDS = new Set(["icon", "banner", "screenshot"]);
+
+/** Loose DID shape (`did:method:id`); the aggregator lexicon is authoritative. */
+const DID_PATTERN = /^did:[a-z]+:.+/;
+/** Slug grammar: ASCII letter then letters / digits / `-` / `_`. Mirrors the install route. */
+const SLUG_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+/** Non-negative integer, for the screenshot index param. */
+const INDEX_PATTERN = /^\d+$/;
+
+/** Cap proxied images so a hostile host can't stream an unbounded body. */
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
+/** Redirect hops to follow, re-validating each target against SSRF rules. */
+const MAX_REDIRECTS = 5;
+
+/** Wall-clock budget covering connect + headers + body for the artifact fetch. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+/** Per-aggregator-request timeout and overall budget for release resolution. */
+const AGGREGATOR_REQUEST_TIMEOUT_MS = 15_000;
+const AGGREGATOR_TOTAL_BUDGET_MS = 30_000;
+
+/** Bound the version search: 20 pages * 50 per page = 1000 releases worth. */
+const MAX_LIST_PAGES = 20;
+
+/** Build a fetch that enforces a per-request and per-budget timeout. Mirrors the install handler. */
+function timedFetch(totalDeadline: number): typeof fetch {
+	return (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+		const now = Date.now();
+		const remaining = Math.max(0, totalDeadline - now);
+		if (remaining === 0) {
+			return Promise.reject(new Error("Aggregator request budget exhausted"));
+		}
+		const timeout = Math.min(AGGREGATOR_REQUEST_TIMEOUT_MS, remaining);
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeout);
+		const callerSignal = init?.signal;
+		if (callerSignal) {
+			if (callerSignal.aborted) controller.abort(callerSignal.reason);
+			else callerSignal.addEventListener("abort", () => controller.abort(callerSignal.reason));
+		}
+		return fetch(input, { ...init, signal: controller.signal }).finally(() => {
+			clearTimeout(timer);
+		});
+	};
+}
+
+/**
+ * Narrow one entry of a release's `artifacts` map to a usable image URL.
+ *
+ * The embedded `release` record is lexicon-validated at the DiscoveryClient
+ * boundary, but `artifacts` is an aggregator pass-through typed `unknown`, so
+ * the entry's shape is not guaranteed. Returns the `url` string only when the
+ * value is an object carrying a non-empty string `url`; everything else
+ * (missing key, wrong type, no `url`) yields `null`.
+ */
+function declaredArtifactUrl(value: unknown): string | null {
+	if (!value || typeof value !== "object") return null;
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed to non-null object above; url checked below
+	const entry = value as Record<string, unknown>;
+	const url = entry.url;
+	if (typeof url !== "string" || url.length === 0) return null;
+	return url;
+}
+
+/**
+ * Resolve the declared artifact URL for `(kind, index)` from a release's
+ * `artifacts` map. Returns `null` when the requested artifact isn't present
+ * or doesn't carry a usable URL.
+ */
+function resolveDeclaredUrl(artifacts: unknown, kind: string, index: number): string | null {
+	if (!artifacts || typeof artifacts !== "object") return null;
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed to non-null object above; each entry shape-narrowed by declaredArtifactUrl
+	const map = artifacts as Record<string, unknown>;
+
+	if (kind === "icon") return declaredArtifactUrl(map.icon);
+	if (kind === "banner") return declaredArtifactUrl(map.banner);
+	// kind === "screenshot"
+	const screenshots = map.screenshots;
+	if (!Array.isArray(screenshots)) return null;
+	if (index < 0 || index >= screenshots.length) return null;
+	return declaredArtifactUrl(screenshots[index]);
+}
+
+export const GET: APIRoute = async ({ url, locals }) => {
+	const { emdash, user } = locals;
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	const denied = requirePerm(user, "plugins:read");
+	if (denied) return denied;
+
+	const did = url.searchParams.get("did");
+	const slug = url.searchParams.get("slug");
+	const kind = url.searchParams.get("kind");
+	const versionParam = url.searchParams.get("version");
+	const indexParam = url.searchParams.get("index");
+
+	if (!did || !slug || !kind) {
+		return apiError("INVALID_REQUEST", "Missing did, slug, or kind", 400);
+	}
+	if (did.length > 256 || !DID_PATTERN.test(did)) {
+		return apiError("INVALID_REQUEST", "Invalid did", 400);
+	}
+	if (slug.length > 64 || !SLUG_PATTERN.test(slug)) {
+		return apiError("INVALID_REQUEST", "Invalid slug", 400);
+	}
+	if (!ALLOWED_KINDS.has(kind)) {
+		return apiError("INVALID_REQUEST", "Invalid kind", 400);
+	}
+
+	let index = 0;
+	if (kind === "screenshot") {
+		if (indexParam === null) {
+			return apiError("INVALID_REQUEST", "Missing index for screenshot", 400);
+		}
+		if (!INDEX_PATTERN.test(indexParam)) {
+			return apiError("INVALID_REQUEST", "Invalid index", 400);
+		}
+		index = Number(indexParam);
+		if (!Number.isSafeInteger(index)) {
+			return apiError("INVALID_REQUEST", "Invalid index", 400);
+		}
+	}
+
+	let version: string | undefined;
+	if (versionParam !== null && versionParam.length > 0) {
+		if (versionParam.length > 64) {
+			return apiError("INVALID_REQUEST", "Invalid version", 400);
+		}
+		version = versionParam;
+	}
+
+	const registryConfig = coerceRegistryConfig(emdash.config.experimental?.registry);
+	if (!registryConfig) {
+		return apiError("REGISTRY_NOT_CONFIGURED", "Registry is not configured", 400);
+	}
+	try {
+		validateAggregatorUrl(registryConfig.aggregatorUrl);
+	} catch {
+		return apiError("REGISTRY_NOT_CONFIGURED", "Registry aggregator URL is invalid", 500);
+	}
+
+	// Resolve the publisher-declared artifact URL from the release record.
+	let declaredUrl: string;
+	try {
+		const resolved = await resolveArtifactUrl(registryConfig, did, slug, version, kind, index);
+		if (resolved === null) {
+			return apiError("ARTIFACT_NOT_FOUND", "Artifact not found", 404);
+		}
+		declaredUrl = resolved;
+	} catch {
+		return apiError("ARTIFACT_RESOLVE_FAILED", "Failed to resolve artifact", 502);
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		// `assertSafeArtifactUrl` validates scheme / credentials / loopback +
+		// resolves the hostname and rejects private / link-local / metadata
+		// targets (DNS-rebinding defence). It throws a plain Error on any
+		// block, so a rejection here means the URL is unsafe.
+		let current: URL;
+		try {
+			current = await assertSafeArtifactUrl(declaredUrl);
+		} catch {
+			return apiError("ARTIFACT_URL_REJECTED", "Artifact URL is not allowed", 400);
+		}
+
+		let response: Response;
+		for (let hop = 0; ; hop++) {
+			response = await fetch(current.href, { redirect: "manual", signal: controller.signal });
+			if (response.status < 300 || response.status >= 400) break;
+			const location = response.headers.get("location");
+			if (!location) break;
+			if (hop === MAX_REDIRECTS) {
+				return apiError("ARTIFACT_URL_REJECTED", "Too many redirects", 502);
+			}
+			let next: URL;
+			try {
+				next = await assertSafeArtifactUrl(new URL(location, current).href);
+			} catch {
+				return apiError("ARTIFACT_URL_REJECTED", "Redirect target is not allowed", 400);
+			}
+			current = next;
+		}
+
+		if (!response.ok) {
+			return apiError("ARTIFACT_FETCH_FAILED", "Failed to fetch artifact", 502);
+		}
+
+		// Content-Type allowlist: only image types are proxied. A non-image
+		// (HTML error page, JSON, octet-stream) is rejected so the admin
+		// never renders publisher-controlled markup from the EmDash origin.
+		const rawType = response.headers.get("content-type") ?? "";
+		const contentType = rawType.split(";", 1)[0]!.trim().toLowerCase();
+		if (!ALLOWED_IMAGE_TYPES.has(contentType)) {
+			return apiError("ARTIFACT_NOT_IMAGE", "Artifact is not an allowed image type", 415);
+		}
+
+		const declaredLength = response.headers.get("content-length");
+		if (declaredLength) {
+			const declared = Number(declaredLength);
+			if (Number.isFinite(declared) && declared > MAX_IMAGE_BYTES) {
+				return apiError("ARTIFACT_TOO_LARGE", "Artifact exceeds size limit", 413);
+			}
+		}
+
+		const bytes = await readCapped(response, MAX_IMAGE_BYTES);
+		if (bytes === null) {
+			return apiError("ARTIFACT_TOO_LARGE", "Artifact exceeds size limit", 413);
+		}
+
+		// Only the allowlisted Content-Type is forwarded — never copy other
+		// upstream headers. `private, no-store` keeps publisher images out of
+		// shared caches in the authenticated admin origin.
+		//
+		// SVG is not in the allowlist, so active-content bytes never reach
+		// here. `Content-Disposition: attachment`, the sandbox CSP, and
+		// `nosniff` remain as defence-in-depth: they force a download and
+		// neutralise script/plugins for any image type if a client navigates
+		// directly to the proxy URL.
+		return new Response(bytes, {
+			headers: {
+				"Content-Type": contentType,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+				"Content-Disposition": "attachment",
+				"Content-Security-Policy": "default-src 'none'; sandbox",
+			},
+		});
+	} catch {
+		return apiError("ARTIFACT_FETCH_FAILED", "Failed to fetch artifact", 502);
+	} finally {
+		clearTimeout(timer);
+	}
+};
+
+/**
+ * Resolve the declared artifact URL for `(did, slug, version, kind, index)`
+ * from the aggregator's release record. Mirrors the install handler's release
+ * lookup. Returns `null` when the package/release/artifact isn't found.
+ *
+ * Self-contained to this route: the install/update handlers are intentionally
+ * left untouched, so a small amount of resolution-pattern duplication is
+ * accepted here.
+ */
+async function resolveArtifactUrl(
+	registryConfig: { aggregatorUrl: string; acceptLabelers?: string },
+	did: string,
+	slug: string,
+	version: string | undefined,
+	kind: string,
+	index: number,
+): Promise<string | null> {
+	// Lazy-load the discovery client so the `@atcute/client` dependency only
+	// loads when the registry path is exercised.
+	const { DiscoveryClient } = await import("@emdash-cms/registry-client/discovery");
+
+	const aggregatorDeadline = Date.now() + AGGREGATOR_TOTAL_BUDGET_MS;
+	const discovery = new DiscoveryClient({
+		aggregatorUrl: registryConfig.aggregatorUrl,
+		acceptLabelers: registryConfig.acceptLabelers,
+		fetch: timedFetch(aggregatorDeadline),
+	});
+
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- DID shape validated by the route before this call
+	const publisherDid = did as Did;
+
+	const releaseView = await (async () => {
+		if (!version) {
+			return discovery.getLatestRelease({ did: publisherDid, package: slug });
+		}
+		let cursor: string | undefined;
+		const seenCursors = new Set<string>();
+		for (let page = 0; page < MAX_LIST_PAGES; page++) {
+			if (cursor !== undefined) {
+				if (seenCursors.has(cursor)) break;
+				seenCursors.add(cursor);
+			}
+			const result = await discovery.listReleases({
+				did: publisherDid,
+				package: slug,
+				cursor,
+				limit: 50,
+			});
+			for (const r of result.releases) {
+				if (r.version === version) return r;
+			}
+			if (!result.cursor) break;
+			cursor = result.cursor;
+		}
+		return undefined;
+	})();
+
+	if (!releaseView?.release) return null;
+
+	return resolveDeclaredUrl(releaseView.release.artifacts, kind, index);
+}
+
+/**
+ * Read a response body into memory, aborting once it exceeds `limit`. Returns
+ * `null` when the cap is breached (the streamed body lied about / omitted
+ * Content-Length). The cap is the real defence against an unbounded body.
+ */
+async function readCapped(response: Response, limit: number): Promise<Uint8Array | null> {
+	const body = response.body;
+	if (!body) {
+		const buf = new Uint8Array(await response.arrayBuffer());
+		return buf.length > limit ? null : buf;
+	}
+	const reader = body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) {
+			total += value.length;
+			if (total > limit) {
+				await reader.cancel();
+				return null;
+			}
+			chunks.push(value);
+		}
+	}
+	const combined = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		combined.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return combined;
+}

package/src/astro/routes/api/admin/plugins/registry/install.ts

@@ -12,6 +12,7 @@
  * view time (handle is best-effort per the lexicon).
  */
 
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { APIRoute } from "astro";
 import { z } from "zod";
 
@@ -20,6 +21,8 @@ import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleRegistryInstall } from "#api/index.js";
 import { isParseError, parseBody } from "#api/parse.js";
 
+import { VERSION } from "../../../../../../version.js";
+
 export const prerender = false;
 
 const installBodySchema = z.object({
@@ -91,7 +94,10 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				version: body.version,
 				acknowledgedDeclaredAccess: body.acknowledgedDeclaredAccess,
 			},
-			{ configuredPluginIds: reservedPluginIds },
+			{
+				configuredPluginIds: reservedPluginIds,
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
+			},
 		);
 
 		if (!result.success) return unwrapResult(result);

package/src/astro/routes/api/import/wordpress/rewrite-url-helpers.ts

@@ -27,6 +27,28 @@ export function buildBaseUrlMap(urlMap: Record<string, string>): Map<string, str
 	return baseMap;
 }
 
+/**
+ * Extract the URL to match from a stored media field value.
+ *
+ * Image/file columns hold a JSON-stringified MediaValue
+ * (e.g. `{"provider":"external","id":"","src":"https://.../hero.jpg"}`), but legacy
+ * rows may hold a bare URL string. Returns the inner `src` for a MediaValue, otherwise
+ * the value unchanged. Without this, the whole JSON blob is passed to findMatchingUrl()
+ * and the embedded URL is never matched.
+ */
+export function extractMediaUrl(value: string): string {
+	try {
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- shape validated below
+		const parsed = JSON.parse(value) as { src?: unknown };
+		if (parsed && typeof parsed.src === "string") {
+			return parsed.src;
+		}
+	} catch {
+		// Not JSON — treat the column value as a bare URL.
+	}
+	return value;
+}
+
 /**
  * Find matching new URL for a given URL, checking exact, base, and WordPress image-size matches
  */

package/src/astro/routes/api/import/wordpress/rewrite-urls.ts

@@ -24,6 +24,7 @@ import type { EmDashHandlers } from "#types";
 
 import {
 	buildBaseUrlMap,
+	extractMediaUrl,
 	findMatchingUrl,
 	rewritePortableTextUrls,
 	rewriteStringUrls,
@@ -174,8 +175,10 @@ async function rewriteUrls(
 					const value = row[field.slug];
 					if (!value || typeof value !== "string") continue;
 
-					// Try to find a matching rewritten URL
-					const newUrl = findMatchingUrl(value, urlMap, baseMap);
+					// Values are stored as JSON MediaValue objects (e.g. featured_image from
+					// import normalizes to {"provider":"external","src":"<wp url>"}). Match on the
+					// inner `src`, falling back to the raw value for legacy bare-URL rows.
+					const newUrl = findMatchingUrl(extractMediaUrl(value), urlMap, baseMap);
 					if (newUrl) {
 						// Normalize into a proper MediaValue instead of storing a bare URL
 						try {

package/src/astro/routes/sitemap-[collection].xml.ts

@@ -5,13 +5,25 @@
  *
  * Uses the collection's url_pattern to build URLs. Falls back to
  * /{collection}/{slug} when no pattern is configured.
+ *
+ * i18n behaviour: when Astro i18n is enabled, the locale prefix is
+ * applied via Astro's own `getRelativeLocaleUrl` (which honours
+ * `prefixDefaultLocale`, custom `path` mappings, and other `routing`
+ * config). Each translation row is emitted as its own `<url>` with
+ * `<xhtml:link rel="alternate" hreflang="...">` entries pointing to
+ * its siblings (grouped by `translation_group`). The default-locale
+ * variant is also linked as `hreflang="x-default"`.
  */
 
 import type { APIRoute } from "astro";
 
 import { handleSitemapData } from "#api/handlers/seo.js";
+import { getPublicOrigin } from "#api/public-url.js";
 import { getSiteSettingsWithDb } from "#settings/index.js";
 
+import { getI18nConfig, isI18nEnabled } from "../../i18n/config.js";
+import { interpolateUrlPattern, localizePath } from "../../i18n/resolve.js";
+
 export const prerender = false;
 
 const TRAILING_SLASH_RE = /\/$/;
@@ -20,8 +32,6 @@ const LT_RE = /</g;
 const GT_RE = />/g;
 const QUOT_RE = /"/g;
 const APOS_RE = /'/g;
-const SLUG_PLACEHOLDER = "{slug}";
-const ID_PLACEHOLDER = "{id}";
 
 export const GET: APIRoute = async ({ params, locals, url }) => {
 	const { emdash } = locals;
@@ -36,7 +46,10 @@ export const GET: APIRoute = async ({ params, locals, url }) => {
 
 	try {
 		const settings = await getSiteSettingsWithDb(emdash.db);
-		const siteUrl = (settings.url || url.origin).replace(TRAILING_SLASH_RE, "");
+		const siteUrl = (settings.url || getPublicOrigin(url, emdash?.config)).replace(
+			TRAILING_SLASH_RE,
+			"",
+		);
 
 		const result = await handleSitemapData(emdash.db, collectionSlug);
 
@@ -55,25 +68,112 @@ export const GET: APIRoute = async ({ params, locals, url }) => {
 			});
 		}
 
-		const lines: string[] = [
-			'<?xml version="1.0" encoding="UTF-8"?>',
-			'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
-		];
+		const i18nEnabled = isI18nEnabled();
+		const i18nConfig = getI18nConfig();
 
+		// Group entries by `translation_group` so each <url> can advertise
+		// its sibling translations via xhtml:link. Rows without a group
+		// (legacy/single-locale data) are emitted individually.
+		type Entry = (typeof col.entries)[number];
+		const groups = new Map<string, Entry[]>();
+		const ungrouped: Entry[] = [];
 		for (const entry of col.entries) {
-			const slug = entry.slug || entry.id;
-			const path = col.urlPattern
-				? col.urlPattern
-						.replace(SLUG_PLACEHOLDER, encodeURIComponent(slug))
-						.replace(ID_PLACEHOLDER, encodeURIComponent(entry.id))
-				: `/${encodeURIComponent(col.collection)}/${encodeURIComponent(slug)}`;
+			if (i18nEnabled && entry.translationGroup) {
+				const list = groups.get(entry.translationGroup);
+				if (list) list.push(entry);
+				else groups.set(entry.translationGroup, [entry]);
+			} else {
+				ungrouped.push(entry);
+			}
+		}
 
-			const loc = `${siteUrl}${path}`;
+		// Resolve every URL up-front so we can reference sibling URLs
+		// while emitting hreflang alternates without re-resolving.
+		// `localizePath` returns `null` when the row's locale isn't in
+		// the configured `i18n.locales` list -- the site can't serve a
+		// route for it, so the entry is dropped from the sitemap and
+		// omitted from sibling alternates.
+		const urlByEntry = new Map<string, string | null>();
+		const resolveEntryUrl = async (entry: Entry): Promise<string | null> => {
+			if (urlByEntry.has(entry.id)) return urlByEntry.get(entry.id) ?? null;
+			const path = interpolateUrlPattern({
+				pattern: col.urlPattern,
+				collection: col.collection,
+				slug: entry.slug || entry.id,
+				id: entry.id,
+			});
+			const localized = await localizePath(path, entry.locale);
+			const absolute = localized === null ? null : `${siteUrl}${localized}`;
+			urlByEntry.set(entry.id, absolute);
+			return absolute;
+		};
+
+		const useXhtml = i18nEnabled;
+		const lines: string[] = ['<?xml version="1.0" encoding="UTF-8"?>'];
+		lines.push(
+			useXhtml
+				? '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">'
+				: '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+		);
+
+		const writeUrl = async (entry: Entry, siblings: Entry[] | null) => {
+			const loc = await resolveEntryUrl(entry);
+			// Skip rows whose locale isn't in the configured `i18n.locales`
+			// list. Linking to a route the site can't serve is worse than
+			// no link at all (search engines hit a 404 and downrank).
+			if (loc === null) return;
 
 			lines.push("  <url>");
 			lines.push(`    <loc>${escapeXml(loc)}</loc>`);
 			lines.push(`    <lastmod>${escapeXml(entry.updatedAt)}</lastmod>`);
+
+			if (useXhtml && siblings && siblings.length > 1) {
+				// Emit one xhtml:link per sibling (including self -- Google
+				// recommends including the page's own hreflang annotation).
+				// Siblings with unroutable locales are skipped here too.
+				for (const sib of siblings) {
+					const sibLoc = await resolveEntryUrl(sib);
+					if (sibLoc === null) continue;
+					lines.push(
+						`    <xhtml:link rel="alternate" hreflang="${escapeXml(sib.locale)}" href="${escapeXml(sibLoc)}" />`,
+					);
+				}
+
+				// x-default: prefer the default-locale sibling, otherwise
+				// the first sibling with a routable URL. Stable order:
+				// rows arrive sorted by updated_at DESC from the handler.
+				const defaultSibling =
+					i18nConfig && siblings.find((s) => s.locale === i18nConfig.defaultLocale);
+				let xDefaultLoc: string | null = null;
+				if (defaultSibling) {
+					xDefaultLoc = await resolveEntryUrl(defaultSibling);
+				}
+				if (xDefaultLoc === null) {
+					for (const sib of siblings) {
+						const sibLoc = await resolveEntryUrl(sib);
+						if (sibLoc !== null) {
+							xDefaultLoc = sibLoc;
+							break;
+						}
+					}
+				}
+				if (xDefaultLoc !== null) {
+					lines.push(
+						`    <xhtml:link rel="alternate" hreflang="x-default" href="${escapeXml(xDefaultLoc)}" />`,
+					);
+				}
+			}
+
 			lines.push("  </url>");
+		};
+
+		for (const siblings of groups.values()) {
+			for (const entry of siblings) {
+				await writeUrl(entry, siblings);
+			}
+		}
+		for (const entry of ungrouped) {
+			await writeUrl(entry, null);
 		}
 
 		lines.push("</urlset>");

package/src/astro/types.ts

@@ -108,6 +108,12 @@ export interface EmDashManifest {
 	version: string;
 	commit?: string;
 	hash: string;
+	/**
+	 * Version of Astro the host project is built with. Present when the
+	 * integration could resolve it. Surfaced so the admin can evaluate a
+	 * registry plugin's `env:astro` requirement against the running host.
+	 */
+	astroVersion?: string;
 	collections: Record<string, ManifestCollection>;
 	plugins: Record<string, ManifestPlugin>;
 	/**
@@ -385,6 +391,14 @@ export interface EmDashHandlers {
 		request: Request,
 	) => Promise<HandlerResponse>;
 
+	// Public-only plugin API route handler for SSR page components.
+	handlePublicPluginApiRoute: (
+		pluginId: string,
+		method: string,
+		path: string,
+		request: Request,
+	) => Promise<HandlerResponse>;
+
 	// Plugin route metadata (for auth decisions before dispatch)
 	getPluginRouteMeta: (pluginId: string, path: string) => { public: boolean } | null;