@fntio/infra-client 0.0.0-stage → 0.5.0

package/dist/lib/network-validation.d.ts

@@ -0,0 +1,54 @@
+/** Synth-time site validation. A site routes by IP alone, so CIDR overlap
+ *  WITHIN a site is silently ambiguous; overlap ACROSS sites is the point. */
+import { ConnectorVpcConfig, DevSharesConfig, SiteConfig } from "./project-config";
+/** Deployment-ready `network.devShares` (defaults filled). */
+export interface ResolvedDevShares {
+    readonly enabled: boolean;
+    readonly maxDurationHours: number;
+    readonly allowGroupTargets: boolean;
+}
+/** A bad cap must fail synth — the API clamps silently, which would hide the typo until a user hit it. */
+export declare function resolveDevShares(cfg?: DevSharesConfig): ResolvedDevShares | undefined;
+export interface TailnetRangeOwner {
+    /** Where the ranges come from, for the error message. */
+    readonly label: string;
+    readonly cidrs: readonly string[];
+}
+/** One connector VPC as the deploy sees it — config's single-object form
+ *  normalized to a list per account, entries as written. */
+export type ResolvedConnectorVpc = ConnectorVpcConfig;
+/** Deployment-ready view of one configured site. */
+export interface ResolvedSite {
+    readonly id: string;
+    /** Human-facing name (config displayName; falls back to the id). */
+    readonly displayName: string;
+    /** `<id>.<subdomain>.<zoneName>` — the login hostname devices enroll to. */
+    readonly fqdn: string;
+    readonly controlUrl: string;
+    /** ALB rule priority: a STABLE hash of the id, never positional —
+     *  renumbering deployed rules fails with PriorityInUse. */
+    readonly priority: number;
+    readonly accounts: readonly string[];
+    readonly connectorAccounts: readonly string[];
+    readonly splitDns: Record<string, readonly string[]>;
+    readonly connectorVpcs: Record<string, readonly ResolvedConnectorVpc[]>;
+}
+/** FNV-1a of the id folded into 100–989 — depends on nothing but the id, so
+ *  a site keeps its priority for life. */
+export declare function sitePriority(id: string): number;
+/** Throws when ranges from DIFFERENT owners overlap; one owner's may nest
+ *  (same connector — not ambiguous). Callers scope this to ONE site. */
+export declare function assertDisjointTailnetRanges(owners: readonly TailnetRangeOwner[]): void;
+/** ≤15 chars: the longest derived Lambda name (per-site minter with a
+ *  20-char site id) must fit AWS's 64-char limit. */
+export declare function assertValidResourcePrefix(prefix: string): void;
+/** Validate `network.sites` → deployment-ready sites, sorted by id.
+ *  `extraRangesByAccount` injects ranges CDK only knows elsewhere (testbed). */
+export declare function resolveSites(network: {
+    readonly zoneName: string;
+    readonly subdomain: string;
+    readonly sites: Record<string, SiteConfig>;
+}, extraRangesByAccount?: Record<string, {
+    label: string;
+    cidrs: string[];
+}>): ResolvedSite[];

package/dist/lib/network-validation.js

@@ -0,0 +1,220 @@
+"use strict";
+/** Synth-time site validation. A site routes by IP alone, so CIDR overlap
+ *  WITHIN a site is silently ambiguous; overlap ACROSS sites is the point. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDevShares = resolveDevShares;
+exports.sitePriority = sitePriority;
+exports.assertDisjointTailnetRanges = assertDisjointTailnetRanges;
+exports.assertValidResourcePrefix = assertValidResourcePrefix;
+exports.resolveSites = resolveSites;
+const naming_1 = require("../lambdacode/network/naming");
+/** A bad cap must fail synth — the API clamps silently, which would hide the typo until a user hit it. */
+function resolveDevShares(cfg) {
+    if (!cfg)
+        return undefined;
+    const max = cfg.maxDurationHours ?? 8;
+    if (!Number.isInteger(max) || max < 1 || max > 72) {
+        throw new Error(`network.devShares.maxDurationHours must be an integer from 1 to 72 (got ${String(max)}).`);
+    }
+    return {
+        enabled: cfg.enabled === true,
+        maxDurationHours: max,
+        allowGroupTargets: cfg.allowGroupTargets !== false,
+    };
+}
+/** FNV-1a of the id folded into 100–989 — depends on nothing but the id, so
+ *  a site keeps its priority for life. */
+function sitePriority(id) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < id.length; i++) {
+        h ^= id.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return 100 + (h % 890);
+}
+/** Strict IPv4 "a.b.c.d/nn" with host bits zeroed. A typo must not synth. */
+function parseCidr(cidr, owner) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\/(\d{1,2})$/.exec(cidr);
+    if (!m) {
+        throw new Error(`${owner}: "${cidr}" is not an IPv4 CIDR (a.b.c.d/nn).`);
+    }
+    const octets = m.slice(1, 5).map(Number);
+    const prefix = Number(m[5]);
+    if (octets.some((o) => o > 255) || prefix > 32) {
+        throw new Error(`${owner}: "${cidr}" is not a valid IPv4 CIDR.`);
+    }
+    const ip = ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+    const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+    return { base: (ip & mask) >>> 0, prefix };
+}
+function overlaps(a, b) {
+    const shorter = Math.min(a.prefix, b.prefix);
+    const mask = shorter === 0 ? 0 : (~0 << (32 - shorter)) >>> 0;
+    return ((a.base & mask) >>> 0) === ((b.base & mask) >>> 0);
+}
+/** Throws when ranges from DIFFERENT owners overlap; one owner's may nest
+ *  (same connector — not ambiguous). Callers scope this to ONE site. */
+function assertDisjointTailnetRanges(owners) {
+    const flat = owners.flatMap((o) => o.cidrs.map((cidr) => ({ owner: o.label, cidr, ...parseCidr(cidr, o.label) })));
+    for (let i = 0; i < flat.length; i++) {
+        for (let j = i + 1; j < flat.length; j++) {
+            const a = flat[i];
+            const b = flat[j];
+            if (a.owner === b.owner)
+                continue;
+            if (overlaps(a, b)) {
+                throw new Error(`Tailnet CIDR overlap within one site: ${a.owner} (${a.cidr}) ` +
+                    `collides with ${b.owner} (${b.cidr}). A site routes by IP alone — ` +
+                    `traffic for the shared range would silently reach only one of ` +
+                    `them. Renumber one VPC, or move one of them to a different site.`);
+            }
+        }
+    }
+}
+/** ≤15 chars: the longest derived Lambda name (per-site minter with a
+ *  20-char site id) must fit AWS's 64-char limit. */
+function assertValidResourcePrefix(prefix) {
+    if (!/^[a-z][a-z0-9-]{0,14}$/.test(prefix)) {
+        throw new Error(`resourcePrefix "${prefix}" is invalid — lowercase slug, letter-first, ` +
+            `max 15 chars (longer would overflow Lambda's 64-char function-name ` +
+            `limit on per-site minters). It is SET-ONCE: never change it after ` +
+            `the first deploy.`);
+    }
+}
+const ACCOUNT_RE = /^\d{12}$/;
+const IPV4_RE = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/** AWS region names: eu-west-1, us-gov-west-1, ap-southeast-2. */
+const REGION_RE = /^[a-z]{2}(-[a-z]+)+-\d+$/;
+/** Validate `network.sites` → deployment-ready sites, sorted by id.
+ *  `extraRangesByAccount` injects ranges CDK only knows elsewhere (testbed). */
+function resolveSites(network, extraRangesByAccount = {}) {
+    const ids = Object.keys(network.sites);
+    if (ids.length === 0) {
+        throw new Error("network.sites must define at least one site.");
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(network.subdomain)) {
+        throw new Error(`network.subdomain "${network.subdomain}" must be a DNS label.`);
+    }
+    const accountToSite = new Map();
+    const priorityToSite = new Map();
+    const resolved = [];
+    for (const id of [...ids].sort()) {
+        if (!naming_1.SITE_ID_RE.test(id)) {
+            throw new Error(`Site id "${id}" is invalid — lowercase DNS label, letter-first, ` +
+                `max 20 chars. It becomes the permanent hostname <id>.` +
+                `${network.subdomain}.${network.zoneName}.`);
+        }
+        const site = network.sites[id];
+        if (!site.accounts.length) {
+            throw new Error(`Site "${id}" lists no accounts.`);
+        }
+        for (const account of site.accounts) {
+            if (!ACCOUNT_RE.test(account)) {
+                throw new Error(`Site "${id}": "${account}" is not a 12-digit account id.`);
+            }
+            const prior = accountToSite.get(account);
+            if (prior) {
+                throw new Error(`Account ${account} appears in sites "${prior}" AND "${id}" — an ` +
+                    `account belongs to exactly one site (its connector can only ` +
+                    `enroll into one control plane).`);
+            }
+            accountToSite.set(account, id);
+        }
+        const connectorVpcs = {};
+        for (const [account, entry] of Object.entries(site.connectorVpcs ?? {})) {
+            if (!site.accounts.includes(account)) {
+                throw new Error(`Site "${id}": connectorVpcs lists account ${account}, which is ` +
+                    `missing from the site's accounts list.`);
+            }
+            const where = `Site "${id}": connectorVpcs["${account}"]`;
+            const list = (Array.isArray(entry) ? entry : [entry]);
+            if (!list.length) {
+                throw new Error(`${where} is an empty list — give it at least one VPC or drop the key.`);
+            }
+            const names = new Set();
+            const vpcIds = new Set();
+            let unnamed = 0;
+            for (const vpc of list) {
+                if (vpc.name !== undefined)
+                    (0, naming_1.assertConnectorName)(vpc.name, where);
+                if (vpc.region !== undefined && !REGION_RE.test(vpc.region)) {
+                    throw new Error(`${where}.region "${vpc.region}" is not an AWS region name ` +
+                        `(e.g. eu-west-1). Omit it when the VPC is in the hub's region.`);
+                }
+                if (vpc.name === undefined) {
+                    if (++unnamed > 1) {
+                        throw new Error(`${where} lists more than one VPC without a name — every VPC ` +
+                            `of an account but one needs a name.`);
+                    }
+                }
+                else if (names.has(vpc.name)) {
+                    throw new Error(`${where} names two VPCs "${vpc.name}".`);
+                }
+                else {
+                    names.add(vpc.name);
+                }
+                if (vpcIds.has(vpc.vpcId)) {
+                    throw new Error(`${where} lists ${vpc.vpcId} twice.`);
+                }
+                vpcIds.add(vpc.vpcId);
+            }
+            connectorVpcs[account] = [...list];
+        }
+        // A minter grant must belong to an account of THIS site — a foreign one
+        // could enroll a connector into the wrong routing domain.
+        for (const principal of site.connectorAccounts ?? []) {
+            const arn = /^arn:aws:iam::(\d{12}):/.exec(principal);
+            const account = arn ? arn[1] : ACCOUNT_RE.test(principal) ? principal : null;
+            if (!account || !site.accounts.includes(account)) {
+                throw new Error(`Site "${id}": connectorAccounts entry "${principal}" must be a ` +
+                    `12-digit account id or role ARN belonging to one of the site's ` +
+                    `accounts.`);
+            }
+        }
+        for (const [domain, ips] of Object.entries(site.splitDns ?? {})) {
+            for (const ip of ips) {
+                const m = IPV4_RE.exec(ip);
+                if (!m || m.slice(1).some((o) => Number(o) > 255)) {
+                    throw new Error(`Site "${id}": splitDns["${domain}"] value "${ip}" must be a ` +
+                        `bare IPv4 address — anything else would freeze the site's ` +
+                        `ACL policy at runtime.`);
+                }
+            }
+        }
+        // The site invariant itself: no two VPCs inside it may overlap — an
+        // account's own VPCs included (each is its own owner).
+        const owners = Object.entries(connectorVpcs).flatMap(([account, list]) => list.map((c) => ({
+            label: `site "${id}" account ${account} (${c.vpcId})`,
+            cidrs: [...c.routes],
+        })));
+        for (const [account, extra] of Object.entries(extraRangesByAccount)) {
+            if (site.accounts.includes(account))
+                owners.push(extra);
+        }
+        assertDisjointTailnetRanges(owners);
+        const priority = site.albPriority ?? sitePriority(id);
+        if (!Number.isInteger(priority) || priority < 100 || priority > 989) {
+            throw new Error(`Site "${id}": albPriority must be an integer in 100–989.`);
+        }
+        const holder = priorityToSite.get(priority);
+        if (holder) {
+            throw new Error(`Sites "${holder}" and "${id}" hash to the same ALB rule priority ` +
+                `(${priority}) — set albPriority on the NEW site (never renumber ` +
+                `a deployed one).`);
+        }
+        priorityToSite.set(priority, id);
+        const fqdn = `${id}.${network.subdomain}.${network.zoneName}`;
+        resolved.push({
+            id,
+            displayName: site.displayName ?? id,
+            fqdn,
+            controlUrl: `https://${fqdn}`,
+            priority,
+            accounts: site.accounts,
+            connectorAccounts: site.connectorAccounts ?? [],
+            splitDns: site.splitDns ?? {},
+            connectorVpcs,
+        });
+    }
+    return resolved;
+}

package/dist/lib/pkg-paths.d.ts

@@ -0,0 +1,3 @@
+/** The package root — correct from lib/ (repo TS) and dist/lib/ (compiled in
+ *  a consumer's node_modules): nearest ancestor with a package.json. */
+export declare function packageRoot(): string;

package/dist/lib/pkg-paths.js

@@ -0,0 +1,51 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageRoot = packageRoot;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** The package root — correct from lib/ (repo TS) and dist/lib/ (compiled in
+ *  a consumer's node_modules): nearest ancestor with a package.json. */
+function packageRoot() {
+    let dir = __dirname;
+    while (!fs.existsSync(path.join(dir, "package.json"))) {
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`No package.json found above ${__dirname}`);
+        }
+        dir = parent;
+    }
+    return dir;
+}

package/dist/lib/plugins/plugin-api.d.ts

@@ -0,0 +1,40 @@
+import * as cdk from "aws-cdk-lib";
+import * as apigw from "aws-cdk-lib/aws-apigateway";
+import type * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { Construct } from "constructs";
+import { AppFunction } from "../constructs/app-function";
+import { ResolvedPlugin } from "./registration";
+import { PluginRuntimeTables } from "./runtime";
+import { AuditLogTarget } from "../audit-log";
+/** What the shared authorizer reads: who (the pool, the service-user registry), whether (Access rows), and
+ *  what (the catalog and the accounts it binds — `PluginRuntimeTables`). Read-only on every table. */
+export interface PluginAuthorizerRuntime extends PluginRuntimeTables {
+    readonly userPoolId: string;
+    readonly accessTable: dynamodb.ITable;
+    readonly serviceUsersTable: dynamodb.ITable;
+}
+export interface PluginApiProps {
+    readonly api: apigw.RestApi;
+    /** The Express handler: every non-plugin /api/* path, and /api/plugins itself (discovery) plus its unknown
+     *  sub-paths (its JSON 404), stay on it. */
+    readonly coreHandler: lambda.IFunction;
+    readonly plugins: readonly ResolvedPlugin[];
+    readonly runtime: PluginAuthorizerRuntime;
+    /** Where the authorizer records refused calls; absent = refusals are log lines only. */
+    readonly auditLog?: AuditLogTarget;
+}
+/** Plugin routes on the core REST API. Explicit resources under /api stop the root {proxy+} from covering
+ *  /api/…, so the core keeps /api, /api/{proxy+}, ANY /api/plugins and /api/plugins/{proxy+} explicitly — created as soon as the
+ *  feature is on, even with no plugin, so the routing change is deployed and verified on its own first.
+ *  Each plugin's resource sets the shared REQUEST authorizer (result cache 0) as the default method option,
+ *  so everything under /api/plugins/<id> is authorized by construction. */
+export declare class PluginApi extends Construct {
+    /** Present when at least one plugin has routes (an unattached authorizer fails synth). */
+    readonly authorizer: apigw.RequestAuthorizer | undefined;
+    readonly authorizerFunction: AppFunction | undefined;
+    /** Plugin id → its methods; the catalog activation orders itself after (and, on delete, before) them. */
+    readonly methodsByPlugin: Map<string, cdk.aws_apigateway.Method[]>;
+    get methods(): apigw.Method[];
+    constructor(scope: Construct, id: string, props: PluginApiProps);
+}

package/dist/lib/plugins/plugin-api.js

@@ -0,0 +1,125 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginApi = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const apigw = __importStar(require("aws-cdk-lib/aws-apigateway"));
+const constructs_1 = require("constructs");
+const app_function_1 = require("../constructs/app-function");
+const runtime_1 = require("./runtime");
+const audit_log_1 = require("../audit-log");
+/** Plugin routes on the core REST API. Explicit resources under /api stop the root {proxy+} from covering
+ *  /api/…, so the core keeps /api, /api/{proxy+}, ANY /api/plugins and /api/plugins/{proxy+} explicitly — created as soon as the
+ *  feature is on, even with no plugin, so the routing change is deployed and verified on its own first.
+ *  Each plugin's resource sets the shared REQUEST authorizer (result cache 0) as the default method option,
+ *  so everything under /api/plugins/<id> is authorized by construction. */
+class PluginApi extends constructs_1.Construct {
+    /** Present when at least one plugin has routes (an unattached authorizer fails synth). */
+    authorizer;
+    authorizerFunction;
+    /** Plugin id → its methods; the catalog activation orders itself after (and, on delete, before) them. */
+    methodsByPlugin = new Map();
+    get methods() {
+        return [...this.methodsByPlugin.values()].flat();
+    }
+    constructor(scope, id, props) {
+        super(scope, id);
+        const core = new apigw.LambdaIntegration(props.coreHandler);
+        const apiRoot = props.api.root.addResource("api");
+        apiRoot.addMethod("ANY", core);
+        apiRoot.addProxy({ defaultIntegration: core, anyMethod: true });
+        // Express owns every verb on /api/plugins and every path under it that no registered method claims — an
+        // unknown plugin id, and an unmatched path under a registered one, both fall through to this greedy proxy
+        // and get the app's JSON 404. Verified live: no plugin handler is reachable except through its own
+        // registered method, which is the property that matters.
+        const pluginsRoot = apiRoot.addResource("plugins");
+        pluginsRoot.addMethod("ANY", core);
+        pluginsRoot.addProxy({ defaultIntegration: core, anyMethod: true });
+        if (props.plugins.some((p) => p.routes.length > 0)) {
+            const { runtime } = props;
+            this.authorizerFunction = new app_function_1.AppFunction(this, "AuthorizerFn", {
+                description: "Authorizes plugin API calls: checks the portal sign-in token and the caller's plugin permission.",
+                asset: "plugin-authorizer",
+                timeout: cdk.Duration.seconds(10),
+                environment: {
+                    NODE_ENV: "production",
+                    USER_POOL_ID: runtime.userPoolId,
+                    ACCESS_TABLE_NAME: runtime.accessTable.tableName,
+                    SERVICE_USERS_TABLE_NAME: runtime.serviceUsersTable.tableName,
+                    ...(0, runtime_1.pluginRuntimeEnv)(runtime),
+                    ...(props.auditLog ? (0, audit_log_1.auditLogEnv)(props.auditLog) : {}),
+                },
+            });
+            runtime.accessTable.grantReadData(this.authorizerFunction);
+            runtime.serviceUsersTable.grantReadData(this.authorizerFunction);
+            (0, runtime_1.grantPluginRuntimeRead)(this.authorizerFunction, runtime);
+            if (props.auditLog)
+                (0, audit_log_1.grantAuditLogWrite)(this.authorizerFunction, props.auditLog);
+            this.authorizer = new apigw.RequestAuthorizer(this, "Authorizer", {
+                handler: this.authorizerFunction,
+                identitySources: [apigw.IdentitySource.header("Authorization")],
+                // Decisions are never cached: a completed revoke must bite on the next request.
+                resultsCacheTtl: cdk.Duration.seconds(0),
+            });
+        }
+        for (const plugin of props.plugins) {
+            if (!plugin.routes.length)
+                continue; // UI-only: nothing to mount
+            const pluginScope = new constructs_1.Construct(this, `Plugin-${plugin.manifest.id}`);
+            const handlers = new Map();
+            for (const [key, source] of Object.entries(plugin.handlers)) {
+                handlers.set(key, typeof source === "function" ? source(pluginScope) : source);
+            }
+            const accountRoot = pluginsRoot
+                .addResource(plugin.manifest.id, {
+                defaultMethodOptions: { authorizer: this.authorizer, authorizationType: apigw.AuthorizationType.CUSTOM },
+            })
+                .addResource("accounts")
+                .addResource("{accountNumber}");
+            const methods = plugin.routes.map((route) => {
+                // "/" is the account root itself; resourceForPath creates each segment once.
+                const resource = accountRoot.resourceForPath(route.path.replace(/^\/+/, ""));
+                // The authorizer matches this template against the one the catalog stores. Nothing else ties
+                // the two spellings together, so a drift is caught here rather than as a 403 on every call.
+                if (resource.path !== route.resourcePath) {
+                    throw new Error(`plugin ${plugin.manifest.id} route ${route.id} mounts at ${resource.path}, but the catalog records ${route.resourcePath}`);
+                }
+                return resource.addMethod(route.method, new apigw.LambdaIntegration(handlers.get(route.handlerKey)));
+            });
+            this.methodsByPlugin.set(plugin.manifest.id, methods);
+        }
+    }
+}
+exports.PluginApi = PluginApi;

package/dist/lib/plugins/plugin-catalog-activation.d.ts

@@ -0,0 +1,31 @@
+import * as cdk from "aws-cdk-lib";
+import * as apigw from "aws-cdk-lib/aws-apigateway";
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import { Construct } from "constructs";
+import { ResolvedPlugin } from "./registration";
+import { AuditLogTarget } from "../audit-log";
+export interface PluginCatalogActivationProps {
+    readonly plugins: readonly ResolvedPlugin[];
+    /** The plugin-assets bucket (DataStack); uploads land under `<id>/<version>-<hash>/`, never pruned. */
+    readonly assetsBucket: s3.IBucket;
+    readonly pluginCatalogTable: dynamodb.ITable;
+    readonly accessTable: dynamodb.ITable;
+    readonly accountsTable: dynamodb.ITable;
+    readonly revocationsTable: dynamodb.ITable;
+    /** Where the provider records catalog activations and tombstones; absent = log lines only. */
+    readonly auditLog?: AuditLogTarget;
+    /** The core API stage and each plugin's methods: a record is written after the routes exist and, on
+     *  removal, tombstoned BEFORE they go (CloudFormation deletes dependents first). */
+    readonly apiStage: apigw.IStage;
+    readonly methodsByPlugin: ReadonlyMap<string, readonly apigw.Method[]>;
+    /** Who owns the records (the CloudFormation stack id — stable across renames of constructs); a second
+     *  deployment claiming a plugin id is a deploy error. */
+    readonly owner: string;
+}
+/** Uploads each plugin's UI and writes its catalog record (Custom::PluginCatalogRecord) after the asset upload,
+ *  the API stage and the plugin's methods. Delete tombstones the record; the provider raises loss notices. */
+export declare class PluginCatalogActivation extends Construct {
+    readonly records: cdk.CustomResource[];
+    constructor(scope: Construct, id: string, props: PluginCatalogActivationProps);
+}

package/dist/lib/plugins/plugin-catalog-activation.js

@@ -0,0 +1,109 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginCatalogActivation = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const s3deploy = __importStar(require("aws-cdk-lib/aws-s3-deployment"));
+const cr = __importStar(require("aws-cdk-lib/custom-resources"));
+const constructs_1 = require("constructs");
+const app_function_1 = require("../constructs/app-function");
+const runtime_1 = require("./runtime");
+const audit_log_1 = require("../audit-log");
+/** Uploads each plugin's UI and writes its catalog record (Custom::PluginCatalogRecord) after the asset upload,
+ *  the API stage and the plugin's methods. Delete tombstones the record; the provider raises loss notices. */
+class PluginCatalogActivation extends constructs_1.Construct {
+    records = [];
+    constructor(scope, id, props) {
+        super(scope, id);
+        const providerFn = new app_function_1.AppFunction(this, "CatalogFn", {
+            description: "Deploy-time helper: writes each plugin's record into the plugin catalog.",
+            asset: "plugin-catalog",
+            // Delete/Update diff every holder's access before and after (sequential reads); generous on purpose.
+            timeout: cdk.Duration.minutes(5),
+            environment: {
+                ...(0, runtime_1.pluginRuntimeEnv)({ catalogTable: props.pluginCatalogTable, accountsTable: props.accountsTable }),
+                ACCESS_TABLE_NAME: props.accessTable.tableName,
+                REVOCATIONS_TABLE_NAME: props.revocationsTable.tableName,
+                ...(props.auditLog ? (0, audit_log_1.auditLogEnv)(props.auditLog) : {}),
+                NODE_ENV: "production",
+            },
+        });
+        if (props.auditLog)
+            (0, audit_log_1.grantAuditLogWrite)(providerFn, props.auditLog);
+        props.pluginCatalogTable.grantReadWriteData(providerFn);
+        props.accountsTable.grantReadData(providerFn);
+        props.accessTable.grantReadData(providerFn);
+        props.revocationsTable.grantReadWriteData(providerFn);
+        const provider = new cr.Provider(this, "CatalogProvider", { onEventHandler: providerFn });
+        for (const plugin of props.plugins) {
+            const { manifest } = plugin;
+            let assets;
+            if (plugin.assetDirectory && plugin.assetPrefix) {
+                assets = new s3deploy.BucketDeployment(this, `Assets-${manifest.id}`, {
+                    sources: [s3deploy.Source.asset(plugin.assetDirectory)],
+                    destinationBucket: props.assetsBucket,
+                    // The key must equal the URL path: the CloudFront behavior matches /plugin-assets/* and forwards
+                    // the whole path to this bucket, so an object stored without that prefix answers 403.
+                    destinationKeyPrefix: plugin.assetPrefix.replace(/^\//, ""),
+                    // Earlier revisions stay for open sessions and rollback (no GC in v1).
+                    prune: false,
+                    // The prefix carries the content hash, so a revision's bytes never change under their URL.
+                    cacheControl: [s3deploy.CacheControl.maxAge(cdk.Duration.days(365)), s3deploy.CacheControl.immutable()],
+                });
+            }
+            const record = new cdk.CustomResource(this, `Catalog-${manifest.id}`, {
+                serviceToken: provider.serviceToken,
+                resourceType: "Custom::PluginCatalogRecord",
+                properties: {
+                    PluginId: manifest.id,
+                    Owner: props.owner,
+                    Revision: plugin.revision,
+                    Manifest: JSON.stringify(manifest),
+                    Ui: JSON.stringify(plugin.ui ?? {}),
+                    Routes: JSON.stringify(plugin.routes),
+                    AssetPrefix: plugin.assetPrefix ?? "",
+                    SchemaVersion: "1",
+                },
+            });
+            if (assets)
+                record.node.addDependency(assets);
+            record.node.addDependency(props.apiStage);
+            for (const method of props.methodsByPlugin.get(manifest.id) ?? [])
+                record.node.addDependency(method);
+            this.records.push(record);
+        }
+    }
+}
+exports.PluginCatalogActivation = PluginCatalogActivation;