@fntio/infra-client 0.0.0-stage → 0.5.0

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

@@ -0,0 +1,103 @@
+import type { ResolvedDevShares } from "./network-validation";
+import type { ResolvedAccountDimensions } from "./dimensions-validation";
+import * as cdk from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as apigw from "aws-cdk-lib/aws-apigateway";
+import * as cognito from "aws-cdk-lib/aws-cognito";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import { type ResolvedFederation } from "./federation";
+/** Angular SPA from a private bucket behind CloudFront, the vending API
+ *  fronted same-origin under /api/* (no CORS), plus the SPA's Cognito client. */
+/** What the sidebar brand row shows (mirrors the frontend Branding type). */
+export type BrandShow = "logo" | "project" | "company" | "logo-and-project" | "logo-and-company";
+/** Per-project branding injected into the generated config.json (white-label:
+ *  one frontend build, re-branded per deployment). */
+export interface WebBranding {
+    /** Sidebar title + browser-tab title (default "Access Portal"). */
+    readonly projectName?: string;
+    /** The client's company name, for the 'company' brandShow modes. */
+    readonly companyName?: string;
+    /** Which of logo / project name / company name the brand row shows.
+     *  Omitted → 'logo-and-project' when logoUrl is set, else 'project'. */
+    readonly brandShow?: BrandShow;
+    /** URL of a square logo image; omitted = letter mark from projectName. */
+    readonly logoUrl?: string;
+    /** A local image file to use as the logo instead of `logoUrl` (.svg, .png, .jpg, .webp or .gif,
+     *  up to about 47 KB). Read at synth and embedded in the web app's config, so nothing has to be
+     *  hosted publicly. A relative path resolves from the directory `cdk` runs in. */
+    readonly logoFile?: string;
+    readonly primaryColor?: string;
+    /** Hover shade; darkened primary if omitted. */
+    readonly primaryHoverColor?: string;
+    readonly accentColor?: string;
+}
+/** Custom domains for the app + its sign-in pages. */
+export interface WebDomains {
+    readonly hostedZoneId: string;
+    readonly zoneName: string;
+    /** The app's public URL (CloudFront alias). */
+    readonly domainName: string;
+    /** Managed Login sign-in domain — must be a child of `domainName`. */
+    readonly authDomainName: string;
+}
+/** By-name contract: the API Lambda derives the same name to write
+ *  /branding.json without a cross-stack ref (CredsStack deploys first). */
+export declare function webBucketName(resourcePrefix: string, account: string): string;
+export interface WebStackProps extends cdk.StackProps {
+    /** SET-ONCE product prefix — names the site bucket; see webBucketName(). */
+    readonly resourcePrefix: string;
+    /** The CredsStack REST API, mounted under /api/* on the distribution. */
+    readonly api: apigw.LambdaRestApi;
+    /** The SPA's app client + domain are created HERE — their callback URLs
+     *  need the CloudFront domain (avoids a circular stack ref). */
+    readonly userPool: cognito.IUserPool;
+    /** This project's branding, baked into config.json at deploy time. */
+    readonly branding?: WebBranding;
+    /** Baked into config.json so the frontend only offers MFA screens when the
+     *  pool actually challenges TOTP. Omit = MFA UI hidden. */
+    readonly mfa?: "optional" | "required";
+    /** Baked into config.json so the frontend only offers passkey management
+     *  when the pool accepts WebAuthn. Omit/false = passkey UI hidden. */
+    readonly passkey?: boolean;
+    /** Whether private-network (VPN) sites exist on this deployment, baked
+     *  into config.json so the SPA hides its Network pages when they don't. */
+    readonly network?: boolean;
+    /** `loginMethods.federation`, validated: one Cognito OIDC provider each, offered on the
+     *  SPA client; the login buttons + claim labels ride config.json. */
+    readonly federation?: ResolvedFederation;
+    /** Enabled `network.devShares`, baked into config.json (the UI's limits); absent = hidden. */
+    readonly devShares?: ResolvedDevShares;
+    /** Enabled `accountDimensions`, baked into config.json (labels + stage silhouettes); absent = no filters. */
+    readonly accountDimensions?: ResolvedAccountDimensions;
+    /** Custom domains; omit to stay on the raw CloudFront URL + default
+     *  Cognito domain. */
+    readonly web?: WebDomains;
+    /** Cert covering both `web` domains. Must come from WebCertStack
+     *  (us-east-1) — CloudFront and Cognito reject certs from any other region. */
+    readonly certificate?: acm.ICertificate;
+    /** CloudFront-scope WAFv2 web ACL ARN — from WebCertStack, since WAF only
+     *  accepts CloudFront ACLs in us-east-1. Omit = no WAF. */
+    readonly webAclArn?: string;
+    /** A prebuilt web bundle to serve instead of the frontend build shipped
+     *  with this package — the seam for deploying your own frontend build. */
+    readonly webAssetPath?: string;
+    /** Customer plugins, on: the /plugin-assets/* behavior over DataStack's assets bucket (by name — a
+     *  bucket reference would try to write its policy from here and cycle the stacks) and the discovery
+     *  settings in config.json. Absent = feature off. */
+    readonly plugins?: WebStackPlugins;
+    /** DataStack's log bucket: S3 server-access logs of the site bucket and the distribution's standard logs. */
+    readonly accessLogsBucket?: s3.IBucket;
+}
+export interface WebStackPlugins {
+    readonly discoveryRefreshSeconds: number;
+    readonly assetsBucketName: string;
+}
+/** The session cap: refresh-token validity of the web clients AND config.json's `sessionHours`, which the
+ *  SPA uses to show when a sign-in ends — one constant so the two can't disagree (issue #29). */
+export declare const SESSION_HOURS = 12;
+export declare class WebStack extends cdk.Stack {
+    /** The generated config.json body — what the SPA self-configures from. */
+    readonly appConfig: Record<string, unknown>;
+    constructor(scope: Construct, id: string, props: WebStackProps);
+}

package/dist/lib/web-stack.js

@@ -0,0 +1,540 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebStack = exports.SESSION_HOURS = void 0;
+exports.webBucketName = webBucketName;
+const cdk = __importStar(require("aws-cdk-lib"));
+const cognito = __importStar(require("aws-cdk-lib/aws-cognito"));
+const cloudfront = __importStar(require("aws-cdk-lib/aws-cloudfront"));
+const origins = __importStar(require("aws-cdk-lib/aws-cloudfront-origins"));
+const route53 = __importStar(require("aws-cdk-lib/aws-route53"));
+const targets = __importStar(require("aws-cdk-lib/aws-route53-targets"));
+const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
+const s3deploy = __importStar(require("aws-cdk-lib/aws-s3-deployment"));
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const pkg_paths_1 = require("./pkg-paths");
+const brandingShapes_1 = require("../lambdacode/api/services/brandingShapes");
+const managed_login_branding_json_1 = __importDefault(require("./managed-login-branding.json"));
+const federation_1 = require("./federation");
+const LOGO_FILE_TYPES = {
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+};
+/** `logoFile` as the data: URI `logoUrl` already accepts — the same thing the theme wizard's upload stores. */
+function inlineLogoFile(file) {
+    const mime = LOGO_FILE_TYPES[path.extname(file).toLowerCase()];
+    if (!mime) {
+        throw new Error(`branding.logoFile ("${file}") must be a .svg, .png, .jpg, .webp or .gif image.`);
+    }
+    const resolved = path.resolve(file);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`branding.logoFile not found at ${resolved} (a relative path resolves from the directory cdk runs in).`);
+    }
+    const uri = `data:${mime};base64,${fs.readFileSync(resolved).toString("base64")}`;
+    if (uri.length > brandingShapes_1.LOGO_MAX) {
+        throw new Error(`branding.logoFile ("${file}") is too large: it must be at most about ${Math.floor((brandingShapes_1.LOGO_MAX * 3) / 4 / 1000)} KB. ` +
+            `Use a smaller image or an SVG, or host it and set branding.logoUrl.`);
+    }
+    return uri;
+}
+/** By-name contract: the API Lambda derives the same name to write
+ *  /branding.json without a cross-stack ref (CredsStack deploys first). */
+function webBucketName(resourcePrefix, account) {
+    return `${resourcePrefix}-web-${account}`;
+}
+// Prebuilt output, NOT CDK bundling (which would rerun the 30s+ Angular build
+// on every synth). Repo build when developing here, else the prepack copy.
+const REPO_DIST = path.join((0, pkg_paths_1.packageRoot)(), "..", "..", "frontend", "dist", "frontend", "browser");
+const PACKAGED_DIST = path.join((0, pkg_paths_1.packageRoot)(), "assets", "web");
+/** The session cap: refresh-token validity of the web clients AND config.json's `sessionHours`, which the
+ *  SPA uses to show when a sign-in ends — one constant so the two can't disagree (issue #29). */
+exports.SESSION_HOURS = 12;
+class WebStack extends cdk.Stack {
+    /** The generated config.json body — what the SPA self-configures from. */
+    appConfig;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const webAssetPath = props.webAssetPath ??
+            (fs.existsSync(path.join(REPO_DIST, "index.html"))
+                ? REPO_DIST
+                : PACKAGED_DIST);
+        if (!fs.existsSync(path.join(webAssetPath, "index.html"))) {
+            throw new Error(`Web assets not found at ${webAssetPath} (no index.html) — build the frontend first, or point webAssetPath at a prebuilt bundle.`);
+        }
+        // Fail loudly at synth rather than shipping a blank brand row: a brandShow
+        // that names the company or a logo must have that value provided.
+        if (props.branding?.logoFile && props.branding.logoUrl) {
+            throw new Error(`Set branding.logoFile or branding.logoUrl, not both.`);
+        }
+        const { logoFile, ...brandingRest } = props.branding ?? {};
+        const b = props.branding && {
+            ...brandingRest,
+            ...(logoFile ? { logoUrl: inlineLogoFile(logoFile) } : {}),
+        };
+        if (b?.brandShow?.includes("company") && !b.companyName) {
+            throw new Error(`branding.brandShow is "${b.brandShow}" but branding.companyName is not set.`);
+        }
+        if (b?.brandShow?.includes("logo") && !b.logoUrl) {
+            throw new Error(`branding.brandShow is "${b.brandShow}" but neither branding.logoUrl nor branding.logoFile is set.`);
+        }
+        // Shared shapes (brandingShapes): a value the admin API would reject must
+        // not deploy — applyBranding silently no-ops on a bad color.
+        for (const key of ["primaryColor", "primaryHoverColor", "accentColor"]) {
+            const value = b?.[key];
+            if (value && !(0, brandingShapes_1.isBrandColor)(key, value)) {
+                throw new Error(`branding.${key} ("${value}") must be a #rgb or #rrggbb hex color` +
+                    (key === "primaryColor" ? ` (or "mono")` : "") +
+                    `.`);
+            }
+        }
+        if (b?.logoUrl &&
+            !(brandingShapes_1.LOGO_URL_RE.test(b.logoUrl) && b.logoUrl.length <= brandingShapes_1.LOGO_MAX)) {
+            throw new Error(`branding.logoUrl must be an https:// URL or a data:image/ URI of ` +
+                `at most ${brandingShapes_1.LOGO_MAX} characters.`);
+        }
+        const web = props.web;
+        if (web) {
+            if (!props.certificate) {
+                throw new Error("`web` domains are set but no `certificate` was passed — CloudFront/Cognito require a us-east-1 cert: deploy WebCertStack and pass its certificate.");
+            }
+            if (web.domainName !== web.zoneName &&
+                !web.domainName.endsWith(`.${web.zoneName}`)) {
+                throw new Error(`web.domainName (${web.domainName}) must be web.zoneName or a subdomain of it (${web.zoneName}).`);
+            }
+            // Cognito rejects an auth domain whose parent has no A record — as a
+            // child of domainName, the app's own alias record satisfies that.
+            if (!web.authDomainName.endsWith(`.${web.domainName}`)) {
+                throw new Error(`web.authDomainName (${web.authDomainName}) must be a subdomain of web.domainName (${web.domainName}) — its parent must resolve for Cognito to accept it.`);
+            }
+        }
+        // The API Lambda (deployed BEFORE this stack) writes /branding.json here
+        // by derived name — see webBucketName().
+        const siteBucket = new s3.Bucket(this, "SiteBucket", {
+            bucketName: webBucketName(props.resourcePrefix, this.account),
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            enforceSSL: true,
+            removalPolicy: cdk.RemovalPolicy.DESTROY, // contents are redeployable build output
+            autoDeleteObjects: true, // otherwise destroy fails on a non-empty bucket
+            // Security Hub S3.13 wants a lifecycle configuration; this is the one
+            // rule that is useful on a build-output bucket.
+            lifecycleRules: [{ abortIncompleteMultipartUploadAfter: cdk.Duration.days(7) }],
+            serverAccessLogsBucket: props.accessLogsBucket,
+            serverAccessLogsPrefix: props.accessLogsBucket && "s3/web/",
+        });
+        // NOT CloudFront errorResponses — those are distribution-wide and would
+        // rewrite the API's JSON 403/404s into a 200 index page.
+        const spaRewrite = new cloudfront.Function(this, "SpaRewrite", {
+            comment: "Rewrite extensionless paths to /index.html (SPA routing)",
+            code: cloudfront.FunctionCode.fromInline(`
+function handler(event) {
+  var request = event.request;
+  if (!request.uri.includes(".")) {
+    request.uri = "/index.html";
+  }
+  return request;
+}
+`),
+        });
+        // ONE origin instance shared by both bucket behaviors — a second
+        // withOriginAccessControl() call would mint a duplicate origin + OAC.
+        const siteOrigin = origins.S3BucketOrigin.withOriginAccessControl(siteBucket);
+        const plugins = props.plugins;
+        const pluginAssetsOrigin = plugins
+            ? origins.S3BucketOrigin.withOriginAccessControl(s3.Bucket.fromBucketName(this, "PluginAssetsBucket", plugins.assetsBucketName))
+            : undefined;
+        // Where the SPA is allowed to talk: itself, the Cognito API of its region, and the hosted-UI domain
+        // (the federation token exchange). Everything else the page loads or sends to is a violation.
+        const cognitoOrigin = `https://cognito-idp.${cdk.Stack.of(this).region}.amazonaws.com`;
+        const authOrigin = web ? `https://${web.authDomainName}` : "https://*.amazoncognito.com";
+        // The shell's inline scripts (the boot-failure fallback) are allowed by hash, taken from the index.html
+        // that this very deploy uploads, so the policy and the page cannot drift. Inline event handlers are
+        // not covered by hashes: the page must bind them from a script.
+        const inlineScriptHashes = [
+            ...fs.readFileSync(path.join(webAssetPath, "index.html"), "utf8").matchAll(/<script(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi),
+        ].map((m) => `'sha256-${crypto.createHash("sha256").update(m[1]).digest("base64")}'`);
+        const appCsp = [
+            "default-src 'self'",
+            ["script-src 'self'", ...inlineScriptHashes].join(" "),
+            "style-src 'self' 'unsafe-inline'",
+            "img-src 'self' data: https:",
+            "font-src 'self' data:",
+            `connect-src 'self' ${cognitoOrigin} ${authOrigin}`,
+            "frame-src 'self'",
+            "frame-ancestors 'none'",
+            "base-uri 'self'",
+            `form-action 'self' ${authOrigin}`,
+            "object-src 'none'",
+        ].join("; ");
+        // The same headers the managed SECURITY_HEADERS policy sends, plus the CSP enforced (report-only in
+        // 0.1.18's first deploy, no violation seen): tokens live in localStorage, so a script or connection the
+        // page did not intend is exactly what a CSP is for. A blocked load logs a console error, so the e2e run
+        // fails on a missing allow-list entry. CloudFront rejects `Content-Security-Policy` as a CUSTOM header
+        // (the report-only name was accepted only because it is not on the reserved list) — it must be the
+        // security-headers field, like the plugin policy below.
+        const appHeaders = new cloudfront.ResponseHeadersPolicy(this, "AppHeaders", {
+            securityHeadersBehavior: {
+                frameOptions: { frameOption: cloudfront.HeadersFrameOption.DENY, override: true },
+                contentTypeOptions: { override: true },
+                strictTransportSecurity: { accessControlMaxAge: cdk.Duration.days(365), includeSubdomains: true, override: true },
+                referrerPolicy: { referrerPolicy: cloudfront.HeadersReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN, override: true },
+                xssProtection: { protection: true, modeBlock: true, override: true },
+                contentSecurityPolicy: { contentSecurityPolicy: appCsp, override: true },
+            },
+        });
+        // Plugin UIs are same-origin iframes: SECURITY_HEADERS would send X-Frame-Options DENY, which blocks even
+        // same-origin framing. Immutable revision paths cache long; no SPA rewrite, so a missing file is a real error
+        // (S3 answers 403 for a key the GetObject-only policy cannot serve), never index.html.
+        // A plugin page runs with the signed-in user's authority (same origin), so its CSP is enforced: it may
+        // load and talk to the portal only — no third-party scripts, no sending data elsewhere.
+        const pluginAssetHeaders = plugins
+            ? new cloudfront.ResponseHeadersPolicy(this, "PluginAssetHeaders", {
+                securityHeadersBehavior: {
+                    frameOptions: { frameOption: cloudfront.HeadersFrameOption.SAMEORIGIN, override: true },
+                    contentTypeOptions: { override: true },
+                    strictTransportSecurity: { accessControlMaxAge: cdk.Duration.days(365), includeSubdomains: true, override: true },
+                    referrerPolicy: { referrerPolicy: cloudfront.HeadersReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN, override: true },
+                    contentSecurityPolicy: {
+                        contentSecurityPolicy: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'self'; base-uri 'self'; form-action 'self'; object-src 'none'",
+                        override: true,
+                    },
+                },
+            })
+            : undefined;
+        const distribution = new cloudfront.Distribution(this, "Distribution", {
+            comment: "Web frontend (Angular SPA)",
+            defaultRootObject: "index.html",
+            webAclId: props.webAclArn,
+            ...(props.accessLogsBucket
+                ? { enableLogging: true, logBucket: props.accessLogsBucket, logFilePrefix: "cloudfront/web/", logIncludesCookies: false }
+                : {}),
+            ...(web
+                ? { domainNames: [web.domainName], certificate: props.certificate }
+                : {}),
+            defaultBehavior: {
+                origin: siteOrigin,
+                viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+                // HSTS/nosniff/frame-deny + the CSP on the app pages only — /api/* stays
+                // untouched so API responses aren't rewritten.
+                responseHeadersPolicy: appHeaders,
+                functionAssociations: [
+                    {
+                        function: spaRewrite,
+                        eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
+                    },
+                ],
+            },
+            additionalBehaviors: {
+                // Runtime-written branding overlay — never cached, so a saved theme
+                // shows on the next load without an invalidation.
+                "/branding.json": {
+                    origin: siteOrigin,
+                    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+                    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
+                },
+                ...(pluginAssetsOrigin
+                    ? {
+                        "/plugin-assets/*": {
+                            origin: pluginAssetsOrigin,
+                            viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+                            cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
+                            responseHeadersPolicy: pluginAssetHeaders,
+                        },
+                    }
+                    : {}),
+                // /api/<route> → API Gateway /dev/api/<route>; the Express app strips
+                // the /api prefix. No SPA rewrite here, so API status codes pass through.
+                "/api/*": {
+                    origin: new origins.RestApiOrigin(props.api),
+                    allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
+                    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.HTTPS_ONLY,
+                    // Never cache API responses (per-user, carry credentials).
+                    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
+                    // Forward all headers EXCEPT Host — API Gateway routes on its own
+                    // execute-api hostname and 403s on the CloudFront Host header.
+                    originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+                },
+            },
+        });
+        let zone;
+        let appAlias;
+        if (web) {
+            zone = route53.HostedZone.fromHostedZoneAttributes(this, "Zone", {
+                hostedZoneId: web.hostedZoneId,
+                zoneName: web.zoneName,
+            });
+            const target = route53.RecordTarget.fromAlias(new targets.CloudFrontTarget(distribution));
+            appAlias = new route53.ARecord(this, "AppAlias", {
+                zone,
+                recordName: web.domainName,
+                target,
+            });
+            new route53.AaaaRecord(this, "AppAliasV6", {
+                zone,
+                recordName: web.domainName,
+                target,
+            });
+        }
+        const webUrl = web
+            ? `https://${web.domainName}`
+            : `https://${distribution.distributionDomainName}`;
+        // Federated providers: the pool trusts each issuer; the sign-in itself runs through
+        // Cognito's hosted endpoints on the auth domain (authorize → IdP → idpresponse → the app's
+        // /auth/callback). Secret by dynamic reference — never in the template.
+        const federation = props.federation;
+        const idps = (federation?.providers ?? []).map((p) => new cognito.UserPoolIdentityProviderOidc(this, `Idp${p.name}`, {
+            userPool: props.userPool,
+            name: p.name,
+            clientId: p.clientId,
+            clientSecret: (0, federation_1.clientSecretReference)(p),
+            issuerUrl: p.issuerUrl,
+            scopes: [...p.scopes],
+            attributeRequestMethod: cognito.OidcAttributeRequestMethod.GET,
+            attributeMapping: (0, federation_1.providerAttributeMapping)(p),
+        }));
+        const claimKeys = federation?.claimKeys ?? [];
+        const tokenValidity = {
+            // Hard session cap: the SPA renews 1-hour tokens against the
+            // refresh token, so its validity IS the max time between logins.
+            idTokenValidity: cdk.Duration.hours(1),
+            accessTokenValidity: cdk.Duration.hours(1),
+            refreshTokenValidity: cdk.Duration.hours(exports.SESSION_HOURS),
+        };
+        const callbackUrls = [
+            ...(web ? [`https://${web.domainName}/auth/callback`] : []),
+            `https://${distribution.distributionDomainName}/auth/callback`,
+            "http://localhost:4200/auth/callback", // ng serve
+        ];
+        const logoutUrls = [
+            ...(web ? [`https://${web.domainName}`] : []),
+            `https://${distribution.distributionDomainName}`,
+            "http://localhost:4200",
+        ];
+        // Sign-in is the app's own /login page; the OAuth block only keeps the
+        // hosted-UI endpoints valid for pre-cutover sessions. Local only: the mapped claims are
+        // readable (they ride local ID tokens of linked users) but never writable here — this
+        // client's USER_AUTH access tokens can call UpdateUserAttributes.
+        const spaClient = new cognito.UserPoolClient(this, "SpaClient", {
+            userPool: props.userPool,
+            generateSecret: false,
+            supportedIdentityProviders: [cognito.UserPoolClientIdentityProvider.COGNITO],
+            ...(claimKeys.length
+                ? {
+                    readAttributes: (0, federation_1.readAttributes)(claimKeys),
+                    writeAttributes: (0, federation_1.writeAttributes)(claimKeys, { claims: false }),
+                }
+                : {}),
+            ...tokenValidity,
+            // `user` = choice-based sign-in (password / email code / passkey).
+            authFlows: { user: true },
+            // Unknown emails get a simulated challenge menu, so the sign-in page
+            // can't be used to probe which emails exist.
+            preventUserExistenceErrors: true,
+            oAuth: {
+                flows: { authorizationCodeGrant: true },
+                scopes: [
+                    cognito.OAuthScope.OPENID,
+                    cognito.OAuthScope.EMAIL,
+                    cognito.OAuthScope.PROFILE,
+                ],
+                // The raw CloudFront URL stays registered alongside a custom domain
+                // so existing tabs/bookmarks survive the cutover.
+                callbackUrls,
+                logoutUrls,
+            },
+        });
+        // The federated code flow runs on its own client: providers only (no local sign-in on
+        // it), refresh as the sole auth flow, and the ONE place the mapped claims are writable —
+        // its tokens never carry the self-service scope, so only Cognito's mapping writes them.
+        let federationClient;
+        if (federation) {
+            federationClient = new cognito.UserPoolClient(this, "FederationClient", {
+                userPool: props.userPool,
+                generateSecret: false,
+                supportedIdentityProviders: federation.providers.map((p) => cognito.UserPoolClientIdentityProvider.custom(p.name)),
+                readAttributes: (0, federation_1.readAttributes)(claimKeys),
+                writeAttributes: (0, federation_1.writeAttributes)(claimKeys, { claims: true }),
+                ...tokenValidity,
+                preventUserExistenceErrors: true,
+                oAuth: {
+                    flows: { authorizationCodeGrant: true },
+                    scopes: [cognito.OAuthScope.OPENID, cognito.OAuthScope.EMAIL, cognito.OAuthScope.PROFILE],
+                    callbackUrls,
+                    logoutUrls,
+                },
+            });
+            // CDK can't express refresh-only; Cognito's default for an unset list would enable SRP.
+            federationClient.node.defaultChild.explicitAuthFlows = [
+                "ALLOW_REFRESH_TOKEN_AUTH",
+            ];
+            // A client may only list providers that already exist.
+            for (const idp of idps)
+                federationClient.node.addDependency(idp);
+        }
+        // Fallback prefix is region-globally unique across ALL AWS accounts,
+        // so include the account id.
+        const hostedUiDomain = new cognito.UserPoolDomain(this, "HostedUiDomain", {
+            userPool: props.userPool,
+            ...(web
+                ? {
+                    customDomain: {
+                        domainName: web.authDomainName,
+                        certificate: props.certificate,
+                    },
+                }
+                : { cognitoDomain: { domainPrefix: `creds-${this.account}` } }),
+            // Managed Login v2 — required for the passkey chooser + branding designer.
+            managedLoginVersion: cognito.ManagedLoginVersion.NEWER_MANAGED_LOGIN,
+        });
+        if (web && zone && appAlias) {
+            // Cognito checks the parent A record at create time — the app's alias
+            // must exist first.
+            hostedUiDomain.node.addDependency(appAlias);
+            new route53.ARecord(this, "AuthAlias", {
+                zone,
+                recordName: web.authDomainName,
+                target: route53.RecordTarget.fromAlias(new targets.UserPoolDomainTarget(hostedUiDomain)),
+            });
+        }
+        // White-label: swap the accent tokens in managed-login-branding.json to
+        // re-skin a client's login page.
+        const loginBranding = new cognito.CfnManagedLoginBranding(this, "SpaLoginBranding", {
+            userPoolId: props.userPool.userPoolId,
+            clientId: spaClient.userPoolClientId,
+            useCognitoProvidedValues: false,
+            // Imported (not fs-read) so tsc copies the JSON into dist/ and the
+            // published package needs no lib/ source next to the compiled code.
+            settings: managed_login_branding_json_1.default,
+        });
+        // The domain must serve v2 before a v2 branding style is meaningful.
+        loginBranding.addResourceDependency(hostedUiDomain.node.defaultChild);
+        if (federationClient) {
+            // Same style for the federation client's hosted pages (error pages, mostly).
+            const federationBranding = new cognito.CfnManagedLoginBranding(this, "FederationLoginBranding", {
+                userPoolId: props.userPool.userPoolId,
+                clientId: federationClient.userPoolClientId,
+                useCognitoProvidedValues: false,
+                settings: managed_login_branding_json_1.default,
+            });
+            federationBranding.addResourceDependency(hostedUiDomain.node.defaultChild);
+        }
+        // The /* invalidation matters: index.html isn't content-hashed — without
+        // it users get a stale page for up to 24h.
+        const appConfig = {
+            userPoolId: props.userPool.userPoolId,
+            spaClientId: spaClient.userPoolClientId,
+            hostedUiDomain: hostedUiDomain.baseUrl(),
+            region: this.region,
+            sessionHours: exports.SESSION_HOURS,
+            network: !!props.network,
+            ...(props.devShares ? { devShares: props.devShares } : {}),
+            ...(props.accountDimensions ? { dimensions: { labels: props.accountDimensions.labels, stages: props.accountDimensions.stages } } : {}),
+            ...(props.mfa ? { mfa: props.mfa } : {}),
+            ...(props.passkey ? { passkey: true } : {}),
+            ...(federation && federationClient
+                ? { federation: (0, federation_1.federationAppConfig)(federation, federationClient.userPoolClientId) }
+                : {}),
+            ...(b ? { branding: b } : {}),
+            ...(plugins ? { plugins: { enabled: true, discoveryRefreshSeconds: plugins.discoveryRefreshSeconds } } : {}),
+        };
+        this.appConfig = appConfig;
+        if (federationClient) {
+            // What the operator registers at every IdP as the redirect URI.
+            new cdk.CfnOutput(this, "FederationRedirectUri", {
+                value: `${hostedUiDomain.baseUrl()}/oauth2/idpresponse`,
+            });
+            new cdk.CfnOutput(this, "FederationClientId", { value: federationClient.userPoolClientId });
+        }
+        // Two uploads because two cache rules: hashed chunks never change under their name, while index.html
+        // and config.json change on every deploy under the SAME name. Without a Cache-Control header browsers
+        // apply heuristic freshness to those two, kept the old shell for a day after a deploy and then asked
+        // for chunks the prune had removed (the "old bundle still live" incidents; desktop/main.js clears its
+        // HTTP cache for the same reason).
+        // Three steps so no moment of a deploy serves an index.html whose chunks are missing: (1) the new
+        // chunks land beside the old ones, (2) the new index.html and config.json go live, (3) only then are the
+        // previous build's chunks pruned (a tab still on the old shell that loads a pruned chunk reloads —
+        // frontend/src/app/app.config.ts).
+        const hashedAssets = s3deploy.Source.asset(webAssetPath, { exclude: ["config.json", "index.html"] });
+        const immutable = [s3deploy.CacheControl.maxAge(cdk.Duration.days(365)), s3deploy.CacheControl.immutable()];
+        const assets = new s3deploy.BucketDeployment(this, "DeploySite", {
+            sources: [hashedAssets],
+            destinationBucket: siteBucket,
+            cacheControl: immutable,
+            prune: false,
+        });
+        const entry = new s3deploy.BucketDeployment(this, "DeploySiteEntry", {
+            sources: [
+                s3deploy.Source.asset(webAssetPath, { exclude: ["*", "!index.html"] }),
+                s3deploy.Source.jsonData("config.json", appConfig),
+            ],
+            destinationBucket: siteBucket,
+            cacheControl: [s3deploy.CacheControl.noCache()],
+            prune: false,
+            distribution,
+            distributionPaths: ["/*"],
+        });
+        entry.node.addDependency(assets);
+        const prune = new s3deploy.BucketDeployment(this, "DeploySitePrune", {
+            sources: [hashedAssets],
+            destinationBucket: siteBucket,
+            cacheControl: immutable,
+            // Removes the previous build's chunks, never the entry files or the admin-saved theme (runtime state,
+            // not a deploy artifact).
+            exclude: ["branding.json", "index.html", "config.json"],
+        });
+        prune.node.addDependency(entry);
+        new cdk.CfnOutput(this, "DistributionDomain", {
+            value: distribution.distributionDomainName,
+        });
+        new cdk.CfnOutput(this, "WebUrl", {
+            value: webUrl,
+        });
+        new cdk.CfnOutput(this, "SpaClientId", {
+            value: spaClient.userPoolClientId,
+        });
+        new cdk.CfnOutput(this, "HostedUiUrl", {
+            value: hostedUiDomain.baseUrl(),
+        });
+    }
+}
+exports.WebStack = WebStack;