@jini-ai/agent-plugins 0.4.7 → 0.4.8

package/dist/admin-surfaces/settings-value.js

@@ -0,0 +1,45 @@
+/**
+ * @file The one check every plugin-written settings value passes before a host stores it: plugin
+ * state (`./surface-capabilities.ts`) and a delivery binding's config (`./delivery-bindings.ts`).
+ *
+ * Why it is shared: both are plugin-chosen JSON the host persists and later hands back (to the
+ * plugin's tools, or to the delivery adapter), so both need the same guarantees — plain JSON only,
+ * bounded depth and size, and never a token the plugin obtained — and must not drift apart.
+ */
+import { PLUGIN_STATE_MAX_KEY_LENGTH } from '../lifecycle/tools/capabilities.js';
+export const ADMIN_SURFACE_STATE_LIMITS = Object.freeze({ maxKeyLength: PLUGIN_STATE_MAX_KEY_LENGTH, maxValueBytes: 16 * 1024, maxDepth: 16 });
+export const STATE_CREDENTIAL_MESSAGE = 'The plugin tried to save a connection credential in its settings; nothing was saved.';
+function isStateScalar(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}
+/** True for plain JSON data only: no undefined, functions, NaN, class instances or deep nesting. @complexity O(n) nodes. */
+function isStateValue(value, depth) {
+    if (isStateScalar(value))
+        return true;
+    if (typeof value !== 'object' || depth >= ADMIN_SURFACE_STATE_LIMITS.maxDepth)
+        return false;
+    if (Array.isArray(value))
+        return value.every((item) => isStateValue(item, depth + 1));
+    const prototype = Object.getPrototypeOf(value);
+    return (prototype === Object.prototype || prototype === null) && Object.values(value).every((item) => isStateValue(item, depth + 1));
+}
+/**
+ * The value the host stores: serialized once, scanned and size-checked on that text, then parsed
+ * back, so what is stored is exactly what was checked (the plugin cannot change it afterwards).
+ * @param required.gate - The call's capability gate (its token memory drives the scan).
+ * @param required.value - The plugin's value, unchecked.
+ * @throws Error when the value is not plain JSON, is too large, or mentions an obtained token.
+ * @complexity O(n) in the serialized size.
+ */
+export function storedStateValue(required, _optional = {}) {
+    const { gate, value } = required;
+    if (!isStateValue(value, 0))
+        throw new Error('A settings value must be plain JSON data (no undefined, functions, NaN or class instances).');
+    const text = JSON.stringify(value);
+    if (new TextEncoder().encode(text).byteLength > ADMIN_SURFACE_STATE_LIMITS.maxValueBytes)
+        throw new Error(`A settings value may be at most ${ADMIN_SURFACE_STATE_LIMITS.maxValueBytes} bytes of JSON.`);
+    if (gate.mentionsToken({ value: text }))
+        throw new Error(STATE_CREDENTIAL_MESSAGE);
+    return JSON.parse(text);
+}
+//# sourceMappingURL=settings-value.js.map

package/dist/admin-surfaces/surface-capabilities.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @file The host capability ports a plugin's admin-surface handlers receive, and the per-call
+ * session that wraps them. Jini defines the shapes and the checks; the host implements the ports
+ * (connections backed by its API-connection service, state by its own store, public config by its
+ * own settings) and Jini never names a provider.
+ *
+ * Why surfaces get more than tools: account actions (connect, reconnect, switch account, disconnect)
+ * and saving a chosen resource are admin actions a person takes on a settings screen, so they exist
+ * here and never on the executable-tool port. Why every check sits here and not only in the host:
+ * the surfaces file is the shipped, digest-checked allowlist, so the session refuses anything the
+ * surface did not declare (a connection, a start parameter, a callback field, a config name) before
+ * the host sees it, and a host that answers with more than the port promises (a connection ref, raw
+ * scopes, undeclared callback fields) is cut back to the declared shape. Like the tool session it
+ * revokes everything once the plugin is disabled and withholds results and errors that mention a
+ * token the plugin obtained (in this call, an earlier one, or one of its tools); it also refuses to persist
+ * such a token in plugin state.
+ */
+import { type AgentPluginStateReader, type AgentPluginStateValue, type AgentPluginToolCapabilities, type AgentPluginToolCapabilityScope, type IssuedTokenMemory } from '../lifecycle/tools/capabilities.js';
+import type { AdminSurfaceCapabilityDeclarations } from './capability-declarations.js';
+import { type AdminSurfaceDeliveryBindings } from './delivery-bindings.js';
+export { ADMIN_SURFACE_STATE_LIMITS, STATE_CREDENTIAL_MESSAGE } from './settings-value.js';
+/** Mirrors the API-connection lifecycle (`ApiConnectionStatus`); only `connected` serves access tokens. */
+export type AdminSurfaceConnectionState = 'connected' | 'reconnect-required' | 'revocation-pending' | 'disconnected';
+/**
+ * The API-connection start intent each account action maps to (`ApiConnectionIntent` in
+ * `@jini-ai/integrations/api-connections`, mirrored because agent-plugins does not depend on it), so a
+ * host passes `ADMIN_SURFACE_ACTION_INTENTS[action]` straight to `start`. `reconnect` and `add-scopes`
+ * are a same-account `connect` with the scope sets the handler passes (`add-scopes` re-consents for
+ * more of them); `switch` stages another account.
+ */
+export declare const ADMIN_SURFACE_ACTION_INTENTS: Readonly<{
+    readonly connect: "connect";
+    readonly reconnect: "connect";
+    readonly switch: "switch-account";
+    readonly 'add-scopes': "connect";
+}>;
+export type AdminSurfaceConnectionAction = keyof typeof ADMIN_SURFACE_ACTION_INTENTS;
+/**
+ * The honest remote outcome of a disconnect, the same values as `ApiConnectionRemoteRevocation`:
+ * never `confirmed` unless the provider confirmed it.
+ */
+export type AdminSurfaceRevocationOutcome = 'confirmed' | 'pending' | 'not-needed';
+/** Token-free status. Scope sets are the plugin's own ids, never raw provider scopes. */
+export interface AdminSurfaceConnectionStatus {
+    readonly connectionId: string;
+    readonly status: AdminSurfaceConnectionState;
+    readonly accountLabel: string | null;
+    readonly grantedScopeSetIds: readonly string[];
+    /** The account a staged switch would move to, awaiting `confirmSwitch`. */
+    readonly pendingSwitchAccountLabel: string | null;
+    /** Why the latest sign-in did not complete and what to do next, as the HOST's own lowercase
+     *  hyphenated codes (for example `access-denied` / `reconnect`), never provider text; `null` when
+     *  the latest attempt succeeded or none is recorded. A value that is not a safe code becomes `null`. */
+    readonly lastSignInAttempt: AdminSurfaceSignInAttempt | null;
+}
+/** The outcome codes of a sign-in attempt that did not complete. */
+export interface AdminSurfaceSignInAttempt {
+    readonly code: string;
+    readonly nextAction: string;
+}
+/** A sign-in the person opens (a button on hosted, the system browser on desktop). */
+export interface AdminSurfaceAuthorizationStart {
+    readonly authorizationUrl: string;
+    /** Opaque id for `takeCallbackFields` once the sign-in completed: the connection service's attempt
+     *  id, never the authorization `state`. */
+    readonly attemptId: string;
+    readonly expiresAt: string;
+}
+export interface AdminSurfaceConnections {
+    /** A fresh access token for one of the surface's declared connections; never a refresh token. */
+    getAccessToken(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<string>;
+    status(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    begin(required: {
+        readonly connectionId: string;
+        readonly action: AdminSurfaceConnectionAction;
+    }, optional?: {
+        readonly scopeSetIds?: readonly string[];
+        readonly startParams?: Readonly<Record<string, string>>;
+    }): Promise<AdminSurfaceAuthorizationStart>;
+    confirmSwitch(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    cancelSwitch(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    disconnect(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus & {
+        readonly revocation: AdminSurfaceRevocationOutcome;
+    }>;
+    /** The declared callback fields of a completed sign-in, once; `null` when absent, taken or not completed.
+     *  Still untrusted: verify them through the provider's API before saving anything. */
+    takeCallbackFields(required: {
+        readonly connectionId: string;
+        readonly attemptId: string;
+    }, optional?: Record<string, never>): Promise<Readonly<Record<string, string>> | null>;
+}
+export type AdminSurfaceStateValue = AgentPluginStateValue;
+/** Plugin- and workspace-scoped JSON values (the host keys them by the session's scope). The plugin's
+ *  tools read the same store through the read-only `AgentPluginStateReader`; only surfaces write. */
+export interface AdminSurfaceState extends AgentPluginStateReader {
+    set(required: {
+        readonly key: string;
+        readonly value: AdminSurfaceStateValue;
+    }, optional?: Record<string, never>): Promise<void>;
+    delete(required: {
+        readonly key: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/** Host-supplied public values (an app id, a browser key) for names the surface declares; `null` when unset. */
+export interface AdminSurfacePublicConfig {
+    get(required: {
+        readonly name: string;
+    }, optional?: Record<string, never>): Promise<string | null>;
+}
+/** Only form identity and display text, never fields, recipients or submission data. */
+export interface AdminSurfaceForm {
+    readonly slug: string;
+    readonly title: string;
+}
+/** Workspace-scoped discovery. The session returns at most 200 choices; titles are capped at 1024 characters. */
+export interface AdminSurfaceForms {
+    list(required: Record<string, never>, optional?: Record<string, never>): Promise<readonly AdminSurfaceForm[]>;
+}
+export type AdminSurfaceCapabilities = Pick<AgentPluginToolCapabilities, 'http' | 'limiter' | 'artifacts'> & {
+    readonly connections: AdminSurfaceConnections;
+    readonly state: AdminSurfaceState;
+    readonly publicConfig: AdminSurfacePublicConfig;
+    /** The workspace's form-delivery bindings (`./delivery-bindings.ts`). Optional for the host; a handler
+     *  gets it only when its surface declares `deliveryAdapters` and the host provides it. */
+    readonly deliveryBindings?: AdminSurfaceDeliveryBindings;
+    /** Absent unless both the host supplies it and this surface declares `forms: ["list"]`. */
+    readonly forms?: AdminSurfaceForms;
+};
+/** Host port: builds one call's capabilities for the loaded plugin, workspace and admin principal. */
+export type AdminSurfaceCapabilitiesPort = (required: AgentPluginToolCapabilityScope, optional?: Record<string, never>) => AdminSurfaceCapabilities;
+/**
+ * Opens the capability session for one admin-surface handler call.
+ * @param required.capabilities - The host's ports for this call (already scoped to plugin, workspace, principal).
+ * @param required.isLive - False once the plugin's surface handlers are revoked.
+ * @param required.declared - The surface's own capability declarations (the allowlists).
+ * @param required.issued - The plugin's token memory, shared by all its calls (tools included).
+ * @param optional.actorId - The signed-in admin; account actions are refused without one.
+ * @returns Wrapped capabilities plus the shared `release` (result) and `sanitize` (error) gates.
+ * @complexity O(1) to open; each check is bounded by the declared lists and the value caps.
+ */
+export declare function openAdminSurfaceCapabilitySession(required: {
+    readonly capabilities: AdminSurfaceCapabilities;
+    readonly isLive: () => boolean;
+    readonly declared: AdminSurfaceCapabilityDeclarations;
+    readonly issued: IssuedTokenMemory;
+}, optional?: {
+    readonly actorId?: string;
+}): {
+    capabilities: AdminSurfaceCapabilities;
+    release: <T>({ value }: {
+        readonly value: T;
+    }) => T;
+    sanitize: ({ error }: {
+        readonly error: unknown;
+    }) => unknown;
+};
+//# sourceMappingURL=surface-capabilities.d.ts.map

package/dist/admin-surfaces/surface-capabilities.js

@@ -0,0 +1,215 @@
+/**
+ * @file The host capability ports a plugin's admin-surface handlers receive, and the per-call
+ * session that wraps them. Jini defines the shapes and the checks; the host implements the ports
+ * (connections backed by its API-connection service, state by its own store, public config by its
+ * own settings) and Jini never names a provider.
+ *
+ * Why surfaces get more than tools: account actions (connect, reconnect, switch account, disconnect)
+ * and saving a chosen resource are admin actions a person takes on a settings screen, so they exist
+ * here and never on the executable-tool port. Why every check sits here and not only in the host:
+ * the surfaces file is the shipped, digest-checked allowlist, so the session refuses anything the
+ * surface did not declare (a connection, a start parameter, a callback field, a config name) before
+ * the host sees it, and a host that answers with more than the port promises (a connection ref, raw
+ * scopes, undeclared callback fields) is cut back to the declared shape. Like the tool session it
+ * revokes everything once the plugin is disabled and withholds results and errors that mention a
+ * token the plugin obtained (in this call, an earlier one, or one of its tools); it also refuses to persist
+ * such a token in plugin state.
+ */
+import { checkedStateKey, guardSharedCapabilities, guardStateReader, openCapabilityGate, } from '../lifecycle/tools/capabilities.js';
+import { guardDeliveryBindings } from './delivery-bindings.js';
+import { storedStateValue } from './settings-value.js';
+// Moved to `./settings-value.ts` so delivery-binding config shares the exact checks; re-exported so callers keep importing them here.
+export { ADMIN_SURFACE_STATE_LIMITS, STATE_CREDENTIAL_MESSAGE } from './settings-value.js';
+/**
+ * The API-connection start intent each account action maps to (`ApiConnectionIntent` in
+ * `@jini-ai/integrations/api-connections`, mirrored because agent-plugins does not depend on it), so a
+ * host passes `ADMIN_SURFACE_ACTION_INTENTS[action]` straight to `start`. `reconnect` and `add-scopes`
+ * are a same-account `connect` with the scope sets the handler passes (`add-scopes` re-consents for
+ * more of them); `switch` stages another account.
+ */
+export const ADMIN_SURFACE_ACTION_INTENTS = Object.freeze({
+    connect: 'connect', reconnect: 'connect', switch: 'switch-account', 'add-scopes': 'connect',
+});
+const ACTIONS = Object.keys(ADMIN_SURFACE_ACTION_INTENTS);
+const SCOPE_SET_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ATTEMPT_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const MAX_SCOPE_SETS = 16;
+const MAX_START_PARAM_LENGTH = 2048;
+/** 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 declaredConnection(declared, connectionId) {
+    const found = declared.find((connection) => connection.id === connectionId);
+    if (found === undefined)
+        throw new Error(`This admin surface does not declare connection '${named(connectionId)}', so its handlers cannot use it. Declare it in the surface's connections.`);
+    return found;
+}
+/** A copy of the start parameters, every name declared for this connection and every value a bounded string. @complexity O(p). */
+function checkedStartParams(connection, startParams) {
+    if (!isRecord(startParams))
+        throw new Error('Start parameters must be an object of strings.');
+    for (const [name, value] of Object.entries(startParams)) {
+        if (!connection.startParams.includes(name))
+            throw new Error(`Start parameter '${named(name)}' is not declared for connection '${connection.id}' on this admin surface.`);
+        if (typeof value !== 'string' || value.length > MAX_START_PARAM_LENGTH)
+            throw new Error(`Start parameter '${name}' must be a string of at most ${MAX_START_PARAM_LENGTH} characters.`);
+    }
+    return { ...startParams };
+}
+function checkedScopeSetIds(scopeSetIds) {
+    const valid = Array.isArray(scopeSetIds) && scopeSetIds.length <= MAX_SCOPE_SETS && scopeSetIds.every((id) => typeof id === 'string' && SCOPE_SET_ID_PATTERN.test(id));
+    if (!valid)
+        throw new Error(`Scope sets must be at most ${MAX_SCOPE_SETS} short ids.`);
+    return [...scopeSetIds];
+}
+/** The begin options the host receives: only the ones the handler passed, checked and copied. */
+function beginOptions(connection, optional = {}) {
+    return {
+        ...(optional.scopeSetIds !== undefined && { scopeSetIds: checkedScopeSetIds(optional.scopeSetIds) }),
+        ...(optional.startParams !== undefined && { startParams: checkedStartParams(connection, optional.startParams) }),
+    };
+}
+const SAFE_CODE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_SAFE_CODE_LENGTH = 64;
+const isSafeCode = (value) => typeof value === 'string' && value.length <= MAX_SAFE_CODE_LENGTH && SAFE_CODE_PATTERN.test(value);
+/** Only `code` and `nextAction`, and only when both are safe codes: a host that forwarded provider
+ * text (an error description) by mistake must not put it in front of the person or the plugin. */
+function toSignInAttempt(attempt) {
+    if (typeof attempt !== 'object' || attempt === null)
+        return null;
+    const { code, nextAction } = attempt;
+    return isSafeCode(code) && isSafeCode(nextAction) ? { code, nextAction } : null;
+}
+/** The status shape the port promises, whatever else the host's object carried. */
+function toStatus(connectionId, status) {
+    return {
+        connectionId, status: status.status, accountLabel: status.accountLabel ?? null,
+        grantedScopeSetIds: [...status.grantedScopeSetIds], pendingSwitchAccountLabel: status.pendingSwitchAccountLabel ?? null,
+        lastSignInAttempt: toSignInAttempt(status.lastSignInAttempt),
+    };
+}
+/** Only this connection's declared callback fields, as strings; anything else the host returned is dropped. */
+function declaredCallbackFields(connection, fields) {
+    if (fields === null)
+        return null;
+    return Object.fromEntries(connection.callbackFields.filter((name) => typeof fields[name] === 'string').map((name) => [name, fields[name]]));
+}
+/** Account actions run for a person; a call without one (a background route) is refused. */
+function requireActor(actorId) {
+    if (actorId === undefined)
+        throw new Error('Account actions need a signed-in admin. Open the surface from an authenticated admin page and retry.');
+}
+/**
+ * A token is handed out (to a handler, and through bootstrap data to the frame) only for a signed-in
+ * admin: a route without one must not mint a bearer token a frame keeps until it expires. Disabling
+ * the plugin cannot recall a token already handed out; disconnecting revokes it at the provider.
+ */
+function requireTokenActor(actorId) {
+    if (actorId === undefined)
+        throw new Error('Connection access needs a signed-in admin. Open the surface from an authenticated admin page and retry.');
+}
+/** The read side: a token (noted for the scans) and token-free status. */
+function readConnections({ gate, host, declared, actorId }) {
+    return {
+        getAccessToken: gate.guard(async ({ connectionId }) => {
+            const { id } = declaredConnection(declared, connectionId);
+            requireTokenActor(actorId);
+            return gate.noteToken({ token: await host.getAccessToken({ connectionId: id }) });
+        }),
+        status: gate.guard(async ({ connectionId }) => {
+            const { id } = declaredConnection(declared, connectionId);
+            return toStatus(id, await host.status({ connectionId: id }));
+        }),
+        takeCallbackFields: gate.guard(async ({ connectionId, attemptId }) => {
+            const connection = declaredConnection(declared, connectionId);
+            if (typeof attemptId !== 'string' || !ATTEMPT_ID_PATTERN.test(attemptId))
+                throw new Error('The sign-in attempt id is not valid; start the sign-in again.');
+            return declaredCallbackFields(connection, await host.takeCallbackFields({ connectionId: connection.id, attemptId }));
+        }),
+    };
+}
+/** The account actions: declared connection, declared start parameters, a signed-in admin. */
+function actConnections({ gate, host, declared, actorId }) {
+    const forActor = (connectionId) => { requireActor(actorId); return declaredConnection(declared, connectionId); };
+    const statusAction = (run) => gate.guard(async ({ connectionId }) => {
+        const { id } = forActor(connectionId);
+        return toStatus(id, await run({ connectionId: id }));
+    });
+    return {
+        begin: gate.guard(async ({ connectionId, action }, optional) => {
+            const connection = forActor(connectionId);
+            if (!ACTIONS.includes(action))
+                throw new Error(`Account action '${named(action)}' is not one of ${ACTIONS.join(', ')}.`);
+            const started = await host.begin({ connectionId: connection.id, action }, beginOptions(connection, optional));
+            return { authorizationUrl: started.authorizationUrl, attemptId: started.attemptId, expiresAt: started.expiresAt };
+        }),
+        confirmSwitch: statusAction((input) => host.confirmSwitch(input)),
+        cancelSwitch: statusAction((input) => host.cancelSwitch(input)),
+        disconnect: gate.guard(async ({ connectionId }) => {
+            const { id } = forActor(connectionId);
+            const outcome = await host.disconnect({ connectionId: id });
+            return { ...toStatus(id, outcome), revocation: outcome.revocation };
+        }),
+    };
+}
+function guardState(gate, host) {
+    return Object.freeze({
+        ...guardStateReader({ gate, state: host }),
+        set: gate.guard(async ({ key, value }) => host.set({ key: checkedStateKey({ key }), value: storedStateValue({ gate, value }) })),
+        delete: gate.guard(({ key }) => host.delete({ key: checkedStateKey({ key }) })),
+    });
+}
+function guardPublicConfig(gate, host, declared) {
+    return Object.freeze({
+        get: gate.guard(async ({ name }) => {
+            if (!declared.includes(name))
+                throw new Error(`This admin surface does not declare public config '${named(name)}'. Declare it in the surface's publicConfig.`);
+            return host.get({ name });
+        }),
+    });
+}
+/** Read-only discovery shares revocation and actor checks with other surface-only ports. Unknown
+ * host fields never reach a handler; collection and string caps bound the disclosure.
+ * @complexity O(min(f, 200)) time/space for f host forms, one workspace read. */
+function guardForms(required, optional = {}) {
+    const { gate, host } = required;
+    return Object.freeze({
+        list: gate.guard(async (_input, _options = {}) => {
+            requireActor(optional.actorId);
+            const forms = await host.list({});
+            return forms.slice(0, 200).map(({ slug, title }) => {
+                if (typeof slug !== 'string' || slug.length === 0 || slug.length > 64 || typeof title !== 'string')
+                    throw new Error('The forms host returned an invalid form choice.');
+                return { slug, title: title.slice(0, 1024) };
+            });
+        }),
+    });
+}
+/**
+ * Opens the capability session for one admin-surface handler call.
+ * @param required.capabilities - The host's ports for this call (already scoped to plugin, workspace, principal).
+ * @param required.isLive - False once the plugin's surface handlers are revoked.
+ * @param required.declared - The surface's own capability declarations (the allowlists).
+ * @param required.issued - The plugin's token memory, shared by all its calls (tools included).
+ * @param optional.actorId - The signed-in admin; account actions are refused without one.
+ * @returns Wrapped capabilities plus the shared `release` (result) and `sanitize` (error) gates.
+ * @complexity O(1) to open; each check is bounded by the declared lists and the value caps.
+ */
+export function openAdminSurfaceCapabilitySession(required, optional = {}) {
+    const { capabilities: host, isLive, declared, issued } = required;
+    const gate = openCapabilityGate({ isLive, issued });
+    const input = { gate, host: host.connections, declared: declared.connections ?? [], actorId: optional.actorId };
+    const { deliveryAdapters } = declared;
+    const deliveryBindings = deliveryAdapters === undefined || host.deliveryBindings === undefined ? undefined
+        : guardDeliveryBindings({ gate, host: host.deliveryBindings, adapterIds: deliveryAdapters, connectionIds: input.declared.map((connection) => connection.id) }, { actorId: optional.actorId });
+    const capabilities = Object.freeze({
+        ...guardSharedCapabilities({ gate, host }),
+        connections: Object.freeze({ ...readConnections(input), ...actConnections(input) }),
+        state: guardState(gate, host.state),
+        publicConfig: guardPublicConfig(gate, host.publicConfig, declared.publicConfig ?? []),
+        ...(deliveryBindings && { deliveryBindings }),
+        ...(declared.forms?.includes('list') && host.forms !== undefined && { forms: guardForms({ gate, host: host.forms }, optional) }),
+    });
+    return { capabilities, release: gate.release, sanitize: gate.sanitize };
+}
+//# sourceMappingURL=surface-capabilities.js.map

package/dist/admin-surfaces/surface-client.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @file The surface-side half of the admin-surface message protocol, for a plugin's own UI.
+ *
+ * Self-contained on purpose (no imports): a plugin's surface is plain static files, so it may import
+ * this module from the package or copy the compiled file next to its entry. The constants repeat
+ * `./protocol.ts`; the vertical-slice test proves the two still agree.
+ *
+ * Trust rules it applies: it accepts init only from its parent window (once), learns the host's
+ * origin from that init and posts only to that origin (never "*"), and accepts a response only from
+ * the parent, from that origin, for this mount, for a request it still has pending, in a valid shape.
+ *
+ * Theme: the host may send its design tokens with init and again in `theme` messages (`./theme.ts`).
+ * The client applies the `--jini-*` ones with a safe value as custom properties on the surface's root
+ * element (CSSOM `setProperty`, which a CSP without 'unsafe-inline' allows), plus `color-scheme` and
+ * `data-jini-scheme`, so the surface's own stylesheet can follow the admin's look and light/dark mode.
+ */
+/** The parts of `window.parent` the client uses. */
+export interface AdminSurfaceParentPort {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+/** The fields of a `MessageEvent` the client reads. */
+export interface AdminSurfaceIncomingMessage {
+    readonly origin: string;
+    readonly source: unknown;
+    readonly data: unknown;
+}
+/** Subscribes to `message` events; returns the unsubscribe function. */
+export type AdminSurfaceListenPort = (handler: (event: AdminSurfaceIncomingMessage) => void) => () => void;
+/** The element the host's tokens are applied to (in a browser, `document.documentElement`). */
+export interface AdminSurfaceThemeRoot {
+    readonly style: {
+        setProperty(name: string, value: string): void;
+        removeProperty(name: string): void;
+    };
+    setAttribute(name: string, value: string): void;
+}
+/**
+ * Reports the surface's content height in CSS pixels whenever it may have changed; returns the stop
+ * function. The host sizes the frame to it, so a surface never scrolls inside the admin page.
+ */
+export type AdminSurfaceSizePort = (onHeight: (height: number) => void) => () => void;
+/** The body element the default size source measures and listens on (in a browser, `document.body`). */
+export interface AdminSurfaceSizedBody {
+    readonly scrollHeight: number;
+    getBoundingClientRect(): {
+        readonly height: number;
+    };
+    addEventListener(type: 'mouseover' | 'focusin', listener: () => void): void;
+    removeEventListener(type: 'mouseover' | 'focusin', listener: () => void): void;
+}
+/** An observer constructor the default size source re-measures from (Resize/MutationObserver). */
+export type AdminSurfaceObserverConstructor = new (callback: () => void) => {
+    observe(target: AdminSurfaceSizedBody, options?: Readonly<Record<string, boolean>>): void;
+    disconnect(): void;
+};
+/**
+ * The browser globals the default theme root and size source read. Injectable so the defaults are
+ * testable without a DOM; `globalThis` is wired in at the client's composition edge.
+ */
+export interface AdminSurfaceBrowserScope {
+    readonly document?: {
+        readonly documentElement?: AdminSurfaceThemeRoot;
+        readonly body?: AdminSurfaceSizedBody | null;
+    };
+    readonly ResizeObserver?: AdminSurfaceObserverConstructor;
+    readonly MutationObserver?: AdminSurfaceObserverConstructor;
+    readonly getComputedStyle?: (element: AdminSurfaceSizedBody) => {
+        readonly marginTop: string;
+        readonly marginBottom: string;
+    };
+}
+/** The host's design tokens as the client accepted them. */
+export interface AdminSurfaceClientTheme {
+    readonly scheme: 'light' | 'dark';
+    readonly tokens: Readonly<Record<string, string>>;
+}
+export interface AdminSurfaceClientFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+}
+/** Rejection value of `call` when the host refused the action or the request timed out. */
+export declare class AdminSurfaceCallError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(required: AdminSurfaceClientFailure);
+}
+/**
+ * Connects a surface to its host. In a browser:
+ * `createAdminSurfaceClient({ parent: window.parent, listen: (h) => { addEventListener('message', h); return () => removeEventListener('message', h); } })`.
+ * @param optional.timeoutMs - How long `call` waits for a response before rejecting with `timeout`.
+ * @complexity O(1) per message.
+ */
+export declare function createAdminSurfaceClient(required: {
+    readonly parent: AdminSurfaceParentPort;
+    readonly listen: AdminSurfaceListenPort;
+}, optional?: {
+    readonly timeoutMs?: number;
+    readonly nowMs?: () => number;
+    readonly themeRoot?: AdminSurfaceThemeRoot | null;
+    readonly size?: AdminSurfaceSizePort | null;
+    readonly browser?: AdminSurfaceBrowserScope;
+}): {
+    ready: Promise<void>;
+    call: (input: {
+        readonly action: string;
+        readonly payload: unknown;
+    }) => Promise<unknown>;
+    openLink: (input: {
+        readonly url: string;
+    }) => Promise<void>;
+    bootstrap: () => unknown;
+    theme: () => AdminSurfaceClientTheme | undefined;
+    close: () => void;
+};
+//# sourceMappingURL=surface-client.d.ts.map