@fjall/components-infrastructure 25.0.0 → 27.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/computeEcsTypes.d.ts

@@ -1070,9 +1070,11 @@ export interface EcsComputeProps {
     /**
      * CloudWatch Container Insights (default off). Enabling it bills
      * ~$0.30/metric-month of custom `ECS/ContainerInsights` metrics per cluster
-     * plus performance-log ingestion; nothing in the constructs consumes that
-     * namespace (alarms sit on `AWS/ECS` and `Fjall/ECS`), so it is an explicit
-     * opt-in for clusters whose operators read the per-task console breakdown.
+     * plus performance-log ingestion, and also arms the per-service
+     * `RunningTaskCount` liveness alarms (`ecsAlarms.ts` gates them on this
+     * flag because the metric only exists in `ECS/ContainerInsights`).
+     * Scale-to-zero services should pair it with
+     * `alarms: { runningTasksMinimum: 0 }` or they idle in ALARM.
      */
     containerInsights?: true;
     /** Application ID for alarm tagging (used by webhook to map alarms to applications). */

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,6 +17,7 @@
 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";
@@ -385,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

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

@@ -50,6 +50,29 @@ export declare class StaticSite extends Construct implements IStaticSite {
     private validateProps;
     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;

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

@@ -27,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";
@@ -49,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)
@@ -124,8 +142,48 @@ export class StaticSite extends Construct {
     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)
@@ -178,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
                 })

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.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": "25.0.0",
+  "version": "27.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -68,20 +68,18 @@
     "@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": "^25.0.0",
-    "@fjall/util": "^25.0.0",
+    "@fjall/generator": "^27.0.0",
+    "@fjall/util": "^27.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },