@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/plugin-manifest.d.ts

@@ -0,0 +1,516 @@
+/**
+ * @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 { PluginConfigField } from '../plugin-manager/plugin-config';
+import { type PluginContributions } from '../plugin-manager/plugin-contributions';
+/**
+ * Executable-plugin manifest, artifact-path, CSP, and revocation helpers
+ * (AGL-45), per the accepted AGL-43 design. Plugins — unlike declarative
+ * components (see `marketplace.ts`) — are code, so they never run in the
+ * console/tenant origin: they load in a sandboxed iframe on a dedicated
+ * plugin origin, and this manifest is the contract the install screen
+ * shows verbatim and the serving layer turns into CSP. Pure module — safe
+ * to import from API routes, the loader, and the host runtime alike.
+ */
+/** Capabilities a plugin declares; shown verbatim at install. */
+/**
+ * How a declared prop should be EDITED. Authoring metadata only (AGL-1049).
+ *
+ * Deliberately separate from `props`, which stays the security allowlist. A
+ * schema entry for a name that is not in `props` widens nothing — it is
+ * dropped, because the filter and the author disagreeing must resolve in the
+ * filter's favour. The point of this is to make them agree, never to let a
+ * publisher grant themselves a prop by describing it.
+ */
+export interface PluginPropSchema {
+    /** Must also appear in `capabilities.props`, or this entry is ignored. */
+    name: string;
+    /**
+     * Which editor to render. Unknown values degrade to `string` rather than
+     * being rejected: this is publisher-authored data, and a manifest from a
+     * newer platform version must not make an older host refuse the plugin.
+     */
+    type?: 'string' | 'number' | 'boolean' | 'color' | 'date' | 'url' | 'select';
+    label?: string;
+    description?: string;
+    /** Shown as the field's initial value, so "leave it alone" is visible. */
+    default?: string | number | boolean;
+    /** `select` only. */
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+}
+/**
+ * A canvas element a plugin version contributes (AGL-1031).
+ *
+ * A first-party plugin that extends the besigner declares a `ComponentSchema`
+ * and gets a first-class palette entry. A marketplace plugin doing the same
+ * work got a generic "Plugin" wrapper and a JSON textarea. Where an element
+ * came from is a fact about its provenance, not a different kind of thing.
+ *
+ * The line this must not cross: **declared schema drives AUTHORING; the
+ * sandbox still owns runtime.** This is publisher-authored DATA. It never
+ * becomes a React component in the host bundle — the palette entry, the label
+ * and the attribute fields are host-rendered from the declaration, and the
+ * saved node still resolves to a sandboxed `PluginFrame` integrity-checked
+ * against the pinned sha256. Nothing here changes what executes or where.
+ */
+export interface PluginElementDeclaration {
+    /**
+     * Stable id, unique within the plugin. Saved on the node beside the listing
+     * id, so renaming the display name never orphans a placed element.
+     */
+    id: string;
+    displayName: string;
+    description?: string;
+    /**
+     * Drawer category. Constrained to a subset — see
+     * {@link PLUGIN_ELEMENT_CATEGORIES}.
+     */
+    category?: string;
+    /**
+     * An mdi icon NAME (`mdiTimerOutline`), never markup and never a path.
+     *
+     * A path would be arbitrary SVG from a publisher rendered into console
+     * chrome; a name is looked up in the icon set the host already ships, so the
+     * worst a bad value can do is render nothing.
+     */
+    icon?: string;
+    /**
+     * The element's editable attributes. Intersected with `capabilities.props`
+     * exactly as {@link PluginPropSchema} is — an attribute the plugin cannot
+     * receive is not an attribute.
+     */
+    attributes?: PluginPropSchema[];
+}
+/**
+ * Categories a third-party element may declare.
+ *
+ * Deliberately not the whole enum. `LAYOUT` and `NAVIGATION` are structural —
+ * a third-party element appearing among the containers a page is built out of
+ * invites placements the sandbox cannot honour, and taking a category away
+ * later breaks every site that used it. Cheaper to decide now, as the issue
+ * says; widening later is easy and narrowing is not.
+ */
+export declare const PLUGIN_ELEMENT_CATEGORIES: readonly string[];
+/** Bound on how many elements one plugin may contribute to the palette. */
+export declare const PLUGIN_MAX_ELEMENTS = 12;
+export interface PluginCapabilities {
+    /**
+     * Outbound origins the plugin may call (`connect-src`), each an exact
+     * https origin (`https://api.example.com`). Empty = no network.
+     */
+    network?: string[];
+    /** Prop names the host passes IN through the bridge. THE allowlist. */
+    props?: string[];
+    /**
+     * Optional editing metadata for the props above (AGL-1049). Absent on every
+     * plugin published before this existed, which is why the authoring surface
+     * falls back to a plain text field per declared name rather than requiring
+     * it.
+     */
+    propSchema?: PluginPropSchema[];
+    /** Event names the plugin may emit OUT through the bridge. */
+    events?: string[];
+    /** Rendered iframe region size (host reserves this box). */
+    size?: {
+        width?: number;
+        height?: number;
+    };
+}
+export interface PluginManifest {
+    /** Stable plugin id (matches the listing); persisted, never renamed. */
+    id: string;
+    /** Human name shown in the drawer + install screen. */
+    name: string;
+    /** Semver-ish version string (`1.2.0`); must match the artifact version. */
+    version: string;
+    /** Bundle entry the loader imports on the plugin origin. */
+    entry: string;
+    /**
+     * Host ABI generation the bundle was built against (AGL-429). Realm and
+     * remote-server loaders refuse a bundle whose declared ABI differs from
+     * the running host's PLUGIN_HOST_ABI_VERSION; absent = pre-compat
+     * bundle, loaded with a warning. Bumping the ABI is a breaking change.
+     */
+    hostAbi?: number;
+    capabilities?: PluginCapabilities;
+    /**
+     * Canvas elements this version contributes to the palette (AGL-1031).
+     *
+     * Part of the reviewed bytes: a new element is a new version through review,
+     * and a revoked version's elements vanish from the palette with it, because
+     * the palette is built from the pinned install.
+     */
+    elements?: PluginElementDeclaration[];
+    /** Besigner lineal rules the registered component honors (AGL-45 §4). */
+    restrictParent?: string[];
+    restrictChildren?: string[];
+    description?: string;
+    /**
+     * Settings this plugin takes, declared in the manifest (AGL-428).
+     *
+     * First-party plugins call `registerPluginConfigSchema` at module scope,
+     * which a sandboxed third-party bundle cannot do: it does not run in the
+     * console process at all, so nothing it executes can reach the registry the
+     * settings form reads. The manifest is the one declaration of a marketplace
+     * plugin that IS present in the console — denormalized onto every install
+     * pin, and part of the reviewed bytes — so it is where a publisher's fields
+     * come from.
+     *
+     * Read through `pluginConfigSchemaFromManifest`, never directly: this is
+     * publisher-authored data on a document the console renders a form from, so
+     * every field is re-validated on the way in rather than trusted for having
+     * been reviewed once.
+     */
+    config?: {
+        fields: PluginConfigField[];
+        defaults?: Record<string, unknown>;
+    };
+    /**
+     * What `register(host)` contributes, and where (AGL-3116): the elements and
+     * features a published page loads the plugin for, and the console slots,
+     * routes and shell entries a console screen loads it for. See
+     * `plugin-contributions.ts`.
+     *
+     * Absent on every version published before the contract, and those load
+     * under its documented default. A version that declares it is held to it:
+     * the verifier compares it with what the bundle registers, and a published
+     * page never loads the plugin anywhere the declaration does not place it.
+     */
+    contributes?: PluginContributions;
+}
+/** A published, content-addressed version of a plugin listing. */
+export interface PluginListingVersion {
+    version: string;
+    /** Content hash of the artifact bundle (integrity check at load). */
+    sha256: string;
+    /**
+     * Trust tier (AGL-420): 'realm' = staff-reviewed + platform-signed,
+     * may load into the app realm; anything else stays in the sandboxed
+     * PluginFrame. Staff-writable only.
+     */
+    trust?: string;
+    /** Ed25519 signature (base64) over the sha256 hex (AGL-420). */
+    signature?: string;
+    changelog?: string;
+    createdAtMs?: number;
+    manifest: PluginManifest;
+}
+/** `hosts/{hostId}/installs/{listingId}` — a pinned plugin install. */
+export interface PluginInstall {
+    listingId: string;
+    version: string;
+    sha256: string;
+    /** Mirrored trust tier + signature at install time (AGL-420). */
+    trust?: string;
+    signature?: string;
+    installedAtMs?: number;
+    updatedAtMs?: number;
+    entitlementRef?: string;
+}
+/** `revocations/{listingId}` — platform kill switch checked at load. */
+export interface PluginRevocation {
+    /**
+     * Specific versions revoked, or `'all'` to kill the whole listing. The
+     * field every INSTALLABILITY reader consults, via `isPluginRevoked`.
+     *
+     * It used to say this was the only field any reader consulted, and that
+     * was the defect rather than a description of one: staff are required to
+     * type a reason, it was written here, and nothing rendered it — so the
+     * customer whose site broke and the publisher whose version was pulled
+     * both got a bare chip (AGL-2328). `reason` and the timestamp are now
+     * read by `host-plugins-card` and by the publisher branch of
+     * `listing-versions`. Do not restore the old claim.
+     */
+    versions: string[] | 'all';
+    /** Typed by staff, REQUIRED to revoke. Rendered to both audiences. */
+    reason?: string;
+    /**
+     * ⚠️ DECLARED HERE AND WRITTEN BY NOTHING. Every writer in
+     * `apps/console/app/api/admin/plugin-reviews/route.ts` stores
+     * `revokedAt` instead. A reader that trusts this field alone shows no
+     * date for every revocation that actually exists — read both, the way
+     * `revocationTimeMs` in `listing-versions.ts` does.
+     */
+    atMs?: number;
+    /**
+     * What the writers actually store — a Firestore server timestamp, so its
+     * shape depends on which SDK read it back (`toMillis()` on admin, a
+     * `seconds` field through a client). Deliberately `unknown` rather than a
+     * lie about which one a given reader will see.
+     */
+    revokedAt?: unknown;
+    /**
+     * The staff uid that pulled it. Recorded, and deliberately NEVER returned
+     * to a customer or a publisher: who acted belongs in the audit log, not
+     * on the screen of the person it was done to (AGL-2328).
+     */
+    revokedBy?: string;
+    /**
+     * `'takedown'` when the listing-level hide wrote it (AGL-948). Un-hiding
+     * clears a takedown-owned entry, so it must not be the only record.
+     */
+    source?: string;
+    /**
+     * Versions revoked by a REVIEW decision (AGL-1085), kept separately from
+     * `versions` because a takedown flattens that to `'all'`. Without this,
+     * un-hiding a listing would silently un-revoke versions a reviewer stopped
+     * for an unrelated reason.
+     */
+    reviewVersions?: string[];
+}
+export * from './plugin-artifact-path';
+export declare const PLUGIN_ID_PATTERN: RegExp;
+export declare const PLUGIN_VERSION_PATTERN: RegExp;
+export declare const PLUGIN_MAX_NETWORK_ORIGINS = 10;
+export declare const PLUGIN_MAX_PROPS = 32;
+export declare const PLUGIN_MAX_EVENTS = 32;
+export declare const PLUGIN_MAX_SIZE_PX = 4096;
+export declare function validatePluginManifest(input: unknown): {
+    ok: true;
+    manifest: PluginManifest;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The sandbox CSP is NOT built here (AGL-1092).
+ *
+ * A `pluginContentSecurityPolicy` used to live at this spot: exported,
+ * unit-tested, and called by nothing. The policy that actually reaches a
+ * browser is `csp()` in `tools/plugin-loader/origin/api/load.mjs`, on the
+ * plugin-origin deployment, and the two disagreed — this one emitted
+ * `connect-src 'none'` for a manifest with no network, which would have
+ * broken every sandboxed load, since the frame fetches its own bundle from
+ * its own origin. Deleted rather than reconciled: a tested policy nobody
+ * serves is worse than none, because it answers a reader's question wrongly.
+ * `capabilities.network` still decides the allowlist — the loader reads it
+ * from the public listing-versions endpoint and appends it to `connect-src`,
+ * with tests beside it (`npm run test:plugin-loader`).
+ */
+/**
+ * True when a pinned version is killed — the whole listing (`'all'`) or the
+ * specific version. Loaders check this before executing and render a safe
+ * placeholder when true (AGL-45 §3.5 kill switch).
+ */
+export declare function isPluginRevoked(revocation: PluginRevocation | null | undefined, version: string): boolean;
+/**
+ * True when the kill switch is thrown on the WHOLE listing, not one build.
+ *
+ * Split out for the one caller that has no version to ask about: marketplace
+ * checkout (AGL-2288) must refuse to SELL a listing the platform has switched
+ * off, and it decides that before any version is chosen. Written here rather
+ * than as `revocation?.versions === 'all'` at that call site for the reason
+ * the doc comment on `nextRevocationState` gives — what `'all'` means is a
+ * property of this document's shape, and a second reader that spelled it out
+ * itself is how a kill switch silently stops killing.
+ *
+ * A per-version revocation is deliberately NOT listing-wide: it stops one
+ * build while the rest stay installable.
+ */
+export declare function isListingWideRevocation(revocation: PluginRevocation | null | undefined): boolean;
+/**
+ * What a listing OFFERS a client right now (AGL-2368).
+ *
+ * `newestInstallableVersion` is the derivation, and it needs the version set —
+ * which is server-only (`pluginVersions`). A client has the listing's
+ * `latestApprovedVersion` mirror instead, and since AGL-2306 every writer of
+ * that mirror computes it with `newestInstallableVersion`. So on a client the
+ * mirror IS the answer, with one gap: the revocation document and the listing
+ * document are two non-transactional writes, and a live listener sees them
+ * land at different times. In that window the mirror names a version the kill
+ * switch has already stopped, which is the whole shape of this bug.
+ *
+ * So a client that holds the revocation checks it against the mirror and, when
+ * they disagree, offers NOTHING rather than the next-best guess. It cannot
+ * compute the next-best guess — it has no version list — and "no update to
+ * offer" is the safe reading of a mirror it has caught mid-repair. The repair
+ * lands moments later and the real answer appears.
+ *
+ * A client with no revocation in hand passes `undefined` and gets the mirror,
+ * which is what it had before. That is a real fallback, not a silent one: the
+ * gap it leaves is bounded by the repair, and the install route derives live
+ * and refuses regardless.
+ */
+export declare function offeredPluginVersion(listing: {
+    latestApprovedVersion?: unknown;
+} | null | undefined, revocation: PluginRevocation | null | undefined): string | null;
+/**
+ * The newest version a buyer could actually install right now (AGL-2306).
+ *
+ * Two things have to be true of an offer, and the listing's
+ * `latestApprovedVersion` mirror only ever tracked one of them: the version
+ * must be APPROVED (AGL-966 — review lives on the version) and it must not be
+ * REVOKED (AGL-1085 — `install-plugin` answers 409 to a revoked pin).
+ *
+ * Written here rather than in the console route that repairs the mirror, and
+ * rather than reusing `newestApprovedVersion` in the marketplace plugin's
+ * model, because the console is `scope:app` and may not depend on
+ * `aglyn:addons`. Both may import core, and "what is on offer" is one
+ * question that must have one answer.
+ *
+ * `compare` is injected rather than imported so this module stays free of the
+ * artifact-version comparator's own dependencies; every caller already has it.
+ * A `null` comparison (an unparseable version string) sorts as "not newer",
+ * which keeps a malformed version out of an offer rather than into one.
+ *
+ * Returns `null` when nothing qualifies — an ABSENT mirror reads as "no update
+ * to offer", while a stale string reads as an update that does not exist.
+ */
+export declare function newestInstallableVersion(versions: readonly {
+    version: string;
+    reviewState?: unknown;
+}[], revocation: PluginRevocation | null | undefined, compare: (a: string, b: string) => number | null): string | null;
+/**
+ * The next `revocations/{listingId}` state after one write (AGL-1085).
+ *
+ * Two writers share this doc and neither may erase the other:
+ *
+ * * a **takedown** kills the listing, flattening `versions` to `'all'`, and
+ *   un-hiding removes what it wrote (AGL-948);
+ * * a **review** decision stops one version's bytes — the reviewer's only
+ *   alternative used to be a full takedown, which also revokes the version
+ *   customers are happily running.
+ *
+ * `versions` stays the single field every reader consults, so `isPluginRevoked`
+ * and the loaders are untouched. `reviewVersions` is the durable record of the
+ * review-owned half, which is what lets un-hiding restore rather than clear it.
+ * Returns `null` when nothing is revoked any more and the doc should be
+ * deleted — an empty `versions: []` would read as "revoked nothing" but keep a
+ * doc around that a later reader has to interpret.
+ *
+ * Pure so both transitions are testable without Firestore, and colocated with
+ * `isPluginRevoked` on purpose: a writer that disagreed with the reader about
+ * this doc's shape is exactly how a kill switch silently stops killing.
+ */
+export declare function nextRevocationState(current: PluginRevocation | null | undefined, change: {
+    type: 'revoke-version';
+    version: string;
+} | {
+    type: 'unrevoke-version';
+    version: string;
+} | {
+    type: 'takedown';
+} | {
+    type: 'restore';
+}): PluginRevocation | null;
+/** Methods a host-mediated plugin fetch may use (AGL-191). */
+export declare const PLUGIN_FETCH_METHODS: readonly ["GET", "POST"];
+export type PluginFetchMethod = (typeof PLUGIN_FETCH_METHODS)[number];
+/** Request/response body cap for host-mediated fetch (bytes). */
+export declare const PLUGIN_FETCH_MAX_BODY_BYTES: number;
+/**
+ * True when `url`'s origin is an exact match against the manifest's
+ * declared `network` allowlist (AGL-191). The host re-checks this before
+ * proxying a plugin's `fetch-request`, so a plugin can only reach origins
+ * it declared at install (and the install screen surfaced). No allowlist =
+ * no host-mediated network; https-only.
+ */
+export declare function isPluginNetworkAllowed(url: string, capabilities: PluginCapabilities | undefined): boolean;
+/** Component id of the sandboxed plugin canvas element (plugins-mui). */
+export declare const PLUGIN_COMPONENT_ID = "marketplacePlugin";
+/** Resolved install data injected into a plugin node's props at compose. */
+export interface ResolvedPluginInstall {
+    listingId: string;
+    version: string;
+    sha256: string;
+    capabilities?: PluginCapabilities;
+    revoked?: boolean;
+}
+/**
+ * Compose-time injection (AGL-45), mirroring `attachFunctionDefinitions`:
+ * a `marketplacePlugin` node carries only a `listingId` in the saved screen;
+ * the tenant compose pass resolves that to the host's pinned install
+ * (version/sha256/capabilities) and the kill-switch state, and stamps them
+ * onto the node's props so `PluginFrame` renders without a client read.
+ * Unknown/uninstalled listings leave the node untouched (it shows a safe
+ * "not installed" placeholder rather than taking the screen down).
+ */
+export declare function attachPluginInstalls<T extends Record<string, any>>(nodes: T, installsByListingId: Record<string, ResolvedPluginInstall | undefined>): T;
+/** One editable setting on a placed plugin, resolved for the attributes panel. */
+export interface PluginPropField {
+    name: string;
+    type: NonNullable<PluginPropSchema['type']>;
+    label: string;
+    description?: string;
+    default?: string | number | boolean;
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+}
+/**
+ * The settings an author may edit on a placed plugin (AGL-1049).
+ *
+ * Driven by `capabilities.props` — THE allowlist — and decorated by
+ * `propSchema` where the publisher supplied one. That order is the whole
+ * security property: the list of editable settings can never be longer than
+ * the list of props that cross the bridge, whatever the schema says, so a
+ * publisher cannot describe their way into a prop they did not declare.
+ *
+ * A plugin published before `propSchema` existed still gets a field per
+ * declared prop, as plain text. That is the difference between guessing key
+ * names in a JSON textarea and being shown them, and it needs no manifest
+ * change to work — which matters, because every plugin installed today
+ * predates this.
+ */
+export declare function resolvePluginPropFields(manifest: {
+    capabilities?: PluginCapabilities;
+} | null | undefined): PluginPropField[];
+/**
+ * Keys an author has set that the plugin will silently ignore.
+ *
+ * The failure this exists to surface: `filterPluginProps` drops anything not
+ * in the allowlist, so a typo does not fail — it just quietly does nothing,
+ * which is the worst of the options. Naming the key is the whole fix.
+ */
+export declare function unknownPluginPropKeys(manifest: {
+    capabilities?: PluginCapabilities;
+} | null | undefined, values: Record<string, unknown> | null | undefined): string[];
+/** A declared element, resolved for the palette. */
+export interface PluginPaletteElement {
+    listingId: string;
+    elementId: string;
+    displayName: string;
+    description?: string;
+    category: string;
+    /** mdi icon NAME; the surface looks it up, never renders it as markup. */
+    icon?: string;
+    fields: PluginPropField[];
+}
+/**
+ * The palette entries an installed plugin contributes (AGL-1031).
+ *
+ * Resolved from the PINNED install, which is what makes the two guarantees in
+ * the issue hold without extra machinery: an element only appears where the
+ * plugin is installed, and a revoked or downgraded version's elements vanish
+ * with it, because the palette is rebuilt from whatever the pin now points at.
+ *
+ * Attributes come back through `resolvePluginPropFields`, so an element's
+ * editable fields are bounded by `capabilities.props` exactly like the generic
+ * plugin element's are. A declared element cannot widen what crosses the
+ * bridge; it only gives the same props a better name and a better editor.
+ */
+export declare function resolvePluginElements(install: {
+    listingId?: string;
+    capabilities?: PluginCapabilities;
+    manifest?: {
+        elements?: PluginElementDeclaration[];
+    };
+    elements?: PluginElementDeclaration[];
+} | null | undefined): PluginPaletteElement[];