emdash 0.12.0 → 0.13.0

package/src/registry/config.ts

@@ -0,0 +1,311 @@
+/**
+ * Helpers for normalizing the experimental registry integration option
+ * (`config.experimental.registry` in `astro.config.mjs`) into the shape
+ * exposed on the admin manifest.
+ *
+ * The integration option accepts a human-friendly duration string for
+ * `policy.minimumReleaseAge` (`"48h"`, `"7d"`); the manifest exposes
+ * seconds so the browser doesn't need a duration parser.
+ */
+
+import type { RegistryConfig, RegistryConfigInput } from "./types.js";
+
+/**
+ * Shape returned in the admin manifest's `registry` field. The browser
+ * consumes this directly -- all duration normalization and aggregator URL
+ * validation has already happened by the time it gets here.
+ */
+export interface ManifestRegistryConfig {
+	aggregatorUrl: string;
+	acceptLabelers?: string;
+	policy?: {
+		minimumReleaseAgeSeconds?: number;
+		/**
+		 * Allowlist of publishers / packages exempt from the
+		 * {@link minimumReleaseAgeSeconds} holdback. Each entry is either:
+		 *
+		 *   - A bare publisher identifier: `"did:plc:abc123"` or a handle
+		 *     like `"example.dev"`. Every package from that publisher is
+		 *     exempt.
+		 *   - A `publisher/slug` pair: only that specific package is exempt.
+		 *
+		 * Normalized to lowercase strings at config load time so the
+		 * browser does case-insensitive comparison. See
+		 * {@link releaseExemptFromMinimumAge}.
+		 */
+		minimumReleaseAgeExclude?: string[];
+	};
+}
+
+/**
+ * Canonicalize a capabilities list for set-style comparison.
+ *
+ * Capabilities (the legacy declared-access shape used by the current
+ * sandbox enforcer) are conceptually a *set*: order, duplicates, and
+ * non-string entries don't carry meaning. The install handler's drift
+ * check compares the admin's acknowledged set against the bundle
+ * manifest's set; both sides pass through this canonicalizer first so
+ * an aggregator-supplied array with unstable order or junk entries
+ * can't cause a spurious drift rejection.
+ *
+ * Filters non-strings, deduplicates, and sorts lexically. Named to
+ * avoid shadowing `@emdash-cms/plugin-types`'s existing
+ * `normalizeCapabilities` (which dedupes + applies the deprecated →
+ * current alias map but does not filter junk or sort).
+ *
+ * Exported so the same shape is produced by the browser before sending
+ * the `acknowledgedDeclaredAccess` payload and by the server before
+ * comparing against the bundle.
+ */
+export function canonicalCapabilitiesForDriftCheck(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	const seen = new Set<string>();
+	for (const entry of value) {
+		if (typeof entry === "string" && entry.length > 0) {
+			seen.add(entry);
+		}
+	}
+	return [...seen].toSorted();
+}
+
+/**
+ * Returns whether a `(publisher_did, slug)` pair is on the
+ * minimum-release-age exemption list. Exported so the same matcher is
+ * used by the browser policy filter and the server-side install
+ * enforcement.
+ *
+ * Matching is DID-only. Handles are aggregator-supplied envelope data
+ * (mutable, controlled by an attacker who compromises the aggregator)
+ * and cannot be used as a trust input -- a compromised aggregator
+ * could claim any handle for any package and bypass the holdback. DIDs
+ * are part of the AT URI of the package record and are independently
+ * resolvable, so even a compromised aggregator can't lie about the
+ * publisher DID without also breaking checksum verification downstream.
+ *
+ * Entries from config are already lowercased at manifest-build time.
+ * Runtime values are lowercased here at compare time.
+ */
+export function releaseExemptFromMinimumAge(
+	exclude: readonly string[] | undefined,
+	publisherDid: string,
+	slug: string,
+): boolean {
+	if (!exclude || exclude.length === 0) return false;
+	const didLower = publisherDid.toLowerCase();
+	const slugLower = slug.toLowerCase();
+	const fullDid = `${didLower}/${slugLower}`;
+
+	for (const entry of exclude) {
+		if (entry === didLower) return true;
+		if (entry === fullDid) return true;
+	}
+	return false;
+}
+
+const DURATION_PATTERN = /^(\d+)(s|m|h|d|w)$/;
+
+/** Trailing slashes on the aggregator URL, stripped during normalization. */
+const TRAILING_SLASHES = /\/+$/;
+
+/** Trailing dot on a hostname, stripped before URL host comparisons. */
+const TRAILING_DOT = /\.$/;
+
+/**
+ * Parse a duration string or raw second count into a non-negative
+ * integer count of seconds. Throws on unrecognised input so config
+ * mistakes fail at startup rather than silently disabling the policy.
+ */
+export function parseDurationSeconds(duration: string | number): number {
+	if (typeof duration === "number") {
+		if (!Number.isFinite(duration) || duration < 0) {
+			throw new Error(`Invalid duration: ${duration} (must be a non-negative finite number)`);
+		}
+		return Math.floor(duration);
+	}
+
+	const match = duration.match(DURATION_PATTERN);
+	if (!match) {
+		throw new Error(
+			`Invalid duration format: "${duration}". Use a duration string like "48h", "7d", "30m", or a number of seconds.`,
+		);
+	}
+
+	const value = parseInt(match[1]!, 10);
+	const unit = match[2];
+
+	switch (unit) {
+		case "s":
+			return value;
+		case "m":
+			return value * 60;
+		case "h":
+			return value * 60 * 60;
+		case "d":
+			return value * 24 * 60 * 60;
+		case "w":
+			return value * 7 * 24 * 60 * 60;
+		default:
+			// Unreachable given the regex, but keep the exhaustive arm for
+			// future maintainers who add a unit to the pattern.
+			throw new Error(`Unknown duration unit: ${unit}`);
+	}
+}
+
+/**
+ * Validate that `aggregatorUrl` is a safe outbound target for the
+ * registry's XRPC calls. Same posture as artifact downloads: HTTPS
+ * required in production; `http://localhost` allowed only in dev.
+ *
+ * The aggregator's responses are the trust source for release records,
+ * checksums, labels, mirrors, and `indexedAt` (until full MST
+ * verification lands). Allowing plain HTTP here would let a network
+ * attacker swap a release record and point the artifact URL at their
+ * own HTTPS bundle, defeating the checksum trust chain because the
+ * attacker controls the unsigned transport that supplied the checksum.
+ */
+export function validateAggregatorUrl(aggregatorUrl: string): URL {
+	let parsed: URL;
+	try {
+		parsed = new URL(aggregatorUrl);
+	} catch {
+		throw new Error(`registry.aggregatorUrl is not a valid URL: ${aggregatorUrl}`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(`registry.aggregatorUrl must use http or https: ${aggregatorUrl}`);
+	}
+	// Reject embedded credentials. The normalized aggregator URL ends
+	// up in the admin manifest and is shipped to every admin browser;
+	// browser `fetch()` also outright rejects URLs with `user:pass@`,
+	// so leaving them in would both leak the credentials and break the
+	// registry UI at runtime.
+	if (parsed.username || parsed.password) {
+		throw new Error("registry.aggregatorUrl must not contain embedded credentials (user:pass@)");
+	}
+
+	// WHATWG URL preserves the brackets on IPv6 hostnames -- strip them
+	// before any comparison so `https://[::1]/` is recognised as localhost
+	// and not treated as a generic domain string.
+	const rawHostname = parsed.hostname.toLowerCase().replace(TRAILING_DOT, "");
+	const hostname =
+		rawHostname.startsWith("[") && rawHostname.endsWith("]")
+			? rawHostname.slice(1, -1)
+			: rawHostname;
+	const isLocalhost =
+		hostname === "localhost" ||
+		hostname.endsWith(".localhost") ||
+		hostname === "127.0.0.1" ||
+		hostname === "::1" ||
+		// IPv4-mapped IPv6 forms of loopback, e.g. `::ffff:127.0.0.1` and `::ffff:7f00:1`.
+		hostname.startsWith("::ffff:127.") ||
+		hostname.startsWith("::ffff:7f00:");
+
+	if (!import.meta.env.DEV) {
+		if (parsed.protocol === "http:") {
+			throw new Error(`registry.aggregatorUrl must use https in production: ${aggregatorUrl}`);
+		}
+		if (isLocalhost) {
+			throw new Error(
+				`registry.aggregatorUrl points at localhost; allowed only in dev: ${aggregatorUrl}`,
+			);
+		}
+	} else if (parsed.protocol === "http:" && !isLocalhost) {
+		throw new Error(
+			`registry.aggregatorUrl must use https (http allowed only for localhost in dev): ${aggregatorUrl}`,
+		);
+	}
+
+	return parsed;
+}
+
+/**
+ * Expand the `RegistryConfigInput` shorthand into the full
+ * `RegistryConfig` object shape.
+ *
+ * Users can pass a bare aggregator URL string for the common case
+ * (`experimental.registry: "https://registry.emdashcms.com"`); the
+ * normalizer handles either form transparently.
+ *
+ * Returns `undefined` for `undefined` input so callers can chain with
+ * optional chaining.
+ */
+export function coerceRegistryConfig(
+	input: RegistryConfigInput | undefined,
+): RegistryConfig | undefined {
+	if (input === undefined) return undefined;
+	if (typeof input === "string") return { aggregatorUrl: input };
+	return input;
+}
+
+/**
+ * Normalize the user-supplied `RegistryConfigInput` into the shape that
+ * ships to the admin browser via the manifest endpoint.
+ *
+ * Accepts either the shorthand string form
+ * (`"https://registry.emdashcms.com"`) or the full `RegistryConfig`
+ * object. Returns `null` when `input` is undefined so callers can
+ * spread the result directly into the manifest object.
+ *
+ * Throws if the aggregator URL is malformed, points at a forbidden host,
+ * or `policy.minimumReleaseAge` is unparseable. These surface at
+ * runtime startup as 500s from the manifest endpoint -- intended,
+ * because the alternative is silently disabling the registry on
+ * misconfigured sites.
+ *
+ * TODO: switch to a Zod schema for richer per-field error messages and
+ * to surface misconfigurations to the admin UI as a banner instead of
+ * a manifest 500.
+ */
+export function normalizeRegistryConfig(
+	input: RegistryConfigInput | undefined,
+): ManifestRegistryConfig | null {
+	const config = coerceRegistryConfig(input);
+	if (!config) return null;
+
+	const aggregatorUrl = config.aggregatorUrl?.trim();
+	if (!aggregatorUrl) {
+		throw new Error("registry.aggregatorUrl is required when registry is configured");
+	}
+
+	validateAggregatorUrl(aggregatorUrl);
+
+	const out: ManifestRegistryConfig = {
+		// Strip any trailing slash so `${aggregatorUrl}/xrpc/...` works
+		// regardless of how the user wrote it.
+		aggregatorUrl: aggregatorUrl.replace(TRAILING_SLASHES, ""),
+	};
+
+	if (config.acceptLabelers) {
+		out.acceptLabelers = config.acceptLabelers;
+	}
+
+	const policy: ManifestRegistryConfig["policy"] = {};
+	let hasPolicy = false;
+
+	if (config.policy?.minimumReleaseAge !== undefined) {
+		policy.minimumReleaseAgeSeconds = parseDurationSeconds(config.policy.minimumReleaseAge);
+		hasPolicy = true;
+	}
+
+	if (config.policy?.minimumReleaseAgeExclude !== undefined) {
+		// Normalize at load time so callers (browser and server) can do
+		// plain string compares without each one re-implementing the
+		// case-folding rule.
+		const list = config.policy.minimumReleaseAgeExclude.map((entry) => {
+			const trimmed = entry.trim();
+			if (!trimmed) {
+				throw new Error("registry.policy.minimumReleaseAgeExclude entries cannot be empty");
+			}
+			return trimmed.toLowerCase();
+		});
+		if (list.length > 0) {
+			policy.minimumReleaseAgeExclude = list;
+			hasPolicy = true;
+		}
+	}
+
+	if (hasPolicy) {
+		out.policy = policy;
+	}
+
+	return out;
+}

package/src/registry/plugin-id.ts

@@ -0,0 +1,116 @@
+/**
+ * Plugin identifier helpers for the experimental decentralized plugin
+ * registry.
+ *
+ * Registry plugins are addressed by `(publisher_did, slug)`, but the
+ * EmDash runtime threads a single `pluginId: string` through every
+ * install primitive (R2 storage keys, `PluginStateRepository`,
+ * `syncMarketplacePlugins`, sandbox cache keys). Rather than refactor
+ * everything to carry a composite identifier, we normalize the registry
+ * tuple to an opaque content-addressed id that satisfies the existing
+ * `validatePluginIdentifier` shape (`/^[a-z][a-z0-9_-]*$/`).
+ *
+ * The normalized id is:
+ *
+ *   `r_` + base32-encoded SHA-256(publisher_did + "\n" + slug), truncated.
+ *
+ * Properties:
+ *
+ *   - Deterministic. The same `(publisher, slug)` always produces the
+ *     same id, so re-resolving an installed plugin's metadata against
+ *     the aggregator is a straightforward lookup keyed by the columns
+ *     stored alongside `plugin_id` in `plugin_states`.
+ *   - Collision-resistant. 80 bits of truncated hash; a 50% birthday
+ *     collision happens around 2^40 distinct plugins, well beyond what
+ *     this registry will ever index.
+ *   - R2-safe. Lowercase alphanumerics + underscore (no hyphens), no
+ *     `:` or `/`. Existing sandbox cache keys (`${pluginId}:${version}`)
+ *     keep working because the id contains no `:`.
+ *   - Syntactically distinct from typical marketplace plugin ids: the
+ *     `r_` prefix plus exactly 16 base32 characters is unlikely to be
+ *     chosen as a marketplace id. Not formally guaranteed by the
+ *     validator -- marketplace ids may begin with `r_` and contain
+ *     hyphens -- so the install handler also performs an explicit
+ *     pre-existing-row check at the derived id and rejects any cross-
+ *     source collision (`PLUGIN_ID_COLLISION`).
+ *
+ * Reverse lookup (id → publisher + slug) requires the `plugin_states`
+ * row -- the hash is one-way. That's intentional: any code path that
+ * needs the human-meaningful pair already has the state row in hand.
+ */
+
+/** Length (in base32 characters) of the truncated hash portion of the id. */
+const HASH_LENGTH = 16;
+
+/** Total expected length of a registry plugin id. */
+export const REGISTRY_PLUGIN_ID_LENGTH = 2 /* "r_" */ + HASH_LENGTH;
+
+/**
+ * Regex matching a well-formed registry plugin id. Used by call sites
+ * that need to distinguish registry installs from marketplace installs
+ * without consulting the `source` column on `plugin_states`.
+ *
+ * The base32 alphabet here uses RFC 4648 lowercase without padding,
+ * matching {@link base32Encode}'s output.
+ */
+export const REGISTRY_PLUGIN_ID_PATTERN = /^r_[a-z2-7]{16}$/;
+
+const BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+
+/**
+ * RFC 4648 base32 encoding without padding, lowercase. Implemented inline
+ * rather than depending on a multibase library because (a) we only need
+ * lowercase base32 here, (b) we need it to run identically in workerd,
+ * Node, and the browser, and (c) the implementation is fewer lines than
+ * the import statement would be.
+ */
+function base32Encode(bytes: Uint8Array): string {
+	let bits = 0;
+	let value = 0;
+	let out = "";
+	for (const byte of bytes) {
+		value = (value << 8) | byte;
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			out += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+		}
+	}
+	if (bits > 0) {
+		out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+	}
+	return out;
+}
+
+/**
+ * Derive the normalized plugin id for a registry-published plugin.
+ *
+ * Throws if either input is empty or whitespace-only -- a missing DID
+ * or slug is always a programming error in the install path, not a
+ * recoverable runtime condition.
+ */
+export async function makeRegistryPluginId(publisherDid: string, slug: string): Promise<string> {
+	const did = publisherDid.trim();
+	const s = slug.trim();
+	if (!did) throw new Error("makeRegistryPluginId: publisherDid is required");
+	if (!s) throw new Error("makeRegistryPluginId: slug is required");
+
+	// `\n` separator avoids ambiguity: no canonical did:plc / did:web form
+	// contains a literal newline, so `("a", "b\nc")` cannot hash to the
+	// same bytes as `("a\nb", "c")`.
+	const input = `${did}\n${s}`;
+	const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+	const encoded = base32Encode(new Uint8Array(hashBuffer));
+	return `r_${encoded.slice(0, HASH_LENGTH)}`;
+}
+
+/**
+ * Return whether `pluginId` is a well-formed registry plugin id.
+ *
+ * This is a syntactic check, not a database lookup -- it answers
+ * "could this id have come from `makeRegistryPluginId`?", not "is this
+ * plugin installed?".
+ */
+export function isRegistryPluginId(pluginId: string): boolean {
+	return REGISTRY_PLUGIN_ID_PATTERN.test(pluginId);
+}

package/src/registry/types.ts

@@ -0,0 +1,206 @@
+/**
+ * Public types for the experimental plugin registry.
+ *
+ * Kept in their own module so they don't get re-bundled into the
+ * `astro/integration/runtime.ts` chunk's dist output. tsdown / rolldown
+ * are sensitive to which top-level types live alongside `definePlugin`'s
+ * overloads, and pulling these types into the integration module
+ * affected downstream `definePlugin()` overload resolution for trusted
+ * plugins built against core's dist (see commit history for the
+ * detailed write-up).
+ */
+
+/**
+ * Experimental plugin registry configuration.
+ *
+ * See {@link ExperimentalConfig.registry}.
+ */
+export interface RegistryConfig {
+	/**
+	 * Base URL of the registry aggregator (an atproto AppView that indexes
+	 * the firehose for `pm.fair.package.*` and `com.emdashcms.*` records).
+	 *
+	 * Must be the origin where the aggregator's XRPC endpoints are mounted,
+	 * such that `${aggregatorUrl}/xrpc/<nsid>` resolves to a valid endpoint.
+	 *
+	 * Must be HTTPS in production; `http://localhost` or `http://127.0.0.1`
+	 * are accepted in dev.
+	 */
+	aggregatorUrl: string;
+
+	/**
+	 * Optional comma-separated list of labeller DIDs forwarded as the
+	 * `atproto-accept-labelers` header on every aggregator request.
+	 *
+	 * Format follows the atproto convention:
+	 * `did:plc:abc;redact, did:plc:def`
+	 *
+	 * When unset, the aggregator applies its operator-default labeller set
+	 * (typically the EmDash publisher-verification labeller and any
+	 * additional trusted labellers the aggregator operator configured).
+	 */
+	acceptLabelers?: string;
+
+	/**
+	 * Site-level policy applied to the latest-release selection filter.
+	 *
+	 * These filters operate over the signed records the aggregator returns;
+	 * they are not protocol-level constraints. See the RFC's
+	 * "Update Discovery and Takedowns" section for the integration point.
+	 */
+	policy?: {
+		/**
+		 * Hold back releases newer than this when computing the recommended
+		 * install or update version. Mitigates "compromised publisher
+		 * account pushes a malicious release of an established plugin" by
+		 * giving the takedown labeller a detection window.
+		 *
+		 * Accepts a duration string (`"24h"`, `"48h"`, `"72h"`, `"7d"`) or a
+		 * number of seconds.
+		 *
+		 * Currently applies uniformly to all releases. A future addition
+		 * may exempt brand-new packages (those with no prior release
+		 * history) so the holdback doesn't block first-time publishing,
+		 * but that exemption is not implemented yet; use
+		 * {@link minimumReleaseAgeExclude} to allowlist trusted publishers
+		 * whose packages should install immediately.
+		 *
+		 * Defaults to `undefined` (no holdback). A future trust/moderation
+		 * RFC will specify the recommended default.
+		 */
+		minimumReleaseAge?: string | number;
+
+		/**
+		 * Packages exempt from the {@link minimumReleaseAge} holdback. Use
+		 * for publishers whose release tempo you've explicitly accepted --
+		 * your own first-party plugins, a trusted partner, etc.
+		 *
+		 * Each entry is either:
+		 *   - A bare publisher DID (e.g. `"did:plc:abc123"`) -- every
+		 *     package from that publisher is exempt.
+		 *   - A `<did>/<slug>` pair (e.g.
+		 *     `"did:plc:abc123/hotfix-plugin"`) -- only that specific
+		 *     package is exempt.
+		 *
+		 * Whole-publisher exemptions are the common case: trust is
+		 * naturally a property of the publisher, not of each individual
+		 * package. Per-package exemptions exist for cases where a publisher
+		 * has one plugin you want fast-track installs for and others you'd
+		 * rather hold back.
+		 *
+		 * Only DIDs are accepted -- not handles. Handles are mutable
+		 * aggregator-supplied envelope data, and accepting them as a
+		 * trust input would let a compromised aggregator bypass the
+		 * holdback by claiming any handle for any package. DIDs are
+		 * tied to the AT URI of the package record itself, so even a
+		 * compromised aggregator cannot lie about which DID published
+		 * a release.
+		 *
+		 * Mirrors pnpm's `minimumReleaseAgeExclude`.
+		 *
+		 * @example
+		 * ```ts
+		 * minimumReleaseAgeExclude: [
+		 *   "did:plc:emdashfirstparty",     // every package from this publisher
+		 *   "did:plc:abc123/hotfix-plugin", // just this one package
+		 * ]
+		 * ```
+		 */
+		minimumReleaseAgeExclude?: readonly string[];
+	};
+}
+
+/**
+ * Shorthand: pass a bare aggregator URL string in place of a full
+ * `RegistryConfig` object when you don't need `acceptLabelers` or
+ * `policy`. The normalizer expands the string into
+ * `{ aggregatorUrl: <string> }` before any downstream code sees it.
+ *
+ * @example
+ * ```ts
+ * experimental: {
+ *   registry: "https://registry.emdashcms.com",
+ * }
+ * ```
+ *
+ * Equivalent to:
+ * ```ts
+ * experimental: {
+ *   registry: { aggregatorUrl: "https://registry.emdashcms.com" },
+ * }
+ * ```
+ */
+export type RegistryConfigInput = string | RegistryConfig;
+
+/**
+ * Experimental EmDash features. See `EmDashConfig.experimental`.
+ *
+ * Each field is independently opt-in. Fields may be promoted out of
+ * `experimental` (becoming top-level `EmDashConfig` options) or removed
+ * in minor releases; check the changelog when upgrading.
+ */
+export interface ExperimentalConfig {
+	/**
+	 * Decentralized plugin registry.
+	 *
+	 * When set, replaces the centralized `marketplace` for the admin UI's
+	 * browse and install flows. The registry is an atproto-backed
+	 * federation: package metadata lives in each publisher's PDS and
+	 * an aggregator (the `aggregatorUrl`) indexes the firehose and
+	 * exposes read-only XRPC endpoints for discovery.
+	 *
+	 * See [RFC 0001](https://github.com/emdash-cms/emdash/pull/694) for
+	 * the protocol design.
+	 *
+	 * **Trust model (v1, experimental).** Today EmDash trusts the
+	 * configured aggregator with these claims, per package and per
+	 * release:
+	 *
+	 *   - The publisher DID associated with a `(did, slug)` pair.
+	 *   - The artifact `url`, the artifact `checksum`, and any mirror
+	 *     URLs returned for a release.
+	 *   - The published handle for a DID (used for display only;
+	 *     EmDash separately verifies the DID->handle round-trip in the
+	 *     admin UI before treating a handle as confirmed).
+	 *
+	 * What EmDash verifies independently before activating an
+	 * installed plugin:
+	 *
+	 *   - The artifact bytes hash to the checksum the aggregator
+	 *     returned (so a malicious mirror or in-transit tamper can't
+	 *     swap the bundle).
+	 *   - The bundle's `manifest.id` matches the requested slug, and
+	 *     its `manifest.version` matches the release version (so an
+	 *     attacker who controls the aggregator can't trick the
+	 *     sandbox into addressing the wrong plugin id).
+	 *   - The bundle's `manifest.capabilities` matches what the admin
+	 *     acknowledged in the consent dialog (so a publisher can't
+	 *     ship a bundle that requests more permissions than the
+	 *     dialog displayed).
+	 *
+	 * What's NOT yet verified:
+	 *
+	 *   - Full MST proof / publisher signature on the release record.
+	 *     A compromised aggregator can forge a release for any DID
+	 *     and slug, and the install will succeed as long as the
+	 *     bundle matches the (forged) checksum.
+	 *   - Per-release replay / rollback: the aggregator chooses which
+	 *     release version is "latest".
+	 *
+	 * **Recommendation.** Until full signature verification lands,
+	 * point `aggregatorUrl` only at an aggregator you operate
+	 * yourself or one you trust with the same level of authority as
+	 * a centralized plugin source. The `policy.minimumReleaseAge` and
+	 * `acceptLabelers` knobs partially mitigate by widening the
+	 * detection window for takedowns, but they assume the labeller
+	 * system is operating.
+	 *
+	 * Requires `sandboxRunner` to be configured -- registry plugins
+	 * always run sandboxed.
+	 *
+	 * Accepts a bare URL string as shorthand for
+	 * `{ aggregatorUrl: "..." }`. Use the full object form when you
+	 * need `acceptLabelers` or `policy`.
+	 */
+	registry?: RegistryConfigInput;
+}