@aglyn/aglyn 1.0.0-beta.150 → 1.0.0-beta.152

package/src/lib/plugin-manager/plugin-site-cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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.
+ */
+/** What the caller wants dropped, and why. */
+export interface PluginSiteCacheRequest {
+    /**
+     * The sites whose rendered pages must go. Duplicates are the caller's to
+     * avoid or not — the implementation is free to collapse them.
+     */
+    hostIds: readonly string[];
+    /**
+     * Why, in a few words, for the fan-out's own logging: a truncated purge
+     * is only debuggable if the record says what it was purging for.
+     * `'marketplace listing revoked'`, not `'revoke'`.
+     */
+    reason: string;
+}
+export interface PluginSiteCacheResult {
+    /** Sites whose cached pages were dropped. */
+    dropped: number;
+    /**
+     * Sites deliberately left holding cached pages because the fan-out hit
+     * its cap. Not an error — a decision the shell made and logged — but a
+     * number a caller may want to surface, because those sites are still
+     * serving what was just stopped.
+     */
+    skipped: number;
+    /**
+     * Whether the drop certainly happened. FALSE when no implementation is
+     * registered or one threw, and a caller must not read `dropped: 0` as
+     * "there was nothing to drop" without checking this first.
+     */
+    complete: boolean;
+}
+export interface PluginSiteCache {
+    drop(request: PluginSiteCacheRequest): Promise<PluginSiteCacheResult>;
+}
+/**
+ * One implementation: the app's. Two would be two cache layers disagreeing
+ * about whether a page is gone, and the second to register would be the one
+ * nobody knew about.
+ */
+export declare const PLUGIN_SITE_CACHE: import("./plugin-services").PluginServiceContract<PluginSiteCache>;
+/**
+ * Installs the app's implementation. Called once, at server boot, by the app
+ * that owns the tenant's cache.
+ *
+ * `pluginId` is required from outside a plugin's register fn, as it is for
+ * every service: the app passes its own marker, and the contract refuses an
+ * anonymous registration rather than accepting one nothing can be traced to.
+ */
+export declare function registerPluginSiteCache(cache: PluginSiteCache, options?: {
+    pluginId?: string;
+}): void;
+/** Whether an implementation is installed — for a caller that wants to say so. */
+export declare function hasPluginSiteCache(): boolean;
+/**
+ * Drops the cached pages of the named sites.
+ *
+ * NEVER THROWS and never silently succeeds: a failure comes back as
+ * `complete: false` with the reason logged, because the callers are stop
+ * paths that must complete their own work either way. Read `complete`
+ * before reading `dropped`.
+ */
+export declare function dropPluginSiteCache(request: PluginSiteCacheRequest): Promise<PluginSiteCacheResult>;

package/src/lib/plugin-manager/plugin-site-cache.js

@@ -0,0 +1,125 @@
+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.
+ */ /**
+ * HOW A PLUGIN DROPS A SITE'S CACHED PAGES (AGL-3080).
+ *
+ * The shell hands this one down rather than up. Every other contract in this
+ * directory is a plugin telling the shell something; this is the shell
+ * telling plugins it can do something — purge the rendered HTML of a site —
+ * because purging it takes the tenant's cache tags and revalidation paths,
+ * which live in the app and are not a plugin's to know.
+ *
+ * ## The case, and why it is a kill switch rather than a nicety
+ *
+ * A marketplace plugin can be REVOKED. Revoking writes a stop on the
+ * version, and the tenant refuses revoked bytes at render time — but a page
+ * already rendered and cached does not re-render to find that out. So the
+ * revoke has a second half: drop the cached pages of every site running it.
+ * Without it a revoked plugin keeps executing in visitors' browsers for as
+ * long as the cache holds, which is the whole failure the stop exists to
+ * prevent.
+ *
+ * ## ⛔ AN ABSENT IMPLEMENTATION IS AN ANSWER, AND IT IS `complete: false`
+ *
+ * The registry is filled by the APP at boot. A process that has not filled
+ * it resolves "no cache to drop" — indistinguishable, from the inside, from
+ * a workspace whose sites were all already fresh. That is the AGL-3025 shape
+ * and on this path it means a revoked plugin quietly kept serving.
+ *
+ * So there is no silent branch. {@link dropPluginSiteCache} always answers a
+ * {@link PluginSiteCacheResult}, and `complete` is false whenever the drop
+ * did not certainly happen — nothing registered, or the implementation
+ * threw. A caller acts on that: the revoke itself must still stand (a plugin
+ * left un-revoked because a cache purge failed is strictly worse), but the
+ * reader has to be told the purge did not run, and the log has to carry it.
+ *
+ * ## The split, in one line
+ *
+ * The plugin knows WHICH sites — that is its own install pins, its own
+ * collection. The shell knows HOW to drop one, and owns the fan-out policy:
+ * the cap, the concurrency, and saying out loud when a cap truncated the
+ * list. Neither half is guessable from the other side.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+/**
+ * One implementation: the app's. Two would be two cache layers disagreeing
+ * about whether a page is gone, and the second to register would be the one
+ * nobody knew about.
+ */ export const PLUGIN_SITE_CACHE = definePluginServiceContract('core.site-cache', {
+    multiple: false
+});
+/**
+ * Installs the app's implementation. Called once, at server boot, by the app
+ * that owns the tenant's cache.
+ *
+ * `pluginId` is required from outside a plugin's register fn, as it is for
+ * every service: the app passes its own marker, and the contract refuses an
+ * anonymous registration rather than accepting one nothing can be traced to.
+ */ export function registerPluginSiteCache(cache, options) {
+    if (typeof (cache == null ? void 0 : cache.drop) !== 'function') {
+        throw new Error('a site cache needs a drop function');
+    }
+    registerPluginService(PLUGIN_SITE_CACHE, cache, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** Whether an implementation is installed — for a caller that wants to say so. */ export function hasPluginSiteCache() {
+    return Boolean(resolvePluginService(PLUGIN_SITE_CACHE));
+}
+/**
+ * Drops the cached pages of the named sites.
+ *
+ * NEVER THROWS and never silently succeeds: a failure comes back as
+ * `complete: false` with the reason logged, because the callers are stop
+ * paths that must complete their own work either way. Read `complete`
+ * before reading `dropped`.
+ */ export async function dropPluginSiteCache(request) {
+    const hostIds = [
+        ...new Set(request.hostIds.filter(Boolean))
+    ];
+    if (!hostIds.length) {
+        // Nothing asked for is the one case where "nothing dropped" is complete
+        // on its own terms, whether or not anything is registered.
+        return {
+            dropped: 0,
+            skipped: 0,
+            complete: true
+        };
+    }
+    const cache = resolvePluginService(PLUGIN_SITE_CACHE);
+    if (!cache) {
+        console.error(`[site-cache] no implementation is installed, so ${hostIds.length} ` + `site(s) keep their cached pages after: ${request.reason}. The app ` + 'registers this at boot; a process that has not is serving stopped ' + 'content.');
+        return {
+            dropped: 0,
+            skipped: 0,
+            complete: false
+        };
+    }
+    try {
+        return await cache.drop(_extends({}, request, {
+            hostIds
+        }));
+    } catch (error) {
+        console.error(`[site-cache] the drop failed after: ${request.reason}`, error);
+        return {
+            dropped: 0,
+            skipped: 0,
+            complete: false
+        };
+    }
+}
+
+//# sourceMappingURL=plugin-site-cache.js.map

package/src/lib/plugin-manager/plugin-site-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-cache.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\n/**\n * HOW A PLUGIN DROPS A SITE'S CACHED PAGES (AGL-3080).\n *\n * The shell hands this one down rather than up. Every other contract in this\n * directory is a plugin telling the shell something; this is the shell\n * telling plugins it can do something — purge the rendered HTML of a site —\n * because purging it takes the tenant's cache tags and revalidation paths,\n * which live in the app and are not a plugin's to know.\n *\n * ## The case, and why it is a kill switch rather than a nicety\n *\n * A marketplace plugin can be REVOKED. Revoking writes a stop on the\n * version, and the tenant refuses revoked bytes at render time — but a page\n * already rendered and cached does not re-render to find that out. So the\n * revoke has a second half: drop the cached pages of every site running it.\n * Without it a revoked plugin keeps executing in visitors' browsers for as\n * long as the cache holds, which is the whole failure the stop exists to\n * prevent.\n *\n * ## ⛔ AN ABSENT IMPLEMENTATION IS AN ANSWER, AND IT IS `complete: false`\n *\n * The registry is filled by the APP at boot. A process that has not filled\n * it resolves \"no cache to drop\" — indistinguishable, from the inside, from\n * a workspace whose sites were all already fresh. That is the AGL-3025 shape\n * and on this path it means a revoked plugin quietly kept serving.\n *\n * So there is no silent branch. {@link dropPluginSiteCache} always answers a\n * {@link PluginSiteCacheResult}, and `complete` is false whenever the drop\n * did not certainly happen — nothing registered, or the implementation\n * threw. A caller acts on that: the revoke itself must still stand (a plugin\n * left un-revoked because a cache purge failed is strictly worse), but the\n * reader has to be told the purge did not run, and the log has to carry it.\n *\n * ## The split, in one line\n *\n * The plugin knows WHICH sites — that is its own install pins, its own\n * collection. The shell knows HOW to drop one, and owns the fan-out policy:\n * the cap, the concurrency, and saying out loud when a cap truncated the\n * list. Neither half is guessable from the other side.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** What the caller wants dropped, and why. */\nexport interface PluginSiteCacheRequest {\n  /**\n   * The sites whose rendered pages must go. Duplicates are the caller's to\n   * avoid or not — the implementation is free to collapse them.\n   */\n  hostIds: readonly string[]\n  /**\n   * Why, in a few words, for the fan-out's own logging: a truncated purge\n   * is only debuggable if the record says what it was purging for.\n   * `'marketplace listing revoked'`, not `'revoke'`.\n   */\n  reason: string\n}\n\nexport interface PluginSiteCacheResult {\n  /** Sites whose cached pages were dropped. */\n  dropped: number\n  /**\n   * Sites deliberately left holding cached pages because the fan-out hit\n   * its cap. Not an error — a decision the shell made and logged — but a\n   * number a caller may want to surface, because those sites are still\n   * serving what was just stopped.\n   */\n  skipped: number\n  /**\n   * Whether the drop certainly happened. FALSE when no implementation is\n   * registered or one threw, and a caller must not read `dropped: 0` as\n   * \"there was nothing to drop\" without checking this first.\n   */\n  complete: boolean\n}\n\nexport interface PluginSiteCache {\n  drop(request: PluginSiteCacheRequest): Promise<PluginSiteCacheResult>\n}\n\n/**\n * One implementation: the app's. Two would be two cache layers disagreeing\n * about whether a page is gone, and the second to register would be the one\n * nobody knew about.\n */\nexport const PLUGIN_SITE_CACHE = definePluginServiceContract<PluginSiteCache>(\n  'core.site-cache',\n  { multiple: false },\n)\n\n/**\n * Installs the app's implementation. Called once, at server boot, by the app\n * that owns the tenant's cache.\n *\n * `pluginId` is required from outside a plugin's register fn, as it is for\n * every service: the app passes its own marker, and the contract refuses an\n * anonymous registration rather than accepting one nothing can be traced to.\n */\nexport function registerPluginSiteCache(\n  cache: PluginSiteCache,\n  options?: { pluginId?: string },\n): void {\n  if (typeof cache?.drop !== 'function') {\n    throw new Error('a site cache needs a drop function')\n  }\n  registerPluginService(PLUGIN_SITE_CACHE, cache, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Whether an implementation is installed — for a caller that wants to say so. */\nexport function hasPluginSiteCache(): boolean {\n  return Boolean(resolvePluginService(PLUGIN_SITE_CACHE))\n}\n\n/**\n * Drops the cached pages of the named sites.\n *\n * NEVER THROWS and never silently succeeds: a failure comes back as\n * `complete: false` with the reason logged, because the callers are stop\n * paths that must complete their own work either way. Read `complete`\n * before reading `dropped`.\n */\nexport async function dropPluginSiteCache(\n  request: PluginSiteCacheRequest,\n): Promise<PluginSiteCacheResult> {\n  const hostIds = [...new Set(request.hostIds.filter(Boolean))]\n  if (!hostIds.length) {\n    // Nothing asked for is the one case where \"nothing dropped\" is complete\n    // on its own terms, whether or not anything is registered.\n    return { dropped: 0, skipped: 0, complete: true }\n  }\n  const cache = resolvePluginService(PLUGIN_SITE_CACHE)\n  if (!cache) {\n    console.error(\n      `[site-cache] no implementation is installed, so ${hostIds.length} ` +\n        `site(s) keep their cached pages after: ${request.reason}. The app ` +\n        'registers this at boot; a process that has not is serving stopped ' +\n        'content.',\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n  try {\n    return await cache.drop({ ...request, hostIds })\n  } catch (error) {\n    console.error(\n      `[site-cache] the drop failed after: ${request.reason}`,\n      error,\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_SITE_CACHE","multiple","registerPluginSiteCache","cache","options","drop","Error","pluginId","hasPluginSiteCache","Boolean","dropPluginSiteCache","request","hostIds","Set","filter","length","dropped","skipped","complete","console","error","reason"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAwC1B;;;;CAIC,GACD,OAAO,MAAMC,oBAAoBH,4BAC/B,mBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;;;CAOC,GACD,OAAO,SAASC,wBACdC,KAAsB,EACtBC,OAA+B;IAE/B,IAAI,QAAOD,yBAAAA,MAAOE,IAAI,MAAK,YAAY;QACrC,MAAM,IAAIC,MAAM;IAClB;IACAR,sBAAsBE,mBAAmBG,OAAO,aAC1CC,CAAAA,2BAAAA,QAASG,QAAQ,IAAG;QAAEA,UAAUH,QAAQG,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,gFAAgF,GAChF,OAAO,SAASC;IACd,OAAOC,QAAQV,qBAAqBC;AACtC;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeU,oBACpBC,OAA+B;IAE/B,MAAMC,UAAU;WAAI,IAAIC,IAAIF,QAAQC,OAAO,CAACE,MAAM,CAACL;KAAU;IAC7D,IAAI,CAACG,QAAQG,MAAM,EAAE;QACnB,wEAAwE;QACxE,2DAA2D;QAC3D,OAAO;YAAEC,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAK;IAClD;IACA,MAAMf,QAAQJ,qBAAqBC;IACnC,IAAI,CAACG,OAAO;QACVgB,QAAQC,KAAK,CACX,CAAC,gDAAgD,EAAER,QAAQG,MAAM,CAAC,CAAC,CAAC,GAClE,CAAC,uCAAuC,EAAEJ,QAAQU,MAAM,CAAC,UAAU,CAAC,GACpE,uEACA;QAEJ,OAAO;YAAEL,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;IACA,IAAI;QACF,OAAO,MAAMf,MAAME,IAAI,CAAC,aAAKM;YAASC;;IACxC,EAAE,OAAOQ,OAAO;QACdD,QAAQC,KAAK,CACX,CAAC,oCAAoC,EAAET,QAAQU,MAAM,EAAE,EACvDD;QAEF,OAAO;YAAEJ,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;AACF"}

package/src/lib/plugin-manager/plugin-trust-signing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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.
+ */
+export interface PluginTrustSignature {
+    /** Base64 Ed25519 signature over the sha256 hex. Absent unless `signed`. */
+    signature?: string;
+    /**
+     * Whether a signature was produced. FALSE when nothing is registered, the
+     * deployment holds no key, or signing failed — and a caller must refuse
+     * the grant, never write one without a signature.
+     */
+    signed: boolean;
+    /** Why not, in the operator's terms, when `signed` is false. */
+    reason?: string;
+}
+export interface PluginTrustSigner {
+    /** Signs a version's sha256 hex with the platform's Ed25519 key. */
+    sign(sha256: string): Promise<PluginTrustSignature>;
+}
+/**
+ * One implementation: the app that holds the key. A second would be a second
+ * signing authority, and the loaders verify against ONE public key.
+ */
+export declare const PLUGIN_TRUST_SIGNER: import("./plugin-services").PluginServiceContract<PluginTrustSigner>;
+/** Installs the app's signer. Called once, at server boot. */
+export declare function registerPluginTrustSigner(signer: PluginTrustSigner, options?: {
+    pluginId?: string;
+}): void;
+/** Whether this deployment can sign at all — for a surface that says so. */
+export declare function hasPluginTrustSigner(): boolean;
+/**
+ * Signs `sha256`, or says why it could not.
+ *
+ * NEVER THROWS, and never answers a signature it did not make. Read
+ * `signed` before reading `signature`; see the module docblock for why a
+ * caller must refuse rather than continue.
+ */
+export declare function signPluginTrust(sha256: string): Promise<PluginTrustSignature>;

package/src/lib/plugin-manager/plugin-trust-signing.js

@@ -0,0 +1,119 @@
+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.
+ */ /**
+ * WHO HOLDS THE PLATFORM'S TRUST KEY (AGL-3080).
+ *
+ * Realm trust is the strongest grant in the platform: it drops a marketplace
+ * bundle into the app realm, where neither the sandbox iframe nor the
+ * manifest CSP stands between it and user data. A grant is an Ed25519
+ * signature, made with `PLUGIN_TRUST_PRIVATE_KEY`, over the reviewed
+ * version's sha256 — and every loader verifies it before a byte executes.
+ *
+ * ## Why this is a seam rather than a move
+ *
+ * The queue around it is the MARKETPLACE's: `marketplaceListings` is its
+ * collection, "a version must have passed review" is its rule, and the
+ * fields the grant writes are its documents. All of that belongs with the
+ * plugin, the way the review queue and the report queue already do.
+ *
+ * The KEY does not. It is deployed to the console and nowhere else — never
+ * to a tenant runtime — and this package is published to npm, where a
+ * self-hoster generates their own pair. A plugin that read the key directly
+ * would put the platform's signing authority inside a package anyone can
+ * install, to no benefit: the plugin has nothing to do with it beyond
+ * wanting one string signed.
+ *
+ * So the shell signs, and the marketplace decides what is worth signing.
+ * The sibling of `core.site-cache`, and the same direction: the shell
+ * offering a capability down.
+ *
+ * ## ⛔ AN ABSENT SIGNER REFUSES. IT DOES NOT GRANT.
+ *
+ * This is the opposite failure direction from every other contract here, and
+ * it is the one that matters. `core.site-cache` answers `complete: false`
+ * and the caller carries on, because a stale cache is survivable. An
+ * unsigned realm grant is not survivable: the loaders fail closed on a
+ * missing signature, so a "grant" without one produces a version that is
+ * marked trusted and cannot load — or, far worse if a loader is ever
+ * lenient, one that loads unverified.
+ *
+ * {@link signPluginTrust} therefore never returns a bare string. It answers
+ * `{ signed: false, reason }` when nothing is registered, when the
+ * deployment has no key, or when signing throws, and the caller MUST refuse
+ * the grant on it rather than writing a partial one.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+/**
+ * One implementation: the app that holds the key. A second would be a second
+ * signing authority, and the loaders verify against ONE public key.
+ */ export const PLUGIN_TRUST_SIGNER = definePluginServiceContract('core.plugin-trust-signer', {
+    multiple: false
+});
+/** Installs the app's signer. Called once, at server boot. */ export function registerPluginTrustSigner(signer, options) {
+    if (typeof (signer == null ? void 0 : signer.sign) !== 'function') {
+        throw new Error('a plugin trust signer needs a sign function');
+    }
+    registerPluginService(PLUGIN_TRUST_SIGNER, signer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** Whether this deployment can sign at all — for a surface that says so. */ export function hasPluginTrustSigner() {
+    return Boolean(resolvePluginService(PLUGIN_TRUST_SIGNER));
+}
+/**
+ * Signs `sha256`, or says why it could not.
+ *
+ * NEVER THROWS, and never answers a signature it did not make. Read
+ * `signed` before reading `signature`; see the module docblock for why a
+ * caller must refuse rather than continue.
+ */ export async function signPluginTrust(sha256) {
+    const digest = sha256 == null ? void 0 : sha256.trim();
+    if (!digest) {
+        return {
+            signed: false,
+            reason: 'No version hash to sign.'
+        };
+    }
+    const signer = resolvePluginService(PLUGIN_TRUST_SIGNER);
+    if (!signer) {
+        console.error('[trust-signer] no implementation is installed, so realm trust cannot ' + 'be granted. The app registers this at boot.');
+        return {
+            signed: false,
+            reason: 'Trust signing is not available on this deployment.'
+        };
+    }
+    try {
+        const result = await signer.sign(digest);
+        // A signer that answered `signed` with nothing to show is a bug in the
+        // signer, and granting on it would write the trust flag with no
+        // signature — the one state the loaders cannot distinguish from tampering.
+        if (result.signed && !result.signature) {
+            return {
+                signed: false,
+                reason: 'Trust signing returned no signature.'
+            };
+        }
+        return result;
+    } catch (error) {
+        console.error('[trust-signer] signing failed', error);
+        return {
+            signed: false,
+            reason: 'Trust signing failed.'
+        };
+    }
+}
+
+//# sourceMappingURL=plugin-trust-signing.js.map

package/src/lib/plugin-manager/plugin-trust-signing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-trust-signing.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\n/**\n * WHO HOLDS THE PLATFORM'S TRUST KEY (AGL-3080).\n *\n * Realm trust is the strongest grant in the platform: it drops a marketplace\n * bundle into the app realm, where neither the sandbox iframe nor the\n * manifest CSP stands between it and user data. A grant is an Ed25519\n * signature, made with `PLUGIN_TRUST_PRIVATE_KEY`, over the reviewed\n * version's sha256 — and every loader verifies it before a byte executes.\n *\n * ## Why this is a seam rather than a move\n *\n * The queue around it is the MARKETPLACE's: `marketplaceListings` is its\n * collection, \"a version must have passed review\" is its rule, and the\n * fields the grant writes are its documents. All of that belongs with the\n * plugin, the way the review queue and the report queue already do.\n *\n * The KEY does not. It is deployed to the console and nowhere else — never\n * to a tenant runtime — and this package is published to npm, where a\n * self-hoster generates their own pair. A plugin that read the key directly\n * would put the platform's signing authority inside a package anyone can\n * install, to no benefit: the plugin has nothing to do with it beyond\n * wanting one string signed.\n *\n * So the shell signs, and the marketplace decides what is worth signing.\n * The sibling of `core.site-cache`, and the same direction: the shell\n * offering a capability down.\n *\n * ## ⛔ AN ABSENT SIGNER REFUSES. IT DOES NOT GRANT.\n *\n * This is the opposite failure direction from every other contract here, and\n * it is the one that matters. `core.site-cache` answers `complete: false`\n * and the caller carries on, because a stale cache is survivable. An\n * unsigned realm grant is not survivable: the loaders fail closed on a\n * missing signature, so a \"grant\" without one produces a version that is\n * marked trusted and cannot load — or, far worse if a loader is ever\n * lenient, one that loads unverified.\n *\n * {@link signPluginTrust} therefore never returns a bare string. It answers\n * `{ signed: false, reason }` when nothing is registered, when the\n * deployment has no key, or when signing throws, and the caller MUST refuse\n * the grant on it rather than writing a partial one.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\n\nexport interface PluginTrustSignature {\n  /** Base64 Ed25519 signature over the sha256 hex. Absent unless `signed`. */\n  signature?: string\n  /**\n   * Whether a signature was produced. FALSE when nothing is registered, the\n   * deployment holds no key, or signing failed — and a caller must refuse\n   * the grant, never write one without a signature.\n   */\n  signed: boolean\n  /** Why not, in the operator's terms, when `signed` is false. */\n  reason?: string\n}\n\nexport interface PluginTrustSigner {\n  /** Signs a version's sha256 hex with the platform's Ed25519 key. */\n  sign(sha256: string): Promise<PluginTrustSignature>\n}\n\n/**\n * One implementation: the app that holds the key. A second would be a second\n * signing authority, and the loaders verify against ONE public key.\n */\nexport const PLUGIN_TRUST_SIGNER =\n  definePluginServiceContract<PluginTrustSigner>('core.plugin-trust-signer', {\n    multiple: false,\n  })\n\n/** Installs the app's signer. Called once, at server boot. */\nexport function registerPluginTrustSigner(\n  signer: PluginTrustSigner,\n  options?: { pluginId?: string },\n): void {\n  if (typeof signer?.sign !== 'function') {\n    throw new Error('a plugin trust signer needs a sign function')\n  }\n  registerPluginService(PLUGIN_TRUST_SIGNER, signer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Whether this deployment can sign at all — for a surface that says so. */\nexport function hasPluginTrustSigner(): boolean {\n  return Boolean(resolvePluginService(PLUGIN_TRUST_SIGNER))\n}\n\n/**\n * Signs `sha256`, or says why it could not.\n *\n * NEVER THROWS, and never answers a signature it did not make. Read\n * `signed` before reading `signature`; see the module docblock for why a\n * caller must refuse rather than continue.\n */\nexport async function signPluginTrust(\n  sha256: string,\n): Promise<PluginTrustSignature> {\n  const digest = sha256?.trim()\n  if (!digest) {\n    return { signed: false, reason: 'No version hash to sign.' }\n  }\n  const signer = resolvePluginService(PLUGIN_TRUST_SIGNER)\n  if (!signer) {\n    console.error(\n      '[trust-signer] no implementation is installed, so realm trust cannot ' +\n        'be granted. The app registers this at boot.',\n    )\n    return {\n      signed: false,\n      reason: 'Trust signing is not available on this deployment.',\n    }\n  }\n  try {\n    const result = await signer.sign(digest)\n    // A signer that answered `signed` with nothing to show is a bug in the\n    // signer, and granting on it would write the trust flag with no\n    // signature — the one state the loaders cannot distinguish from tampering.\n    if (result.signed && !result.signature) {\n      return {\n        signed: false,\n        reason: 'Trust signing returned no signature.',\n      }\n    }\n    return result\n  } catch (error) {\n    console.error('[trust-signer] signing failed', error)\n    return { signed: false, reason: 'Trust signing failed.' }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_TRUST_SIGNER","multiple","registerPluginTrustSigner","signer","options","sign","Error","pluginId","hasPluginTrustSigner","Boolean","signPluginTrust","sha256","digest","trim","signed","reason","console","error","result","signature"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAoB1B;;;CAGC,GACD,OAAO,MAAMC,sBACXH,4BAA+C,4BAA4B;IACzEI,UAAU;AACZ,GAAE;AAEJ,4DAA4D,GAC5D,OAAO,SAASC,0BACdC,MAAyB,EACzBC,OAA+B;IAE/B,IAAI,QAAOD,0BAAAA,OAAQE,IAAI,MAAK,YAAY;QACtC,MAAM,IAAIC,MAAM;IAClB;IACAR,sBAAsBE,qBAAqBG,QAAQ,aAC7CC,CAAAA,2BAAAA,QAASG,QAAQ,IAAG;QAAEA,UAAUH,QAAQG,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,0EAA0E,GAC1E,OAAO,SAASC;IACd,OAAOC,QAAQV,qBAAqBC;AACtC;AAEA;;;;;;CAMC,GACD,OAAO,eAAeU,gBACpBC,MAAc;IAEd,MAAMC,SAASD,0BAAAA,OAAQE,IAAI;IAC3B,IAAI,CAACD,QAAQ;QACX,OAAO;YAAEE,QAAQ;YAAOC,QAAQ;QAA2B;IAC7D;IACA,MAAMZ,SAASJ,qBAAqBC;IACpC,IAAI,CAACG,QAAQ;QACXa,QAAQC,KAAK,CACX,0EACE;QAEJ,OAAO;YACLH,QAAQ;YACRC,QAAQ;QACV;IACF;IACA,IAAI;QACF,MAAMG,SAAS,MAAMf,OAAOE,IAAI,CAACO;QACjC,uEAAuE;QACvE,gEAAgE;QAChE,2EAA2E;QAC3E,IAAIM,OAAOJ,MAAM,IAAI,CAACI,OAAOC,SAAS,EAAE;YACtC,OAAO;gBACLL,QAAQ;gBACRC,QAAQ;YACV;QACF;QACA,OAAOG;IACT,EAAE,OAAOD,OAAO;QACdD,QAAQC,KAAK,CAAC,iCAAiCA;QAC/C,OAAO;YAAEH,QAAQ;YAAOC,QAAQ;QAAwB;IAC1D;AACF"}