@fjall/components-infrastructure 23.0.0 → 25.0.0

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

@@ -55,6 +55,21 @@ export interface AccountProps extends StackProps {
      */
     machineTrustMode?: MachineTrustMode;
 }
+/**
+ * `fjall:description` values for the governance tiers — the same user-facing
+ * gold-plating the domain-side constructs carry, so a governance stack's
+ * resources explain themselves in the console exactly like a zone or
+ * certificate does. Keyed by `organisationType` so each tier self-describes
+ * from ONE stamp in this base class.
+ *
+ * CHARSET CONTRACT: every value must stay inside the AWS tag-value pattern
+ * `^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$` — no commas. IAM roles and nested-stack
+ * resources (AWS::CloudFormation::Stack) validate tag values against it, so
+ * one comma aborts the whole governance deploy at changeset creation ("Tag
+ * [fjall:description] contained invalid characters"). Exported so the
+ * governanceTagging suite pins the contract for every tier.
+ */
+export declare const GOVERNANCE_TIER_DESCRIPTIONS: Record<OrganisationType, string>;
 export declare class Account extends Stack {
     readonly organisationType: OrganisationType;
     protected readonly resolvedRegion: string;

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

@@ -22,9 +22,16 @@ import { InspectorEnablement } from "../../config/aws/inspectorEnablement.js";
  * resources explain themselves in the console exactly like a zone or
  * certificate does. Keyed by `organisationType` so each tier self-describes
  * from ONE stamp in this base class.
+ *
+ * CHARSET CONTRACT: every value must stay inside the AWS tag-value pattern
+ * `^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$` — no commas. IAM roles and nested-stack
+ * resources (AWS::CloudFormation::Stack) validate tag values against it, so
+ * one comma aborts the whole governance deploy at changeset creation ("Tag
+ * [fjall:description] contained invalid characters"). Exported so the
+ * governanceTagging suite pins the contract for every tier.
  */
-const GOVERNANCE_TIER_DESCRIPTIONS = {
-    organisation: "Fjall-managed organisation governance: org root, member accounts and organisation-wide policy",
+export const GOVERNANCE_TIER_DESCRIPTIONS = {
+    organisation: "Fjall-managed organisation governance: org root and member accounts under organisation-wide policy",
     platform: "Fjall-managed platform governance: shared platform services and CI trust",
     account: "Fjall-managed account governance: account security and operations baseline"
 };

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/pattern.d.ts

@@ -23,8 +23,9 @@ 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.
@@ -422,6 +423,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 +503,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 +595,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 +609,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,8 @@ 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;
     private createFormsEndpoint;
     private createCdn;
     private buildBehaviours;
@@ -57,4 +60,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)
@@ -75,11 +76,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 +114,18 @@ 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._bucket.deployAssets({ source: deploymentSource, prune: true }, invalidate ? this._cdn.getDistribution() : undefined);
+    }
     createFormsEndpoint() {
         const forms = this.props.forms;
         if (!forms)
@@ -189,9 +196,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 +317,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/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/utils/validationLogger.js

@@ -6,17 +6,8 @@
 import { appendFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { fjallLogDir } from "@fjall/util";
-import { FileRotator, LOG_ROTATION_DEFAULTS } from "@fjall/util/logRotation";
+import { FileRotator, resolveLogRotationBudget } from "@fjall/util/logRotation";
 const LOG_FILENAME = "infrastructure.jsonl";
-/**
- * Shared with the CLI's own logs, so this file cannot outgrow the budget
- * the rest of Fjall's logging keeps to. Without it this log had no bound of
- * any kind: it is appended to on every CDK synth, and one developer machine
- * reached 267MB of it inside a single release cycle.
- */
-const rotator = new FileRotator({
-    maxFiles: LOG_ROTATION_DEFAULTS.MAX_FILES
-});
 /**
  * Write a log entry to the infrastructure JSONL file
  */
@@ -36,7 +27,14 @@ function writeToLog(level, message) {
             source: "cdk-subprocess"
         });
         const logPath = join(logDir, LOG_FILENAME);
-        rotator.rotateIfNeeded(logPath, LOG_ROTATION_DEFAULTS.MAX_FILE_SIZE);
+        // Budget shared with the CLI's own logs — same defaults, same
+        // FJALL_LOG_MAX_SIZE / FJALL_LOG_MAX_FILES overrides — so this file
+        // cannot outgrow what the rest of Fjall's logging keeps to. It reached
+        // 267MB on one developer machine when it had no bound. Resolved per
+        // write for the same reason as the log dir above: CDK imports this
+        // module long before a command's environment is readable.
+        const { maxFileSize, maxFiles } = resolveLogRotationBudget();
+        new FileRotator({ maxFiles }).rotateIfNeeded(logPath, maxFileSize);
         appendFileSync(logPath, entry + "\n");
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,9 +80,10 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^23.0.0",
-    "@fjall/util": "^23.0.0",
-    "constructs": "^10.7.2"
+    "@fjall/generator": "^25.0.0",
+    "@fjall/util": "^25.0.0",
+    "constructs": "^10.7.2",
+    "zod": "^4.4.3"
   },
   "overrides": {
     "@smithy/core": "2.5.5"