@fjall/components-infrastructure 2.27.0 → 2.30.0

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

@@ -0,0 +1,59 @@
+/**
+ * Static-site Pattern.
+ *
+ * Serves a pre-built folder of files from a private S3 bucket behind CloudFront
+ * (OAC), with clean URLs, security headers, an optional custom domain, and an
+ * optional contact-form endpoint (Lambda Function URL → SES, CloudFront-fronted).
+ *
+ * Resources created:
+ * - Private S3 bucket + BucketDeployment (asset upload)
+ * - CloudFront distribution (OAC, clean-URL function, security-headers policy)
+ * - ACM certificate + Route53 alias record (when `domain` is set)
+ * - Contact-form Lambda + Function URL (when `forms` is set)
+ *
+ * @example
+ * const site = app.addPattern(PatternFactory.build("LbexcSite", {
+ *   type: "staticsite",
+ *   name: "lbexc",
+ *   source: "../../lbexc-static-export",
+ *   build: { command: "npm run build", outputDir: "out" },
+ *   routing: "multipage",
+ *   security: { headers: true },
+ *   domain: "lbexc.com",
+ *   forms: { to: "hello@lbexc.com", corsOrigin: "https://lbexc.com" }
+ * }));
+ */
+import { Construct } from "constructs";
+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 { LambdaFunction } from "../../resources/aws/compute/index.js";
+/**
+ * Static-site pattern implementation.
+ */
+export declare class StaticSite extends Construct implements IStaticSite {
+    readonly patternType: "staticsite";
+    private readonly app;
+    private readonly props;
+    private readonly pascalName;
+    private _bucket;
+    private _cdn;
+    private _formsFunction?;
+    private _headersPolicy?;
+    private _resolvedDomain;
+    constructor(scope: Construct, id: string, app: App, props: IStaticSiteProps);
+    private registerManifest;
+    private validateProps;
+    private createBucketAndDeployment;
+    private createFormsEndpoint;
+    private createCdn;
+    private buildBehaviours;
+    private resolveDomainConfig;
+    private resolveSimpleDomain;
+    private createDnsRecord;
+    private exportPatternOutputs;
+    getBucket(): Storage;
+    getCdn(): Cdn;
+    getFormsFunction(): LambdaFunction | undefined;
+}

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

@@ -0,0 +1,307 @@
+/**
+ * Static-site Pattern.
+ *
+ * Serves a pre-built folder of files from a private S3 bucket behind CloudFront
+ * (OAC), with clean URLs, security headers, an optional custom domain, and an
+ * optional contact-form endpoint (Lambda Function URL → SES, CloudFront-fronted).
+ *
+ * Resources created:
+ * - Private S3 bucket + BucketDeployment (asset upload)
+ * - CloudFront distribution (OAC, clean-URL function, security-headers policy)
+ * - ACM certificate + Route53 alias record (when `domain` is set)
+ * - Contact-form Lambda + Function URL (when `forms` is set)
+ *
+ * @example
+ * const site = app.addPattern(PatternFactory.build("LbexcSite", {
+ *   type: "staticsite",
+ *   name: "lbexc",
+ *   source: "../../lbexc-static-export",
+ *   build: { command: "npm run build", outputDir: "out" },
+ *   routing: "multipage",
+ *   security: { headers: true },
+ *   domain: "lbexc.com",
+ *   forms: { to: "hello@lbexc.com", corsOrigin: "https://lbexc.com" }
+ * }));
+ */
+import { Construct } from "constructs";
+import { CfnOutput, Fn, Stack } from "aws-cdk-lib";
+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 { Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { HostedZone } from "aws-cdk-lib/aws-route53";
+import { CloudFrontTarget } from "aws-cdk-lib/aws-route53-targets";
+import { DNS_APEX, defaultFormsCorsOrigin, defaultFormsFromAddress, isAddressAtDomain } from "@fjall/util";
+import { StorageFactory } from "./storage.js";
+import { CdnFactory } from "./cdn.js";
+import { SecurityHeadersPolicy } from "../../resources/aws/cdn/index.js";
+import { LambdaFunction } from "../../resources/aws/compute/index.js";
+import { DomainCertificate, AliasRecord } from "../../resources/aws/networking/index.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FORMS_ASSET_DIR = resolve(__dirname, "../../lambda-assets/static-site-forms/asset");
+const FORMS_DEFAULTS = {
+    RUNTIME: Runtime.NODEJS_22_X,
+    ARCHITECTURE: Architecture.ARM_64,
+    TIMEOUT_SECONDS: 10,
+    MEMORY_MB: 256,
+    MAX_CONCURRENCY: 5
+};
+/** Extract the registrable root (e.g. "a.b.example.com" → "example.com"). */
+function extractRootDomain(domain) {
+    const parts = domain.split(".");
+    return parts.length > 2 ? parts.slice(-2).join(".") : domain;
+}
+/** Record label relative to the zone — DNS_APEX for the apex. */
+function recordLabelFor(domain, zoneName) {
+    if (domain === zoneName)
+        return DNS_APEX;
+    const suffix = `.${zoneName}`;
+    return domain.endsWith(suffix) ? domain.slice(0, -suffix.length) : domain;
+}
+/**
+ * Static-site pattern implementation.
+ */
+export class StaticSite extends Construct {
+    patternType = "staticsite";
+    app;
+    props;
+    pascalName;
+    _bucket;
+    _cdn;
+    _formsFunction;
+    _headersPolicy;
+    _resolvedDomain;
+    constructor(scope, id, app, props) {
+        super(scope, id);
+        this.app = app;
+        this.props = props;
+        this.pascalName = toPascalCase(props.name);
+        this.registerManifest();
+        this.validateProps();
+        this.createBucketAndDeployment();
+        // Forms must exist before the CDN — createCdn wires the /api/contact*
+        // behaviour to the forms Function URL host (§15).
+        this.createFormsEndpoint();
+        this.createCdn();
+        this.createDnsRecord();
+        this.exportPatternOutputs();
+    }
+    registerManifest() {
+        const manifestPattern = {
+            type: "staticsite",
+            name: this.props.name,
+            source: this.props.source
+        };
+        this.app.getManifestCollector().setPattern(manifestPattern);
+    }
+    validateProps() {
+        const forms = this.props.forms;
+        if (!forms)
+            return;
+        const domain = this.props.domain;
+        if (!domain) {
+            throw new Error(`Static site '${this.props.name}' has a contact form but no 'domain'. ` +
+                "SES sends only from a verified identity, and the site's domain is " +
+                "the identity this pattern verifies. Set 'domain' alongside 'forms'.");
+        }
+        if (forms.from !== undefined && !isAddressAtDomain(forms.from, domain)) {
+            throw new Error(`Static site '${this.props.name}' sets forms.from to '${forms.from}', ` +
+                `which is not an address at '${domain}'. SES sends only from the ` +
+                `verified domain identity — use noreply@${domain} (the default), or ` +
+                "another address at that domain. 'forms.to' is where submissions go " +
+                "and may be any address.");
+        }
+    }
+    createBucketAndDeployment() {
+        const deploymentSource = resolve(this.props.source, this.props.build.outputDir);
+        this._bucket = this.app.addStorage(StorageFactory.build(`${this.pascalName}Site`, {
+            stackPlacement: "cdn",
+            deployment: {
+                source: deploymentSource,
+                prune: true
+            }
+        }));
+    }
+    createFormsEndpoint() {
+        const forms = this.props.forms;
+        if (!forms)
+            return;
+        // Validated present by validateProps.
+        const domain = this.props.domain;
+        const stack = Stack.of(this);
+        const sesIdentityArn = `arn:aws:ses:${stack.region}:${stack.account}:identity/${domain}`;
+        // The envelope sender must sit at the verified domain; the recipient is
+        // wherever the site owner reads mail. Conflating them makes SES reject
+        // every send the moment `to` is an address SES has never heard of.
+        const contactFrom = forms.from ?? defaultFormsFromAddress(domain);
+        const allowedOrigin = forms.corsOrigin ?? defaultFormsCorsOrigin(domain);
+        this._formsFunction = new LambdaFunction(this, `${this.pascalName}FormsFn`, {
+            code: Code.fromAsset(FORMS_ASSET_DIR),
+            handler: "index.handler",
+            runtime: FORMS_DEFAULTS.RUNTIME,
+            architecture: FORMS_DEFAULTS.ARCHITECTURE,
+            timeout: FORMS_DEFAULTS.TIMEOUT_SECONDS,
+            memorySize: FORMS_DEFAULTS.MEMORY_MB,
+            reservedConcurrentExecutions: forms.maxConcurrency ?? FORMS_DEFAULTS.MAX_CONCURRENCY,
+            lambdaDescription: `Contact-form handler for ${this.props.name}`,
+            roleDescription: `Contact-form send role for ${this.props.name}`,
+            enableFunctionUrl: true,
+            functionUrlAuthType: FunctionUrlAuthType.NONE,
+            functionUrlCors: {
+                allowedOrigins: [allowedOrigin],
+                allowedMethods: [HttpMethod.POST],
+                allowedHeaders: ["content-type"]
+            },
+            environment: {
+                CONTACT_TO: forms.to,
+                CONTACT_FROM: contactFrom,
+                ALLOWED_ORIGIN: allowedOrigin
+            },
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ses:SendEmail"],
+                    resources: [sesIdentityArn],
+                    conditions: {
+                        StringEquals: { "ses:FromAddress": contactFrom }
+                    }
+                })
+            ]
+        });
+    }
+    createCdn() {
+        const { domainNames, certificate } = this.resolveDomainConfig();
+        if (this.props.security?.headers === true) {
+            this._headersPolicy = new SecurityHeadersPolicy(this, `${this.pascalName}Headers`, {
+                comment: `Security headers for ${this.props.name}`,
+                ...(this.props.security.contentSecurityPolicy !== undefined && {
+                    contentSecurityPolicy: this.props.security.contentSecurityPolicy
+                })
+            });
+        }
+        const behaviours = this.buildBehaviours();
+        const cdnProps = {
+            originType: "s3",
+            bucket: this._bucket,
+            originAccess: "oac",
+            defaultRootObject: "index.html",
+            routing: this.props.routing ?? "multipage",
+            cachePolicy: "CACHING_OPTIMIZED",
+            priceClass: "PriceClass_100",
+            domainNames,
+            certificate,
+            ...(this._headersPolicy && {
+                responseHeadersPolicy: this._headersPolicy.getPolicy()
+            }),
+            ...(behaviours.length > 0 && { behaviours })
+        };
+        this._cdn = this.app.addCdn(CdnFactory.build(this.props.name, cdnProps));
+    }
+    buildBehaviours() {
+        const behaviours = [];
+        if (this._formsFunction) {
+            const formsUrl = this._formsFunction.getFunctionUrl();
+            if (!formsUrl) {
+                throw new Error("Forms Function URL unavailable — cannot wire /api/contact behaviour.");
+            }
+            // Extract the Function-URL host (mirrors CdnFactory Lambda-origin idiom):
+            // https://<host>/ → split by "/" → index 2 is the host.
+            const formsHost = Fn.select(2, Fn.split("/", formsUrl));
+            behaviours.push({
+                pathPattern: "/api/contact*",
+                origin: formsHost,
+                allowedMethods: "ALL",
+                cachePolicy: "CACHING_DISABLED"
+            });
+        }
+        behaviours.push(...(this.props.cdn?.behaviours ?? []));
+        return behaviours;
+    }
+    resolveDomainConfig() {
+        if (this._resolvedDomain)
+            return this._resolvedDomain;
+        this._resolvedDomain = this.props.domain
+            ? this.resolveSimpleDomain(this.props.domain)
+            : {
+                domainNames: undefined,
+                certificate: undefined,
+                hostedZone: undefined
+            };
+        return this._resolvedDomain;
+    }
+    resolveSimpleDomain(domain) {
+        if (this.props.managedDomain) {
+            const managed = this.props.managedDomain;
+            const hostedZone = HostedZone.fromHostedZoneAttributes(this, `${this.pascalName}ManagedHostedZone`, {
+                hostedZoneId: Fn.importValue(managed.hostedZoneIdExport),
+                zoneName: managed.zoneName
+            });
+            const certificate = Certificate.fromCertificateArn(this, `${this.pascalName}ManagedCertificate`, Fn.importValue(managed.certificateArnExport));
+            return { domainNames: [domain], certificate, hostedZone };
+        }
+        const rootDomain = extractRootDomain(domain);
+        const hostedZone = HostedZone.fromLookup(this, `${this.pascalName}HostedZone`, { domainName: rootDomain });
+        // Single-stack: the cert is consumed in-stack, so suppress the ARN export
+        // to avoid a collision with a managed-domain/apex stack (§12-I).
+        const domainCert = new DomainCertificate(this, `${this.pascalName}Certificate`, {
+            domainName: domain,
+            hostedZone,
+            exportCertificateArn: false
+        });
+        return {
+            domainNames: [domain],
+            certificate: domainCert.certificate,
+            hostedZone
+        };
+    }
+    createDnsRecord() {
+        if (!this.props.domain)
+            return;
+        const { hostedZone } = this.resolveDomainConfig();
+        if (!hostedZone)
+            return;
+        const zoneName = this.props.managedDomain?.zoneName ??
+            extractRootDomain(this.props.domain);
+        // Alias record lives in the CDN stack (where the distribution is) so there
+        // is no cross-stack cycle back to this pattern node.
+        const cdnStack = this.app.getDefaultCdnStack().getStack();
+        new AliasRecord(cdnStack, `${this.pascalName}AliasRecord`, {
+            zone: hostedZone,
+            zoneName,
+            recordName: recordLabelFor(this.props.domain, zoneName),
+            target: new CloudFrontTarget(this._cdn.getDistribution())
+        });
+    }
+    exportPatternOutputs() {
+        new CfnOutput(this, `${this.pascalName}PatternType`, {
+            key: `${this.pascalName}PatternType`,
+            value: "staticsite",
+            description: `Pattern type for ${this.props.name}`
+        });
+        new CfnOutput(this, `${this.pascalName}PatternName`, {
+            key: `${this.pascalName}PatternName`,
+            value: this.props.name,
+            description: `Pattern name for ${this.props.name}`
+        });
+        new CfnOutput(this, `${this.pascalName}PatternResources`, {
+            key: `${this.pascalName}PatternResources`,
+            value: JSON.stringify({
+                storage: [`${this.props.name}-site`],
+                cdn: this.props.name,
+                ...(this._formsFunction && { forms: `${this.props.name}-forms` })
+            }),
+            description: `Related resource names for pattern ${this.props.name}`
+        });
+    }
+    getBucket() {
+        return this._bucket;
+    }
+    getCdn() {
+        return this._cdn;
+    }
+    getFormsFunction() {
+        return this._formsFunction;
+    }
+}

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

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { Distribution, type ICachePolicy } from "aws-cdk-lib/aws-cloudfront";
+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";
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
@@ -8,6 +8,8 @@ export interface S3OriginConfig {
     type: "s3";
     bucket: IBucket;
     originPath?: string;
+    /** OAI (cross-stack-safe default) or OAC (modern, single-stack only). */
+    originAccess?: "oai" | "oac";
 }
 export interface AlbOriginConfig {
     type: "alb";
@@ -54,6 +56,27 @@ export interface CloudFrontDistributionProps {
     /** Adds access gating to the distribution via a CloudFront Function.
      * Set to false to explicitly disable (or omit). */
     accessGate?: false | AccessGateConfig;
+    /** Object served for a bare `/` request (static sites: "index.html"). */
+    defaultRootObject?: string;
+    /** Rewrites extensionless URLs to `.html`/`/index.html` via a CloudFront
+     * Function. Dynamic `/api/` paths are carved out so POSTs are not rewritten. */
+    cleanUrls?: boolean;
+    /** SPA fallback: 403/404 → `/index.html` @200 for client-side routing. */
+    spaFallback?: boolean;
+    /** Security-headers policy applied to the default + every additional behaviour. */
+    responseHeadersPolicy?: IResponseHeadersPolicy;
+    /**
+     * Origin-request policy for the DEFAULT behaviour. Defaults to
+     * `all-viewer-except-host`, which every distribution has had since before the
+     * static-site pattern — changing the default silently strips
+     * `OriginRequestPolicyId` from live distributions on their next deploy.
+     *
+     * `none` is for an origin that has no use for viewer headers: an S3 origin
+     * serves objects by key and ignores forwarded headers, cookies and query
+     * strings. Additional behaviours always forward (a static site's `/api/*`
+     * Lambda Function URL origin needs the viewer's headers to serve the form).
+     */
+    originRequestPolicy?: "all-viewer-except-host" | "none";
 }
 export declare class CloudFrontDistribution extends Construct {
     readonly id: string;
@@ -61,10 +84,20 @@ export declare class CloudFrontDistribution extends Construct {
     constructor(scope: Construct, id: string, props: CloudFrontDistributionProps);
     /**
      * Build a composable CloudFront Function for VIEWER_REQUEST.
-     * Merges accessGate and forwardHostHeader into a single function
+     * Merges accessGate, forwardHostHeader and cleanUrls into a single function
      * (CloudFront allows only one function per event type).
+     *
+     * ORDER IS LOAD-BEARING. The access gate is emitted first because it is the
+     * only fragment that can reject a request, and a fragment that returns early
+     * ahead of it would silently un-gate whatever paths it short-circuits. The
+     * cleanUrls fragment carves `/api/*` out of the `.html` rewriting — that
+     * carve-out must therefore be a guard around the rewrite, never an early
+     * `return request`, or the whole `/api/*` surface leaves the gate behind it.
      */
     private buildViewerRequestFunction;
+    /** SPA fallback: serve /index.html @200 for 403/404 so client-side routing
+     * handles the path. CloudFront returns 403 (not 404) for missing S3 keys. */
+    private buildSpaErrorResponses;
     private createOrigin;
     private resolveCachePolicy;
     private resolveAllowedMethods;

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

@@ -13,8 +13,9 @@ export class CloudFrontDistribution extends Construct {
         const outputName = toPascalCase(id);
         const defaultOrigin = this.createOrigin(props.defaultOrigin);
         const defaultCachePolicy = this.resolveCachePolicy(props.defaultCachePolicy);
-        // Build composable viewer request function (accessGate + forwardHostHeader)
-        const viewerRequestFunction = this.buildViewerRequestFunction(id, props.forwardHostHeader, props.accessGate);
+        // Build composable viewer request function (accessGate + forwardHostHeader
+        // + cleanUrls)
+        const viewerRequestFunction = this.buildViewerRequestFunction(id, props.forwardHostHeader, props.accessGate, props.cleanUrls);
         const functionAssociations = viewerRequestFunction
             ? [
                 {
@@ -31,9 +32,9 @@ export class CloudFrontDistribution extends Construct {
                     cachePolicy: this.resolveCachePolicy(behaviour.cachePolicy),
                     viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
                     allowedMethods: this.resolveAllowedMethods(behaviour.allowedMethods),
-                    // Forward viewer headers (cookies, auth) to non-S3 origins
-                    ...(behaviour.origin.type !== "s3" && {
-                        originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER
+                    originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+                    ...(props.responseHeadersPolicy !== undefined && {
+                        responseHeadersPolicy: props.responseHeadersPolicy
                     }),
                     ...(functionAssociations !== undefined && { functionAssociations })
                 };
@@ -44,13 +45,22 @@ export class CloudFrontDistribution extends Construct {
                 origin: defaultOrigin,
                 cachePolicy: defaultCachePolicy,
                 viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
-                originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+                ...(props.originRequestPolicy !== "none" && {
+                    originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER
+                }),
                 allowedMethods: this.resolveAllowedMethods(props.defaultAllowedMethods),
+                ...(props.responseHeadersPolicy !== undefined && {
+                    responseHeadersPolicy: props.responseHeadersPolicy
+                }),
                 ...(functionAssociations !== undefined && { functionAssociations })
             },
             additionalBehaviors: Object.keys(additionalBehaviors).length > 0
                 ? additionalBehaviors
                 : undefined,
+            defaultRootObject: props.defaultRootObject,
+            ...(props.spaFallback && {
+                errorResponses: this.buildSpaErrorResponses()
+            }),
             domainNames: props.domainNames,
             certificate: props.certificate,
             comment: props.comment,
@@ -80,43 +90,71 @@ export class CloudFrontDistribution extends Construct {
     }
     /**
      * Build a composable CloudFront Function for VIEWER_REQUEST.
-     * Merges accessGate and forwardHostHeader into a single function
+     * Merges accessGate, forwardHostHeader and cleanUrls into a single function
      * (CloudFront allows only one function per event type).
+     *
+     * ORDER IS LOAD-BEARING. The access gate is emitted first because it is the
+     * only fragment that can reject a request, and a fragment that returns early
+     * ahead of it would silently un-gate whatever paths it short-circuits. The
+     * cleanUrls fragment carves `/api/*` out of the `.html` rewriting — that
+     * carve-out must therefore be a guard around the rewrite, never an early
+     * `return request`, or the whole `/api/*` surface leaves the gate behind it.
      */
-    buildViewerRequestFunction(id, forwardHostHeader, accessGate) {
-        if (!accessGate && !forwardHostHeader) {
+    buildViewerRequestFunction(id, forwardHostHeader, accessGate, cleanUrls) {
+        if (!accessGate && !forwardHostHeader && !cleanUrls) {
             return undefined;
         }
-        let functionBody = "function handler(event) { var request = event.request;";
+        const fragments = [];
         if (accessGate) {
             const credentials = Buffer.from(`${accessGate.username}:${accessGate.password}`).toString("base64");
-            functionBody +=
-                ` var authHeader = request.headers.authorization;` +
-                    ` if (!authHeader || authHeader.value !== "Basic ${credentials}") {` +
-                    ` return {` +
-                    ` statusCode: 401,` +
-                    ` statusDescription: "Unauthorized",` +
-                    ` headers: { "www-authenticate": { value: 'Basic realm="Restricted"' } },` +
-                    ` body: { encoding: "text", data: "Unauthorized" }` +
-                    ` }; }`;
+            fragments.push(` var authHeader = request.headers.authorization;` +
+                ` if (!authHeader || authHeader.value !== "Basic ${credentials}") {` +
+                ` return {` +
+                ` statusCode: 401,` +
+                ` statusDescription: "Unauthorized",` +
+                ` headers: { "www-authenticate": { value: 'Basic realm="Restricted"' } },` +
+                ` body: { encoding: "text", data: "Unauthorized" }` +
+                ` }; }`);
         }
         if (forwardHostHeader) {
-            functionBody +=
-                " request.headers['x-forwarded-host'] = { value: request.headers.host.value };";
+            fragments.push(" request.headers['x-forwarded-host'] = { value: request.headers.host.value };");
         }
-        functionBody += " return request; }";
+        if (cleanUrls) {
+            fragments.push(" var uri = request.uri;" +
+                " if (!uri.startsWith('/api/')) {" +
+                " if (uri.endsWith('/')) { request.uri = uri + 'index.html'; }" +
+                " else { var seg = uri.substring(uri.lastIndexOf('/') + 1);" +
+                " if (seg.indexOf('.') === -1) { request.uri = uri + '.html'; } } }");
+        }
+        const functionBody = "function handler(event) { var request = event.request;" +
+            fragments.join("") +
+            " return request; }";
         return new CloudFrontFunction(this, `${id}ViewerRequestFn`, {
             code: FunctionCode.fromInline(functionBody),
             runtime: FunctionRuntime.JS_2_0
         });
     }
+    /** SPA fallback: serve /index.html @200 for 403/404 so client-side routing
+     * handles the path. CloudFront returns 403 (not 404) for missing S3 keys. */
+    buildSpaErrorResponses() {
+        return [403, 404].map((httpStatus) => ({
+            httpStatus,
+            responseHttpStatus: 200,
+            responsePagePath: "/index.html"
+        }));
+    }
     createOrigin(config) {
         switch (config.type) {
             case "s3":
-                // Using OAI instead of OAC to avoid cross-stack circular dependencies
+                // OAC (single-stack only) is safe when the bucket and distribution live
+                // in the same stack — no cross-stack bucket→CDN policy cycle. Default is
+                // OAI, which avoids that cycle for cross-stack origins.
                 // See: https://github.com/aws/aws-cdk/issues/31462
-                // OAC creates bucket → CDN dependency (bucket policy references distribution)
-                // OAI works across stacks without triggering cyclic dependency errors
+                if (config.originAccess === "oac") {
+                    return S3BucketOrigin.withOriginAccessControl(config.bucket, {
+                        originPath: config.originPath
+                    });
+                }
                 return S3BucketOrigin.withOriginAccessIdentity(config.bucket, {
                     originPath: config.originPath
                 });

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

@@ -1 +1,2 @@
 export * from "./cloudFront.js";
+export * from "./responseHeadersPolicy.js";

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

@@ -1 +1,2 @@
 export * from "./cloudFront.js";
+export * from "./responseHeadersPolicy.js";

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

@@ -0,0 +1,56 @@
+import { type Construct } from "constructs";
+import { ResponseHeadersPolicy as CdkResponseHeadersPolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-cloudfront";
+/**
+ * The Referrer-Policy values CloudFront accepts, as the wire header string.
+ * Mirrors `HeadersReferrerPolicy` (whose enum values ARE these strings) so
+ * consumers pass the readable header value, not the CDK enum member.
+ */
+export type ReferrerPolicyValue = "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url";
+/** HTTP Strict-Transport-Security configuration; `false` opts the header out. */
+export interface HstsConfig {
+    maxAgeDays?: number;
+    includeSubdomains?: boolean;
+    preload?: boolean;
+}
+export interface SecurityHeadersPolicyProps {
+    /** CloudFront policy name. Left undefined by default so CloudFront
+     * auto-generates a unique name (a fixed name collides across distributions). */
+    policyName?: string;
+    /** Description carried on the L2 `comment` field (ResponseHeadersPolicy is
+     * NOT taggable, so the Fjall description cannot ride on a tag). */
+    comment?: string;
+    /** HSTS defaults to 730 days + includeSubdomains + preload. `false` opts out. */
+    hsts?: false | HstsConfig;
+    /** Content-Security-Policy. Absent ⇒ NO CSP header emitted (opt-in only): a
+     * wrong `default-src 'self'` silently blocks inline hydration scripts and the
+     * site serves but never becomes interactive, so CSP is never a shipped default. */
+    contentSecurityPolicy?: string;
+    /** X-Frame-Options; defaults to DENY. `false` opts out. */
+    frameOptions?: false | "DENY" | "SAMEORIGIN";
+    /** Referrer-Policy; defaults to strict-origin-when-cross-origin. `false` opts out. */
+    referrerPolicy?: false | ReferrerPolicyValue;
+    /** X-Content-Type-Options: nosniff; defaults to on. `false` opts out. */
+    contentTypeOptions?: boolean;
+    /** Additional custom response headers (all emitted with override:true). */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * Fjall wrapper for `aws-cdk-lib/aws-cloudfront.ResponseHeadersPolicy`.
+ *
+ * Wrapped on the description + SOC2-defaults trigger (NOT taggability — the
+ * resource is not taggable): it owns Fjall's uniform security-header defaults
+ * so every consumer inherits the same posture in one edit. Per
+ * `.claude/rules/generator-standards.md § Wrapper Routing Discipline`,
+ * `lib/{config,patterns}/` instantiate this class, never the raw L2.
+ *
+ * Defaults (all `override:true`): HSTS 730d+includeSubdomains+preload,
+ * X-Content-Type-Options: nosniff, X-Frame-Options: DENY,
+ * Referrer-Policy: strict-origin-when-cross-origin. CSP is opt-in only (§5.5).
+ */
+export declare class SecurityHeadersPolicy extends CdkResponseHeadersPolicy {
+    constructor(scope: Construct, id: string, props: SecurityHeadersPolicyProps);
+    private static buildSecurityHeaders;
+    private static buildCustomHeaders;
+    /** The underlying policy, for wiring into a distribution behaviour. */
+    getPolicy(): IResponseHeadersPolicy;
+}