@fjall/components-infrastructure 24.0.0 → 26.0.0

package/dist/lib/app.js

@@ -13,6 +13,7 @@ import { BuildkiteFactory } from "./patterns/aws/buildkite.js";
 import { DevSubstrate } from "./patterns/aws/devSubstrate.js";
 import { StandardTagsAspect } from "./utils/standardTagsAspect.js";
 import { emitAppLevelAlbAliasExports } from "./utils/albAliasTargetRegistry.js";
+import { emitAppLevelCdnAliasExports } from "./utils/cdnAliasTargetRegistry.js";
 import { ensureFunctionLogGroups } from "./resources/aws/logging/logGroupHygiene.js";
 import { BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP } from "./utils/backupTierMapping.js";
 import { randomBytes } from "crypto";
@@ -843,8 +844,9 @@ export class App extends CdkApp {
         // they synthesise untagged. Idempotent via the aspectApplied guard.
         this.applyTagsAspect();
         // Must precede super.synth(): the tree is still mutable here, and only
-        // now is the ALB count per app final.
+        // now is the ALB / CloudFront count per app final.
         emitAppLevelAlbAliasExports(this);
+        emitAppLevelCdnAliasExports(this);
         // Also pre-super, and before aspects run inside it, so the log groups
         // this creates are still visited by the app-wide tag aspects.
         ensureFunctionLogGroups(this);

package/dist/lib/patterns/aws/cdn.d.ts

@@ -6,7 +6,7 @@ import { type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-
 import type App from "../../app.js";
 import { CloudFrontDistribution, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
 import { type ICdn } from "./interfaces/cdn.js";
-import { type StaticSiteRouting } from "@fjall/util";
+import { type StaticSiteRouting, type CloudFrontPriceClass } from "@fjall/util";
 import { type ManagedDomainBinding, type ManagedDomainExports } from "../../utils/domainTypes.js";
 import { type Storage } from "./storage.js";
 import { type AnyCompute } from "./compute.js";
@@ -83,7 +83,7 @@ interface BaseCdnProps {
     comment?: string;
     enableLogging?: boolean;
     logBucket?: IBucket;
-    priceClass?: "PriceClass_100" | "PriceClass_200" | "PriceClass_All";
+    priceClass?: CloudFrontPriceClass;
     forwardHostHeader?: boolean;
     accessGate?: false | AccessGateConfig;
 }

package/dist/lib/patterns/aws/interfaces/domain.d.ts

@@ -20,6 +20,12 @@ export type FjallTarget = {
 } | {
     readonly kind: "cdn";
     readonly appName: string;
+    /**
+     * Names one CloudFront distribution when the app fronts several. Absent
+     * means the app's sole CDN, which only exists as an export when the app
+     * has exactly one (lib/utils/cdnAliasTargetRegistry.ts).
+     */
+    readonly cdnName?: string;
 } | {
     readonly kind: "bucket";
     readonly appName: string;

package/dist/lib/patterns/aws/interfaces/pattern.d.ts

@@ -17,14 +17,16 @@
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type Duration } from "aws-cdk-lib";
 import { type Construct } from "constructs";
+import type { HstsConfig } from "../../../resources/aws/cdn/responseHeadersPolicy.js";
 import { type RelationalDatabase, type DynamoDBDatabase, type ProxyConfig, type ReadReplicaConfig, type CredentialsConfig, type EncryptionConfig, type AuroraEncryptionConfig, type AuroraWriterConfig, type AuroraReadersConfig, type DatabaseInsightsConfig } from "../database.js";
 import { type LambdaCompute } from "../compute.js";
 import { type Storage } from "../storage.js";
 import { type QueueMessaging } from "../messaging.js";
 import { type Cdn, type SmartCdnBehaviour, type StaticSiteRouting } from "../cdn.js";
 import { type LambdaFunction } from "../../../resources/aws/compute/index.js";
+import type { AccessGateConfig, SecurityHeadersPolicy } from "../../../resources/aws/cdn/index.js";
 import type { ManagedDomainBinding, ManagedDomainExports } from "../../../utils/domainTypes.js";
-import type { PatternType } from "@fjall/util";
+import type { PatternType, CloudFrontPriceClass, STATIC_SITE_CONFIG_KEYS, STATIC_SITE_CDN_CONFIG_KEYS } from "@fjall/util";
 export type { ProxyConfig, ReadReplicaConfig, CredentialsConfig, EncryptionConfig, AuroraEncryptionConfig, AuroraWriterConfig, AuroraReadersConfig, DatabaseInsightsConfig };
 /**
  * Full database configuration for patterns.
@@ -384,10 +386,25 @@ export interface StaticSiteBuildConfig {
 export interface StaticSiteSecurityConfig {
     /** Ship the four safe headers (HSTS/nosniff/frame/referrer). */
     headers?: boolean;
+    /**
+     * HSTS tuning. Absent ⇒ the header ships scoped to this host only, for the
+     * standard max-age: a site that did not ask for HSTS does not get its
+     * subdomains bound or a preload-list entry. Supply the members to widen it,
+     * or `false` to drop the header entirely.
+     */
+    hsts?: false | StaticSiteHstsConfig;
     /** Opt-in Content-Security-Policy. Absent ⇒ no CSP header (a wrong policy
      * silently breaks inline hydration, so it is never a shipped default). */
     contentSecurityPolicy?: string;
 }
+/**
+ * HSTS configuration for a static site.
+ *
+ * Aliased from the response-headers wrapper rather than redeclared: the two
+ * describe one shape, and a second declaration is a silent-drift seam — a
+ * member added to one would compile clean against the other.
+ */
+export type StaticSiteHstsConfig = HstsConfig;
 /**
  * Contact-form configuration for a static site. Requires a custom `domain`: SES
  * sends only from a verified identity, and the site's domain is the identity
@@ -422,6 +439,23 @@ export interface StaticSiteFormsConfig {
 export interface StaticSiteCdnConfig {
     /** Additional CDN behaviours (per-path overrides). */
     behaviours?: SmartCdnBehaviour[];
+    /**
+     * CloudFront price class — which edge locations serve the site. Default
+     * `"PriceClass_100"` (NA + Europe only). At small-site traffic the price
+     * difference between classes is ~zero, so treat this as a latency knob:
+     * an audience outside NA/Europe (e.g. Australia) wants `"PriceClass_All"`,
+     * or every request crosses an ocean to the nearest POP.
+     */
+    priceClass?: CloudFrontPriceClass;
+    /**
+     * Invalidate the distribution (`/*`) when a deploy uploads new assets.
+     * Default `true`: without it CloudFront serves stale edge copies until the
+     * cache policy's TTL (up to 24h) expires, which a non-expert cannot tell
+     * apart from a failed deploy. AWS grants 1,000 free invalidation paths per
+     * month and `/*` counts as one path per deploy. Set `false` to keep pure
+     * TTL semantics (e.g. very frequent deploys where a stale window is fine).
+     */
+    invalidateOnDeploy?: boolean;
 }
 /**
  * Static-site pattern props.
@@ -485,7 +519,30 @@ export interface IStaticSiteProps {
     forms?: StaticSiteFormsConfig;
     /** CDN configuration - for advanced per-path overrides. */
     cdn?: StaticSiteCdnConfig;
+    /**
+     * Gate every request behind HTTP Basic auth at the edge (a CloudFront
+     * viewer function; the gate runs BEFORE the routing rewrite). This is an
+     * obscurity gate for staging sign-off — keeping a not-yet-launched site
+     * out of casual view and search indexes — NOT a security boundary: the
+     * credentials sit in plain text here and in the distribution's function
+     * code, and the origin objects are unchanged. Remove it at launch.
+     */
+    accessGate?: AccessGateConfig;
 }
+/**
+ * Field-parity witnesses (compile-time, zero runtime cost).
+ *
+ * `STATIC_SITE_CONFIG_KEYS` in `@fjall/util` is the manifest every
+ * field-enumerating surface is held to (generator schema, AST parser,
+ * emitter — see its JSDoc). These aliases fail to compile the moment
+ * `IStaticSiteProps` or `StaticSiteCdnConfig` gains or loses a key the
+ * manifest does not list, so the interface cannot drift from the manifest —
+ * and via the generator's parity tests, from the other surfaces.
+ */
+type MutuallyAssignable<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+type AssertTrue<T extends true> = T;
+export type StaticSitePropsParityWitness = AssertTrue<MutuallyAssignable<keyof IStaticSiteProps, (typeof STATIC_SITE_CONFIG_KEYS)[number]>>;
+export type StaticSiteCdnConfigParityWitness = AssertTrue<MutuallyAssignable<keyof StaticSiteCdnConfig, (typeof STATIC_SITE_CDN_CONFIG_KEYS)[number]>>;
 /**
  * Union of all pattern props.
  * Extend this when adding new patterns (e.g., INextjsProps, IRemixProps).
@@ -554,7 +611,10 @@ export interface IPayload extends IPattern {
  * Provides access to the underlying resources for escape hatches.
  *
  * @example
- * site.getBucket().getBucket().addLifecycleRule({ ... });
+ * // Expire old objects: the concrete S3 Bucket is two getters away.
+ * site.getBucket().getBucket().addLifecycleRule({
+ *   expiration: Duration.days(90)
+ * });
  * site.getCdn().getDistribution().addBehavior("/custom/*", customOrigin);
  */
 export interface IStaticSite extends IPattern {
@@ -565,6 +625,11 @@ export interface IStaticSite extends IPattern {
     getCdn(): Cdn;
     /** Get the contact-form Lambda (undefined when `forms` is not configured) */
     getFormsFunction(): LambdaFunction | undefined;
+    /**
+     * Get the security-headers ResponseHeadersPolicy (undefined unless
+     * `security.headers` is set) — e.g. to attach it to extra behaviours.
+     */
+    getResponseHeadersPolicy(): SecurityHeadersPolicy | undefined;
 }
 /**
  * Union type representing any pattern interface.

package/dist/lib/patterns/aws/staticSite.d.ts

@@ -6,7 +6,8 @@
  * optional contact-form endpoint (Lambda Function URL → SES, CloudFront-fronted).
  *
  * Resources created:
- * - Private S3 bucket + BucketDeployment (asset upload)
+ * - Private S3 bucket + BucketDeployment (asset upload + post-upload
+ *   invalidation of the distribution, unless `cdn.invalidateOnDeploy: false`)
  * - CloudFront distribution (OAC, routing-mode viewer function, security-headers policy)
  * - ACM certificate + Route53 alias record (when `domain` is set)
  * - Contact-form Lambda + Function URL (when `forms` is set)
@@ -29,6 +30,7 @@ import type App from "../../app.js";
 import { type IStaticSiteProps, type IStaticSite } from "./interfaces/pattern.js";
 import { type Storage } from "./storage.js";
 import { type Cdn } from "./cdn.js";
+import { SecurityHeadersPolicy } from "../../resources/aws/cdn/index.js";
 import { LambdaFunction } from "../../resources/aws/compute/index.js";
 /**
  * Static-site pattern implementation.
@@ -46,7 +48,31 @@ export declare class StaticSite extends Construct implements IStaticSite {
     constructor(scope: Construct, id: string, app: App, props: IStaticSiteProps);
     private registerManifest;
     private validateProps;
-    private createBucketAndDeployment;
+    private createBucket;
+    private deploySiteAssets;
+    /**
+     * Refuse to synthesise a site whose build output directory is not there.
+     *
+     * Ordered before the emptiness gate because that gate READS the directory:
+     * without this, `readdirSync` throws a bare `ENOENT` naming an absolute
+     * path, which is the least useful form of exactly the diagnosis its sibling
+     * spells out. A mis-set `build.outputDir` is the common cause and the one
+     * the message names.
+     */
+    private assertSourceExists;
+    /**
+     * Refuse to synthesise a pruning upload from an empty build output.
+     *
+     * The upload prunes, so an empty source does not deploy nothing — it
+     * deletes every object already in the bucket, taking the live site down.
+     * A build that creates its output directory and then fails to write into
+     * it exits 0 and looks identical to a successful one, so presence alone is
+     * not proof.
+     *
+     * `staticSiteBuilder` makes the same check at deploy time through the same
+     * helper, so the two verdicts cannot drift.
+     */
+    private assertSourceHasContent;
     private createFormsEndpoint;
     private createCdn;
     private buildBehaviours;
@@ -57,4 +83,5 @@ export declare class StaticSite extends Construct implements IStaticSite {
     getBucket(): Storage;
     getCdn(): Cdn;
     getFormsFunction(): LambdaFunction | undefined;
+    getResponseHeadersPolicy(): SecurityHeadersPolicy | undefined;
 }

package/dist/lib/patterns/aws/staticSite.js

@@ -6,7 +6,8 @@
  * optional contact-form endpoint (Lambda Function URL → SES, CloudFront-fronted).
  *
  * Resources created:
- * - Private S3 bucket + BucketDeployment (asset upload)
+ * - Private S3 bucket + BucketDeployment (asset upload + post-upload
+ *   invalidation of the distribution, unless `cdn.invalidateOnDeploy: false`)
  * - CloudFront distribution (OAC, routing-mode viewer function, security-headers policy)
  * - ACM certificate + Route53 alias record (when `domain` is set)
  * - Contact-form Lambda + Function URL (when `forms` is set)
@@ -26,12 +27,14 @@
  */
 import { Construct } from "constructs";
 import { CfnOutput, Fn, Stack } from "aws-cdk-lib";
+import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Code, Runtime, Architecture, FunctionUrlAuthType, HttpMethod } from "aws-cdk-lib/aws-lambda";
 import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
 import { CloudFrontTarget } from "aws-cdk-lib/aws-route53-targets";
 import { DNS_APEX, defaultFormsCorsOrigin, defaultFormsFromAddress, isAddressAtDomain } from "@fjall/util";
+import { hasDeployableContent } from "@fjall/util/staticSiteOutput";
 import { StorageFactory } from "./storage.js";
 import { CdnFactory } from "./cdn.js";
 import { SecurityHeadersPolicy } from "../../resources/aws/cdn/index.js";
@@ -48,6 +51,22 @@ const FORMS_DEFAULTS = {
     MEMORY_MB: 256,
     MAX_CONCURRENCY: 5
 };
+/**
+ * HSTS for a site that never asked for it.
+ *
+ * `SecurityHeadersPolicy` defaults to includeSubdomains + preload, which is
+ * the right posture for an operator who chose it and the wrong one to apply
+ * on the user's behalf: both directives have a blast radius beyond this
+ * distribution. includeSubdomains binds every subdomain of the apex — a
+ * sibling host on plain HTTP becomes unreachable — and preload is effectively
+ * one-way, since removal from the browser preload list ships on a release
+ * train measured in months. The max-age is unchanged; only the two
+ * out-of-scope directives are withheld until asked for.
+ */
+const UNREQUESTED_HSTS = {
+    includeSubdomains: false,
+    preload: false
+};
 /** Record label relative to the zone — DNS_APEX for the apex. */
 function recordLabelFor(domain, zoneName) {
     if (domain === zoneName)
@@ -75,11 +94,15 @@ export class StaticSite extends Construct {
         this.pascalName = toPascalCase(props.name);
         this.registerManifest();
         this.validateProps();
-        this.createBucketAndDeployment();
+        this.createBucket();
         // Forms must exist before the CDN — createCdn wires the /api/contact*
         // behaviour to the forms Function URL host (§15).
         this.createFormsEndpoint();
         this.createCdn();
+        // Assets deploy AFTER the CDN: the deployment invalidates the
+        // distribution post-upload, and the distribution needs the bucket first
+        // (it is the origin) — so the order is bucket → CDN → deployment.
+        this.deploySiteAssets();
         this.createDnsRecord();
         this.exportPatternOutputs();
     }
@@ -109,16 +132,58 @@ export class StaticSite extends Construct {
                 "and may be any address.");
         }
     }
-    createBucketAndDeployment() {
-        const deploymentSource = resolve(this.props.source, this.props.build.outputDir);
+    createBucket() {
+        // No `deployment` here — assets deploy via deploySiteAssets() once the
+        // distribution exists, so the upload can invalidate it.
         this._bucket = this.app.addStorage(StorageFactory.build(`${this.pascalName}Site`, {
-            stackPlacement: "cdn",
-            deployment: {
-                source: deploymentSource,
-                prune: true
-            }
+            stackPlacement: "cdn"
         }));
     }
+    deploySiteAssets() {
+        const deploymentSource = resolve(this.props.source, this.props.build.outputDir);
+        const invalidate = this.props.cdn?.invalidateOnDeploy ?? true;
+        this.assertSourceExists(deploymentSource);
+        this.assertSourceHasContent(deploymentSource);
+        this._bucket.deployAssets({ source: deploymentSource, prune: true }, invalidate ? this._cdn.getDistribution() : undefined);
+    }
+    /**
+     * Refuse to synthesise a site whose build output directory is not there.
+     *
+     * Ordered before the emptiness gate because that gate READS the directory:
+     * without this, `readdirSync` throws a bare `ENOENT` naming an absolute
+     * path, which is the least useful form of exactly the diagnosis its sibling
+     * spells out. A mis-set `build.outputDir` is the common cause and the one
+     * the message names.
+     */
+    assertSourceExists(deploymentSource) {
+        if (existsSync(deploymentSource))
+            return;
+        throw new Error(`Static site '${this.props.name}' has nothing to deploy: the build ` +
+            `output directory '${deploymentSource}' does not exist. Run the ` +
+            "build before deploying, or check that 'build.outputDir' names the " +
+            "directory the build actually writes to.");
+    }
+    /**
+     * Refuse to synthesise a pruning upload from an empty build output.
+     *
+     * The upload prunes, so an empty source does not deploy nothing — it
+     * deletes every object already in the bucket, taking the live site down.
+     * A build that creates its output directory and then fails to write into
+     * it exits 0 and looks identical to a successful one, so presence alone is
+     * not proof.
+     *
+     * `staticSiteBuilder` makes the same check at deploy time through the same
+     * helper, so the two verdicts cannot drift.
+     */
+    assertSourceHasContent(deploymentSource) {
+        if (hasDeployableContent(deploymentSource))
+            return;
+        throw new Error(`Static site '${this.props.name}' has nothing to deploy: the build ` +
+            `output directory '${deploymentSource}' is empty. The upload prunes, ` +
+            "so deploying it would delete the site's current contents. Run the " +
+            "build before deploying, or check that 'build.outputDir' names the " +
+            "directory the build actually writes to.");
+    }
     createFormsEndpoint() {
         const forms = this.props.forms;
         if (!forms)
@@ -171,6 +236,10 @@ export class StaticSite extends Construct {
         if (this.props.security?.headers === true) {
             this._headersPolicy = new SecurityHeadersPolicy(this, `${this.pascalName}Headers`, {
                 comment: `Security headers for ${this.props.name}`,
+                // `??`, not a conditional spread: an omitted `hsts` must resolve to
+                // the scoped default, and spreading would hand the decision back to
+                // the wrapper's aggressive one.
+                hsts: this.props.security.hsts ?? UNREQUESTED_HSTS,
                 ...(this.props.security.contentSecurityPolicy !== undefined && {
                     contentSecurityPolicy: this.props.security.contentSecurityPolicy
                 })
@@ -189,9 +258,15 @@ export class StaticSite extends Construct {
             // routing: "directory" — the default cannot protect it.
             routing: this.props.routing ?? "multipage",
             cachePolicy: "CACHING_OPTIMIZED",
-            priceClass: "PriceClass_100",
+            // Default NA+Europe-only: the cheapest class, and right for most
+            // sites. An audience elsewhere (e.g. Australia) should set
+            // cdn.priceClass — see StaticSiteCdnConfig.
+            priceClass: this.props.cdn?.priceClass ?? "PriceClass_100",
             domainNames,
             certificate,
+            ...(this.props.accessGate !== undefined && {
+                accessGate: this.props.accessGate
+            }),
             ...(this._headersPolicy && {
                 responseHeadersPolicy: this._headersPolicy.getPolicy()
             }),
@@ -304,4 +379,7 @@ export class StaticSite extends Construct {
     getFormsFunction() {
         return this._formsFunction;
     }
+    getResponseHeadersPolicy() {
+        return this._headersPolicy;
+    }
 }

package/dist/lib/patterns/aws/storage.d.ts

@@ -1,8 +1,9 @@
 import { Construct } from "constructs";
-import { type IBucket, type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
+import { type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
+import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import type App from "../../app.js";
-import { BucketDeployment, type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
+import { BucketDeployment, S3Bucket, type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
 import { type IStorage } from "./interfaces/storage.js";
 import { type IStorageConnector } from "./interfaces/connector.js";
@@ -68,11 +69,35 @@ export declare function validateStorageProps(props: S3Props): void;
 export declare class Storage extends Construct implements IStorage, IStorageConnector {
     readonly connectorType: "storage";
     private readonly bucket;
-    private readonly bucketDeployment?;
+    private bucketDeployment?;
     constructor(scope: Construct, id: string, props: S3Props);
+    /**
+     * Upload assets to the bucket AFTER construction — for composition orders
+     * where the deployment must reference a construct that does not exist yet
+     * when the bucket is built. The static-site pattern is the canonical case:
+     * the CDN needs the bucket as its origin, and the deployment needs the
+     * distribution for its post-upload invalidation, so the pattern builds
+     * bucket → CDN → deployment. Hand-composed sites hit the same ordering and
+     * can call this directly with `cdn.getDistribution()`.
+     *
+     * A bucket deploys one asset set: calling this when a deployment already
+     * exists (constructor `deployment` config, or a prior call) throws rather
+     * than stacking a second BucketDeployment whose prune semantics would
+     * fight the first.
+     *
+     * @param distribution When set, the deployment invalidates it (`/*`) after
+     *   upload, so the new assets are served immediately instead of after the
+     *   cache TTL (up to 24h) expires.
+     */
+    deployAssets(config: S3DeploymentConfig, distribution?: IDistribution): BucketDeployment;
     private createDeployment;
     private addOutputs;
-    getBucket(): IBucket;
+    /**
+     * The concrete bucket (narrowed from `IStorage`'s `IBucket`), so
+     * mutating escape hatches — `addLifecycleRule`, `addCorsRule` — are
+     * reachable without a cast.
+     */
+    getBucket(): S3Bucket;
     getBucketName(): string;
     getBucketArn(): string;
     getBucketDomainName(): string;

package/dist/lib/patterns/aws/storage.js

@@ -88,11 +88,39 @@ export class Storage extends Construct {
             ...(removalPolicy !== undefined && { removalPolicy })
         });
         if (props.deployment) {
-            this.bucketDeployment = this.createDeployment(id, props.deployment);
+            this.bucketDeployment = this.createDeployment(props.deployment);
         }
         this.addOutputs(id);
     }
-    createDeployment(id, config) {
+    /**
+     * Upload assets to the bucket AFTER construction — for composition orders
+     * where the deployment must reference a construct that does not exist yet
+     * when the bucket is built. The static-site pattern is the canonical case:
+     * the CDN needs the bucket as its origin, and the deployment needs the
+     * distribution for its post-upload invalidation, so the pattern builds
+     * bucket → CDN → deployment. Hand-composed sites hit the same ordering and
+     * can call this directly with `cdn.getDistribution()`.
+     *
+     * A bucket deploys one asset set: calling this when a deployment already
+     * exists (constructor `deployment` config, or a prior call) throws rather
+     * than stacking a second BucketDeployment whose prune semantics would
+     * fight the first.
+     *
+     * @param distribution When set, the deployment invalidates it (`/*`) after
+     *   upload, so the new assets are served immediately instead of after the
+     *   cache TTL (up to 24h) expires.
+     */
+    deployAssets(config, distribution) {
+        if (this.bucketDeployment !== undefined) {
+            throw new Error(`Storage '${this.node.id}' already has a bucket deployment — a ` +
+                "bucket deploys one asset set. Pass everything in one " +
+                "deployment config instead of calling deployAssets twice (or " +
+                "combining it with the constructor's `deployment`).");
+        }
+        this.bucketDeployment = this.createDeployment(config, distribution);
+        return this.bucketDeployment;
+    }
+    createDeployment(config, distribution) {
         const cacheControlHeaders = [];
         if (config.cacheControl?.maxAge !== undefined) {
             cacheControlHeaders.push(CacheControl.maxAge(Duration.seconds(config.cacheControl.maxAge)));
@@ -100,12 +128,16 @@ export class Storage extends Construct {
         if (config.cacheControl?.immutable) {
             cacheControlHeaders.push(CacheControl.immutable());
         }
-        return new BucketDeployment(this, `${id}Deployment`, {
+        return new BucketDeployment(this, `${this.node.id}Deployment`, {
             sources: [Source.asset(config.source)],
             destinationBucket: this.bucket,
             prune: config.prune ?? true,
             ...(cacheControlHeaders.length > 0 && {
                 cacheControl: cacheControlHeaders
+            }),
+            ...(distribution !== undefined && {
+                distribution,
+                distributionPaths: ["/*"]
             })
         });
     }
@@ -124,6 +156,11 @@ export class Storage extends Construct {
             description: `S3 Bucket Name for ${id}`
         });
     }
+    /**
+     * The concrete bucket (narrowed from `IStorage`'s `IBucket`), so
+     * mutating escape hatches — `addLifecycleRule`, `addCorsRule` — are
+     * reachable without a cast.
+     */
     getBucket() {
         return this.bucket;
     }

package/dist/lib/patterns/aws/targets/fjallTargets.d.ts

@@ -23,12 +23,18 @@ export declare function fjallApp(appName: string, computeName?: string): FjallAl
 /**
  * Target helper for a Fjall CloudFront-fronted app.
  *
- * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`
- * — emitted by every `CloudFrontDistribution` given an `appName` (the
- * `CdnFactory.build` path fills it from the App). Naming an app with no such
- * export fails at CloudFormation execution, exactly as `fjallApp` documents.
+ * With no `cdnName`, requires the CDN stack to publish export
+ * `${safeApp}CdnDistributionDomainName` — which `App.synth()` emits only for
+ * an app fronting exactly ONE distribution, since "the app's CDN" names
+ * nothing otherwise. Pass `cdnName` for an app with several (one per
+ * static-site pattern, plus any added by `fjall add cdn`); that name
+ * (`${safeApp}-${safeCdn}-CdnDistributionDomainName`) is emitted
+ * unconditionally per distribution.
+ *
+ * Naming an app that has no matching export fails at CloudFormation execution
+ * with "No export named … found", after synth and every unit test pass.
  */
-export declare function fjallCdn(appName: string): FjallAliasTarget;
+export declare function fjallCdn(appName: string, cdnName?: string): FjallAliasTarget;
 /**
  * Target helper for a Fjall S3 static-site bucket.
  *

package/dist/lib/patterns/aws/targets/fjallTargets.js

@@ -25,16 +25,23 @@ export function fjallApp(appName, computeName) {
 /**
  * Target helper for a Fjall CloudFront-fronted app.
  *
- * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`
- * — emitted by every `CloudFrontDistribution` given an `appName` (the
- * `CdnFactory.build` path fills it from the App). Naming an app with no such
- * export fails at CloudFormation execution, exactly as `fjallApp` documents.
+ * With no `cdnName`, requires the CDN stack to publish export
+ * `${safeApp}CdnDistributionDomainName` — which `App.synth()` emits only for
+ * an app fronting exactly ONE distribution, since "the app's CDN" names
+ * nothing otherwise. Pass `cdnName` for an app with several (one per
+ * static-site pattern, plus any added by `fjall add cdn`); that name
+ * (`${safeApp}-${safeCdn}-CdnDistributionDomainName`) is emitted
+ * unconditionally per distribution.
+ *
+ * Naming an app that has no matching export fails at CloudFormation execution
+ * with "No export named … found", after synth and every unit test pass.
  */
-export function fjallCdn(appName) {
-    const resolved = resolveCdnTarget(appName);
+export function fjallCdn(appName, cdnName) {
+    const resolved = resolveCdnTarget(appName, cdnName);
     return {
         kind: "cdn",
         appName,
+        ...(cdnName !== undefined && { cdnName }),
         bind(record, zone) {
             return resolved.bind(record, zone);
         }

package/dist/lib/patterns/aws/targets/targetResolution.d.ts

@@ -46,7 +46,7 @@ export declare function resolveEcsTarget(appName: string, computeName?: string):
  * defaults that to `<App>Cdn`). The CloudFront hosted-zone id is the globally
  * fixed `Z2FDTNDATAQYW2`.
  */
-export declare function resolveCdnTarget(appName: string): IAliasRecordTarget;
+export declare function resolveCdnTarget(appName: string, cdnName?: string): IAliasRecordTarget;
 /**
  * Resolve a Fjall S3 static-site bucket to an `IAliasRecordTarget`.
  *

package/dist/lib/patterns/aws/targets/targetResolution.js

@@ -62,8 +62,8 @@ export function resolveEcsTarget(appName, computeName) {
  * defaults that to `<App>Cdn`). The CloudFront hosted-zone id is the globally
  * fixed `Z2FDTNDATAQYW2`.
  */
-export function resolveCdnTarget(appName) {
-    const dnsName = Fn.importValue(cdnDomainExportName(appName));
+export function resolveCdnTarget(appName, cdnName) {
+    const dnsName = Fn.importValue(cdnDomainExportName(appName, cdnName));
     return buildAliasTarget(dnsName, CLOUDFRONT_HOSTED_ZONE_ID);
 }
 /**

package/dist/lib/resources/aws/cdn/cloudFront.d.ts

@@ -1,4 +1,5 @@
 import { Construct } from "constructs";
+import { type CloudFrontPriceClass } from "@fjall/util";
 import { Distribution, type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-cloudfront";
 import { type IBucket } from "aws-cdk-lib/aws-s3";
 import { type IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
@@ -59,7 +60,7 @@ export interface CloudFrontDistributionProps {
     comment?: string;
     enableLogging?: boolean;
     logBucket?: IBucket;
-    priceClass?: "PriceClass_100" | "PriceClass_200" | "PriceClass_All";
+    priceClass?: CloudFrontPriceClass;
     /** Adds a CloudFront Function to copy the viewer Host header into X-Forwarded-Host.
      * Required when the origin is a Lambda Function URL or ALB behind CloudFront,
      * because AllViewerExceptHostHeader replaces Host with the origin domain. */

package/dist/lib/resources/aws/cdn/cloudFront.js

@@ -1,6 +1,7 @@
 import { Construct } from "constructs";
 import { CfnOutput, Names, Stack } from "aws-cdk-lib";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { registerCdnAliasTarget } from "../../../utils/cdnAliasTargetRegistry.js";
 import { cdnDomainExportName } from "@fjall/util";
 import { Distribution, PriceClass, ViewerProtocolPolicy, CachePolicy, OriginRequestPolicy, AllowedMethods, OriginProtocolPolicy, Function as CloudFrontFunction, FunctionCode, FunctionRuntime, FunctionEventType, OriginAccessIdentity, S3OriginAccessControl } from "aws-cdk-lib/aws-cloudfront";
 import { S3BucketOrigin, LoadBalancerV2Origin, HttpOrigin } from "aws-cdk-lib/aws-cloudfront-origins";
@@ -111,12 +112,23 @@ export class CloudFrontDistribution extends Construct {
             logBucket: props.logBucket,
             priceClass: this.resolvePriceClass(props.priceClass)
         });
+        // The CDN-qualified export is unconditional and always unique, so an app
+        // fronting several distributions stays deployable. The unqualified
+        // app-level export is emitted once from `App.synth()`, and only when the
+        // app has exactly one CDN — see `cdnAliasTargetRegistry`.
+        const aliasAppName = props.appName ?? id;
         new CfnOutput(this, `${outputName}DistributionDomainName`, {
             key: `${outputName}DistributionDomainName`,
-            exportName: cdnDomainExportName(props.appName ?? id),
+            exportName: cdnDomainExportName(aliasAppName, id),
             value: this.distribution.distributionDomainName,
             description: `CloudFront distribution domain name for ${id}`
         });
+        registerCdnAliasTarget({
+            appName: aliasAppName,
+            cdnName: id,
+            scope: this,
+            domainName: this.distribution.distributionDomainName
+        });
         new CfnOutput(this, `${outputName}DistributionId`, {
             key: `${outputName}DistributionId`,
             value: this.distribution.distributionId,

package/dist/lib/utils/cdnAliasTargetRegistry.d.ts

@@ -0,0 +1,48 @@
+import type { Construct } from "constructs";
+/**
+ * The app-level half of the `Domain` CloudFront alias-target contract.
+ *
+ * Sibling of {@link ./albAliasTargetRegistry.ts}, and deliberately the same
+ * shape: `fjallCdn(appName)` resolves `<App>CdnDistributionDomainName` from a
+ * *different* stack, so the name has to be derivable from the app name alone —
+ * the Domain stack cannot see how many distributions the app has. But an app
+ * may legitimately front several: one per static-site pattern, plus any CDN
+ * added directly.
+ *
+ * Emitting the app-keyed export from each of them produces the identical
+ * `Outputs` entry N times and CloudFormation rejects the entire template ("The
+ * Outputs section contains duplicate Export names") — the same failure the ALB
+ * family hit on 2026-08-09, and the reason two static sites could not live in
+ * one app until this registry existed.
+ *
+ * So the two halves are split by who can answer the question:
+ *
+ *   - Each distribution emits its own `<App>-<Cdn>-CdnDistributionDomainName`
+ *     unconditionally. Always unique, always present, addressable as
+ *     `fjallCdn(app, cdn)`.
+ *   - The App emits the unqualified `<App>CdnDistributionDomainName` at synth
+ *     time, and ONLY when the app registered exactly one distribution — the
+ *     sole case where "the app's CDN" names one thing.
+ *
+ * Two or more and no app-level export is written. A `Domain` using the bare
+ * `fjallCdn(app)` then fails at CloudFormation with "No export named
+ * <App>CdnDistributionDomainName found", which names the missing export and is
+ * fixed by naming the distribution. Picking one of N silently would deploy a
+ * domain pointing at an arbitrary distribution, and would keep working right
+ * up until the registration order changed.
+ */
+export interface CdnAliasTargetRegistration {
+    readonly appName: string;
+    readonly cdnName: string;
+    /** Stack-attached scope the app-level `CfnOutput` is emitted into. */
+    readonly scope: Construct;
+    readonly domainName: string;
+}
+export declare function registerCdnAliasTarget(registration: CdnAliasTargetRegistration): void;
+/**
+ * Emit the unqualified app-level alias export for every app in this tree that
+ * registered exactly one distribution. Call once, from `App.synth()`, before
+ * `super.synth()` — the construct tree is still mutable there, and that is the
+ * same window `applyTagsAspect()` and `emitAppLevelAlbAliasExports()` use.
+ */
+export declare function emitAppLevelCdnAliasExports(root: Construct): void;

package/dist/lib/utils/cdnAliasTargetRegistry.js

@@ -0,0 +1,63 @@
+import { CfnOutput } from "aws-cdk-lib";
+import { cdnDomainExportName } from "@fjall/util";
+import { toPascalCase } from "./capitaliseString.js";
+import { FjallLogger } from "./validationLogger.js";
+/**
+ * Keyed on the construct-tree root (the `App`) so two apps synthesised in one
+ * process — the platform and organisation stacks do this — never see each
+ * other's registrations. Weak so a discarded tree does not leak.
+ */
+const registryByRoot = new WeakMap();
+export function registerCdnAliasTarget(registration) {
+    const root = registration.scope.node.root;
+    const existing = registryByRoot.get(root);
+    if (existing === undefined) {
+        registryByRoot.set(root, [registration]);
+        return;
+    }
+    existing.push(registration);
+}
+/**
+ * Emit the unqualified app-level alias export for every app in this tree that
+ * registered exactly one distribution. Call once, from `App.synth()`, before
+ * `super.synth()` — the construct tree is still mutable there, and that is the
+ * same window `applyTagsAspect()` and `emitAppLevelAlbAliasExports()` use.
+ */
+export function emitAppLevelCdnAliasExports(root) {
+    const registrations = registryByRoot.get(root);
+    if (registrations === undefined)
+        return;
+    // `App.synth()` is re-entrant (CDK caches the assembly and returns it), and
+    // a second emission would collide on the output's construct id. Draining
+    // makes the call idempotent.
+    registryByRoot.delete(root);
+    const byApp = new Map();
+    for (const registration of registrations) {
+        const forApp = byApp.get(registration.appName);
+        if (forApp === undefined) {
+            byApp.set(registration.appName, [registration]);
+        }
+        else {
+            forApp.push(registration);
+        }
+    }
+    for (const [appName, forApp] of byApp) {
+        const only = forApp.length === 1 ? forApp[0] : undefined;
+        if (only === undefined) {
+            const cdnNames = forApp.map((r) => r.cdnName).join(", ");
+            FjallLogger.warn(`App '${appName}' fronts ${String(forApp.length)} CloudFront distributions (${cdnNames}), ` +
+                `so no app-level '${cdnDomainExportName(appName)}' export was emitted — ` +
+                `'the app's CDN' would be ambiguous. Target a specific one with ` +
+                `fjallCdn('${appName}', '<cdn>') in your Domain records.`);
+            continue;
+        }
+        // Output logical ids are alphanumeric-only; the app name is not.
+        const logicalId = `${toPascalCase(appName)}AppCdn`;
+        new CfnOutput(only.scope, `${logicalId}DistributionDomainName`, {
+            key: `${logicalId}DistributionDomainName`,
+            exportName: cdnDomainExportName(appName),
+            value: only.domainName,
+            description: `CloudFront distribution domain name for ${appName} (sole CDN; consumed by fjallCdn('${appName}'))`
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "24.0.0",
+  "version": "26.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -68,21 +68,20 @@
     "@aws-sdk/client-identitystore": "^3.1098.0",
     "@aws-sdk/client-sesv2": "^3.1098.0",
     "@peculiar/x509": "2.0.0",
-    "@types/aws-lambda": "^8.10.162",
     "@types/node": "^26.1.2",
-    "@typescript-eslint/eslint-plugin": "^8.65.0",
-    "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",
     "prettier": "^3.9.6",
     "reflect-metadata": "^0.2.2",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^24.0.0",
-    "@fjall/util": "^24.0.0",
-    "constructs": "^10.7.2"
+    "@fjall/generator": "^26.0.0",
+    "@fjall/util": "^26.0.0",
+    "constructs": "^10.7.2",
+    "zod": "^4.4.3"
   },
   "overrides": {
     "@smithy/core": "2.5.5"