@jini-ai/agent-plugins 0.4.6 → 0.4.8

package/dist/admin-surfaces/capability-declarations.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Parses the capability declarations a surface with a `handlerModule` may make: which of the
+ * plugin's own connections its handlers administer (with the per-start parameters and callback
+ * fields each may use), which public configuration values the host may hand its handlers, and which
+ * of the plugin's delivery adapters' form-delivery bindings they manage (`./delivery-bindings.ts`).
+ *
+ * Why they are declared, not requested at run time: the surfaces file is part of the shipped,
+ * digest-checked package, so these lists are the trusted allowlists the admin-surface capability
+ * session (`./surface-capabilities.ts`) enforces. A handler can never reach a connection, a start
+ * parameter, a callback field or a config value its surface did not declare. Config names that look
+ * like secrets are refused here, so a secret can never become "public config" by a naming slip.
+ */
+/** One connection a surface's handlers may administer. `id` is the plugin's own connection id, never a ref. */
+export interface AdminSurfaceConnectionDeclaration {
+    readonly id: string;
+    /** Authorization parameters a handler may set for one sign-in (the connection must also allow them). */
+    readonly startParams: readonly string[];
+    /** Provider callback fields a handler may take once after a completed sign-in. */
+    readonly callbackFields: readonly string[];
+}
+export interface AdminSurfaceCapabilityDeclarations {
+    readonly connections?: readonly AdminSurfaceConnectionDeclaration[];
+    readonly publicConfig?: readonly string[];
+    /** Delivery adapter ids whose bindings the handlers manage. Jini checks only the shape; the host
+     *  checks that each is an adapter this same plugin contributes. */
+    readonly deliveryAdapters?: readonly string[];
+    /** Read-only form discovery; no form contents, submissions or mutation access. */
+    readonly forms?: readonly 'list'[];
+}
+type Entry = Readonly<Record<string, unknown>>;
+/**
+ * The surface's capability declarations, with keys present only when declared (an undeclared list
+ * adds no key, so existing descriptors parse unchanged), or why the file is refused.
+ * @complexity O(c * f + n + d) connections with their fields, config names and delivery adapters; every list is capped.
+ */
+export declare function parseAdminSurfaceCapabilityDeclarations(required: {
+    readonly entry: Entry;
+    readonly at: string;
+}, _optional?: Record<string, never>): AdminSurfaceCapabilityDeclarations | string;
+export {};
+//# sourceMappingURL=capability-declarations.d.ts.map

package/dist/admin-surfaces/capability-declarations.js

@@ -0,0 +1,102 @@
+/**
+ * @file Parses the capability declarations a surface with a `handlerModule` may make: which of the
+ * plugin's own connections its handlers administer (with the per-start parameters and callback
+ * fields each may use), which public configuration values the host may hand its handlers, and which
+ * of the plugin's delivery adapters' form-delivery bindings they manage (`./delivery-bindings.ts`).
+ *
+ * Why they are declared, not requested at run time: the surfaces file is part of the shipped,
+ * digest-checked package, so these lists are the trusted allowlists the admin-surface capability
+ * session (`./surface-capabilities.ts`) enforces. A handler can never reach a connection, a start
+ * parameter, a callback field or a config value its surface did not declare. Config names that look
+ * like secrets are refused here, so a secret can never become "public config" by a naming slip.
+ */
+/** Same shapes the API-connection descriptor accepts for connection ids and parameter names. */
+const CONNECTION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const FIELD_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * Copy of the OAuth core's `isCallbackFieldName` pattern (`@jini-ai/oauth` loopback-callback.ts is
+ * the source of truth; agent-plugins does not depend on it). The descriptor applies the full check,
+ * including the reserved protocol names, so a field passing here but reserved there is never declared.
+ */
+const CALLBACK_FIELD_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+/** Environment-style names, so a host can map them to its own config without translation. */
+const CONFIG_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** Name parts that mark a credential. A plugin's public values never need one of them. */
+const SECRET_NAME_PATTERN = /SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|COOKIE|SESSION|SIGNING/;
+/** The host's destination-id shape (lowercase hyphenated, at most 64), so a declared id can match one. */
+const ADAPTER_ID_PATTERN = /^(?=.{1,64}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_CONNECTIONS = 4;
+const MAX_DELIVERY_ADAPTERS = 8;
+const MAX_FIELDS = 8;
+const MAX_CONFIG_NAMES = 16;
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A bounded, de-duplicated list of names matching `pattern`, or why not. @complexity O(n) names. */
+function parseNames(value, required) {
+    const { pattern, max, at } = required;
+    if (!Array.isArray(value) || value.length > max)
+        return `${at} must be an array of at most ${max}`;
+    const bad = value.findIndex((name, index) => typeof name !== 'string' || !pattern.test(name) || value.indexOf(name) !== index);
+    return bad === -1 ? value : `${at}[${bad}] must be a unique name matching ${pattern.source}`;
+}
+function parseConnection(entry, at) {
+    if (!isPlainObject(entry))
+        return `${at} must be an object`;
+    if (typeof entry.id !== 'string' || !CONNECTION_ID_PATTERN.test(entry.id))
+        return `${at}.id must be a short connection id`;
+    const startParams = parseNames(entry.startParams ?? [], { pattern: FIELD_NAME_PATTERN, max: MAX_FIELDS, at: `${at}.startParams` });
+    if (typeof startParams === 'string')
+        return startParams;
+    const callbackFields = parseNames(entry.callbackFields ?? [], { pattern: CALLBACK_FIELD_NAME_PATTERN, max: MAX_FIELDS, at: `${at}.callbackFields` });
+    return typeof callbackFields === 'string' ? callbackFields : { id: entry.id, startParams, callbackFields };
+}
+function parseConnections(value, at) {
+    if (!Array.isArray(value) || value.length > MAX_CONNECTIONS)
+        return `${at} must be an array of at most ${MAX_CONNECTIONS}`;
+    const connections = [];
+    for (const [index, entry] of value.entries()) {
+        const parsed = parseConnection(entry, `${at}[${index}]`);
+        if (typeof parsed === 'string')
+            return parsed;
+        if (connections.some((seen) => seen.id === parsed.id))
+            return `${at}[${index}].id '${parsed.id}' is declared twice`;
+        connections.push(parsed);
+    }
+    return connections;
+}
+function parsePublicConfig(value, at) {
+    const names = parseNames(value, { pattern: CONFIG_NAME_PATTERN, max: MAX_CONFIG_NAMES, at });
+    if (typeof names === 'string')
+        return names;
+    const secret = names.findIndex((name) => SECRET_NAME_PATTERN.test(name));
+    return secret === -1 ? names : `${at}[${secret}] names a secret; public config may only hold values that are safe to show`;
+}
+function parseDeliveryAdapters(value, at) {
+    return parseNames(value, { pattern: ADAPTER_ID_PATTERN, max: MAX_DELIVERY_ADAPTERS, at });
+}
+/** Only the read operation can be granted; unknown operations fail admission. */
+function parseForms(value, at) {
+    return parseNames(value, { pattern: /^list$/, max: 1, at });
+}
+/** Each declaration's parser, in the order refusals are reported. */
+const DECLARATION_PARSERS = [
+    ['connections', parseConnections], ['publicConfig', parsePublicConfig], ['deliveryAdapters', parseDeliveryAdapters], ['forms', parseForms],
+];
+/**
+ * The surface's capability declarations, with keys present only when declared (an undeclared list
+ * adds no key, so existing descriptors parse unchanged), or why the file is refused.
+ * @complexity O(c * f + n + d) connections with their fields, config names and delivery adapters; every list is capped.
+ */
+export function parseAdminSurfaceCapabilityDeclarations(required, _optional = {}) {
+    const { entry, at } = required;
+    const declarations = {};
+    for (const [name, parse] of DECLARATION_PARSERS) {
+        if (entry[name] === undefined)
+            continue;
+        const parsed = parse(entry[name], `${at}.${name}`);
+        if (typeof parsed === 'string')
+            return parsed;
+        declarations[name] = parsed;
+    }
+    return declarations;
+}
+//# sourceMappingURL=capability-declarations.js.map

package/dist/admin-surfaces/contribution.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Plugs admin surfaces into the existing plugin contribution loader
+ * (`../lifecycle/contribution-loader.ts`) and serves their declared files.
+ *
+ * Why the filename is a parameter: the host names its own contribution file (one host might use
+ * `<product>-admin-surfaces.json`), exactly as it does for every other seam; Jini never hardcodes a
+ * product prefix. Surfaces are a DATA contribution: nothing is imported into the server process. The
+ * loader still applies the shared trust gate (active + shipped digest), and file reads go through
+ * the lifecycle's `readTrustedPluginFile`, which resolves symlinks and refuses anything outside the
+ * package root.
+ */
+import type { PluginContributionDefinition } from '../lifecycle/contribution-loader.js';
+import type { TrustedPluginPackage } from '../lifecycle/trusted-plugin-files.js';
+import { type AdminSurfaceDescriptor } from './descriptor.js';
+/** One surface the trust gate admitted, with the package its files are read from. */
+export interface LoadedAdminSurface {
+    readonly plugin: TrustedPluginPackage;
+    readonly descriptor: AdminSurfaceDescriptor;
+}
+/**
+ * The contribution definition for a host-chosen filename. Pass it to the lifecycle's
+ * `loadPluginContributions({ workspaceId, definition })`.
+ * @complexity O(1) composition; parsing is O(file size).
+ */
+export declare function defineAdminSurfaceContribution(required: {
+    readonly filename: string;
+}, _optional?: Record<string, never>): PluginContributionDefinition<AdminSurfaceDescriptor, LoadedAdminSurface>;
+/**
+ * Reads one file of a loaded surface for serving, with the headers it must be served with. Only the
+ * entry and the declared `files` are ever read; any other path answers `not-declared` without I/O.
+ * @param required.readFile - The lifecycle's `readTrustedPluginFile` (on-disk containment check).
+ * @complexity O(f) declared files plus the read.
+ */
+export declare function readAdminSurfaceFile(required: {
+    readonly surface: LoadedAdminSurface;
+    readonly path: string;
+    readonly readFile: (input: {
+        readonly plugin: TrustedPluginPackage;
+        readonly filename: string;
+    }) => Promise<string>;
+}, _optional?: Record<string, never>): Promise<{
+    readonly ok: true;
+    readonly body: string;
+    readonly headers: Readonly<Record<string, string>>;
+} | {
+    readonly ok: false;
+    readonly reason: 'not-declared';
+}>;
+//# sourceMappingURL=contribution.d.ts.map

package/dist/admin-surfaces/contribution.js

@@ -0,0 +1,30 @@
+import { parseAdminSurfacesFile } from './descriptor.js';
+import { adminSurfaceFileHeaders } from './sandbox.js';
+/**
+ * The contribution definition for a host-chosen filename. Pass it to the lifecycle's
+ * `loadPluginContributions({ workspaceId, definition })`.
+ * @complexity O(1) composition; parsing is O(file size).
+ */
+export function defineAdminSurfaceContribution(required, _optional = {}) {
+    return {
+        filename: required.filename,
+        contribution: 'admin surfaces',
+        kind: 'data',
+        parse: ({ raw }) => parseAdminSurfacesFile({ raw }),
+        load: ({ plugin, descriptor }) => ({ plugin, descriptor }),
+    };
+}
+/**
+ * Reads one file of a loaded surface for serving, with the headers it must be served with. Only the
+ * entry and the declared `files` are ever read; any other path answers `not-declared` without I/O.
+ * @param required.readFile - The lifecycle's `readTrustedPluginFile` (on-disk containment check).
+ * @complexity O(f) declared files plus the read.
+ */
+export async function readAdminSurfaceFile(required, _optional = {}) {
+    const { surface, path } = required;
+    if (path !== surface.descriptor.entry && !surface.descriptor.files.includes(path))
+        return { ok: false, reason: 'not-declared' };
+    const body = await required.readFile({ plugin: surface.plugin, filename: path });
+    return { ok: true, body, headers: adminSurfaceFileHeaders({ descriptor: surface.descriptor, path }) };
+}
+//# sourceMappingURL=contribution.js.map

package/dist/admin-surfaces/delivery-bindings.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file The admin-surface `deliveryBindings` port: a plugin's destination screen lists, saves and
+ * removes the workspace's form-delivery bindings for the delivery adapters its surface declares, so an
+ * admin no longer copies a destination's config by hand.
+ *
+ * Why the checks sit here and not only in the host: the surface's `deliveryAdapters` and `connections`
+ * are the shipped, digest-checked allowlists. So before the host sees a call, the session refuses an
+ * adapter or connection the surface did not declare, a config that is not bounded plain JSON or that
+ * mentions a token the plugin obtained (`./settings-value.ts`, the same check as plugin state), and any
+ * binding id that is not one of the surface's own bindings (so another adapter's binding can be neither
+ * overwritten nor removed); and it filters and re-shapes what the host lists. The host still owns
+ * ownership itself (that the adapter ids are ones this plugin contributes), storage, the binding ids,
+ * and mapping a declared connection id to its own connection for the scope's plugin and workspace.
+ */
+import type { AgentPluginCapabilityGate, AgentPluginStateValue } from '../lifecycle/tools/capabilities.js';
+/**
+ * Which forms a binding delivers, always stated: the listed form ids (`[]` = none), or `allForms: true`
+ * for every current and future form. There is no implicit "every form": submissions carry personal
+ * data, so a plugin bug that forgets the field must fail, not widen the routing.
+ */
+export type AdminSurfaceDeliveryBindingForms = {
+    readonly formIds: readonly string[];
+    readonly allForms?: never;
+} | {
+    readonly allForms: true;
+    readonly formIds?: never;
+};
+interface DeliveryBindingFields {
+    readonly adapterId: string;
+    readonly connectionId: string;
+    readonly enabled: boolean;
+    /** Adapter-owned, non-secret configuration. */
+    readonly config: Readonly<Record<string, AgentPluginStateValue>>;
+}
+/** One binding as a surface sees it: plugin-owned config, the plugin's own connection id (never a ref). */
+export type AdminSurfaceDeliveryBinding = DeliveryBindingFields & AdminSurfaceDeliveryBindingForms & {
+    readonly bindingId: string;
+};
+/** What `save` takes: a new binding (the host assigns its id) or, with `bindingId`, one of the surface's own. */
+export type AdminSurfaceDeliveryBindingDraft = DeliveryBindingFields & AdminSurfaceDeliveryBindingForms & {
+    readonly bindingId?: string;
+};
+/**
+ * The port. The host implements it scoped to the call's plugin and workspace, listing only the plugin's
+ * own adapters' bindings; the session hands the plugin the same interface, checked.
+ */
+export interface AdminSurfaceDeliveryBindings {
+    list(required?: Record<string, never>, optional?: Record<string, never>): Promise<readonly AdminSurfaceDeliveryBinding[]>;
+    save(required: AdminSurfaceDeliveryBindingDraft, optional?: Record<string, never>): Promise<AdminSurfaceDeliveryBinding>;
+    remove(required: {
+        readonly bindingId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+export declare const DELIVERY_BINDING_WITHHELD_MESSAGE = "A delivery binding held a connection credential, so it was withheld. Remove it and save it again.";
+interface Allowlists {
+    readonly adapterIds: readonly string[];
+    readonly connectionIds: readonly string[];
+}
+/**
+ * Wraps the host's port for one admin-surface call.
+ * @param required.gate - The call's capability gate (revocation and token scans).
+ * @param required.host - The host's port, already scoped to the plugin and workspace.
+ * @param required.adapterIds - The surface's declared delivery adapters.
+ * @param required.connectionIds - The surface's declared connection ids.
+ * @param optional.actorId - The signed-in admin; every call is refused without one.
+ * @returns The checked port.
+ * @complexity Each call is one host list (plus one save or remove), O(b) over the listed bindings.
+ */
+export declare function guardDeliveryBindings(required: {
+    readonly gate: AgentPluginCapabilityGate;
+    readonly host: AdminSurfaceDeliveryBindings;
+} & Allowlists, optional?: {
+    readonly actorId?: string | undefined;
+}): AdminSurfaceDeliveryBindings;
+export {};
+//# sourceMappingURL=delivery-bindings.d.ts.map

package/dist/admin-surfaces/delivery-bindings.js

@@ -0,0 +1,99 @@
+import { storedStateValue } from './settings-value.js';
+export const DELIVERY_BINDING_WITHHELD_MESSAGE = 'A delivery binding held a connection credential, so it was withheld. Remove it and save it again.';
+const FORM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const MAX_FORM_IDS = 64;
+/** Names in messages come from plugin code: cut them so a message stays a message. */
+const named = (value) => String(value).slice(0, 64);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function checkedFormIds(formIds) {
+    const valid = Array.isArray(formIds) && formIds.length <= MAX_FORM_IDS
+        && formIds.every((id, index) => typeof id === 'string' && FORM_ID_PATTERN.test(id) && formIds.indexOf(id) === index);
+    if (!valid)
+        throw new Error(`formIds must be at most ${MAX_FORM_IDS} unique short form ids.`);
+    return [...formIds];
+}
+/** Exactly one of a valid `formIds` list or `allForms: true`. @complexity O(f) form ids. */
+function checkedForms(formIds, allForms) {
+    if (allForms === undefined && formIds !== undefined)
+        return { formIds: checkedFormIds(formIds) };
+    if (allForms === true && formIds === undefined)
+        return { allForms: true };
+    throw new Error('A delivery binding must name its forms: formIds (a list; [] for none) or allForms: true for every current and future form, not both.');
+}
+/** The forms a host-listed binding states; a binding stating neither is a host bug, never "every form". */
+function listedForms(binding) {
+    if (Array.isArray(binding.formIds))
+        return { formIds: [...binding.formIds] };
+    if (binding.allForms === true)
+        return { allForms: true };
+    throw new Error(`The host listed delivery binding '${named(binding.bindingId)}' without formIds or allForms; fix the host's binding store.`);
+}
+function checkedConfig(gate, config) {
+    if (!isRecord(config))
+        throw new Error("A delivery binding's config must be a JSON object.");
+    return storedStateValue({ gate, value: config });
+}
+/** The draft the host receives: only the known fields, each checked, the config a stored copy. @complexity O(f + n) form ids plus config size. */
+function checkedDraft(gate, allow, draft) {
+    if (!isRecord(draft))
+        throw new Error('A delivery binding must be an object.');
+    const { bindingId, adapterId, connectionId, enabled, formIds, allForms, config } = draft;
+    if (!allow.adapterIds.includes(adapterId))
+        throw new Error(`This admin surface does not declare delivery adapter '${named(adapterId)}', so its handlers cannot manage its bindings. Declare it in the surface's deliveryAdapters.`);
+    if (!allow.connectionIds.includes(connectionId))
+        throw new Error(`Delivery bindings may only use this surface's declared connections; '${named(connectionId)}' is not one of them.`);
+    if (typeof enabled !== 'boolean')
+        throw new Error('A delivery binding needs enabled: true or false.');
+    return {
+        ...(bindingId !== undefined && { bindingId: bindingId }),
+        adapterId: adapterId, connectionId: connectionId, enabled,
+        ...checkedForms(formIds, allForms),
+        config: checkedConfig(gate, config),
+    };
+}
+/** The port shape, whatever else the host's object carried (a connection ref), refused when it mentions an obtained token. */
+function toBinding(gate, binding) {
+    const { bindingId, adapterId, connectionId, enabled, config } = binding;
+    const shaped = { bindingId, adapterId, connectionId, enabled, ...listedForms(binding), config };
+    if (gate.mentionsToken({ value: shaped }))
+        throw new Error(DELIVERY_BINDING_WITHHELD_MESSAGE);
+    return shaped;
+}
+/**
+ * Wraps the host's port for one admin-surface call.
+ * @param required.gate - The call's capability gate (revocation and token scans).
+ * @param required.host - The host's port, already scoped to the plugin and workspace.
+ * @param required.adapterIds - The surface's declared delivery adapters.
+ * @param required.connectionIds - The surface's declared connection ids.
+ * @param optional.actorId - The signed-in admin; every call is refused without one.
+ * @returns The checked port.
+ * @complexity Each call is one host list (plus one save or remove), O(b) over the listed bindings.
+ */
+export function guardDeliveryBindings(required, 
+// `| undefined`: the session forwards its own optional actor as is.
+optional = {}) {
+    const { gate, host } = required;
+    const forActor = (call) => gate.guard(async (...args) => {
+        if (optional.actorId === undefined)
+            throw new Error('Delivery settings need a signed-in admin. Open the surface from an authenticated admin page and retry.');
+        return call(...args);
+    });
+    const ours = async () => (await host.list()).filter((binding) => required.adapterIds.includes(binding.adapterId));
+    /** The id when it names one of this surface's bindings; a plugin never reaches another adapter's binding. */
+    const ownId = async (bindingId) => {
+        if (!(await ours()).some((binding) => binding.bindingId === bindingId))
+            throw new Error(`No delivery binding '${named(bindingId)}' belongs to this surface's delivery adapters; list the bindings and retry.`);
+        return bindingId;
+    };
+    return Object.freeze({
+        list: forActor(async () => (await ours()).map((binding) => toBinding(gate, binding))),
+        save: forActor(async (draft) => {
+            const checked = checkedDraft(gate, required, draft);
+            if (checked.bindingId !== undefined)
+                await ownId(checked.bindingId);
+            return toBinding(gate, await host.save(checked));
+        }),
+        remove: forActor(async ({ bindingId }) => { await host.remove({ bindingId: await ownId(bindingId) }); }),
+    });
+}
+//# sourceMappingURL=delivery-bindings.js.map

package/dist/admin-surfaces/descriptor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file Parses a plugin's admin-surface contribution file: which surfaces it ships, the contained
+ * files each one serves, the actions it may ask the host to run (with their schemas), the few
+ * extra Content-Security-Policy sources it needs and, optionally, the server-side handler module that
+ * answers those actions (`./surface-handlers.ts`) with the schema of the bootstrap data it provides
+ * and the connections and public config its handlers may use (`./capability-declarations.ts`).
+ *
+ * Why parsing is strict: everything here is later trusted by the host. A file path that is not a
+ * plain relative path, an action schema outside the supported subset, or a CSP source that is not a
+ * bare `https://` origin refuses the WHOLE file, so a half-valid declaration never widens what a
+ * surface can reach. Containment on disk (symlinks) is the lifecycle's job (`readTrustedPluginFile`);
+ * this file only guarantees the declared strings cannot name anything outside the package root.
+ */
+import type { AgentPluginToolEffect } from '../lifecycle/tools/manifest.js';
+import { type AdminSurfaceActionSchema } from './action-schema.js';
+import { type AdminSurfaceCapabilityDeclarations } from './capability-declarations.js';
+/** The CSP directives a descriptor may extend. Everything else stays at the strict default. */
+export declare const ADMIN_SURFACE_CSP_DIRECTIVES: readonly ["script-src", "style-src", "img-src", "font-src", "connect-src", "frame-src"];
+export type AdminSurfaceCspDirective = (typeof ADMIN_SURFACE_CSP_DIRECTIVES)[number];
+export interface AdminSurfaceAction {
+    readonly name: string;
+    /** Assistant confirmation class; omitted declarations are writes. */
+    readonly effect?: AgentPluginToolEffect;
+    readonly input: AdminSurfaceActionSchema;
+    /** When declared, the dispatcher refuses a handler result that does not conform. */
+    readonly result?: AdminSurfaceActionSchema;
+}
+export interface AdminSurfaceDescriptor extends AdminSurfaceCapabilityDeclarations {
+    readonly id: string;
+    readonly title: string;
+    /** The `.html` document the frame loads, relative to the plugin root. */
+    readonly entry: string;
+    /** Other files the entry loads (`.mjs`, `.js`, `.css`, `.json`); nothing else is ever served. */
+    readonly files: readonly string[];
+    readonly actions: readonly AdminSurfaceAction[];
+    readonly csp: Readonly<Partial<Record<AdminSurfaceCspDirective, readonly string[]>>>;
+    /** A server-side `.mjs` module exporting this surface's action handlers and optional bootstrap
+     * provider (`./surface-handlers.ts`). Loaded only through the executable trust gate; never served. */
+    readonly handlerModule?: string;
+    /** The schema bootstrap data from `handlerModule` must match before it reaches the frame. */
+    readonly bootstrap?: AdminSurfaceActionSchema;
+    /** Bare https origins the host may open links to for this surface (`./external-links.ts`); present only when declared. */
+    readonly linkOrigins?: readonly string[];
+}
+/** True when `value` is a relative POSIX path whose every segment is plain and that ends in one of
+ * `extensions`. @complexity O(n) in the path length. */
+export declare function isContainedAdminSurfacePath(required: {
+    readonly value: unknown;
+    readonly extensions: readonly string[];
+}, _optional?: Record<string, never>): boolean;
+/** True when `value` is a CSP source this protocol allows a plugin to add.
+ * @complexity O(n) in the source length. */
+export declare function isAllowedAdminSurfaceCspSource(required: {
+    readonly value: unknown;
+}, _optional?: Record<string, never>): boolean;
+/**
+ * Parses the contribution file. One invalid surface refuses the whole file (the loader reports it).
+ * @complexity O(s * (f + a + c)) surfaces with their files, actions and CSP sources; input bounded to 64 KiB.
+ */
+export declare function parseAdminSurfacesFile(required: {
+    readonly raw: string;
+}, _optional?: Record<string, never>): {
+    readonly ok: true;
+    readonly descriptors: readonly AdminSurfaceDescriptor[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+//# sourceMappingURL=descriptor.d.ts.map