@fntio/infra-client 0.0.0-stage → 0.5.0

package/dist/lib/plugins/registration.d.ts

@@ -0,0 +1,41 @@
+import type * as lambda from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import { PluginCatalogRouteV1, PluginCatalogUiEntryV1, PluginManifestV1 } from "@fntio/infra-client-plugin-sdk";
+import type { PluginsConfig } from "../project-config";
+export type PluginHandlerSource = lambda.IFunction | ((scope: Construct) => lambda.IFunction);
+/** What a deployment registers: the shape `definePlugin` (@fntio/infra-client-plugin-cdk) returns. */
+export interface PluginRegistration {
+    readonly manifest: PluginManifestV1;
+    /** Built frontend directory; required when the manifest has UI entries. */
+    readonly assetDirectory?: string;
+    /** Keyed by the `handlerKey` routes name; factories run once, inside the routes construct. */
+    readonly handlers: Readonly<Record<string, PluginHandlerSource>>;
+}
+/** A registration plus everything the stacks derive from it. */
+export interface ResolvedPlugin {
+    readonly manifest: PluginManifestV1;
+    readonly assetDirectory?: string;
+    readonly assetHash?: string;
+    /** `/plugin-assets/<id>/<version>-<hash>` — changed bytes never reuse a URL. */
+    readonly assetPrefix?: string;
+    readonly handlers: Readonly<Record<string, PluginHandlerSource>>;
+    readonly ui?: {
+        readonly user?: PluginCatalogUiEntryV1;
+        readonly admin?: PluginCatalogUiEntryV1;
+    };
+    readonly routes: readonly PluginCatalogRouteV1[];
+    /** Content digest of permission/route metadata + the asset hash. */
+    readonly revision: string;
+}
+/** The feature, on: absent from every stack prop when it is off (like `network` / `devShares`). */
+export interface ResolvedPlugins {
+    readonly discoveryRefreshSeconds: number;
+    readonly plugins: readonly ResolvedPlugin[];
+}
+/** Synth-time validation of the feature block + registrations; undefined when the feature is off.
+ *  Registrations without the feature are an error, never a silent no-op. */
+export declare function resolvePlugins(config: PluginsConfig | undefined, registrations?: readonly PluginRegistration[]): ResolvedPlugins | undefined;
+export declare function resolvePlugin(registration: PluginRegistration): ResolvedPlugin;
+/** Deterministic content hash of a directory (CDK's own asset fingerprint), 16 hex chars. */
+export declare function hashDirectory(dir: string): string;
+export declare function pluginRevision(manifest: PluginManifestV1, assetHash?: string): string;

package/dist/lib/plugins/registration.js

@@ -0,0 +1,121 @@
+"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.resolvePlugins = resolvePlugins;
+exports.resolvePlugin = resolvePlugin;
+exports.hashDirectory = hashDirectory;
+exports.pluginRevision = pluginRevision;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const infra_client_plugin_sdk_1 = require("@fntio/infra-client-plugin-sdk");
+/** Synth-time validation of the feature block + registrations; undefined when the feature is off.
+ *  Registrations without the feature are an error, never a silent no-op. */
+function resolvePlugins(config, registrations = []) {
+    if (!config?.enabled) {
+        if (registrations.length) {
+            throw new Error(`plugins: ${registrations.length} plugin registration(s) supplied but project.plugins.enabled is not true — ` +
+                "enable the feature or drop the registrations.");
+        }
+        return undefined;
+    }
+    const refresh = config?.discoveryRefreshSeconds ?? infra_client_plugin_sdk_1.PLUGIN_DISCOVERY_DEFAULT_REFRESH_SECONDS;
+    if (!Number.isInteger(refresh) ||
+        refresh < infra_client_plugin_sdk_1.PLUGIN_DISCOVERY_MIN_REFRESH_SECONDS ||
+        refresh > infra_client_plugin_sdk_1.PLUGIN_DISCOVERY_MAX_REFRESH_SECONDS) {
+        throw new Error(`plugins.discoveryRefreshSeconds must be an integer between ${infra_client_plugin_sdk_1.PLUGIN_DISCOVERY_MIN_REFRESH_SECONDS} and ${infra_client_plugin_sdk_1.PLUGIN_DISCOVERY_MAX_REFRESH_SECONDS} (got ${String(refresh)}).`);
+    }
+    const seen = new Set();
+    const plugins = registrations.map((r) => {
+        const resolved = resolvePlugin(r);
+        if (seen.has(resolved.manifest.id))
+            throw new Error(`plugins: plugin id "${resolved.manifest.id}" is registered twice.`);
+        seen.add(resolved.manifest.id);
+        return resolved;
+    });
+    return { discoveryRefreshSeconds: refresh, plugins };
+}
+function resolvePlugin(registration) {
+    const result = (0, infra_client_plugin_sdk_1.validatePluginManifest)(registration.manifest, { handlerKeys: Object.keys(registration.handlers) });
+    if (!result.ok)
+        throw new infra_client_plugin_sdk_1.PluginValidationError(result.issues, `Plugin "${String(registration.manifest?.id ?? "?")}"`);
+    const manifest = result.manifest;
+    let assetHash;
+    let assetPrefix;
+    let ui;
+    if (manifest.ui) {
+        const dir = registration.assetDirectory;
+        if (!dir || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+            throw new Error(`Plugin "${manifest.id}": UI entries need an asset directory (got ${dir ?? "none"}).`);
+        }
+        for (const kind of ["user", "admin"]) {
+            const entry = manifest.ui[kind];
+            if (entry && !fs.existsSync(path.join(dir, (0, infra_client_plugin_sdk_1.pluginEntryFile)(entry.entry)))) {
+                throw new Error(`Plugin "${manifest.id}": ui.${kind}.entry "${entry.entry}" not found under ${dir}.`);
+            }
+        }
+        assetHash = hashDirectory(dir);
+        assetPrefix = (0, infra_client_plugin_sdk_1.pluginAssetPrefix)(manifest.id, manifest.version, assetHash);
+        const resolve = (entry) => entry && {
+            label: entry.label,
+            ...(entry.icon ? { icon: entry.icon } : {}),
+            ...(entry.order !== undefined ? { order: entry.order } : {}),
+            url: (0, infra_client_plugin_sdk_1.pluginUiUrl)(assetPrefix, entry.entry),
+        };
+        ui = {
+            ...(manifest.ui.user ? { user: resolve(manifest.ui.user) } : {}),
+            ...(manifest.ui.admin ? { admin: resolve(manifest.ui.admin) } : {}),
+        };
+    }
+    const routes = manifest.routes.map((route) => ({ ...route, resourcePath: (0, infra_client_plugin_sdk_1.pluginRouteResourcePath)(manifest.id, route.path) }));
+    return {
+        manifest,
+        assetDirectory: registration.assetDirectory,
+        assetHash,
+        assetPrefix,
+        handlers: registration.handlers,
+        ui,
+        routes,
+        revision: pluginRevision(manifest, assetHash),
+    };
+}
+/** Deterministic content hash of a directory (CDK's own asset fingerprint), 16 hex chars. */
+function hashDirectory(dir) {
+    return cdk.FileSystem.fingerprint(dir).slice(0, 16);
+}
+function pluginRevision(manifest, assetHash) {
+    return crypto.createHash("sha256").update((0, infra_client_plugin_sdk_1.canonicalJson)({ manifest, assetHash: assetHash ?? null })).digest("hex").slice(0, 16);
+}

package/dist/lib/plugins/runtime.d.ts

@@ -0,0 +1,10 @@
+import type * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import type * as iam from "aws-cdk-lib/aws-iam";
+export interface PluginRuntimeTables {
+    readonly catalogTable: dynamodb.ITable;
+    readonly accountsTable: dynamodb.ITable;
+}
+/** Env for any Lambda that READS the plugin catalog. The catalog implies the accounts catalog (binding
+ *  availability — pluginAccess.registeredAccounts throws without it), so the two always travel together. */
+export declare function pluginRuntimeEnv(tables: PluginRuntimeTables, discoveryRefreshSeconds?: number): Record<string, string>;
+export declare function grantPluginRuntimeRead(grantee: iam.IGrantable, tables: PluginRuntimeTables): void;

package/dist/lib/plugins/runtime.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginRuntimeEnv = pluginRuntimeEnv;
+exports.grantPluginRuntimeRead = grantPluginRuntimeRead;
+/** Env for any Lambda that READS the plugin catalog. The catalog implies the accounts catalog (binding
+ *  availability — pluginAccess.registeredAccounts throws without it), so the two always travel together. */
+function pluginRuntimeEnv(tables, discoveryRefreshSeconds) {
+    return {
+        PLUGIN_CATALOG_TABLE_NAME: tables.catalogTable.tableName,
+        ACCOUNTS_TABLE_NAME: tables.accountsTable.tableName,
+        ...(discoveryRefreshSeconds === undefined ? {} : { PLUGIN_DISCOVERY_REFRESH_SECONDS: String(discoveryRefreshSeconds) }),
+    };
+}
+function grantPluginRuntimeRead(grantee, tables) {
+    tables.catalogTable.grantReadData(grantee);
+    tables.accountsTable.grantReadData(grantee);
+}

package/dist/lib/project-config.d.ts

@@ -0,0 +1,164 @@
+import { FirstAdminConfig, LoginMethods } from "./creds-stack";
+import { EmailConfig } from "./data-stack";
+import { WebBranding, WebDomains } from "./web-stack";
+import { TargetRoleSpec } from "./constructs/web-identity";
+import { WafConfig } from "./constructs/web-acl";
+import { AuditConfig } from "./audit-log";
+/** All per-project configuration for one deployment. */
+export interface ProjectConfig {
+    readonly projectName: string;
+    /** The hub account + region. Explicit: nothing may depend on which
+     *  credentials run the synth (that ambiguity has faked a CIDR collision). */
+    readonly env: {
+        readonly account: string;
+        readonly region: string;
+    };
+    /** true = production hardening: tables (+ PITR, deletion protection), the
+     *  user pool, and the issuer signing keys all RETAIN on teardown; every hub
+     *  stack gets termination protection and the VPN load balancer deletion
+     *  protection — a teardown disables both first (runbook "Tear down"). */
+    readonly prod: boolean;
+    /** Ops alert recipient(s) — one address or a list; each gets its own SNS
+     *  subscription. AWS emails every address a confirmation on first deploy —
+     *  click it or that address gets nothing. The first one is the default
+     *  `email.dmarcReportEmail`. */
+    readonly alertEmail: string | readonly string[];
+    /** SET ONCE before the first deploy — every cross-account by-name contract
+     *  derives from it; renaming breaks them all. ≤15 chars. Default "infra-client". */
+    readonly resourcePrefix?: string;
+    /** `https://<domainName>` is baked into every target account's trust —
+     *  NEVER change it once deployed; host drift breaks vending everywhere. */
+    readonly issuer: {
+        readonly hostedZoneId: string;
+        readonly zoneName: string;
+        readonly domainName: string;
+        /** All listed versions publish in the JWKS; `signerVersion` signs. Omit
+         *  both on day one. Rotation: wiki Runbooks, "Signing-key rotation". */
+        readonly keyVersions?: number[];
+        readonly signerVersion?: number;
+    };
+    readonly loginMethods: LoginMethods;
+    /** First admin, created (idempotently, never deleted) by the deploy —
+     *  behavior + failure modes: wiki Runbooks, "First admin". */
+    readonly firstAdmin?: FirstAdminConfig;
+    /** Cognito email via SES from this domain (DKIM/SPF/DMARC). Omit = the
+     *  built-in sender (~50/day, spam-prone). Runbook: "Email deliverability". */
+    readonly email?: EmailConfig;
+    /** App on `domainName`, sign-in on `authDomainName` — must be a child of
+     *  domainName (Cognito needs the parent to resolve). Runbook: "Custom web domain". */
+    readonly web?: WebDomains;
+    /** WAF on CloudFront + the API — ON by default (~$26/month). Turning it
+     *  off later leaves an orphan to delete by hand. Runbook: "Security posture". */
+    readonly waf?: WafConfig;
+    /** The activity log (Activity page): retention of every recorded action. Omit = 400 days.
+     *  Wiki: Admin Guide, "Activity". */
+    readonly audit?: AuditConfig;
+    /** Customer plugins: independently built UIs + Lambda routes registered from this CDK app. Off or absent =
+     *  no plugin runtime is created and every plugin grant row stays dormant. Registrations passed to
+     *  `addAccessPortal` while this is off fail at synth. Package README "Plugins". */
+    readonly plugins?: PluginsConfig;
+    /** Account dimensions — tenant / project / stage read off each account's name at registration
+     *  (`<tenant>-<project>-<stage>`), filterable on every account list and the group editor. Omit = no
+     *  dimensions anywhere, which is what every deployment had before. Wiki: Admin Guide, "Dimensions". */
+    readonly accountDimensions?: AccountDimensionsConfig;
+    /** Web app look — logo + colors (project name comes from `projectName`). */
+    readonly branding: Omit<WebBranding, "projectName">;
+    /** MUST match the DynamoDB Roles catalog — roles live cross-account, so
+     *  CDK can't verify them at synth. */
+    readonly rolesByAccount: Record<string, TargetRoleSpec[]>;
+    /** Per-site Headscale control planes; omit to skip NetworkStack. A site =
+     *  ONE routing domain; only manual step: deleting a removed site's secret. */
+    readonly network?: {
+        readonly hostedZoneId: string;
+        readonly zoneName: string;
+        /** Sites live at `<site>.<subdomain>.<zoneName>` behind ONE wildcard
+         *  cert + DNS record — adding a site changes neither. */
+        readonly subdomain: string;
+        /** Keyed by site id — IMMUTABLE once anything enrolls (it is the login
+         *  hostname of every device and connector). */
+        readonly sites: Record<string, SiteConfig>;
+        /** CloudWatch Container Insights on the control-plane cluster (Security
+         *  Hub ECS.12): per-metric cost, a few dollars a month. Default: `prod`. */
+        readonly containerInsights?: boolean;
+        /** Run the control servers from a copy of the Headscale image in the hub's own registry, made at
+         *  deploy, so a task restart never depends on the public registry being up. Turning it on (or off)
+         *  restarts each control server once; needs `cdk-ecr-deployment` installed in the deployment project.
+         *  Connector stacks take the same switch as a prop. Default false. */
+        readonly mirrorImages?: boolean;
+        /** Dev shares: a user shares one local port on their laptop with named users/groups on
+         *  the same site for a bounded time (desktop app runs `tailscale serve`). Off unless
+         *  `enabled`. Runbook: the wiki's Private Network page, "Dev shares". */
+        readonly devShares?: DevSharesConfig;
+    };
+}
+/** `plugins` — validated at synth (lib/plugins/registration.ts resolvePlugins). */
+export interface PluginsConfig {
+    readonly enabled: boolean;
+    /** How often a signed-in portal re-reads plugin discovery, in seconds (15–300). Default 60. */
+    readonly discoveryRefreshSeconds?: number;
+}
+/** What a stage value means to the UI — the role card's silhouette (prod / staging / dev / sandbox). */
+export type StageKind = "prod" | "staging" | "dev" | "sandbox";
+/** `accountDimensions` — validated at synth (dimensions-validation.ts resolveAccountDimensions). The naming
+ *  rule is fixed: first hyphen-separated segment = tenant, last = stage, the rest (which may contain hyphens)
+ *  = project; `acme-prod` has no project; a name without a hyphen gets no dimensions ("unclassified"). Values
+ *  are stored on the catalog row when the account is registered and are edited by an admin afterwards —
+ *  renaming an account never re-derives them. They filter lists; they never decide access. */
+export interface AccountDimensionsConfig {
+    readonly enabled: boolean;
+    /** What the UI calls each dimension (1–30 characters). Default "Tenant" / "Project" / "Stage". */
+    readonly labels?: {
+        readonly tenant?: string;
+        readonly project?: string;
+        readonly stage?: string;
+    };
+    /** Stage value (as it appears in names, lower-case letters/digits) → silhouette, on top of the built-in
+     *  map (prod/live → prod, staging/test/qa/uat → staging, dev → dev, sandbox → sandbox). */
+    readonly stages?: Readonly<Record<string, StageKind>>;
+}
+/** `network.devShares` — validated at synth (network-validation.ts resolveDevShares). */
+export interface DevSharesConfig {
+    readonly enabled: boolean;
+    /** Longest share a user may create, in hours (1–72). Default 8. */
+    readonly maxDurationHours?: number;
+    /** Whether a share may target a group (every member reaches it). Default true. */
+    readonly allowGroupTargets?: boolean;
+}
+/** One VPC joined via ConnectorStack. */
+export interface ConnectorVpcConfig {
+    readonly vpcId: string;
+    /** CIDRs to advertise — usually just the VPC's CIDR. */
+    readonly routes: readonly string[];
+    /** Only when the VPC is outside the hub's region. */
+    readonly region?: string;
+    /** Tells this VPC from the account's others: letters and digits, letter-first, at
+     *  most 10; unique per account, and at most one entry per account goes unnamed.
+     *  Becomes the connector's hostname suffix (`connector-<account>-<name>`) and the
+     *  suffix of its SG-manager and resolver function names — set once; renaming a
+     *  deployed VPC re-enrolls its connector under a new node name. */
+    readonly name?: string;
+}
+export interface SiteConfig {
+    /** Editable any time; the site id stays the permanent machine slug. */
+    readonly displayName?: string;
+    /** An account belongs to EXACTLY ONE site; membership always derives from
+     *  accountNumber, never stored on resource rows. */
+    readonly accounts: readonly string[];
+    /** May invoke THIS site's connector minter (machine keys only — never the
+     *  device minter). A role ARN is least-privilege; a bare id grants the account. */
+    readonly connectorAccounts?: readonly string[];
+    /** Private domain → that VPC's resolver IPs (CIDR base + 2). Per-site:
+     *  overlapping VPCs collide on resolver IPs too. */
+    readonly splitDns?: Record<string, readonly string[]>;
+    /** VPCs joined via ConnectorStack, keyed by account id (must appear in
+     *  `accounts`) — drives the deploy and the per-site CIDR overlap check.
+     *  One VPC per account is the common case; several take a list, every
+     *  entry but one carrying a `name`. `region` only when a VPC is outside
+     *  the hub's region (omit = hub region): ConnectorStack deploys there, and
+     *  the reconciler reaches that VPC's SG-manager and resolver through a
+     *  relay outside the hub VPC. */
+    readonly connectorVpcs?: Record<string, ConnectorVpcConfig | readonly ConnectorVpcConfig[]>;
+    /** Override (100–989) only if two site ids hash-collide (synth tells you).
+     *  Never renumber a deployed rule — CloudFormation fails with PriorityInUse. */
+    readonly albPriority?: number;
+}

package/dist/lib/project-config.js

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

package/dist/lib/target-account-stack.d.ts

@@ -0,0 +1,15 @@
+import * as cdk from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { TargetRoleSpec } from "./constructs/web-identity";
+export interface TargetAccountStackProps extends cdk.StackProps {
+    /** The hub's stable issuer URL (trailing slash tolerated — stripped to
+     *  match the minted `iss` claim). */
+    readonly issuerUrl: string;
+    /** The roles to create in this account, each assumable via web identity. */
+    readonly roles: readonly TargetRoleSpec[];
+}
+/** Only the OIDC provider trusting the hub's ISSUER (never the hub account)
+ *  + the roles. Deliberately small — the target security team's audit surface. */
+export declare class TargetAccountStack extends cdk.Stack {
+    constructor(scope: Construct, id: string, props: TargetAccountStackProps);
+}

package/dist/lib/target-account-stack.js

@@ -0,0 +1,59 @@
+"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.TargetAccountStack = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const target_account_trust_1 = require("./constructs/target-account-trust");
+/** Only the OIDC provider trusting the hub's ISSUER (never the hub account)
+ *  + the roles. Deliberately small — the target security team's audit surface. */
+class TargetAccountStack extends cdk.Stack {
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        // A typo'd account (a rolesByAccount key) would synthesize a stack that
+        // can never deploy. Tokens (env-agnostic synth) pass through.
+        const account = props.env?.account;
+        if (account &&
+            !cdk.Token.isUnresolved(account) &&
+            !/^\d{12}$/.test(account)) {
+            throw new Error(`TargetAccountStack env.account ("${account}") is not a 12-digit ` +
+                `AWS account id.`);
+        }
+        (0, target_account_trust_1.addTargetAccountTrust)(this, {
+            issuerUrl: props.issuerUrl,
+            roles: props.roles,
+        });
+    }
+}
+exports.TargetAccountStack = TargetAccountStack;

package/dist/lib/target-account-template.d.ts

@@ -0,0 +1,13 @@
+import { TargetRoleSpec } from "./constructs/web-identity";
+export interface TargetAccountTemplateProps {
+    /** The hub's issuer URL — the same value every TargetAccountStack is given. */
+    readonly issuerUrl: string;
+    readonly roles: readonly TargetRoleSpec[];
+}
+/** The target-account trust as a plain CloudFormation template that deploys into any account with nothing
+ *  prepared there: no account id baked in (the role-scoped sub pin resolves through `AWS::AccountId`), a native
+ *  `AWS::IAM::OIDCProvider` instead of CDK's asset-backed custom resource, no bootstrap bucket, no parameters.
+ *  For accounts the hub has never seen — a StackSet over an OU, or the account-creation pipeline's
+ *  CloudFormation step; an account that already runs `Roles-<acct>` keeps that stack. The hub registers the
+ *  account afterwards with the role names used here. */
+export declare function synthTargetAccountTemplate(props: TargetAccountTemplateProps): Record<string, unknown>;

package/dist/lib/target-account-template.js

@@ -0,0 +1,64 @@
+"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.synthTargetAccountTemplate = synthTargetAccountTemplate;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const target_account_trust_1 = require("./constructs/target-account-trust");
+/** The target-account trust as a plain CloudFormation template that deploys into any account with nothing
+ *  prepared there: no account id baked in (the role-scoped sub pin resolves through `AWS::AccountId`), a native
+ *  `AWS::IAM::OIDCProvider` instead of CDK's asset-backed custom resource, no bootstrap bucket, no parameters.
+ *  For accounts the hub has never seen — a StackSet over an OU, or the account-creation pipeline's
+ *  CloudFormation step; an account that already runs `Roles-<acct>` keeps that stack. The hub registers the
+ *  account afterwards with the role names used here. */
+function synthTargetAccountTemplate(props) {
+    // The cloud assembly is a by-product: synthesize into a scratch dir and remove it.
+    const outdir = fs.mkdtempSync(path.join(os.tmpdir(), "target-account-template-"));
+    try {
+        const app = new cdk.App({ analyticsReporting: false, outdir });
+        const stack = new cdk.Stack(app, "TargetAccountTemplate", {
+            stackName: "RolesStack",
+            analyticsReporting: false,
+            synthesizer: new cdk.DefaultStackSynthesizer({ generateBootstrapVersionRule: false }),
+        });
+        (0, target_account_trust_1.addTargetAccountTrust)(stack, { issuerUrl: props.issuerUrl, roles: props.roles, nativeProvider: true });
+        return app.synth().getStackArtifact(stack.artifactId).template;
+    }
+    finally {
+        fs.rmSync(outdir, { recursive: true, force: true });
+    }
+}

package/dist/lib/web-cert-stack.d.ts

@@ -0,0 +1,30 @@
+import * as cdk from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import { WebDomains } from "./web-stack";
+import { WafLimits } from "./constructs/web-acl";
+import type { OidcIssuerProps } from "./constructs/oidc-issuer";
+export interface WebCertStackProps extends cdk.StackProps {
+    /** The issuer host — its CloudFront certificate is minted here. */
+    readonly issuer: Pick<OidcIssuerProps, "hostedZoneId" | "zoneName" | "domainName">;
+    /** Omit when the app stays on the raw CloudFront URL — no web cert then. */
+    readonly web?: WebDomains;
+    /** Resolved WAF limits → builds the CloudFront web ACL here (WAF's only
+     *  region for CloudFront); only the per-IP limit applies to it — the
+     *  per-token rule lives on the API stage (creds-stack.ts). Omit = no WAF. */
+    readonly waf?: WafLimits;
+    /** Names the web ACL; must match the other hub stacks'. */
+    readonly resourcePrefix?: string;
+}
+/** us-east-1 companion: what CloudFront only accepts from there — the
+ *  issuer's certificate, the web + auth-domain certificate (Cognito's too)
+ *  and the WAF web ACL. Never deployed alone — it rides along as a
+ *  CredsStack + WebStack dependency. */
+export declare class WebCertStack extends cdk.Stack {
+    readonly issuerCertificate: acm.ICertificate;
+    readonly certificate?: acm.ICertificate;
+    readonly webAclArn?: string;
+    /** Observe-only ACL for the issuer distribution — it never blocks STS. */
+    readonly issuerWebAclArn?: string;
+    constructor(scope: Construct, id: string, props: WebCertStackProps);
+}

package/dist/lib/web-cert-stack.js

@@ -0,0 +1,90 @@
+"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.WebCertStack = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const acm = __importStar(require("aws-cdk-lib/aws-certificatemanager"));
+const route53 = __importStar(require("aws-cdk-lib/aws-route53"));
+const naming_1 = require("../lambdacode/network/naming");
+const web_acl_1 = require("./constructs/web-acl");
+/** us-east-1 companion: what CloudFront only accepts from there — the
+ *  issuer's certificate, the web + auth-domain certificate (Cognito's too)
+ *  and the WAF web ACL. Never deployed alone — it rides along as a
+ *  CredsStack + WebStack dependency. */
+class WebCertStack extends cdk.Stack {
+    issuerCertificate;
+    certificate;
+    webAclArn;
+    /** Observe-only ACL for the issuer distribution — it never blocks STS. */
+    issuerWebAclArn;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const issuerZone = route53.HostedZone.fromHostedZoneAttributes(this, "IssuerZone", {
+            hostedZoneId: props.issuer.hostedZoneId,
+            zoneName: props.issuer.zoneName,
+        });
+        this.issuerCertificate = new acm.Certificate(this, "IssuerCert", {
+            domainName: props.issuer.domainName,
+            validation: acm.CertificateValidation.fromDns(issuerZone),
+        });
+        if (props.web) {
+            const zone = route53.HostedZone.fromHostedZoneAttributes(this, "Zone", {
+                hostedZoneId: props.web.hostedZoneId,
+                zoneName: props.web.zoneName,
+            });
+            this.certificate = new acm.Certificate(this, "WebCert", {
+                domainName: props.web.domainName,
+                subjectAlternativeNames: [props.web.authDomainName],
+                validation: acm.CertificateValidation.fromDns(zone),
+            });
+        }
+        if (props.waf) {
+            const prefix = props.resourcePrefix ?? naming_1.DEFAULT_RESOURCE_PREFIX;
+            this.webAclArn = new web_acl_1.WebAcl(this, "WebAcl", {
+                scope: "CLOUDFRONT",
+                name: `${prefix}-web`,
+                rateLimit: { limit: props.waf.rateLimit, pathPrefix: "/api/" },
+            }).arn;
+            // Separate from the app's ACL so web-motivated tuning can never reach
+            // STS's fetch of the discovery document + JWKS.
+            this.issuerWebAclArn = new web_acl_1.WebAcl(this, "IssuerWebAcl", {
+                scope: "CLOUDFRONT",
+                name: `${prefix}-issuer`,
+                observeOnly: true,
+            }).arn;
+        }
+    }
+}
+exports.WebCertStack = WebCertStack;