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

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# @fntio/infra-client-plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract every part of a customer plugin agrees on: the manifest a deployment
+registers, the catalog record it becomes, the discovery responses the portal reads,
+the messages a plugin iframe exchanges with the portal shell, and the context the
+shared authorizer hands a plugin Lambda. Types plus runtime validators, no runtime
+dependencies.
+
+Status: contracts (issue #19), the iframe SDK with its host adapter (issue #24) and the
+backend handler helpers (issue #22). Nothing here is published yet; the package is private
+until the publishing workflow enables it.
+
+## Entry points
+
+| Import | For | Contains |
+| --- | --- | --- |
+| `@fntio/infra-client-plugin-sdk` | anyone | the contracts every entry shares: types, validators, path and key helpers (no runtime code) |
+| `@fntio/infra-client-plugin-sdk/browser` | plugin frontends | `connectToInfraClient`, the `PluginContext` it resolves, `context.api`, theme application, message protocol, theme tokens, discovery types |
+| `@fntio/infra-client-plugin-sdk/host` | the portal shell, the dev host | `createPluginHost`: the host side of the protocol |
+| `@fntio/infra-client-plugin-sdk/backend` | plugin Lambdas, the core API | manifest + validator, catalog record, access target keys, authorizer context, path helpers, `pluginAuthorizerContextOf`, `pluginRoutePath`, `rebasePluginEvent`, `createPluginLogger` |
+| `@fntio/infra-client-plugin-sdk/fixtures` | tests in any package, local plugin development | valid manifests in every shape, one invalid manifest per rule, sample payloads, `createFakeWindowPair`, `createDevHost` |
+
+The browser, host and backend entries import nothing external; a test fails if that changes.
+
+## Contracts
+
+- **Manifest** (`PluginManifestV1`, `validatePluginManifest`, `assertPluginManifest`).
+  `schemaVersion: 1`, `hostApiVersion: 1`, id, display name, version, enabled flag,
+  account bindings, `user` and/or `admin` permissions, zero to two UI entries, routes.
+  The validator reports every problem at once with a stable `code`; the codes are the
+  `PluginValidationCode` union. `admin` implies `user` only when both are declared
+  (`pluginPermissionsImpliedBy`).
+- **Paths.** Routes mount at `/api/plugins/<id>/accounts/{accountNumber}<path>`
+  (`pluginRouteResourcePath`); assets at `/plugin-assets/<id>/<version>-<hash>/`
+  (`pluginAssetPrefix`). `{accountNumber}` is reserved for the platform.
+- **Access target** (`pluginTargetKey`): `plugin#<id>#<account>#<user|admin>`, the
+  Access-table target string for plugin grants.
+- **Catalog record** (`PluginCatalogRecordV1`, `pluginCatalogStatus`): what the
+  PluginCatalog table stores per plugin. Holds no user grants. Status is `active`,
+  `disabled`, `removed` (tombstone) or `unsupported`.
+- **Discovery** (`PluginDiscoveryResponseV1` for `GET /api/plugins`,
+  `PluginAdminCatalogResponseV1` for `GET /api/admin/plugins`).
+- **Messages** (`createPluginMessage`, `parsePluginMessage`): the `postMessage`
+  envelope `{ protocol: "infra-client-plugin", version: 2, type, instanceId, requestId?, payload }`.
+  Host → plugin: `init`, `sessionChanged`, `sessionEnded`, `accessChanged`,
+  `themeChanged`. Plugin → host: `ready`, `requestSessionRefresh`,
+  `requestAccessRefresh`. `parsePluginMessage` returns `null` for
+  anything malformed; callers still check `event.source` and `event.origin`.
+- **Theme** (`PLUGIN_THEME_TOKENS`, `PluginTheme`): the documented subset of the
+  portal's CSS custom properties, plus appearance and branding.
+- **Authorizer context** (`PluginAuthorizerContextV1`, `parsePluginAuthorizerContext`):
+  the string fields the shared authorizer attaches to an allowed request. Parsing fails
+  closed.
+
+## Browser SDK
+
+A plugin frontend runs in an iframe on the portal's origin and never signs in itself. The
+host owns sign-in and the refresh token; the SDK receives the current bearer token over
+`postMessage`, keeps it in memory, and hands it to requests the iframe makes itself.
+
+```ts
+import { connectToInfraClient } from "@fntio/infra-client-plugin-sdk/browser";
+
+const context = await connectToInfraClient();          // posts `ready`, resolves on `init`
+const [account] = context.accounts();                  // every account the caller may use; choosing one is yours
+const items = await context.api.get(`accounts/${account.accountNumber}/parameters`);
+context.on("accessChanged", () => render());
+context.on("themeChanged", () => {});                  // the SDK already re-applied the tokens
+context.on("sessionEnded", () => showSignedOut());
+```
+
+`connectToInfraClient` rejects with `not_framed` when the page is a top-level document (a user
+opened the plugin URL directly), `invalid_options` when something it needs is missing or the
+host window refuses the message (outside a browser pass `hostWindow`, `hostOrigin`, `listenOn`
+and `fetch`), `incompatible_host` when the host speaks another protocol version, and
+`handshake_timeout` (10 s, re-announcing every second; 0 disables) when no `init` arrives;
+call it again to retry. Every error is a `PluginSdkError` with a `code`.
+
+**Session.** `context.session.current()` is the token and expiry. `token()` returns the current
+token at once while it is valid; inside the last 30 s (`refreshLeadMs`) it also asks the host to
+renew in the background, and only once the token has expired does it wait for the host. Any
+`sessionChanged` the host sends satisfies a pending refresh, whether it answers the request or
+was pushed by the host's own timer. `refresh(reason)` asks outright; concurrent callers share
+one round trip. A refresh nobody answers within 15 s (`refreshTimeoutMs`, 0 disables) rejects
+with `refresh_timeout`. After the session ends every call rejects with `session_ended`.
+
+**Requests.** `context.api` (`get`/`post`/`put`/`patch`/`delete` for JSON, `request` for a raw
+`Response`, `url` for other clients) resolves paths under `plugin.apiBaseUrl`, refuses absolute
+URLs and `..` segments so the token is not sent outside the plugin's own API root by mistake (a
+guardrail, not a boundary — see the trust model below), and sends `Authorization: Bearer`. After an
+authentication-layer 401 it asks the host to renew and retries exactly once: the authorizer
+rejects before plugin code runs, so the retry cannot repeat a completed write. The retry is
+skipped, and the 401 surfaces, when the body is a stream, when the account in the request path
+(`accounts/<accountNumber>/…`, read by `pluginRequestAccount`) is not in `accounts()` at the 401 or
+no longer there once the renewal returns, or when the host hands back the very token that was
+rejected (`canRetryAfterUnauthorized` is that rule, shared with the Angular interceptor). A
+request whose path names no account is not held to the list. Timeouts
+(`timeoutMs`, which also covers reading the body), 5xx and 403 are never retried. A 403 also
+sends `requestAccessRefresh` (`forbidden`) so the host reloads discovery; pass
+`accessRefreshOnForbidden: false` to keep that manual. Plugin business handlers should answer
+with domain 4xx codes, never 401.
+
+**Context.** `accounts()`, `permissionsFor(accountNumber)`,
+`hasPermission(permission, accountNumber)`, `entryAvailable()` and `theme()` follow
+`accessChanged` and `themeChanged`. `accounts()` is every account the caller may use on this
+entry, each with its permissions; an account outside the list has none. The portal tracks no
+selected account: which one the plugin works in, if it has the notion at all, is the plugin's
+own state, as is any picker it draws. Re-check that state on `accessChanged`, since the account
+may have left the list.
+
+**Theme.** On `init` and every `themeChanged` the SDK writes the documented tokens into one
+`<style>` element (`applyPluginTheme`) and sets `data-theme="light|dark"` on `<html>`. An
+iframe inherits none of the parent's custom properties, so this is the only way in. Pass
+`applyTheme: false` to theme the document yourself, or your own function to receive each
+theme.
+
+**End of session.** `sessionEnded` marks the context ended, fails pending refreshes with
+`session_ended`, drops listeners and stops listening: a late message from the old frame
+cannot restore a session. `dispose()` is the plugin's own cleanup and does the same locally.
+
+**What the shipped portal sends.** The contract allows more than the portal uses today
+(`frontend/src/app/features/plugins/plugin-page.component.ts`), so handle every value but
+expect these: `sessionEnded` arrives with reason `expired` (a renewal failed: the 12 h wall)
+or `unloaded` (the user left the page, reloaded the frame, or the entry vanished from
+discovery), never `signedOut` — signing out navigates away, which is `unloaded`.
+`accessChanged` always carries `entryAvailable: true`: when the entry itself is revoked or
+disabled the portal tears the frame down and shows its own "access ended" page instead.
+`init.user` has `subject`, `principalType: "user"` and `email` when known; `displayName` is
+never set. `createDevHost` (under Local development) is broader than the portal on all three
+points.
+
+## Host adapter
+
+`createPluginHost` (entry `/host`) is the portal side. It validates `event.source` against
+the iframe's window and `event.origin` against the expected origin, answers `ready` with
+`init` built from `initialState()` (read each time, so a reloaded frame starts current),
+forwards `sendSession`/`sendAccess`/`sendTheme`, coalesces
+`requestSessionRefresh` into one `refreshSession()` call and replies to each request id, and
+drops messages from a replaced instance. A `null`, rejecting or throwing renewal sends
+`sessionEnded(expired)` and ends the host. `onIncompatible` reports a frame on another protocol
+version (the portal shows its "built for a different version" page); `onHandshakeTimeout` fires when no `ready` arrives (0 disables) — it counts from when the
+host is created, which is before the frame's assets have loaded, so allow for that or pass 0 and
+time out yourself. `end(reason)` is terminal; `dispose()` sends `unloaded` from the host's own
+teardown. `onEnded` fires for every `end`/`dispose`, connected or not, so discriminate on `reason`.
+Message classification (`inspectPluginMessage`) lives in the contracts, shared with the plugin side.
+
+A renewal answers once, and only the frame that asked for it: a frame that reloads mid-renewal is
+not given the answer, and its failure does not end the session of the frame that replaced it.
+
+Both ends require an exact origin match. Plugins are same-origin by design, so do not render the
+frame with a `sandbox` attribute that omits `allow-same-origin` — the document's origin becomes
+`null`, every message is dropped, and the only symptom is a handshake timeout.
+
+**Trust model.** Because the plugin page is served from the portal's own origin, it runs with the
+signed-in user's full authority: it could read the portal's tokens from `localStorage`, call any
+core API as that user and script the parent document. The message protocol and `context.api`'s
+path pinning protect a well-behaved plugin from mistakes; they are not a sandbox. Installing a
+plugin means trusting its author and its dependencies as you trust the portal bundle. The portal
+enforces a Content-Security-Policy on `/plugin-assets/*` that lets a plugin page load from and talk
+to the portal only — no third-party scripts, no sending data to other hosts.
+
+## Local development
+
+`createDevHost` (entry `/fixtures`) drives a plugin through the real protocol with a fake
+identity and fixture tokens (`fixture-token-N`, accepted by no backend). Create it before
+setting the iframe's `src`:
+
+```ts
+import { createDevHost } from "@fntio/infra-client-plugin-sdk/fixtures";
+
+const frame = document.querySelector("iframe")!;
+const host = createDevHost({ frame, listenOn: window, origin: location.origin, entry: "admin", onEvent: console.log });
+frame.src = "/plugin/index.html#/admin";
+// scenarios: host.renewSession(), host.expireSession(), host.failNextRefresh(),
+// host.revoke(n), host.grant(a), host.setEntryAvailable(false),
+// host.setAppearance("dark"), host.signOut()
+```
+
+Its defaults differ from the shipped portal on purpose, so a plugin can be exercised against
+states the portal does not produce today: the user is `dev-user` with an `email` and a
+`displayName` (the portal sends no `displayName`), the accounts are the sample set, tokens
+live five minutes (`tokenLifetimeMs`), `setEntryAvailable(false)` sends an `accessChanged`
+the portal never sends, and `signOut()` ends with reason `signedOut`, which the portal never
+uses (see "What the shipped portal sends" under Browser SDK).
+
+The usual arrangement is one dev server for the plugin's own assets, with the portal's API
+proxied so `/api/plugins/<id>/...` reaches a real deployment:
+
+```js
+// vite.config.js, webpack devServer, or whatever this project already uses
+proxy: { "/api": { target: "https://portal.example.com", changeOrigin: true } }
+```
+
+Point `plugin.apiBaseUrl` at whatever your dev server proxies to a real deployment or a
+local backend. The fixture never bypasses production authentication: it exercises the
+protocol, the theme and the error paths offline, and anything touching a real API needs a
+real sign-in through the portal. For unit tests, `createFakeWindowPair` gives two windows
+wired like a page and its frame (browser semantics: `postMessage` on a window delivers to
+that window) and `createFakeThemeDocument` the slice of `document` the SDK themes.
+
+## Backend handlers
+
+A plugin route's Lambda receives the ordinary REST proxy event. The shared authorizer has
+already answered who and whether: it verified the token with the core's rules (ID token for
+humans, scoped access token plus a live registry row for service users), resolved the route
+from the catalog by method and resource template, took the account from the path, and asked
+the core's access resolver over strongly consistent reads. What it attached is scalar context,
+never a token.
+
+```ts
+import { createPluginLogger, pluginAuthorizerContextOf, pluginRoutePath } from "@fntio/infra-client-plugin-sdk/backend";
+
+export async function handler(event: APIGatewayProxyEvent) {
+  const ctx = pluginAuthorizerContextOf(event);        // throws if absent or malformed: never run without it
+  const log = createPluginLogger(ctx);                 // JSON lines carrying plugin, account, route, subject, correlation
+  const route = pluginRoutePath(event.path, ctx);      // "/parameters/db-url" for the registered path
+  log.info("listing", { route });
+  ...
+}
+```
+
+`ctx.accountNumber` is the account the platform authorized; a handler works in that account
+and no other. `ctx.requiredPermission` is the permission the route was registered with, not
+an assertion about anything else the caller holds. `rebasePluginEvent(event, ctx)` returns a
+copy whose `path` is account-relative, for an Express app mounted at `/` behind a proxy
+adapter. Business handlers answer domain 4xx codes, never 401: the browser SDK retries once
+after a 401 on the assumption that the authorizer, not the handler, produced it.
+
+Revocation limits: a check that begins after a revoke completed sees it (no cached decisions),
+a request already authorized finishes, and a job the plugin accepted runs until the plugin's
+own cancellation rules stop it.
+
+## Agent skills
+
+`skills/build-infra-client-plugin/` ships with this package. Point an agent at it and it will build a
+plugin in the conventions of the repository it is running in, reading this README for the API rather
+than carrying its own copy of it. The integration half — adding a finished plugin to a CDK application
+that already exists — is `skills/integrate-infra-client-plugin/` in
+`@fntio/infra-client-plugin-cdk`.
+
+Make them available the way your agent setup already does: most read a `skills/` directory inside
+`node_modules`, or you can copy the folder into your own skills location. There is no installer.
+
+## Versioning
+
+Three numbers move independently and are checked at runtime:
+
+| Number | Where | Bumps when |
+| --- | --- | --- |
+| `schemaVersion` | manifest, catalog record | the manifest shape changes incompatibly |
+| `hostApiVersion` | manifest | the host stops loading plugins built for an older contract |
+| `version` (protocol) | messages | the iframe message envelope or payloads change incompatibly |
+
+The protocol is at version 2 (`PLUGIN_PROTOCOL_VERSION`, SDK 0.2.0). Version 1 (SDK 0.1.x) had
+the portal track a selected account: `selectedAccount` in `init`/`contextChanged`/`accessChanged`
+and a `selectAccount` request. Version 2 removes all of it, so the two do not interoperate in
+either direction: a page built with SDK 0.1.x shows the portal's "built for a different version"
+state until it is rebuilt against 0.2.x, and a 0.2.x page in an older portal rejects with
+`incompatible_host`. `schemaVersion` and `hostApiVersion` are still 1.
+
+A frame also reports the SDK package version it was built with (`sdkVersion` in `ready`,
+surfaced by the host adapter's `onReady`). That number is informational; `protocolVersion`
+is the compatibility gate.
+
+The npm package follows semver. While it is `0.x`, an incompatible change bumps the
+minor version and one of the numbers above; a compatible addition bumps the patch
+version. The three plugin packages (`-sdk`, `-cdk`, `-ui`) release together at the
+same version.
+
+## Develop
+
+```
+cd packages/infra-client-plugin-sdk
+npx tsc --noEmit && npm test
+```
+
+Workspace installs run at the repository root (`npm install`), never here.
+`npm run build:plugins` at the root compiles `dist/` for all three plugin packages
+in dependency order; the CDK and UI packages type-check and test against this
+package's `src/` directly, so no build is needed for day-to-day checks.

package/dist/backend/context.d.ts

@@ -0,0 +1,31 @@
+import { PluginAuthorizerContextV1 } from "../contracts/authorizer";
+/** The slice of a REST proxy event a plugin handler needs; `APIGatewayProxyEvent` satisfies it. */
+export interface PluginProxyEventLike {
+    readonly path: string;
+    readonly httpMethod: string;
+    readonly requestContext: {
+        readonly authorizer?: unknown;
+        readonly requestId?: string;
+    } | null;
+}
+/** The context the shared authorizer attached. Throws when absent or malformed: a handler must never run
+ *  on a request the authorizer did not describe. */
+export declare function pluginAuthorizerContextOf(event: PluginProxyEventLike): PluginAuthorizerContextV1;
+/** The account-relative path a route was registered with: `/api/plugins/<id>/accounts/<acct>/x` → `/x`,
+ *  the account root → `/`. `null` when the path is not under this context's account root, which a handler
+ *  should treat as a bad request rather than guess. */
+export declare function pluginRoutePath(path: string, ctx: Pick<PluginAuthorizerContextV1, "pluginId" | "accountNumber">): string | null;
+/** A copy of the event whose `path` is the account-relative one, for an Express app mounted at `/` behind
+ *  a proxy adapter. Everything else, the authorizer context included, is left as it was. */
+export declare function rebasePluginEvent<E extends PluginProxyEventLike>(event: E, ctx: PluginAuthorizerContextV1): E;
+export type PluginLogLevel = "info" | "warn" | "error";
+export interface PluginLogger {
+    info(msg: string, extra?: Record<string, unknown>): void;
+    warn(msg: string, extra?: Record<string, unknown>): void;
+    error(msg: string, extra?: Record<string, unknown>): void;
+}
+/** JSON lines carrying the authorizer context (who, which plugin, which account, which route, correlation),
+ *  so a handler's own lines correlate with the platform's decision logs. The context always wins over the
+ *  caller's own fields, and top-level keys that look like secrets are redacted — but a secret nested inside
+ *  a value (an event, a header bag) is written as given: keeping those out is the plugin's own job. */
+export declare function createPluginLogger(ctx: PluginAuthorizerContextV1, sink?: (line: string) => void): PluginLogger;

package/dist/backend/context.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginAuthorizerContextOf = pluginAuthorizerContextOf;
+exports.pluginRoutePath = pluginRoutePath;
+exports.rebasePluginEvent = rebasePluginEvent;
+exports.createPluginLogger = createPluginLogger;
+const authorizer_1 = require("../contracts/authorizer");
+const paths_1 = require("../contracts/paths");
+/** The context the shared authorizer attached. Throws when absent or malformed: a handler must never run
+ *  on a request the authorizer did not describe. */
+function pluginAuthorizerContextOf(event) {
+    return (0, authorizer_1.parsePluginAuthorizerContext)(event.requestContext?.authorizer);
+}
+/** The account-relative path a route was registered with: `/api/plugins/<id>/accounts/<acct>/x` → `/x`,
+ *  the account root → `/`. `null` when the path is not under this context's account root, which a handler
+ *  should treat as a bad request rather than guess. */
+function pluginRoutePath(path, ctx) {
+    const root = (0, paths_1.pluginAccountPath)(ctx.pluginId, ctx.accountNumber);
+    if (path === root)
+        return "/";
+    if (!path.startsWith(`${root}/`))
+        return null;
+    return path.slice(root.length);
+}
+/** A copy of the event whose `path` is the account-relative one, for an Express app mounted at `/` behind
+ *  a proxy adapter. Everything else, the authorizer context included, is left as it was. */
+function rebasePluginEvent(event, ctx) {
+    const path = pluginRoutePath(event.path, ctx);
+    if (path === null)
+        throw new Error(`${event.path} is outside ${ctx.pluginId}/${ctx.accountNumber}`);
+    return { ...event, path };
+}
+const SENSITIVE = /token|authorization|secret|password|credential/i;
+/** JSON lines carrying the authorizer context (who, which plugin, which account, which route, correlation),
+ *  so a handler's own lines correlate with the platform's decision logs. The context always wins over the
+ *  caller's own fields, and top-level keys that look like secrets are redacted — but a secret nested inside
+ *  a value (an event, a header bag) is written as given: keeping those out is the plugin's own job. */
+function createPluginLogger(ctx, sink = (line) => console.log(line)) {
+    const base = {
+        pluginId: ctx.pluginId,
+        accountNumber: ctx.accountNumber,
+        routeId: ctx.routeId,
+        subject: ctx.subject,
+        principalType: ctx.principalType,
+        correlationId: ctx.correlationId,
+    };
+    const write = (level, msg, extra = {}) => {
+        const safe = {};
+        for (const [key, value] of Object.entries(extra))
+            safe[key] = SENSITIVE.test(key) ? "[redacted]" : value;
+        sink(JSON.stringify({ level, msg, ...safe, ...base }));
+    };
+    return {
+        info: (msg, extra) => write("info", msg, extra),
+        warn: (msg, extra) => write("warn", msg, extra),
+        error: (msg, extra) => write("error", msg, extra),
+    };
+}

package/dist/backend/index.d.ts

@@ -0,0 +1,9 @@
+export * from "../contracts/manifest";
+export * from "../contracts/validate";
+export * from "../contracts/canonical";
+export * from "../contracts/paths";
+export * from "../contracts/access";
+export * from "../contracts/catalog";
+export * from "../contracts/discovery";
+export * from "../contracts/authorizer";
+export * from "./context";

package/dist/backend/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Entry point for plugin Lambda handlers and the core backend. Must stay free of Angular imports.
+__exportStar(require("../contracts/manifest"), exports);
+__exportStar(require("../contracts/validate"), exports);
+__exportStar(require("../contracts/canonical"), exports);
+__exportStar(require("../contracts/paths"), exports);
+__exportStar(require("../contracts/access"), exports);
+__exportStar(require("../contracts/catalog"), exports);
+__exportStar(require("../contracts/discovery"), exports);
+__exportStar(require("../contracts/authorizer"), exports);
+__exportStar(require("./context"), exports);

package/dist/browser/client.d.ts

@@ -0,0 +1,59 @@
+import { PluginPermission } from "../contracts/manifest";
+import { HostToPluginMessageType, HostToPluginPayloads, PluginAccountContext, PluginEntryKind, PluginInfoContext, PluginToHostPayloads, PluginUserContext } from "../contracts/messages";
+import { PluginTheme } from "../contracts/theme";
+import { PluginMessageListenerTarget, PluginMessagePort } from "../contracts/transport";
+import { FetchLike, PluginApi, PluginTokenProvider } from "./http";
+export declare const PLUGIN_SDK_VERSION = "0.2.0";
+export declare const PLUGIN_REFRESH_TIMEOUT_MS = 15000;
+export declare const PLUGIN_REFRESH_LEAD_MS = 30000;
+export declare const PLUGIN_READY_INTERVAL_MS = 1000;
+export type PluginContextEvent = Exclude<HostToPluginMessageType, "init">;
+export type PluginContextListener<E extends PluginContextEvent> = (payload: HostToPluginPayloads[E]) => void;
+export type PluginContextState = "connected" | "ended";
+export interface PluginContext {
+    readonly instanceId: string;
+    readonly user: PluginUserContext;
+    readonly plugin: PluginInfoContext;
+    readonly entry: PluginEntryKind;
+    /** Bearer token access for callers bringing their own HTTP client. */
+    readonly session: PluginTokenProvider;
+    /** `fetch` helpers for the plugin's own API, relative to `plugin.apiBaseUrl`. */
+    readonly api: PluginApi;
+    state(): PluginContextState;
+    /** Every account the caller may use on this entry. Which one the plugin works in, if it has
+     *  the notion at all, is the plugin's own state. */
+    accounts(): readonly PluginAccountContext[];
+    /** Capabilities on one account; empty when it is not in `accounts()`. */
+    permissionsFor(accountNumber: string): readonly PluginPermission[];
+    hasPermission(permission: PluginPermission, accountNumber: string): boolean;
+    entryAvailable(): boolean;
+    theme(): PluginTheme;
+    /** Ask the host to refresh discovery. Sent automatically after a 403 unless disabled. */
+    requestAccessRefresh(reason?: PluginToHostPayloads["requestAccessRefresh"]["reason"]): void;
+    on<E extends PluginContextEvent>(event: E, listener: PluginContextListener<E>): () => void;
+    /** Stop listening and fail pending work. The host is not told; it unloads the frame itself. */
+    dispose(): void;
+}
+export interface ConnectOptions {
+    /** Defaults to `window.parent`. */
+    hostWindow?: PluginMessagePort;
+    /** Defaults to this document's origin: plugins are served from the portal's origin. */
+    hostOrigin?: string;
+    /** Defaults to `window`. */
+    listenOn?: PluginMessageListenerTarget;
+    /** Runs on `init` and every `themeChanged`. Default: `applyPluginTheme` on `document`; `false`
+     *  leaves the document alone for plugins that theme themselves. */
+    applyTheme?: false | ((theme: PluginTheme) => void);
+    fetch?: FetchLike;
+    /** 0 disables. */
+    handshakeTimeoutMs?: number;
+    /** 0 disables. */
+    refreshTimeoutMs?: number;
+    /** Renew in the background once the token expires within this window. */
+    refreshLeadMs?: number;
+    accessRefreshOnForbidden?: boolean;
+    instanceId?: string;
+}
+/** Announce to the host and resolve once `init` arrives. Rejects with `handshake_timeout` (call
+ *  again to retry), `incompatible_host`, `not_framed` or `invalid_options`. */
+export declare function connectToInfraClient(options?: ConnectOptions): Promise<PluginContext>;