@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-zones.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A zone a plugin declares, and the props it hands each widget (AGL-3124).
+ *
+ * `CONSOLE_WIDGET_SLOTS` is the catalog of zones the console SHELL draws, and
+ * a slot id has always been an open string, so a plugin could already host a
+ * zone of its own. What it could not do is say what that zone HANDS a widget.
+ * The props had to be a type, the type had to be somewhere both sides import,
+ * and "somewhere both sides import" was read as the core — which is how
+ * `plugin-manager/commerce-zone-props.ts` and `plugin-manager/record-zone-props.ts`
+ * came to spell out the commerce catalog and the record vocabulary of two
+ * named plugins inside the platform.
+ *
+ * So the declaration moves to the plugin. A plugin defines a token for its
+ * zone with {@link definePluginZone}, carrying the props type on the token,
+ * and registers it here with a label and the surface it is drawn on. A widget
+ * author takes the props type off the token — `PluginZoneProps<typeof ZONE>`
+ * — without the core ever naming a product, a deal or a lead.
+ *
+ * ## Nothing here reaches a published page
+ *
+ * A zone token is `{ id }` and nothing else: `__props` is a phantom field that
+ * never holds a value, so the props type is carried at the type level and
+ * erased. That is the same trick the two type-only modules above use, and it
+ * is load-bearing rather than tidy — AGL-3082 measured the zone catalog on the
+ * published page's static graph, and a declaration that put a plugin's prop
+ * SHAPES there would have made every published page carry the console's
+ * vocabulary. `plugin-zones.spec.ts` pins the token's own key set so a field
+ * added to it later has to be a decision.
+ *
+ * This module is reached by its own subpath and is deliberately absent from
+ * `plugin-manager/index.ts`, for the reason that barrel already states about
+ * `plugin-figures`: what a published page does not need, it must not import.
+ *
+ * ## One zone id, one owner
+ *
+ * A zone is a position on a page somebody draws. Two plugins declaring the
+ * same id would each believe they set what a widget there receives, and the
+ * widget author would have no way to tell whose props arrived — so a second
+ * plugin's declaration is refused naming both, and the incumbent keeps its
+ * zone. The same plugin declaring again — a second surface, a hot reload —
+ * replaces its own.
+ */
+/**
+ * A zone's identity, with the props it hands a widget carried at the type
+ * level. `__props` never holds a value.
+ */
+export interface PluginZone<Props> {
+    readonly id: string;
+    readonly __props?: Props;
+}
+/** The props a zone hands each widget, read off its token. */
+export type PluginZoneProps<Zone> = Zone extends PluginZone<infer Props> ? Props : never;
+/**
+ * A zone token. Pure: it allocates no registration and reads no registry, so
+ * a plugin may define one at module scope and register it from its register
+ * fn, where the loader's owner marker is set.
+ */
+export declare function definePluginZone<Props>(id: string): PluginZone<Props>;
+/** Where a zone is drawn, which is what decides the gates around it. */
+export type PluginZoneSurface = 'console' | 'besigner' | 'site';
+export interface PluginZoneDeclaration<Props = unknown> {
+    zone: PluginZone<Props>;
+    /** What the plugin's own manifest and the widget picker call the zone. */
+    label: string;
+    /** The surface the zone is drawn on. */
+    surface: PluginZoneSurface;
+    /**
+     * What a widget here may do, and what it may not — the sentence a widget
+     * author reads before writing one. Every zone in the core catalog carries
+     * the same distinction (a widget proposes, the host writes), and a plugin's
+     * zone owes its widgets the same statement.
+     */
+    description?: string;
+    /**
+     * How the zone places its widgets. `stack`, the default, is one block of
+     * the page: its widgets are cards, spaced, and the block takes no room when
+     * nothing in it drew. `bare` adds no element of its own: every widget is one
+     * item of a layout the HOST draws — a button in a row of actions, a control
+     * beside a form's fields, a dialog that portals out of the page. A wrapper
+     * would put every button of a row into one column.
+     */
+    layout?: PluginZoneLayout;
+}
+/** See {@link PluginZoneDeclaration.layout}. */
+export type PluginZoneLayout = 'stack' | 'bare';
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginZone = PluginZoneDeclaration<unknown> & {
+    pluginId: string;
+};
+export declare const PLUGIN_ZONES: import("./plugin-services").PluginServiceContract<PluginZoneDeclaration<never>>;
+/**
+ * Declares a zone the registering plugin hosts. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; with neither
+ * the registration throws. A zone id another plugin declared throws naming
+ * both.
+ */
+export declare function registerPluginZone<Props>(declaration: PluginZoneDeclaration<Props>, options?: {
+    pluginId?: string;
+}): void;
+/** Every declared zone, with its owner, in registration order. */
+export declare function listPluginZones(): ResolvedPluginZone[];
+/** One declared zone by id, with its owner, or `null` when nobody declares it. */
+export declare function pluginZone(zoneId: string): ResolvedPluginZone | null;
+/** The plugin that declared a zone, for attribution, or `undefined`. */
+export declare function pluginIdForZone(zoneId: string): string | undefined;

package/src/lib/plugin-manager/plugin-zones.js

@@ -0,0 +1,74 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+/**
+ * A zone token. Pure: it allocates no registration and reads no registry, so
+ * a plugin may define one at module scope and register it from its register
+ * fn, where the loader's owner marker is set.
+ */ export function definePluginZone(id) {
+    const zoneId = id.trim();
+    if (!zoneId) throw new Error('a plugin zone needs an id');
+    return {
+        id: zoneId
+    };
+}
+export const PLUGIN_ZONES = definePluginServiceContract('core.zones', {
+    multiple: true
+});
+/**
+ * Declares a zone the registering plugin hosts. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; with neither
+ * the registration throws. A zone id another plugin declared throws naming
+ * both.
+ */ export function registerPluginZone(declaration, options) {
+    var _ref, _ref1, _getRegisteringPluginId;
+    var _declaration_zone_id, _declaration_zone, _declaration_label;
+    const key = (_ref = (_declaration_zone = declaration.zone) == null ? void 0 : (_declaration_zone_id = _declaration_zone.id) == null ? void 0 : _declaration_zone_id.trim()) != null ? _ref : '';
+    if (!key) throw new Error('a plugin zone needs an id');
+    if (!((_declaration_label = declaration.label) == null ? void 0 : _declaration_label.trim())) {
+        throw new Error(`plugin zone "${key}" needs a label`);
+    }
+    const pluginId = ((_ref1 = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref1 : '').trim();
+    const incumbent = resolvePluginServices(PLUGIN_ZONES).find((entry)=>entry.key === key);
+    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+        throw new Error(`zone "${key}" is already declared by "${incumbent.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_ZONES, declaration, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, {
+        key
+    }));
+}
+/** Every declared zone, with its owner, in registration order. */ export function listPluginZones() {
+    return resolvePluginServices(PLUGIN_ZONES).map((entry)=>_extends({}, entry.impl, {
+            pluginId: entry.pluginId
+        }));
+}
+/** One declared zone by id, with its owner, or `null` when nobody declares it. */ export function pluginZone(zoneId) {
+    const key = zoneId.trim();
+    const entry = resolvePluginServices(PLUGIN_ZONES).find((one)=>one.key === key);
+    return entry ? _extends({}, entry.impl, {
+        pluginId: entry.pluginId
+    }) : null;
+}
+/** The plugin that declared a zone, for attribution, or `undefined`. */ export function pluginIdForZone(zoneId) {
+    var _pluginZone;
+    return (_pluginZone = pluginZone(zoneId)) == null ? void 0 : _pluginZone.pluginId;
+}
+
+//# sourceMappingURL=plugin-zones.js.map

package/src/lib/plugin-manager/plugin-zones.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-zones.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A zone a plugin declares, and the props it hands each widget (AGL-3124).\n *\n * `CONSOLE_WIDGET_SLOTS` is the catalog of zones the console SHELL draws, and\n * a slot id has always been an open string, so a plugin could already host a\n * zone of its own. What it could not do is say what that zone HANDS a widget.\n * The props had to be a type, the type had to be somewhere both sides import,\n * and \"somewhere both sides import\" was read as the core — which is how\n * `plugin-manager/commerce-zone-props.ts` and `plugin-manager/record-zone-props.ts`\n * came to spell out the commerce catalog and the record vocabulary of two\n * named plugins inside the platform.\n *\n * So the declaration moves to the plugin. A plugin defines a token for its\n * zone with {@link definePluginZone}, carrying the props type on the token,\n * and registers it here with a label and the surface it is drawn on. A widget\n * author takes the props type off the token — `PluginZoneProps<typeof ZONE>`\n * — without the core ever naming a product, a deal or a lead.\n *\n * ## Nothing here reaches a published page\n *\n * A zone token is `{ id }` and nothing else: `__props` is a phantom field that\n * never holds a value, so the props type is carried at the type level and\n * erased. That is the same trick the two type-only modules above use, and it\n * is load-bearing rather than tidy — AGL-3082 measured the zone catalog on the\n * published page's static graph, and a declaration that put a plugin's prop\n * SHAPES there would have made every published page carry the console's\n * vocabulary. `plugin-zones.spec.ts` pins the token's own key set so a field\n * added to it later has to be a decision.\n *\n * This module is reached by its own subpath and is deliberately absent from\n * `plugin-manager/index.ts`, for the reason that barrel already states about\n * `plugin-figures`: what a published page does not need, it must not import.\n *\n * ## One zone id, one owner\n *\n * A zone is a position on a page somebody draws. Two plugins declaring the\n * same id would each believe they set what a widget there receives, and the\n * widget author would have no way to tell whose props arrived — so a second\n * plugin's declaration is refused naming both, and the incumbent keeps its\n * zone. The same plugin declaring again — a second surface, a hot reload —\n * replaces its own.\n */\n\n/**\n * A zone's identity, with the props it hands a widget carried at the type\n * level. `__props` never holds a value.\n */\nexport interface PluginZone<Props> {\n  readonly id: string\n  readonly __props?: Props\n}\n\n/** The props a zone hands each widget, read off its token. */\nexport type PluginZoneProps<Zone> = Zone extends PluginZone<infer Props>\n  ? Props\n  : never\n\n/**\n * A zone token. Pure: it allocates no registration and reads no registry, so\n * a plugin may define one at module scope and register it from its register\n * fn, where the loader's owner marker is set.\n */\nexport function definePluginZone<Props>(id: string): PluginZone<Props> {\n  const zoneId = id.trim()\n  if (!zoneId) throw new Error('a plugin zone needs an id')\n  return { id: zoneId }\n}\n\n/** Where a zone is drawn, which is what decides the gates around it. */\nexport type PluginZoneSurface = 'console' | 'besigner' | 'site'\n\nexport interface PluginZoneDeclaration<Props = unknown> {\n  zone: PluginZone<Props>\n  /** What the plugin's own manifest and the widget picker call the zone. */\n  label: string\n  /** The surface the zone is drawn on. */\n  surface: PluginZoneSurface\n  /**\n   * What a widget here may do, and what it may not — the sentence a widget\n   * author reads before writing one. Every zone in the core catalog carries\n   * the same distinction (a widget proposes, the host writes), and a plugin's\n   * zone owes its widgets the same statement.\n   */\n  description?: string\n  /**\n   * How the zone places its widgets. `stack`, the default, is one block of\n   * the page: its widgets are cards, spaced, and the block takes no room when\n   * nothing in it drew. `bare` adds no element of its own: every widget is one\n   * item of a layout the HOST draws — a button in a row of actions, a control\n   * beside a form's fields, a dialog that portals out of the page. A wrapper\n   * would put every button of a row into one column.\n   */\n  layout?: PluginZoneLayout\n}\n\n/** See {@link PluginZoneDeclaration.layout}. */\nexport type PluginZoneLayout = 'stack' | 'bare'\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginZone = PluginZoneDeclaration<unknown> & {\n  pluginId: string\n}\n\nexport const PLUGIN_ZONES = definePluginServiceContract<\n  PluginZoneDeclaration<never>\n>('core.zones', { multiple: true })\n\n/**\n * Declares a zone the registering plugin hosts. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; with neither\n * the registration throws. A zone id another plugin declared throws naming\n * both.\n */\nexport function registerPluginZone<Props>(\n  declaration: PluginZoneDeclaration<Props>,\n  options?: { pluginId?: string },\n): void {\n  const key = declaration.zone?.id?.trim() ?? ''\n  if (!key) throw new Error('a plugin zone needs an id')\n  if (!declaration.label?.trim()) {\n    throw new Error(`plugin zone \"${key}\" needs a label`)\n  }\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_ZONES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `zone \"${key}\" is already declared by \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(\n    PLUGIN_ZONES,\n    declaration as unknown as PluginZoneDeclaration<never>,\n    {\n      ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n      key,\n    },\n  )\n}\n\n/** Every declared zone, with its owner, in registration order. */\nexport function listPluginZones(): ResolvedPluginZone[] {\n  return resolvePluginServices(PLUGIN_ZONES).map((entry) => ({\n    ...(entry.impl as unknown as PluginZoneDeclaration<unknown>),\n    pluginId: entry.pluginId,\n  }))\n}\n\n/** One declared zone by id, with its owner, or `null` when nobody declares it. */\nexport function pluginZone(zoneId: string): ResolvedPluginZone | null {\n  const key = zoneId.trim()\n  const entry = resolvePluginServices(PLUGIN_ZONES).find(\n    (one) => one.key === key,\n  )\n  return entry\n    ? {\n        ...(entry.impl as unknown as PluginZoneDeclaration<unknown>),\n        pluginId: entry.pluginId,\n      }\n    : null\n}\n\n/** The plugin that declared a zone, for attribution, or `undefined`. */\nexport function pluginIdForZone(zoneId: string): string | undefined {\n  return pluginZone(zoneId)?.pluginId\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","definePluginZone","id","zoneId","trim","Error","PLUGIN_ZONES","multiple","registerPluginZone","declaration","options","key","zone","label","pluginId","incumbent","find","entry","listPluginZones","map","impl","pluginZone","one","pluginIdForZone"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2D1B;;;;CAIC,GACD,OAAO,SAASC,iBAAwBC,EAAU;IAChD,MAAMC,SAASD,GAAGE,IAAI;IACtB,IAAI,CAACD,QAAQ,MAAM,IAAIE,MAAM;IAC7B,OAAO;QAAEH,IAAIC;IAAO;AACtB;AAqCA,OAAO,MAAMG,eAAeR,4BAE1B,cAAc;IAAES,UAAU;AAAK,GAAE;AAEnC;;;;;CAKC,GACD,OAAO,SAASC,mBACdC,WAAyC,EACzCC,OAA+B;cAObb,OAAAA;QALNY,sBAAAA,mBAEPA;IAFL,MAAME,eAAMF,oBAAAA,YAAYG,IAAI,sBAAhBH,uBAAAA,kBAAkBP,EAAE,qBAApBO,qBAAsBL,IAAI,qBAAM;IAC5C,IAAI,CAACO,KAAK,MAAM,IAAIN,MAAM;IAC1B,IAAI,GAACI,qBAAAA,YAAYI,KAAK,qBAAjBJ,mBAAmBL,IAAI,KAAI;QAC9B,MAAM,IAAIC,MAAM,CAAC,aAAa,EAAEM,IAAI,eAAe,CAAC;IACtD;IACA,MAAMG,WAAW,EAACjB,SAAAA,0BAAAA,oCAAAA,0BAA4Ba,2BAAAA,QAASI,QAAQ,YAA7CjB,QAAiD,IAAIO,IAAI;IAC3E,MAAMW,YAAYf,sBAAsBM,cAAcU,IAAI,CACxD,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAIT,MACR,CAAC,MAAM,EAAEM,IAAI,0BAA0B,EAAEI,UAAUD,QAAQ,CAAC,GAAG,CAAC,GAC9D,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAf,sBACEO,cACAG,aACA,aACMC,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC;QAC1DH;;AAGN;AAEA,gEAAgE,GAChE,OAAO,SAASO;IACd,OAAOlB,sBAAsBM,cAAca,GAAG,CAAC,CAACF,QAAW,aACrDA,MAAMG,IAAI;YACdN,UAAUG,MAAMH,QAAQ;;AAE5B;AAEA,gFAAgF,GAChF,OAAO,SAASO,WAAWlB,MAAc;IACvC,MAAMQ,MAAMR,OAAOC,IAAI;IACvB,MAAMa,QAAQjB,sBAAsBM,cAAcU,IAAI,CACpD,CAACM,MAAQA,IAAIX,GAAG,KAAKA;IAEvB,OAAOM,QACH,aACMA,MAAMG,IAAI;QACdN,UAAUG,MAAMH,QAAQ;SAE1B;AACN;AAEA,sEAAsE,GACtE,OAAO,SAASS,gBAAgBpB,MAAc;QACrCkB;IAAP,QAAOA,cAAAA,WAAWlB,4BAAXkB,YAAoBP,QAAQ;AACrC"}

package/src/lib/plugin-manager/realm-plugins.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PluginContributions } from './plugin-contributions';
+/**
+ * Trusted-realm remote plugins (AGL-420). Marketplace bundles normally run
+ * inside the cross-origin sandboxed PluginFrame; listings a staff member
+ * has REVIEWED AND SIGNED (`trust: 'realm'`) may instead load into the app
+ * realm and register real components/runtimes — first-party-grade
+ * extensions installed from the marketplace.
+ *
+ * Trust chain, all of which must hold before a byte executes:
+ * 1. The install doc pins {version, sha256}; the fetched bundle's SHA-256
+ *    must match (content-addressing — a swapped artifact can't load).
+ * 2. The version doc carries an Ed25519 `signature` over the sha256 hex,
+ *    made by the platform signing key (staff publish flow). When a public
+ *    key is configured, verification is MANDATORY and fails closed —
+ *    including on runtimes without WebCrypto Ed25519 support.
+ * 3. Bundles import nothing: the host injects its React/registry
+ *    singletons through `globalThis.__AGLYN_PLUGIN_HOST__` (see
+ *    {@link setRealmPluginHost}), so there is exactly one registry/React
+ *    instance — the same invariant that keeps first-party canvases from
+ *    rendering blank.
+ *
+ * Everything here is isomorphic (WebCrypto only, no node imports) so the
+ * client barrel stays browser-safe; the server-side loader for API
+ * handler bundles lives in realm-server.ts (node-only, /server entry).
+ */
+export declare const PLUGIN_HOST_ABI_VERSION = 1;
+/** The pinned install shape the loaders consume (installs + version doc). */
+export interface RealmPluginInstall {
+    listingId: string;
+    version: string;
+    sha256: string;
+    /** Staff-granted tier; anything but 'realm' never realm-loads. */
+    trust?: string;
+    /** Ed25519 signature (base64) over the sha256 hex string. */
+    signature?: string;
+    /** Host ABI the bundle targets (AGL-429); mismatches never load. */
+    hostAbi?: number;
+    /**
+     * The pinned version's manifest id (AGL-3116): the `pluginId` its own
+     * elements carry, which is how a page shows it uses an undeclared plugin.
+     */
+    pluginId?: string;
+    /**
+     * What the pinned version declares it contributes (AGL-3116); absent when
+     * it declares nothing, and then the default in `plugin-contributions.ts`
+     * decides where it loads.
+     */
+    contributes?: PluginContributions;
+}
+/**
+ * ABI gate (AGL-429): a declared `hostAbi` must equal the running host's
+ * generation; absent = pre-compat bundle, allowed (with a loader warning)
+ * so existing installs keep working across the introduction of the field.
+ */
+export declare function isCompatibleHostAbi(hostAbi: number | undefined): boolean;
+export interface LoadRealmPluginsOptions {
+    /** Base URL of the content-addressed artifacts origin. */
+    artifactsBase: string;
+    /**
+     * Base64 raw Ed25519 public key. When set, unsigned or badly-signed
+     * bundles are rejected; when unset, signature checking is skipped and
+     * the Firestore trust flag + sha pinning are the whole gate (dev mode).
+     */
+    publicKeyBase64?: string;
+}
+export declare function sha256Hex(bytes: ArrayBuffer): Promise<string>;
+/**
+ * Verifies the platform Ed25519 signature over a sha256 hex string.
+ * Fails CLOSED: any import/verify error (including runtimes without
+ * WebCrypto Ed25519) returns false.
+ */
+export declare function verifyRealmSignature(shaHex: string, signatureBase64: string, publicKeyBase64: string): Promise<boolean>;
+/**
+ * Verifies fetched bundle bytes against a pinned install: content hash
+ * always; platform signature when a public key is configured. Returns the
+ * reason on failure so callers can log precisely.
+ */
+export declare function verifyRealmBundle(bytes: ArrayBuffer, install: RealmPluginInstall, publicKeyBase64?: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Publishes the host ABI realm bundles build against. The APP composes it
+ * (React/jsxRuntime must come from the app bundle so singletons hold) —
+ * core only owns the slot and the version stamp.
+ */
+export declare function setRealmPluginHost(host: Record<string, unknown>): void;
+/**
+ * Fetches, verifies, and executes realm bundles in the app realm. Each
+ * bundle default-exports (or exports) `register(host)`; failures are
+ * logged and skipped — a broken marketplace plugin must never take the
+ * console or a site down. Idempotent per listing@version.
+ */
+export declare function loadRealmPlugins(installs: readonly RealmPluginInstall[], options: LoadRealmPluginsOptions): Promise<void>;

package/src/lib/plugin-manager/realm-plugins.js

@@ -0,0 +1,196 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { pluginArtifactPath } from "../app-utils/plugin-artifact-path.js";
+import { capturePluginStyles } from "./plugin-styles.js";
+/**
+ * Trusted-realm remote plugins (AGL-420). Marketplace bundles normally run
+ * inside the cross-origin sandboxed PluginFrame; listings a staff member
+ * has REVIEWED AND SIGNED (`trust: 'realm'`) may instead load into the app
+ * realm and register real components/runtimes — first-party-grade
+ * extensions installed from the marketplace.
+ *
+ * Trust chain, all of which must hold before a byte executes:
+ * 1. The install doc pins {version, sha256}; the fetched bundle's SHA-256
+ *    must match (content-addressing — a swapped artifact can't load).
+ * 2. The version doc carries an Ed25519 `signature` over the sha256 hex,
+ *    made by the platform signing key (staff publish flow). When a public
+ *    key is configured, verification is MANDATORY and fails closed —
+ *    including on runtimes without WebCrypto Ed25519 support.
+ * 3. Bundles import nothing: the host injects its React/registry
+ *    singletons through `globalThis.__AGLYN_PLUGIN_HOST__` (see
+ *    {@link setRealmPluginHost}), so there is exactly one registry/React
+ *    instance — the same invariant that keeps first-party canvases from
+ *    rendering blank.
+ *
+ * Everything here is isomorphic (WebCrypto only, no node imports) so the
+ * client barrel stays browser-safe; the server-side loader for API
+ * handler bundles lives in realm-server.ts (node-only, /server entry).
+ */ export const PLUGIN_HOST_ABI_VERSION = 1;
+/**
+ * ABI gate (AGL-429): a declared `hostAbi` must equal the running host's
+ * generation; absent = pre-compat bundle, allowed (with a loader warning)
+ * so existing installs keep working across the introduction of the field.
+ */ export function isCompatibleHostAbi(hostAbi) {
+    return hostAbi === undefined || hostAbi === PLUGIN_HOST_ABI_VERSION;
+}
+const decodeBase64 = (value)=>{
+    if (typeof atob === 'function') {
+        return Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
+    }
+    // Node without atob (never in practice on the pinned runtime, kept for
+    // safety). Reached through `globalThis` rather than as a bare global: a
+    // free `Buffer` identifier makes a browser bundler inject its 22 KB
+    // polyfill for a branch no browser can enter.
+    return new Uint8Array(globalThis.Buffer.from(value, 'base64'));
+};
+export async function sha256Hex(bytes) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Verifies the platform Ed25519 signature over a sha256 hex string.
+ * Fails CLOSED: any import/verify error (including runtimes without
+ * WebCrypto Ed25519) returns false.
+ */ export async function verifyRealmSignature(shaHex, signatureBase64, publicKeyBase64) {
+    try {
+        const key = await globalThis.crypto.subtle.importKey('raw', decodeBase64(publicKeyBase64), {
+            name: 'Ed25519'
+        }, false, [
+            'verify'
+        ]);
+        return await globalThis.crypto.subtle.verify({
+            name: 'Ed25519'
+        }, key, decodeBase64(signatureBase64), new TextEncoder().encode(shaHex));
+    } catch (unused) {
+        return false;
+    }
+}
+/**
+ * Verifies fetched bundle bytes against a pinned install: content hash
+ * always; platform signature when a public key is configured. Returns the
+ * reason on failure so callers can log precisely.
+ */ export async function verifyRealmBundle(bytes, install, publicKeyBase64) {
+    const digest = await sha256Hex(bytes);
+    if (digest !== install.sha256) {
+        return {
+            ok: false,
+            reason: `sha256 mismatch (got ${digest.slice(0, 12)}…)`
+        };
+    }
+    if (publicKeyBase64) {
+        if (!install.signature) return {
+            ok: false,
+            reason: 'missing signature'
+        };
+        const valid = await verifyRealmSignature(install.sha256, install.signature, publicKeyBase64);
+        if (!valid) return {
+            ok: false,
+            reason: 'invalid signature'
+        };
+    }
+    return {
+        ok: true
+    };
+}
+// ---------------------------------------------------------------------------
+// Host ABI + client loader (browser only past this point).
+// ---------------------------------------------------------------------------
+const HOST_GLOBAL = '__AGLYN_PLUGIN_HOST__';
+/**
+ * Publishes the host ABI realm bundles build against. The APP composes it
+ * (React/jsxRuntime must come from the app bundle so singletons hold) —
+ * core only owns the slot and the version stamp.
+ */ export function setRealmPluginHost(host) {
+    ;
+    globalThis[HOST_GLOBAL] = _extends({
+        version: PLUGIN_HOST_ABI_VERSION
+    }, host);
+}
+const loaded = new Map();
+/**
+ * Fetches, verifies, and executes realm bundles in the app realm. Each
+ * bundle default-exports (or exports) `register(host)`; failures are
+ * logged and skipped — a broken marketplace plugin must never take the
+ * console or a site down. Idempotent per listing@version.
+ */ export async function loadRealmPlugins(installs, options) {
+    const host = globalThis[HOST_GLOBAL];
+    const realmInstalls = installs.filter((install)=>install.trust === 'realm');
+    // Fail closed (AGL-507): without the trust public key we cannot verify
+    // bundle signatures, so refuse to load any realm plugin rather than fall
+    // back to sha256-only — mirroring the mandatory server-side key check
+    // (realm-server.ts). Silently degrading here contradicted the documented
+    // "verification is MANDATORY and fails closed" contract.
+    if (realmInstalls.length > 0 && !options.publicKeyBase64) {
+        console.error(`realm plugins: refusing to load ${realmInstalls.length} bundle(s) — ` + 'NEXT_PUBLIC_PLUGIN_TRUST_PUBLIC_KEY is not configured, so signatures ' + 'cannot be verified');
+        return;
+    }
+    await Promise.all(realmInstalls.map((install)=>{
+        const key = `${install.listingId}@${install.version}`;
+        let promise = loaded.get(key);
+        if (!promise) {
+            promise = (async ()=>{
+                const url = `${options.artifactsBase.replace(/\/+$/, '')}/${pluginArtifactPath(install.listingId, install.version, install.sha256)}`;
+                const response = await fetch(url);
+                if (!response.ok) throw new Error(`fetch ${response.status}`);
+                if (!isCompatibleHostAbi(install.hostAbi)) {
+                    throw new Error(`built for host ABI ${install.hostAbi}, host is ${PLUGIN_HOST_ABI_VERSION}`);
+                }
+                if (install.hostAbi === undefined) {
+                    console.warn(`realm plugin ${key}: no hostAbi declared (pre-AGL-429 bundle)`);
+                }
+                const bytes = await response.arrayBuffer();
+                const verdict = await verifyRealmBundle(bytes, install, options.publicKeyBase64);
+                if (verdict.ok === false) throw new Error(verdict.reason);
+                const blobUrl = URL.createObjectURL(new Blob([
+                    bytes
+                ], {
+                    type: 'text/javascript'
+                }));
+                try {
+                    // AGL-2486: module evaluation and `register()` both run inside
+                    // the style capture, because a bundler's `import './x.css'`
+                    // compiles to a `document.head.appendChild(<style>)` at module
+                    // EVAL time — before `register` is ever called. Anything the
+                    // bundle injects in that window is mirrored into the besigner
+                    // canvas's closed shadow root, which a document-level rule
+                    // otherwise cannot reach at all (measured: no effect on the
+                    // canvas, wins outright on the published page). See
+                    // `plugin-styles.tsx`.
+                    await capturePluginStyles(install.listingId, async ()=>{
+                        var _mod_register;
+                        var _mod_default;
+                        const mod = await import(/* webpackIgnore: true */ blobUrl);
+                        const register = (_mod_register = mod.register) != null ? _mod_register : (_mod_default = mod.default) == null ? void 0 : _mod_default.register;
+                        if (typeof register !== 'function') {
+                            throw new Error('bundle exports no register(host)');
+                        }
+                        register(host);
+                    });
+                } finally{
+                    URL.revokeObjectURL(blobUrl);
+                }
+            })().catch((error)=>{
+                loaded.delete(key);
+                console.error(`realm plugin ${key} failed to load:`, error);
+            });
+            loaded.set(key, promise);
+        }
+        return promise;
+    }));
+}
+
+//# sourceMappingURL=realm-plugins.js.map

package/src/lib/plugin-manager/realm-plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/realm-plugins.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { pluginArtifactPath } from '../app-utils/plugin-artifact-path'\nimport type { PluginContributions } from './plugin-contributions'\nimport { capturePluginStyles } from './plugin-styles'\n\n/**\n * Trusted-realm remote plugins (AGL-420). Marketplace bundles normally run\n * inside the cross-origin sandboxed PluginFrame; listings a staff member\n * has REVIEWED AND SIGNED (`trust: 'realm'`) may instead load into the app\n * realm and register real components/runtimes — first-party-grade\n * extensions installed from the marketplace.\n *\n * Trust chain, all of which must hold before a byte executes:\n * 1. The install doc pins {version, sha256}; the fetched bundle's SHA-256\n *    must match (content-addressing — a swapped artifact can't load).\n * 2. The version doc carries an Ed25519 `signature` over the sha256 hex,\n *    made by the platform signing key (staff publish flow). When a public\n *    key is configured, verification is MANDATORY and fails closed —\n *    including on runtimes without WebCrypto Ed25519 support.\n * 3. Bundles import nothing: the host injects its React/registry\n *    singletons through `globalThis.__AGLYN_PLUGIN_HOST__` (see\n *    {@link setRealmPluginHost}), so there is exactly one registry/React\n *    instance — the same invariant that keeps first-party canvases from\n *    rendering blank.\n *\n * Everything here is isomorphic (WebCrypto only, no node imports) so the\n * client barrel stays browser-safe; the server-side loader for API\n * handler bundles lives in realm-server.ts (node-only, /server entry).\n */\n\nexport const PLUGIN_HOST_ABI_VERSION = 1\n\n/** The pinned install shape the loaders consume (installs + version doc). */\nexport interface RealmPluginInstall {\n  listingId: string\n  version: string\n  sha256: string\n  /** Staff-granted tier; anything but 'realm' never realm-loads. */\n  trust?: string\n  /** Ed25519 signature (base64) over the sha256 hex string. */\n  signature?: string\n  /** Host ABI the bundle targets (AGL-429); mismatches never load. */\n  hostAbi?: number\n  /**\n   * The pinned version's manifest id (AGL-3116): the `pluginId` its own\n   * elements carry, which is how a page shows it uses an undeclared plugin.\n   */\n  pluginId?: string\n  /**\n   * What the pinned version declares it contributes (AGL-3116); absent when\n   * it declares nothing, and then the default in `plugin-contributions.ts`\n   * decides where it loads.\n   */\n  contributes?: PluginContributions\n}\n\n/**\n * ABI gate (AGL-429): a declared `hostAbi` must equal the running host's\n * generation; absent = pre-compat bundle, allowed (with a loader warning)\n * so existing installs keep working across the introduction of the field.\n */\nexport function isCompatibleHostAbi(hostAbi: number | undefined): boolean {\n  return hostAbi === undefined || hostAbi === PLUGIN_HOST_ABI_VERSION\n}\n\nexport interface LoadRealmPluginsOptions {\n  /** Base URL of the content-addressed artifacts origin. */\n  artifactsBase: string\n  /**\n   * Base64 raw Ed25519 public key. When set, unsigned or badly-signed\n   * bundles are rejected; when unset, signature checking is skipped and\n   * the Firestore trust flag + sha pinning are the whole gate (dev mode).\n   */\n  publicKeyBase64?: string\n}\n\nconst decodeBase64 = (value: string): Uint8Array => {\n  if (typeof atob === 'function') {\n    return Uint8Array.from(atob(value), (char) => char.charCodeAt(0))\n  }\n  // Node without atob (never in practice on the pinned runtime, kept for\n  // safety). Reached through `globalThis` rather than as a bare global: a\n  // free `Buffer` identifier makes a browser bundler inject its 22 KB\n  // polyfill for a branch no browser can enter.\n  return new Uint8Array(globalThis.Buffer.from(value, 'base64'))\n}\n\nexport async function sha256Hex(bytes: ArrayBuffer): Promise<string> {\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest))\n    .map((byte) => byte.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/**\n * Verifies the platform Ed25519 signature over a sha256 hex string.\n * Fails CLOSED: any import/verify error (including runtimes without\n * WebCrypto Ed25519) returns false.\n */\nexport async function verifyRealmSignature(\n  shaHex: string,\n  signatureBase64: string,\n  publicKeyBase64: string,\n): Promise<boolean> {\n  try {\n    const key = await globalThis.crypto.subtle.importKey(\n      'raw',\n      decodeBase64(publicKeyBase64) as unknown as ArrayBuffer,\n      { name: 'Ed25519' },\n      false,\n      ['verify'],\n    )\n    return await globalThis.crypto.subtle.verify(\n      { name: 'Ed25519' },\n      key,\n      decodeBase64(signatureBase64) as unknown as ArrayBuffer,\n      new TextEncoder().encode(shaHex),\n    )\n  } catch {\n    return false\n  }\n}\n\n/**\n * Verifies fetched bundle bytes against a pinned install: content hash\n * always; platform signature when a public key is configured. Returns the\n * reason on failure so callers can log precisely.\n */\nexport async function verifyRealmBundle(\n  bytes: ArrayBuffer,\n  install: RealmPluginInstall,\n  publicKeyBase64?: string,\n): Promise<{ ok: true } | { ok: false; reason: string }> {\n  const digest = await sha256Hex(bytes)\n  if (digest !== install.sha256) {\n    return { ok: false, reason: `sha256 mismatch (got ${digest.slice(0, 12)}…)` }\n  }\n  if (publicKeyBase64) {\n    if (!install.signature) return { ok: false, reason: 'missing signature' }\n    const valid = await verifyRealmSignature(\n      install.sha256,\n      install.signature,\n      publicKeyBase64,\n    )\n    if (!valid) return { ok: false, reason: 'invalid signature' }\n  }\n  return { ok: true }\n}\n\n// ---------------------------------------------------------------------------\n// Host ABI + client loader (browser only past this point).\n// ---------------------------------------------------------------------------\n\nconst HOST_GLOBAL = '__AGLYN_PLUGIN_HOST__'\n\n/**\n * Publishes the host ABI realm bundles build against. The APP composes it\n * (React/jsxRuntime must come from the app bundle so singletons hold) —\n * core only owns the slot and the version stamp.\n */\nexport function setRealmPluginHost(host: Record<string, unknown>): void {\n  ;(globalThis as Record<string, unknown>)[HOST_GLOBAL] = {\n    version: PLUGIN_HOST_ABI_VERSION,\n    ...host,\n  }\n}\n\nconst loaded = new Map<string, Promise<void>>()\n\n/**\n * Fetches, verifies, and executes realm bundles in the app realm. Each\n * bundle default-exports (or exports) `register(host)`; failures are\n * logged and skipped — a broken marketplace plugin must never take the\n * console or a site down. Idempotent per listing@version.\n */\nexport async function loadRealmPlugins(\n  installs: readonly RealmPluginInstall[],\n  options: LoadRealmPluginsOptions,\n): Promise<void> {\n  const host = (globalThis as Record<string, unknown>)[HOST_GLOBAL]\n  const realmInstalls = installs.filter((install) => install.trust === 'realm')\n  // Fail closed (AGL-507): without the trust public key we cannot verify\n  // bundle signatures, so refuse to load any realm plugin rather than fall\n  // back to sha256-only — mirroring the mandatory server-side key check\n  // (realm-server.ts). Silently degrading here contradicted the documented\n  // \"verification is MANDATORY and fails closed\" contract.\n  if (realmInstalls.length > 0 && !options.publicKeyBase64) {\n    console.error(\n      `realm plugins: refusing to load ${realmInstalls.length} bundle(s) — ` +\n        'NEXT_PUBLIC_PLUGIN_TRUST_PUBLIC_KEY is not configured, so signatures ' +\n        'cannot be verified',\n    )\n    return\n  }\n  await Promise.all(\n    realmInstalls.map((install) => {\n        const key = `${install.listingId}@${install.version}`\n        let promise = loaded.get(key)\n        if (!promise) {\n          promise = (async () => {\n            const url = `${options.artifactsBase.replace(/\\/+$/, '')}/${pluginArtifactPath(\n              install.listingId,\n              install.version,\n              install.sha256,\n            )}`\n            const response = await fetch(url)\n            if (!response.ok) throw new Error(`fetch ${response.status}`)\n            if (!isCompatibleHostAbi(install.hostAbi)) {\n              throw new Error(\n                `built for host ABI ${install.hostAbi}, host is ${PLUGIN_HOST_ABI_VERSION}`,\n              )\n            }\n            if (install.hostAbi === undefined) {\n              console.warn(\n                `realm plugin ${key}: no hostAbi declared (pre-AGL-429 bundle)`,\n              )\n            }\n            const bytes = await response.arrayBuffer()\n            const verdict = await verifyRealmBundle(\n              bytes,\n              install,\n              options.publicKeyBase64,\n            )\n            if (verdict.ok === false) throw new Error(verdict.reason)\n            const blobUrl = URL.createObjectURL(\n              new Blob([bytes], { type: 'text/javascript' }),\n            )\n            try {\n              // AGL-2486: module evaluation and `register()` both run inside\n              // the style capture, because a bundler's `import './x.css'`\n              // compiles to a `document.head.appendChild(<style>)` at module\n              // EVAL time — before `register` is ever called. Anything the\n              // bundle injects in that window is mirrored into the besigner\n              // canvas's closed shadow root, which a document-level rule\n              // otherwise cannot reach at all (measured: no effect on the\n              // canvas, wins outright on the published page). See\n              // `plugin-styles.tsx`.\n              await capturePluginStyles(install.listingId, async () => {\n                const mod = (await import(\n                  /* webpackIgnore: true */ blobUrl\n                )) as {\n                  register?: (host: unknown) => void\n                  default?: { register?: (host: unknown) => void }\n                }\n                const register = mod.register ?? mod.default?.register\n                if (typeof register !== 'function') {\n                  throw new Error('bundle exports no register(host)')\n                }\n                register(host)\n              })\n            } finally {\n              URL.revokeObjectURL(blobUrl)\n            }\n          })().catch((error) => {\n            loaded.delete(key)\n            console.error(`realm plugin ${key} failed to load:`, error)\n          })\n          loaded.set(key, promise)\n        }\n        return promise\n      }),\n  )\n}\n"],"names":["pluginArtifactPath","capturePluginStyles","PLUGIN_HOST_ABI_VERSION","isCompatibleHostAbi","hostAbi","undefined","decodeBase64","value","atob","Uint8Array","from","char","charCodeAt","globalThis","Buffer","sha256Hex","bytes","digest","crypto","subtle","Array","map","byte","toString","padStart","join","verifyRealmSignature","shaHex","signatureBase64","publicKeyBase64","key","importKey","name","verify","TextEncoder","encode","verifyRealmBundle","install","sha256","ok","reason","slice","signature","valid","HOST_GLOBAL","setRealmPluginHost","host","version","loaded","Map","loadRealmPlugins","installs","options","realmInstalls","filter","trust","length","console","error","Promise","all","listingId","promise","get","url","artifactsBase","replace","response","fetch","Error","status","warn","arrayBuffer","verdict","blobUrl","URL","createObjectURL","Blob","type","mod","register","default","revokeObjectURL","catch","delete","set"],"mappings":"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"}

package/src/lib/plugin-manager/realm-server.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Remote SERVER handler bundles (AGL-420) — the highest-risk switch in the
+ * platform, default OFF everywhere. When explicitly enabled, the API
+ * dispatchers load staff-signed bundles that register plugin API routes
+ * in-process. Guardrails, all mandatory (unlike the client tier, none are
+ * optional here):
+ *
+ * - `PLUGIN_REMOTE_SERVER=enabled` — the master switch.
+ * - `PLUGIN_REMOTE_SERVER_BUNDLES` — an explicit per-deploy allowlist of
+ *   `listingId@version` entries; nothing loads implicitly from installs.
+ * - `PLUGIN_TRUST_PUBLIC_KEY` — REQUIRED; every bundle must carry a valid
+ *   platform Ed25519 signature over its sha256. No key, no loading.
+ * - sha256 content-addressing against the version doc, same as the client.
+ *
+ * Verified bytes are written to a private temp file and imported by
+ * `file://` URL (node can't import blob URLs); the module's exported
+ * `registerApi()` runs with the same registries first-party `/server`
+ * entries use. Failures log and skip — a broken remote bundle must not
+ * take the API surface down (its own paths simply stay unregistered).
+ */
+export interface RemoteServerBundleSource {
+    /** Resolves a listing version doc to its pinned hash + signature. */
+    resolveVersion(listingId: string, version: string): Promise<{
+        sha256: string;
+        signature?: string;
+        trust?: string;
+        hostAbi?: number;
+    } | null>;
+    /** Base URL of the content-addressed artifacts origin. */
+    artifactsBase: string;
+}
+export declare function remoteServerBundlesEnabled(): boolean;
+export interface LoadedServerBundle {
+    listingId: string;
+    version: string;
+    sha256: string;
+}
+export declare function loadRemoteServerBundles(source: RemoteServerBundleSource): Promise<LoadedServerBundle[]>;