@fntio/infra-client-plugin-sdk 0.0.0-stage → 0.2.0

package/dist/contracts/access.d.ts

@@ -0,0 +1,14 @@
+import { PluginPermission } from "./manifest";
+export declare const PLUGIN_TARGET_PREFIX = "plugin#";
+/** The Access-table target: `plugin#<pluginId>#<accountNumber>#<user|admin>`. */
+export interface PluginGrantTarget {
+    readonly pluginId: string;
+    readonly accountNumber: string;
+    readonly permission: PluginPermission;
+}
+export declare function pluginTargetKey(target: PluginGrantTarget): string;
+export declare function parsePluginTargetKey(key: string): PluginGrantTarget | null;
+/** Fixed platform rule: admin includes user, but only when the plugin declares user. */
+export declare function pluginPermissionsImpliedBy(granted: PluginPermission, declared: readonly PluginPermission[]): PluginPermission[];
+/** Effective capabilities from a set of held (stored) grants for one plugin/account. */
+export declare function pluginEffectivePermissions(held: readonly PluginPermission[], declared: readonly PluginPermission[]): PluginPermission[];

package/dist/contracts/access.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_TARGET_PREFIX = void 0;
+exports.pluginTargetKey = pluginTargetKey;
+exports.parsePluginTargetKey = parsePluginTargetKey;
+exports.pluginPermissionsImpliedBy = pluginPermissionsImpliedBy;
+exports.pluginEffectivePermissions = pluginEffectivePermissions;
+const manifest_1 = require("./manifest");
+exports.PLUGIN_TARGET_PREFIX = "plugin#";
+function pluginTargetKey(target) {
+    return `${exports.PLUGIN_TARGET_PREFIX}${target.pluginId}#${target.accountNumber}#${target.permission}`;
+}
+function parsePluginTargetKey(key) {
+    if (!key.startsWith(exports.PLUGIN_TARGET_PREFIX))
+        return null;
+    const parts = key.slice(exports.PLUGIN_TARGET_PREFIX.length).split("#");
+    if (parts.length !== 3)
+        return null;
+    const [pluginId, accountNumber, permission] = parts;
+    if (!manifest_1.PLUGIN_ID_PATTERN.test(pluginId) || !manifest_1.AWS_ACCOUNT_PATTERN.test(accountNumber))
+        return null;
+    if (!manifest_1.PLUGIN_PERMISSIONS.includes(permission))
+        return null;
+    return { pluginId, accountNumber, permission: permission };
+}
+/** Fixed platform rule: admin includes user, but only when the plugin declares user. */
+function pluginPermissionsImpliedBy(granted, declared) {
+    if (!declared.includes(granted))
+        return [];
+    if (granted === "admin" && declared.includes("user"))
+        return ["admin", "user"];
+    return [granted];
+}
+/** Effective capabilities from a set of held (stored) grants for one plugin/account. */
+function pluginEffectivePermissions(held, declared) {
+    const out = new Set();
+    for (const h of held)
+        for (const p of pluginPermissionsImpliedBy(h, declared))
+            out.add(p);
+    return manifest_1.PLUGIN_PERMISSIONS.filter((p) => out.has(p));
+}

package/dist/contracts/authorizer.d.ts

@@ -0,0 +1,17 @@
+import { PluginPermission } from "./manifest";
+export type PluginPrincipalType = "user" | "service";
+/** What the shared authorizer attaches to every allowed request; scalars only, never a token. */
+export interface PluginAuthorizerContextV1 {
+    readonly pluginId: string;
+    readonly pluginRevision: string;
+    readonly routeId: string;
+    readonly accountNumber: string;
+    readonly requiredPermission: PluginPermission;
+    readonly subject: string;
+    readonly principalType: PluginPrincipalType;
+    readonly correlationId: string;
+}
+export declare const PLUGIN_AUTHORIZER_CONTEXT_KEYS: readonly ["pluginId", "pluginRevision", "routeId", "accountNumber", "requiredPermission", "subject", "principalType", "correlationId"];
+/** Fail closed: a handler must not run on a context it cannot read completely. */
+export declare function parsePluginAuthorizerContext(raw: unknown): PluginAuthorizerContextV1;
+export declare function tryParsePluginAuthorizerContext(raw: unknown): PluginAuthorizerContextV1 | null;

package/dist/contracts/authorizer.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_AUTHORIZER_CONTEXT_KEYS = void 0;
+exports.parsePluginAuthorizerContext = parsePluginAuthorizerContext;
+exports.tryParsePluginAuthorizerContext = tryParsePluginAuthorizerContext;
+const manifest_1 = require("./manifest");
+exports.PLUGIN_AUTHORIZER_CONTEXT_KEYS = [
+    "pluginId", "pluginRevision", "routeId", "accountNumber",
+    "requiredPermission", "subject", "principalType", "correlationId",
+];
+/** Fail closed: a handler must not run on a context it cannot read completely. */
+function parsePluginAuthorizerContext(raw) {
+    const ctx = tryParsePluginAuthorizerContext(raw);
+    if (!ctx)
+        throw new Error("plugin authorizer context is missing or malformed");
+    return ctx;
+}
+function tryParsePluginAuthorizerContext(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    for (const key of exports.PLUGIN_AUTHORIZER_CONTEXT_KEYS) {
+        if (typeof r[key] !== "string" || r[key].length === 0)
+            return null;
+    }
+    if (!manifest_1.PLUGIN_ID_PATTERN.test(r.pluginId))
+        return null;
+    if (!manifest_1.AWS_ACCOUNT_PATTERN.test(r.accountNumber))
+        return null;
+    if (!manifest_1.PLUGIN_PERMISSIONS.includes(r.requiredPermission))
+        return null;
+    if (r.principalType !== "user" && r.principalType !== "service")
+        return null;
+    return {
+        pluginId: r.pluginId,
+        pluginRevision: r.pluginRevision,
+        routeId: r.routeId,
+        accountNumber: r.accountNumber,
+        requiredPermission: r.requiredPermission,
+        subject: r.subject,
+        principalType: r.principalType,
+        correlationId: r.correlationId,
+    };
+}

package/dist/contracts/canonical.d.ts

@@ -0,0 +1,2 @@
+/** JSON with object keys sorted at every level, so equal manifests hash and compare equal. */
+export declare function canonicalJson(value: unknown): string;

package/dist/contracts/canonical.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+/** JSON with object keys sorted at every level, so equal manifests hash and compare equal. */
+function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = sortKeys(v);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/contracts/catalog.d.ts

@@ -0,0 +1,37 @@
+import { PluginManifestV1, PluginRoute } from "./manifest";
+export interface PluginCatalogUiEntryV1 {
+    readonly label: string;
+    readonly icon?: string;
+    readonly order?: number;
+    /** Absolute path on the portal origin, under the immutable asset prefix. */
+    readonly url: string;
+}
+export interface PluginCatalogRouteV1 extends PluginRoute {
+    /** The gateway resource template the authorizer resolves the route by. */
+    readonly resourcePath: string;
+}
+/** One PluginCatalog item, keyed by `pluginId`. Deployment-written; holds no user grants. */
+export interface PluginCatalogRecordV1 {
+    readonly pluginId: string;
+    readonly schemaVersion: number;
+    readonly manifest: PluginManifestV1;
+    /** Content digest of permission/route metadata plus the asset hash. */
+    readonly revision: string;
+    readonly assetPrefix?: string;
+    /** false = tombstone: the definition was removed; labels are kept for historical grants. */
+    readonly installed: boolean;
+    /** The deployment that owns this record; another owner claiming the id is a deploy error. */
+    readonly owner: string;
+    readonly ui?: {
+        readonly user?: PluginCatalogUiEntryV1;
+        readonly admin?: PluginCatalogUiEntryV1;
+    };
+    readonly routes: readonly PluginCatalogRouteV1[];
+    readonly installedAt: string;
+    readonly updatedAt: string;
+    readonly removedAt?: string;
+}
+export type PluginCatalogStatus = "active" | "disabled" | "removed" | "unsupported";
+export declare function pluginCatalogStatus(record: PluginCatalogRecordV1): PluginCatalogStatus;
+/** Only an active record may authorize requests or appear in caller discovery. */
+export declare function isPluginActive(record: PluginCatalogRecordV1): boolean;

package/dist/contracts/catalog.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginCatalogStatus = pluginCatalogStatus;
+exports.isPluginActive = isPluginActive;
+const manifest_1 = require("./manifest");
+function pluginCatalogStatus(record) {
+    if (!record.installed)
+        return "removed";
+    if (record.schemaVersion !== manifest_1.PLUGIN_MANIFEST_SCHEMA_VERSION ||
+        record.manifest.hostApiVersion !== manifest_1.PLUGIN_HOST_API_VERSION) {
+        return "unsupported";
+    }
+    return record.manifest.enabled ? "active" : "disabled";
+}
+/** Only an active record may authorize requests or appear in caller discovery. */
+function isPluginActive(record) {
+    return pluginCatalogStatus(record) === "active";
+}

package/dist/contracts/discovery.d.ts

@@ -0,0 +1,78 @@
+import { PluginCatalogStatus } from "./catalog";
+import { PluginPermission, PluginRoute } from "./manifest";
+export declare const PLUGIN_DISCOVERY_DEFAULT_REFRESH_SECONDS = 60;
+export declare const PLUGIN_DISCOVERY_MIN_REFRESH_SECONDS = 15;
+export declare const PLUGIN_DISCOVERY_MAX_REFRESH_SECONDS = 300;
+export interface PluginDiscoveryUiEntryV1 {
+    readonly label: string;
+    readonly icon?: string;
+    readonly order?: number;
+    readonly url: string;
+}
+export interface PluginDiscoveryAccountV1 {
+    readonly accountNumber: string;
+    readonly displayName: string;
+    readonly regions?: readonly string[];
+    /** Effective capabilities, implication applied; not stored assignments. */
+    readonly permissions: readonly PluginPermission[];
+}
+export interface PluginDiscoveryEntryV1 {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly version: string;
+    readonly revision: string;
+    readonly apiBaseUrl: string;
+    readonly ui: {
+        readonly user?: PluginDiscoveryUiEntryV1;
+        readonly admin?: PluginDiscoveryUiEntryV1;
+    };
+    readonly accounts: readonly PluginDiscoveryAccountV1[];
+}
+/** `GET /api/plugins`: only what the caller may use. */
+export interface PluginDiscoveryResponseV1 {
+    readonly schemaVersion: 1;
+    readonly refreshAfterSeconds: number;
+    readonly plugins: readonly PluginDiscoveryEntryV1[];
+}
+export interface PluginAdminAccountV1 {
+    readonly accountNumber: string;
+    readonly displayName?: string;
+    readonly regions?: readonly string[];
+    /** false when the bound account is not registered in the Accounts catalog. */
+    readonly available: boolean;
+    readonly reason?: "unregistered";
+}
+export interface PluginAdminPermissionV1 {
+    readonly id: PluginPermission;
+    readonly label: string;
+    readonly description?: string;
+    readonly implies: readonly PluginPermission[];
+}
+export interface PluginAdminEntryV1 {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly version: string;
+    readonly revision: string;
+    readonly schemaVersion: number;
+    readonly hostApiVersion: number;
+    readonly status: PluginCatalogStatus;
+    readonly enabled: boolean;
+    readonly installed: boolean;
+    readonly permissions: readonly PluginAdminPermissionV1[];
+    readonly accounts: readonly PluginAdminAccountV1[];
+    readonly ui: {
+        readonly user?: Omit<PluginDiscoveryUiEntryV1, "url">;
+        readonly admin?: Omit<PluginDiscoveryUiEntryV1, "url">;
+    };
+    readonly routes: readonly Pick<PluginRoute, "id" | "method" | "path" | "permission">[];
+    readonly updatedAt: string;
+}
+/** `GET /api/admin/plugins`: every definition, for the grant editor. */
+export interface PluginAdminCatalogResponseV1 {
+    readonly schemaVersion: 1;
+    readonly plugins: readonly PluginAdminEntryV1[];
+}
+export declare function isPluginDiscoveryAccount(v: unknown): v is PluginDiscoveryAccountV1;
+export declare function isPluginDiscoveryResponse(value: unknown): value is PluginDiscoveryResponseV1;

package/dist/contracts/discovery.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_DISCOVERY_MAX_REFRESH_SECONDS = exports.PLUGIN_DISCOVERY_MIN_REFRESH_SECONDS = exports.PLUGIN_DISCOVERY_DEFAULT_REFRESH_SECONDS = void 0;
+exports.isPluginDiscoveryAccount = isPluginDiscoveryAccount;
+exports.isPluginDiscoveryResponse = isPluginDiscoveryResponse;
+const manifest_1 = require("./manifest");
+exports.PLUGIN_DISCOVERY_DEFAULT_REFRESH_SECONDS = 60;
+exports.PLUGIN_DISCOVERY_MIN_REFRESH_SECONDS = 15;
+exports.PLUGIN_DISCOVERY_MAX_REFRESH_SECONDS = 300;
+function isUiEntry(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const e = v;
+    return typeof e.label === "string" && typeof e.url === "string";
+}
+function isPluginDiscoveryAccount(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const a = v;
+    return (typeof a.accountNumber === "string" &&
+        manifest_1.AWS_ACCOUNT_PATTERN.test(a.accountNumber) &&
+        typeof a.displayName === "string" &&
+        (a.regions === undefined || (Array.isArray(a.regions) && a.regions.every((r) => typeof r === "string"))) &&
+        Array.isArray(a.permissions) &&
+        a.permissions.every((p) => manifest_1.PLUGIN_PERMISSIONS.includes(p)));
+}
+function isPluginDiscoveryResponse(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const r = value;
+    if (r.schemaVersion !== 1 || typeof r.refreshAfterSeconds !== "number" || !Array.isArray(r.plugins))
+        return false;
+    return r.plugins.every((p) => {
+        if (!p || typeof p !== "object")
+            return false;
+        const e = p;
+        const ui = e.ui;
+        return (typeof e.id === "string" &&
+            typeof e.displayName === "string" &&
+            typeof e.version === "string" &&
+            typeof e.revision === "string" &&
+            typeof e.apiBaseUrl === "string" &&
+            !!ui && typeof ui === "object" &&
+            (ui.user === undefined || isUiEntry(ui.user)) &&
+            (ui.admin === undefined || isUiEntry(ui.admin)) &&
+            Array.isArray(e.accounts) && e.accounts.every(isPluginDiscoveryAccount));
+    });
+}

package/dist/contracts/fields.d.ts

@@ -0,0 +1,7 @@
+/** The fields a validator reads off an unvalidated value, each still `unknown`. A finite key set rather
+ *  than `Record<string, unknown>`: an index signature makes property access illegal for consumers compiling
+ *  with `noPropertyAccessFromIndexSignature`, and the portal frontend compiles this source directly.
+ *  Its own leaf module, so naming it drags nothing else into a consumer's bundle. */
+export type ValidatedFields<K extends string> = {
+    [P in K]?: unknown;
+};

package/dist/contracts/fields.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/manifest.d.ts

@@ -0,0 +1,59 @@
+export type PluginPermission = "user" | "admin";
+export declare const PLUGIN_PERMISSIONS: readonly PluginPermission[];
+export type PluginRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+export declare const PLUGIN_ROUTE_METHODS: readonly PluginRouteMethod[];
+export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+export declare const PLUGIN_HOST_API_VERSION = 1;
+/** The platform's own path parameter on every plugin route; routes may not declare it. */
+export declare const PLUGIN_ACCOUNT_PARAM = "accountNumber";
+export declare const PLUGIN_ID_PATTERN: RegExp;
+/** Becomes part of the immutable asset URL, so it is limited to URL-safe characters. */
+export declare const PLUGIN_VERSION_PATTERN: RegExp;
+export declare const AWS_ACCOUNT_PATTERN: RegExp;
+export declare const AWS_REGION_PATTERN: RegExp;
+export declare const PLUGIN_ICON_PATTERN: RegExp;
+export declare const PLUGIN_DISPLAY_NAME_MAX = 80;
+export declare const PLUGIN_DESCRIPTION_MAX = 500;
+/** The catalog record stores the manifest plus resolved routes and URLs; keep it well under DynamoDB's 400 KB item limit. */
+export declare const PLUGIN_MANIFEST_MAX_BYTES = 100000;
+export interface PluginAccountBinding {
+    readonly accountNumber: string;
+    /** Constrains the account context handed to the plugin; not a grant dimension. */
+    readonly regions?: readonly string[];
+}
+export interface PluginPermissionDefinition {
+    readonly id: PluginPermission;
+    readonly label: string;
+    readonly description?: string;
+}
+export interface PluginUiEntry {
+    readonly label: string;
+    readonly icon?: string;
+    readonly order?: number;
+    /** A file inside the asset directory, optionally with a hash route: "index.html#/user". */
+    readonly entry: string;
+}
+export interface PluginRoute {
+    readonly id: string;
+    readonly method: PluginRouteMethod;
+    /** Relative to the account-scoped plugin root; literal segments and single-segment `{params}` only. */
+    readonly path: string;
+    readonly permission: PluginPermission;
+    readonly handlerKey: string;
+}
+export interface PluginManifestV1 {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly version: string;
+    readonly hostApiVersion: 1;
+    readonly enabled: boolean;
+    readonly accounts: readonly PluginAccountBinding[];
+    readonly permissions: readonly PluginPermissionDefinition[];
+    readonly ui?: {
+        readonly user?: PluginUiEntry;
+        readonly admin?: PluginUiEntry;
+    };
+    readonly routes: readonly PluginRoute[];
+}

package/dist/contracts/manifest.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_MANIFEST_MAX_BYTES = exports.PLUGIN_DESCRIPTION_MAX = exports.PLUGIN_DISPLAY_NAME_MAX = exports.PLUGIN_ICON_PATTERN = exports.AWS_REGION_PATTERN = exports.AWS_ACCOUNT_PATTERN = exports.PLUGIN_VERSION_PATTERN = exports.PLUGIN_ID_PATTERN = exports.PLUGIN_ACCOUNT_PARAM = exports.PLUGIN_HOST_API_VERSION = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_ROUTE_METHODS = exports.PLUGIN_PERMISSIONS = void 0;
+exports.PLUGIN_PERMISSIONS = ["user", "admin"];
+exports.PLUGIN_ROUTE_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+exports.PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+exports.PLUGIN_HOST_API_VERSION = 1;
+/** The platform's own path parameter on every plugin route; routes may not declare it. */
+exports.PLUGIN_ACCOUNT_PARAM = "accountNumber";
+exports.PLUGIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/** Becomes part of the immutable asset URL, so it is limited to URL-safe characters. */
+exports.PLUGIN_VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/;
+exports.AWS_ACCOUNT_PATTERN = /^\d{12}$/;
+exports.AWS_REGION_PATTERN = /^[a-z]{2}(-[a-z]+)+-\d$/;
+exports.PLUGIN_ICON_PATTERN = /^[a-z][a-z0-9-]*$/;
+exports.PLUGIN_DISPLAY_NAME_MAX = 80;
+exports.PLUGIN_DESCRIPTION_MAX = 500;
+/** The catalog record stores the manifest plus resolved routes and URLs; keep it well under DynamoDB's 400 KB item limit. */
+exports.PLUGIN_MANIFEST_MAX_BYTES = 100_000;

package/dist/contracts/messages.d.ts

@@ -0,0 +1,108 @@
+import { PluginPermission } from "./manifest";
+import { PluginPrincipalType } from "./authorizer";
+import { PluginTheme } from "./theme";
+export declare const PLUGIN_PROTOCOL = "infra-client-plugin";
+export declare const PLUGIN_PROTOCOL_VERSION = 2;
+export declare const PLUGIN_HANDSHAKE_TIMEOUT_MS = 10000;
+/** The current API bearer token and its expiry (epoch milliseconds). The host never SENDS the refresh token
+ *  (the frame is same-origin and could read the portal's storage; see README "Trust model"). */
+export interface PluginSession {
+    readonly token: string;
+    readonly expiresAt: number;
+}
+export interface PluginUserContext {
+    readonly subject: string;
+    readonly principalType: PluginPrincipalType;
+    readonly email?: string;
+    readonly displayName?: string;
+}
+export interface PluginAccountContext {
+    readonly accountNumber: string;
+    readonly displayName: string;
+    readonly regions?: readonly string[];
+    readonly permissions: readonly PluginPermission[];
+}
+export interface PluginInfoContext {
+    readonly id: string;
+    readonly displayName: string;
+    readonly version: string;
+    readonly revision: string;
+    readonly apiBaseUrl: string;
+}
+export type PluginEntryKind = PluginPermission;
+export interface HostToPluginPayloads {
+    init: {
+        readonly session: PluginSession;
+        readonly user: PluginUserContext;
+        readonly plugin: PluginInfoContext;
+        readonly entry: PluginEntryKind;
+        readonly accounts: readonly PluginAccountContext[];
+        readonly theme: PluginTheme;
+    };
+    sessionChanged: PluginSession;
+    sessionEnded: {
+        readonly reason: "signedOut" | "expired" | "unloaded";
+    };
+    accessChanged: {
+        readonly accounts: readonly PluginAccountContext[];
+        readonly entryAvailable: boolean;
+    };
+    themeChanged: PluginTheme;
+}
+export interface PluginToHostPayloads {
+    ready: {
+        readonly sdkVersion: string;
+        readonly protocolVersion: typeof PLUGIN_PROTOCOL_VERSION;
+    };
+    requestSessionRefresh: {
+        readonly reason: "unauthorized" | "expiring";
+    };
+    requestAccessRefresh: {
+        readonly reason: "forbidden" | "manual";
+    };
+}
+export type PluginMessagePayloads = HostToPluginPayloads & PluginToHostPayloads;
+export type PluginMessageType = keyof PluginMessagePayloads;
+export type HostToPluginMessageType = keyof HostToPluginPayloads;
+export type PluginToHostMessageType = keyof PluginToHostPayloads;
+export declare const HOST_TO_PLUGIN_MESSAGE_TYPES: readonly HostToPluginMessageType[];
+export declare const PLUGIN_TO_HOST_MESSAGE_TYPES: readonly PluginToHostMessageType[];
+export interface PluginMessage<T extends PluginMessageType = PluginMessageType> {
+    readonly protocol: typeof PLUGIN_PROTOCOL;
+    readonly version: typeof PLUGIN_PROTOCOL_VERSION;
+    readonly type: T;
+    /** Per iframe instance; a reload gets a new one and replies for old ones are dropped. */
+    readonly instanceId: string;
+    readonly requestId?: string;
+    readonly payload: PluginMessagePayloads[T];
+}
+export type AnyPluginMessage = {
+    [T in PluginMessageType]: PluginMessage<T>;
+}[PluginMessageType];
+export declare function createPluginMessage<T extends PluginMessageType>(type: T, instanceId: string, payload: PluginMessagePayloads[T], requestId?: string): PluginMessage<T>;
+export declare function isPluginSession(v: unknown): v is PluginSession;
+export declare function isPluginAccountContext(v: unknown): v is PluginAccountContext;
+/** Envelope + payload shape check. Returns null for anything that is not a well-formed message at the current version. */
+export declare function parsePluginMessage(data: unknown): AnyPluginMessage | null;
+export type HostToPluginMessage = {
+    [T in HostToPluginMessageType]: PluginMessage<T>;
+}[HostToPluginMessageType];
+export type PluginToHostMessage = {
+    [T in PluginToHostMessageType]: PluginMessage<T>;
+}[PluginToHostMessageType];
+export declare function isHostToPluginMessage(message: AnyPluginMessage): message is HostToPluginMessage;
+export declare function isPluginToHostMessage(message: AnyPluginMessage): message is PluginToHostMessage;
+export type PluginMessageInspection = {
+    readonly kind: "message";
+    readonly message: AnyPluginMessage;
+} | {
+    readonly kind: "incompatible";
+    readonly version: unknown;
+}
+/** Not ours, or ours but malformed: either way there is nothing to act on. */
+ | {
+    readonly kind: "ignored";
+};
+/** Classifies `event.data` for both ends of the protocol: a well-formed message, our protocol at
+ *  another version, or nothing to act on. Callers still check `event.source` and `event.origin`. */
+export declare function inspectPluginMessage(data: unknown): PluginMessageInspection;

package/dist/contracts/messages.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_TO_HOST_MESSAGE_TYPES = exports.HOST_TO_PLUGIN_MESSAGE_TYPES = exports.PLUGIN_HANDSHAKE_TIMEOUT_MS = exports.PLUGIN_PROTOCOL_VERSION = exports.PLUGIN_PROTOCOL = void 0;
+exports.createPluginMessage = createPluginMessage;
+exports.isPluginSession = isPluginSession;
+exports.isPluginAccountContext = isPluginAccountContext;
+exports.parsePluginMessage = parsePluginMessage;
+exports.isHostToPluginMessage = isHostToPluginMessage;
+exports.isPluginToHostMessage = isPluginToHostMessage;
+exports.inspectPluginMessage = inspectPluginMessage;
+const manifest_1 = require("./manifest");
+const theme_1 = require("./theme");
+exports.PLUGIN_PROTOCOL = "infra-client-plugin";
+exports.PLUGIN_PROTOCOL_VERSION = 2;
+exports.PLUGIN_HANDSHAKE_TIMEOUT_MS = 10_000;
+exports.HOST_TO_PLUGIN_MESSAGE_TYPES = [
+    "init", "sessionChanged", "sessionEnded", "accessChanged", "themeChanged",
+];
+exports.PLUGIN_TO_HOST_MESSAGE_TYPES = [
+    "ready", "requestSessionRefresh", "requestAccessRefresh",
+];
+function createPluginMessage(type, instanceId, payload, requestId) {
+    return {
+        protocol: exports.PLUGIN_PROTOCOL,
+        version: exports.PLUGIN_PROTOCOL_VERSION,
+        type,
+        instanceId,
+        ...(requestId === undefined ? {} : { requestId }),
+        payload,
+    };
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isNonEmpty = (v) => typeof v === "string" && v.length > 0;
+function isPluginSession(v) {
+    return isRecord(v) && isNonEmpty(v.token) && typeof v.expiresAt === "number" && Number.isFinite(v.expiresAt);
+}
+function isPluginAccountContext(v) {
+    return (isRecord(v) &&
+        typeof v.accountNumber === "string" && manifest_1.AWS_ACCOUNT_PATTERN.test(v.accountNumber) &&
+        typeof v.displayName === "string" &&
+        (v.regions === undefined || (Array.isArray(v.regions) && v.regions.every((r) => typeof r === "string"))) &&
+        Array.isArray(v.permissions) && v.permissions.every((p) => manifest_1.PLUGIN_PERMISSIONS.includes(p)));
+}
+function isAccountList(v) {
+    return Array.isArray(v) && v.every(isPluginAccountContext);
+}
+function isUserContext(v) {
+    return (isRecord(v) && isNonEmpty(v.subject) &&
+        (v.principalType === "user" || v.principalType === "service") &&
+        (v.email === undefined || typeof v.email === "string") &&
+        (v.displayName === undefined || typeof v.displayName === "string"));
+}
+function isPluginInfo(v) {
+    return isRecord(v) && isNonEmpty(v.id) && typeof v.displayName === "string" && typeof v.version === "string" && typeof v.revision === "string" && typeof v.apiBaseUrl === "string";
+}
+const PAYLOAD_CHECKS = {
+    init: (p) => isRecord(p) && isPluginSession(p.session) && isUserContext(p.user) && isPluginInfo(p.plugin) &&
+        (p.entry === "user" || p.entry === "admin") && isAccountList(p.accounts) &&
+        (0, theme_1.isPluginTheme)(p.theme),
+    sessionChanged: isPluginSession,
+    sessionEnded: (p) => isRecord(p) && (p.reason === "signedOut" || p.reason === "expired" || p.reason === "unloaded"),
+    accessChanged: (p) => isRecord(p) && isAccountList(p.accounts) && typeof p.entryAvailable === "boolean",
+    themeChanged: theme_1.isPluginTheme,
+    ready: (p) => isRecord(p) && isNonEmpty(p.sdkVersion) && p.protocolVersion === exports.PLUGIN_PROTOCOL_VERSION,
+    requestSessionRefresh: (p) => isRecord(p) && (p.reason === "unauthorized" || p.reason === "expiring"),
+    requestAccessRefresh: (p) => isRecord(p) && (p.reason === "forbidden" || p.reason === "manual"),
+};
+/** Envelope + payload shape check. Returns null for anything that is not a well-formed message at the current version. */
+function parsePluginMessage(data) {
+    if (!isRecord(data))
+        return null;
+    if (data.protocol !== exports.PLUGIN_PROTOCOL || data.version !== exports.PLUGIN_PROTOCOL_VERSION)
+        return null;
+    // hasOwn, not `in`: `type: "__proto__"` would otherwise pass and be called as a validator.
+    if (typeof data.type !== "string" || !Object.hasOwn(PAYLOAD_CHECKS, data.type))
+        return null;
+    if (!isNonEmpty(data.instanceId))
+        return null;
+    if (data.requestId !== undefined && !isNonEmpty(data.requestId))
+        return null;
+    const type = data.type;
+    if (!PAYLOAD_CHECKS[type](data.payload))
+        return null;
+    return createPluginMessage(type, data.instanceId, data.payload, data.requestId);
+}
+const HOST_TO_PLUGIN_TYPE_SET = new Set(exports.HOST_TO_PLUGIN_MESSAGE_TYPES);
+const PLUGIN_TO_HOST_TYPE_SET = new Set(exports.PLUGIN_TO_HOST_MESSAGE_TYPES);
+function isHostToPluginMessage(message) {
+    return HOST_TO_PLUGIN_TYPE_SET.has(message.type);
+}
+function isPluginToHostMessage(message) {
+    return PLUGIN_TO_HOST_TYPE_SET.has(message.type);
+}
+/** Classifies `event.data` for both ends of the protocol: a well-formed message, our protocol at
+ *  another version, or nothing to act on. Callers still check `event.source` and `event.origin`. */
+function inspectPluginMessage(data) {
+    if (!isRecord(data) || data.protocol !== exports.PLUGIN_PROTOCOL)
+        return { kind: "ignored" };
+    if (data.version !== exports.PLUGIN_PROTOCOL_VERSION)
+        return { kind: "incompatible", version: data.version };
+    const message = parsePluginMessage(data);
+    return message ? { kind: "message", message } : { kind: "ignored" };
+}

package/dist/contracts/paths.d.ts

@@ -0,0 +1,20 @@
+export declare const PLUGIN_API_ROOT = "/api/plugins";
+export declare const PLUGIN_ASSET_ROOT = "/plugin-assets";
+export declare function pluginApiBaseUrl(pluginId: string): string;
+/** The gateway resource every route of a plugin hangs off: `/api/plugins/<id>/accounts/{accountNumber}`. */
+export declare function pluginAccountRoot(pluginId: string): string;
+/** The gateway resource path template for one registered route. */
+export declare function pluginRouteResourcePath(pluginId: string, routePath: string): string;
+/** The concrete account root a request lands on: the template with the account filled in. */
+export declare function pluginAccountPath(pluginId: string, accountNumber: string): string;
+export interface PluginResourcePath {
+    readonly pluginId: string;
+    /** The path the route was registered with, relative to the account root; "/" for the root. */
+    readonly routePath: string;
+}
+/** The inverse of `pluginRouteResourcePath`: the authorizer resolves a gateway resource template
+ *  back to the plugin and route it belongs to. `null` for anything that is not one. */
+export declare function parsePluginResourcePath(resource: string): PluginResourcePath | null;
+/** Immutable asset prefix: a new hash for changed bytes, even under the same version. */
+export declare function pluginAssetPrefix(pluginId: string, version: string, assetHash: string): string;
+export declare function pluginUiUrl(assetPrefix: string, entry: string): string;