@fjall/components-infrastructure 37.0.0 → 39.0.0

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

@@ -58,6 +58,11 @@ export declare class Payload extends Construct implements IPayload {
     private buildBaseDatabaseProps;
     private createAuroraDatabase;
     private createInstanceDatabase;
+    /**
+     * Pinned to `OPENNEXT_BUCKET_KEYS` in both directions: a key the vocabulary
+     * gains fails here until a builder exists, and a builder for a key it does
+     * not carry is an excess property. Built in the vocabulary's order.
+     */
     private createStorageBuckets;
     private createAssetsBucket;
     private createCacheBucket;

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

@@ -23,6 +23,7 @@
  */
 import { Construct } from "constructs";
 import { CfnOutput, Stack } from "aws-cdk-lib";
+import { OPENNEXT_BUCKET_KEYS, patternBucketConstructId } from "@fjall/util/patterns";
 import { Secret } from "../../resources/aws/secrets/index.js";
 import { Code, Runtime, Architecture, FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";
 import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
@@ -209,10 +210,25 @@ export class Payload extends Construct {
         };
         return this.app.addDatabase(DatabaseFactory.build(this.props.name, instanceProps));
     }
+    /**
+     * Pinned to `OPENNEXT_BUCKET_KEYS` in both directions: a key the vocabulary
+     * gains fails here until a builder exists, and a builder for a key it does
+     * not carry is an excess property. Built in the vocabulary's order.
+     */
     createStorageBuckets() {
-        this._assetsBucket = this.createAssetsBucket();
-        this._cacheBucket = this.createCacheBucket();
-        this._mediaBucket = this.createMediaBucket();
+        const builders = {
+            assets: () => {
+                this._assetsBucket = this.createAssetsBucket();
+            },
+            cache: () => {
+                this._cacheBucket = this.createCacheBucket();
+            },
+            media: () => {
+                this._mediaBucket = this.createMediaBucket();
+            }
+        };
+        for (const bucket of OPENNEXT_BUCKET_KEYS)
+            builders[bucket]();
     }
     createAssetsBucket() {
         const assetsConfig = this.props.storage?.assets ?? {};
@@ -230,7 +246,7 @@ export class Payload extends Construct {
                 }
             }
         };
-        return this.app.addStorage(StorageFactory.build(`${this.props.name}-assets`, assetsProps));
+        return this.app.addStorage(StorageFactory.build(patternBucketConstructId(this.props.name, "assets"), assetsProps));
     }
     createCacheBucket() {
         const cacheConfig = this.props.storage?.cache ?? {};
@@ -244,7 +260,7 @@ export class Payload extends Construct {
                 prune: false // ISR adds files at runtime
             }
         };
-        return this.app.addStorage(StorageFactory.build(`${this.props.name}-cache`, cacheProps));
+        return this.app.addStorage(StorageFactory.build(patternBucketConstructId(this.props.name, "cache"), cacheProps));
     }
     createMediaBucket() {
         const mediaConfig = this.props.storage?.media ?? {};
@@ -254,7 +270,7 @@ export class Payload extends Construct {
                 versioned: mediaConfig.versioned
             })
         };
-        return this.app.addStorage(StorageFactory.build(`${this.props.name}-media`, mediaProps));
+        return this.app.addStorage(StorageFactory.build(patternBucketConstructId(this.props.name, "media"), mediaProps));
     }
     createTagCache() {
         const tagCacheProps = {
@@ -561,11 +577,7 @@ export class Payload extends Construct {
             key: `${this.pascalName}PatternResources`,
             value: JSON.stringify({
                 databases: [this.props.name, `${this.props.name}-tag-cache`],
-                storage: [
-                    `${this.props.name}-assets`,
-                    `${this.props.name}-cache`,
-                    `${this.props.name}-media`
-                ],
+                storage: OPENNEXT_BUCKET_KEYS.map((bucket) => patternBucketConstructId(this.props.name, bucket)),
                 cdn: this.props.name
             }),
             description: `Related resource names for pattern ${this.props.name}`

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

@@ -47,7 +47,35 @@ export interface S3Props {
      * that versions after all is not stamped.
      */
     readonly versioningExemption?: S3VersioningExemption;
+    /**
+     * `"AES256"` is SSE-S3: AWS's own key, free, and real encryption at rest.
+     * `"KMS"` is SSE-KMS with a key of YOUR OWN, so it requires `kmsKeyArn` —
+     * it is refused without one rather than falling back.
+     *
+     * The fallback is what this refuses. Asking CloudFormation for KMS
+     * encryption with no key makes CDK mint an `AWS::KMS::Key` of its own,
+     * `DeletionPolicy: Retain`, with no alias and no tags — an orphan every
+     * Fjall teardown sweep is blind to, because a sweep finds keys by the
+     * alias tag `CustomerManagedKey` stamps and that key carries none.
+     *
+     * Nor does the bucket quietly join the stack's shared key, the way an
+     * `"SSE_KMS"` queue does. A queue holds messages for at most fourteen
+     * days; a bucket holds objects forever, and an object is readable only
+     * with the key it was written under — so moving a live bucket's key
+     * revokes read access to everything already in it, at the same deploy
+     * that rewrites the reader's `kms:Decrypt` grant onto the new key. The
+     * choice of key for a bucket is the operator's, always.
+     */
     readonly encryption?: "AES256" | "KMS";
+    /**
+     * The customer managed key this bucket's objects are encrypted with.
+     * Implies `encryption: "KMS"` when no encryption is stated, and is refused
+     * beside `"AES256"` rather than silently ignored.
+     *
+     * An ARN rather than an `IKey` because this is the plan vocabulary the
+     * scaffold and the codemod write; a key you hold in `infrastructure.ts`
+     * passes as `key.keyArn`.
+     */
     readonly kmsKeyArn?: string;
     /**
      * S3 Bucket Keys for KMS-encrypted buckets — defaults to true when
@@ -94,6 +122,19 @@ export interface StorageBuildProps extends S3Props {
 export type StorageFactoryFn = ((app: App, scope: Construct) => Storage) & {
     stackPlacement?: "storage" | "cdn" | "compute";
 };
+/**
+ * Refuse the two `encryption`/`kmsKeyArn` pairings a bucket cannot honour.
+ *
+ * Both were warnings until 38.x, and both warnings said something untrue.
+ * `"KMS"` with no key did not fall back to "the default AWS managed key": it
+ * made CDK mint a retained, alias-less, tag-less key of its own beside a
+ * bucket that may be DESTROY — the orphan class this refusal exists for. And
+ * a key beside `"AES256"` was not "ignored": CDK refuses that pair itself,
+ * one frame later, in construct vocabulary the operator did not type.
+ *
+ * A key with NO stated encryption is neither, and is deliberately allowed —
+ * CDK infers KMS from the key, which is what the caller asked for.
+ */
 export declare function validateStorageProps(props: S3Props): void;
 export declare class Storage extends Construct implements IStorage, IStorageConnector {
     readonly connectorType: "storage";

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

@@ -4,7 +4,6 @@ import { Source, CacheControl } from "aws-cdk-lib/aws-s3-deployment";
 import { Key } from "aws-cdk-lib/aws-kms";
 import { CfnOutput, Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
 import { BucketDeployment, S3Bucket } from "../../resources/aws/storage/index.js";
-import { FjallLogger } from "../../utils/validationLogger.js";
 export { isStorage } from "./interfaces/storage.js";
 function toBucketEncryption(encryption) {
     if (!encryption)
@@ -50,14 +49,30 @@ function resolveStorageRemovalPolicy(props) {
     }
     return props.retain ? RemovalPolicy.RETAIN : undefined;
 }
+/**
+ * Refuse the two `encryption`/`kmsKeyArn` pairings a bucket cannot honour.
+ *
+ * Both were warnings until 38.x, and both warnings said something untrue.
+ * `"KMS"` with no key did not fall back to "the default AWS managed key": it
+ * made CDK mint a retained, alias-less, tag-less key of its own beside a
+ * bucket that may be DESTROY — the orphan class this refusal exists for. And
+ * a key beside `"AES256"` was not "ignored": CDK refuses that pair itself,
+ * one frame later, in construct vocabulary the operator did not type.
+ *
+ * A key with NO stated encryption is neither, and is deliberately allowed —
+ * CDK infers KMS from the key, which is what the caller asked for.
+ */
 export function validateStorageProps(props) {
-    if (props.encryption === "KMS" && !props.kmsKeyArn) {
-        FjallLogger.warn("'encryption' is set to 'KMS' but 'kmsKeyArn' is not provided. " +
-            "The bucket will use the default AWS managed key.");
-    }
-    if (props.kmsKeyArn && props.encryption !== "KMS") {
-        FjallLogger.warn("'kmsKeyArn' is provided but 'encryption' is not set to 'KMS'. " +
-            "The KMS key will be ignored. Set encryption: 'KMS' to use the key.");
+    if (props.encryption === "KMS" && props.kmsKeyArn === undefined) {
+        throw new Error(`encryption: "KMS" needs the ARN of the key to encrypt with. Pass ` +
+            `'kmsKeyArn', or use encryption: "AES256" for S3-managed encryption ` +
+            `at rest, which costs nothing and needs no key.`);
+    }
+    if (props.kmsKeyArn !== undefined && props.encryption === "AES256") {
+        throw new Error(`'kmsKeyArn' encrypts with a key of your own and encryption: "AES256" ` +
+            `encrypts with S3's, so the pair has no meaning. Set ` +
+            `encryption: "KMS" to use the key, or drop 'kmsKeyArn' to keep ` +
+            `"AES256".`);
     }
 }
 export class Storage extends Construct {

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

@@ -64,9 +64,9 @@ export declare function resolveBucketTarget(appName: string, bucketName: string)
 export declare function resolveCustomTarget(dnsName: string, hostedZoneId: string): IAliasRecordTarget;
 /**
  * Resolve a `FjallTarget` to its raw DNS-name string. The return value is a
- * CloudFormation token for the ECS/CDN/bucket variants — Phase 2 resolves the
- * concrete host via `describeStackResources` after deploy. Used only by
- * `externalRecordsPattern.ts` where no Route53 resource exists and manual
- * record emission needs a string value.
+ * CloudFormation token for the ECS/CDN/bucket variants, resolved by
+ * CloudFormation at deploy (the concrete host lands in the stack's manual
+ * record `Value` output). Used only by `externalRecordsPattern.ts` where no
+ * Route53 resource exists and manual record emission needs a string value.
  */
 export declare function resolveTargetToDnsName(target: FjallTarget): string;

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

@@ -89,10 +89,10 @@ export function resolveCustomTarget(dnsName, hostedZoneId) {
 }
 /**
  * Resolve a `FjallTarget` to its raw DNS-name string. The return value is a
- * CloudFormation token for the ECS/CDN/bucket variants — Phase 2 resolves the
- * concrete host via `describeStackResources` after deploy. Used only by
- * `externalRecordsPattern.ts` where no Route53 resource exists and manual
- * record emission needs a string value.
+ * CloudFormation token for the ECS/CDN/bucket variants, resolved by
+ * CloudFormation at deploy (the concrete host lands in the stack's manual
+ * record `Value` output). Used only by `externalRecordsPattern.ts` where no
+ * Route53 resource exists and manual record emission needs a string value.
  */
 export function resolveTargetToDnsName(target) {
     switch (target.kind) {

package/dist/lib/resources/aws/backup/backupVault.d.ts

@@ -2,18 +2,43 @@ import { Construct } from "constructs";
 import { CfnOutput, RemovalPolicy } from "aws-cdk-lib";
 import { BackupVault as Vault, type LockConfiguration } from "aws-cdk-lib/aws-backup";
 import { type PolicyDocument } from "aws-cdk-lib/aws-iam";
-import { CustomerManagedKey } from "../secrets/kms.js";
+import { type IKey } from "aws-cdk-lib/aws-kms";
+export declare function backupVaultKeyAliasName(vaultName: string): string;
 export interface BackupVaultProps {
     vaultName: string;
-    encryptionKey?: CustomerManagedKey;
+    /**
+     * The key the vault is encrypted with when it already exists outside the
+     * stack (a re-owned vault's live key). `EncryptionKeyArn` is create-only,
+     * so a re-owned vault must always name its live key or CloudFormation
+     * replaces it. The wrapper aliases the key and creates none. Omit to create
+     * a stack-managed key.
+     */
+    encryptionKey?: IKey;
     accessPolicy?: PolicyDocument;
     lockConfiguration?: LockConfiguration;
     removalPolicy?: RemovalPolicy;
+    /**
+     * Import pass: declare identity, not intent. Strips the mutable properties
+     * (`BackupVaultTags`, `AccessPolicy`) from the synthesised resource so the
+     * deploy's `--import-existing-resources` change set imports a live mirror;
+     * the converge deploy re-declares them.
+     */
+    importIdentityOnly?: boolean;
 }
 export declare class BackupVault extends Construct {
     readonly vault: Vault;
     readonly vaultArn: CfnOutput;
     readonly vaultName: CfnOutput;
+    /** The key the vault encrypts recovery points with. */
+    readonly encryptionKey: IKey;
+    /**
+     * Whether this stack created the key. A re-owned vault names a live key the
+     * stack does not manage, and `addToResourcePolicy` on an imported key is a
+     * no-op — so a caller that needs a statement on the key policy (a
+     * cross-account copy destination does) must check this and say so when it
+     * cannot apply one.
+     */
+    readonly ownsEncryptionKey: boolean;
     constructor(scope: Construct, id: string, props: BackupVaultProps);
     static build(id: string, props: BackupVaultProps): (scope: Construct) => BackupVault;
 }

package/dist/lib/resources/aws/backup/backupVault.js

@@ -1,31 +1,74 @@
 import { Construct } from "constructs";
 import { CfnOutput, RemovalPolicy } from "aws-cdk-lib";
-import { BackupVault as Vault } from "aws-cdk-lib/aws-backup";
+import { BackupVault as Vault, CfnBackupVault } from "aws-cdk-lib/aws-backup";
+import { Alias } from "aws-cdk-lib/aws-kms";
 import { CustomerManagedKey } from "../secrets/kms.js";
+/**
+ * Vault properties CloudFormation applies as UPDATES, not identity. An import
+ * pass strips them so `--import-existing-resources` records a live mirror and
+ * the converge deploy that follows applies them as the diff (import records
+ * properties, it never applies them — a tag declared on the import pass is
+ * "already there" forever).
+ */
+const MUTABLE_VAULT_PROPERTIES = ["BackupVaultTags", "AccessPolicy"];
+export function backupVaultKeyAliasName(vaultName) {
+    return `cmk/backupVault/${vaultName}`;
+}
 export class BackupVault extends Construct {
     vault;
     vaultArn;
     vaultName;
+    /** The key the vault encrypts recovery points with. */
+    encryptionKey;
+    /**
+     * Whether this stack created the key. A re-owned vault names a live key the
+     * stack does not manage, and `addToResourcePolicy` on an imported key is a
+     * no-op — so a caller that needs a statement on the key policy (a
+     * cross-account copy destination does) must check this and say so when it
+     * cannot apply one.
+     */
+    ownsEncryptionKey;
     constructor(scope, id, props) {
         super(scope, id);
         // RETAIN default: a DESTROY-policy vault is silently deleted with the stack.
         // Callers opt into DESTROY explicitly for ephemeral/dev vaults.
         const removalPolicy = props.removalPolicy ?? RemovalPolicy.RETAIN;
-        const encryptionKey = props.encryptionKey ||
-            new CustomerManagedKey(this, `${props.vaultName}Key`, {
+        const aliasName = backupVaultKeyAliasName(props.vaultName);
+        let encryptionKey;
+        if (props.encryptionKey !== undefined) {
+            encryptionKey = props.encryptionKey;
+            new Alias(this, `${props.vaultName}KeyAlias`, {
+                aliasName,
+                targetKey: encryptionKey
+            });
+        }
+        else {
+            encryptionKey = new CustomerManagedKey(this, `${props.vaultName}Key`, {
                 description: `Encryption key for backup vault ${props.vaultName}`,
-                aliasName: `cmk/backupVault/${props.vaultName}`,
+                aliasName,
                 // Recovery points in a retained vault outlive the stack.
                 protects: "outlives-stack",
                 removalPolicy
-            });
+            }).key;
+        }
+        this.encryptionKey = encryptionKey;
+        this.ownsEncryptionKey = props.encryptionKey === undefined;
         this.vault = new Vault(this, `${props.vaultName}Vault`, {
             backupVaultName: props.vaultName,
-            encryptionKey: encryptionKey.key,
+            encryptionKey,
             accessPolicy: props.accessPolicy,
             lockConfiguration: props.lockConfiguration,
             removalPolicy
         });
+        if (props.importIdentityOnly === true) {
+            const cfnVault = this.vault.node.defaultChild;
+            if (!(cfnVault instanceof CfnBackupVault)) {
+                throw new Error(`Backup vault "${props.vaultName}": expected an AWS::Backup::BackupVault default child to strip for import`);
+            }
+            for (const property of MUTABLE_VAULT_PROPERTIES) {
+                cfnVault.addPropertyDeletionOverride(property);
+            }
+        }
         this.vaultArn = new CfnOutput(this, `${props.vaultName}VaultArn`, {
             key: `${props.vaultName}VaultArn`,
             value: this.vault.backupVaultArn,

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

@@ -1,5 +1,6 @@
 import { Construct } from "constructs";
 import { type CloudFrontPriceClass } from "@fjall/util";
+import { CloudFrontLogDelivery, type CloudFrontLogFormat } from "./cloudFrontLogDelivery.js";
 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,25 +60,13 @@ export interface CloudFrontDistributionProps {
     certificate?: ICertificate;
     comment?: string;
     /**
-     * Standard (legacy) S3 access logging. It cannot deliver to a bucket in an
-     * opt-in region (`af-south-1`, `ap-east-1`, …): CloudFormation rejects the
-     * distribution at deploy, so a concrete opt-in delivery region is refused
-     * at synth instead — cure with `enableLogging: false`, or a `logBucket`
-     * whose region CDK knows to be default-enabled (see `logBucket`).
+     * Standard logging (v2): access logs delivered through CloudWatch Logs to
+     * an S3 bucket in any region, including opt-in ones. Omit for no logging.
+     * The distribution's own `Logging` block (legacy logging) is never
+     * rendered — the legacy `enableLogging`/`logBucket`/`logFilePrefix` props
+     * are refused at synth since 38.0.0.
      */
-    enableLogging?: boolean;
-    /**
-     * Delivery bucket for standard logs; without it CDK creates one in the
-     * distribution's own stack (and region). Its `env.region` is the delivery
-     * region the opt-in refusal on `enableLogging` checks, so an imported
-     * bucket must declare it: `Bucket.fromBucketAttributes(…, { region })`, or
-     * a `Bucket` in a stack pinned to its region. `fromBucketName` and
-     * `fromBucketArn` inherit this stack's region, and a token bucket region
-     * falls back to it.
-     */
-    logBucket?: IBucket;
-    /** Key prefix for standard logs delivered to `logBucket`. */
-    logFilePrefix?: string;
+    logging?: CloudFrontLoggingProps;
     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,
@@ -121,8 +110,43 @@ export interface CloudFrontDistributionProps {
      */
     originRequestPolicy?: "all-viewer-except-host" | "none";
 }
+/**
+ * Standard logging (v2) for a distribution. The delivery resources are
+ * created in `deliveryScope` — which MUST be a us-east-1 stack, the only
+ * region CloudWatch Logs accepts them in — and default to the distribution's
+ * own scope, which is right only when the distribution's stack is itself in
+ * us-east-1. The `Cdn` pattern resolves the scope through
+ * `App.getUsEast1CdnLoggingStack()`; direct callers in another region pass
+ * a us-east-1 stack themselves.
+ */
+export interface CloudFrontLoggingProps {
+    /** Bucket the logs land in — same account as the distribution. */
+    bucket: IBucket;
+    /** Key prefix (no leading or trailing slash); defaults to `cloudfront/<id>`. */
+    prefix?: string;
+    /** CloudWatch Logs output format; defaults to `json`. */
+    format?: CloudFrontLogFormat;
+    /** Scope for the delivery resources; a us-east-1 stack. */
+    deliveryScope?: Construct;
+}
+/**
+ * The props CloudFront standard (legacy) logging took before 38.0.0. They
+ * are not members of `CloudFrontDistributionProps` any more, so a
+ * TypeScript caller cannot pass them; a JavaScript caller, a spread from a
+ * saved config or a generator template still can, and the legacy `Logging`
+ * block would otherwise be silently dropped. Refused at synth by name.
+ */
+export declare const LEGACY_CLOUDFRONT_LOGGING_PROPS: readonly ["enableLogging", "logBucket", "logFilePrefix"];
+/**
+ * `replacement` is the seam's v2 shape, named in the refusal: the resource
+ * requires the bucket and has no `false`, the pattern defaults the bucket
+ * and accepts `false`.
+ */
+export declare function assertNoLegacyLoggingProps(context: string, props: object, replacement: string): void;
 export declare class CloudFrontDistribution extends Construct {
     readonly id: string;
+    /** The v2 log delivery, when `logging` was given. */
+    readonly logDelivery?: CloudFrontLogDelivery;
     private distribution;
     private readonly origins;
     /** Shared S3 access identities, keyed by the owning stack (see

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

@@ -1,8 +1,9 @@
 import { Construct } from "constructs";
-import { CfnOutput, Names, Stack, Token } from "aws-cdk-lib";
+import { CfnOutput, Names, Stack } from "aws-cdk-lib";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { registerCdnAliasTarget } from "../../../utils/cdnAliasTargetRegistry.js";
-import { cdnDomainExportName, getRegionInfo, OPT_IN_REGION_CODES } from "@fjall/util";
+import { cdnDomainExportName } from "@fjall/util";
+import { CloudFrontLogDelivery, DEFAULT_CLOUDFRONT_LOG_FORMAT } from "./cloudFrontLogDelivery.js";
 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";
 /**
@@ -43,56 +44,38 @@ const URI_REWRITE_FRAGMENTS = {
         " if (seg.indexOf('.') === -1) { request.uri = uri + '/index.html'; } } }"
 };
 /**
- * CloudFront standard (legacy) logging cannot deliver to an S3 bucket in an
- * opt-in region: CDK's `renderLogging` performs no region check and
- * CloudFormation rejects the distribution at deploy, after the rest of the
- * stack has been created. The delivery region is known at synth whenever the
- * bucket's stack is env-pinned, so the refusal lives here — the seam every
- * distribution crosses, whether built directly or through the `Cdn`
- * pattern — and names both cures.
- *
- * Logging is on exactly when `renderLogging` emits a Logging block:
- * `enableLogging: true`, or a `logBucket` without an explicit
- * `enableLogging: false` (that pair is CDK's own contradiction error and is
- * left to it). The delivery region is the bucket's `env.region` when it is
- * concrete, else the distribution stack's — the bucket CDK would create.
- * A token delivery region (an unpinned stack, and no region on the bucket)
- * cannot be checked and passes. A concrete region `AWS_REGIONS_METADATA`
- * does not list is refused too — every region launched since 2019 is opt-in,
- * so an unlisted one cannot be assumed default-enabled — naming the metadata
- * as the cure. The guard fires whenever the delivery region is concrete and
- * known to the metadata.
+ * The props CloudFront standard (legacy) logging took before 38.0.0. They
+ * are not members of `CloudFrontDistributionProps` any more, so a
+ * TypeScript caller cannot pass them; a JavaScript caller, a spread from a
+ * saved config or a generator template still can, and the legacy `Logging`
+ * block would otherwise be silently dropped. Refused at synth by name.
  */
-function validateStandardLoggingRegion(scope, id, props) {
-    const loggingOn = props.enableLogging === true ||
-        (props.enableLogging === undefined && props.logBucket !== undefined);
-    if (!loggingOn)
-        return;
-    const bucketRegion = props.logBucket?.env.region;
-    const region = bucketRegion !== undefined && !Token.isUnresolved(bucketRegion)
-        ? bucketRegion
-        : Stack.of(scope).region;
-    if (Token.isUnresolved(region))
-        return;
-    if (getRegionInfo(region) === undefined) {
-        throw new Error(`CloudFront distribution '${id}': region ${region} is not in ` +
-            "@fjall/util's AWS_REGIONS_METADATA, so its opt-in status cannot be " +
-            "checked — update the metadata, or set enableLogging: false on this " +
-            "CDN.");
-    }
-    if (!OPT_IN_REGION_CODES.has(region))
+export const LEGACY_CLOUDFRONT_LOGGING_PROPS = [
+    "enableLogging",
+    "logBucket",
+    "logFilePrefix"
+];
+/**
+ * `replacement` is the seam's v2 shape, named in the refusal: the resource
+ * requires the bucket and has no `false`, the pattern defaults the bucket
+ * and accepts `false`.
+ */
+export function assertNoLegacyLoggingProps(context, props, replacement) {
+    const legacy = new Set(LEGACY_CLOUDFRONT_LOGGING_PROPS);
+    const present = Object.entries(props)
+        .filter(([key, value]) => legacy.has(key) && value !== undefined)
+        .map(([key]) => key);
+    if (present.length === 0)
         return;
-    throw new Error(`CloudFront distribution '${id}': standard (legacy) logging cannot ` +
-        `deliver to an S3 bucket in opt-in region ${region} — logging was ` +
-        "enabled explicitly or by the app backup tier's cloudFrontLogging " +
-        "default. Set enableLogging: false on this CDN, or pass a logBucket " +
-        "whose region CDK knows to be default-enabled: " +
-        "Bucket.fromBucketAttributes(…, { region }), or a bucket in a stack " +
-        "pinned to that region (fromBucketName and fromBucketArn inherit this " +
-        "stack's region).");
+    throw new Error(`${context}: ${present.join(", ")} ${present.length === 1 ? "is" : "are"} ` +
+        "not supported since 38.0.0 — CloudFront standard (legacy) logging was " +
+        `replaced by CloudWatch-vended standard logging (v2). Use ${replacement} ` +
+        "instead; see docs/release-notes/38.0.0.md for the migration.");
 }
 export class CloudFrontDistribution extends Construct {
     id;
+    /** The v2 log delivery, when `logging` was given. */
+    logDelivery;
     distribution;
     origins = new Map();
     /** Shared S3 access identities, keyed by the owning stack (see
@@ -102,7 +85,7 @@ export class CloudFrontDistribution extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         this.id = id;
-        validateStandardLoggingRegion(this, id, props);
+        assertNoLegacyLoggingProps(`CloudFront distribution '${id}'`, props, "logging: { bucket, prefix?, format?, deliveryScope? } (or no logging prop at all)");
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
         const defaultOrigin = this.createOrigin(props.defaultOrigin);
@@ -158,11 +141,16 @@ export class CloudFrontDistribution extends Construct {
             domainNames: props.domainNames,
             certificate: props.certificate,
             comment: props.comment,
-            enableLogging: props.enableLogging,
-            logBucket: props.logBucket,
-            logFilePrefix: props.logFilePrefix,
             priceClass: this.resolvePriceClass(props.priceClass)
         });
+        if (props.logging !== undefined) {
+            this.logDelivery = new CloudFrontLogDelivery(props.logging.deliveryScope ?? this, `${id}LogDelivery`, {
+                distribution: this.distribution,
+                bucket: props.logging.bucket,
+                prefix: props.logging.prefix ?? `cloudfront/${id}`,
+                format: props.logging.format ?? DEFAULT_CLOUDFRONT_LOG_FORMAT
+            });
+        }
         // 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