@fjall/components-infrastructure 2.34.0 → 3.0.0

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

@@ -1,105 +1,13 @@
 import { CaaTag } from "aws-cdk-lib/aws-route53";
 import { ARecord, AaaaRecord, AliasRecord, CnameRecord, MxRecord, TxtRecord, NsRecord, SrvRecord, CaaRecord } from "../../resources/aws/networking/dnsRecord/index.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
-import { ALIAS_CDK_PREFIX } from "../../utils/domainTypes.js";
 import { DNS_APEX } from "@fjall/util";
+// H13: the legacy BIND-era `composeDnsRecords` (untyped `DnsRecordInput` with
+// ALIAS sentinels in `value`) was deleted in Phase 2. The typed composer below
+// deliberately preserves its construct-id formula — see the eject-contract
+// note on `composeTypedDnsRecords`.
 /**
- * Legacy composer consumed by `DomainFactory` (deleted in Phase 2). Accepts
- * the `DnsRecordInput` shape from the BIND-primary era where ALIAS sentinels
- * live in `value`. Typed targets are not supported here; use
- * `composeTypedDnsRecords` instead.
- */
-export function composeDnsRecords(scope, zone, zoneName, records) {
-    const safeZone = toPascalCase(getSafeZoneName(zoneName));
-    records.forEach((record, index) => {
-        // Skip alias sentinels — they are resolved via the typed path in Phase 1+.
-        if (record.value.startsWith(ALIAS_CDK_PREFIX)) {
-            return;
-        }
-        const safeName = toPascalCase(record.name === DNS_APEX ? "Apex" : record.name);
-        const constructId = `${safeZone}${safeName}${record.type}Record${index}`;
-        const common = {
-            zone,
-            zoneName,
-            recordName: record.name,
-            ttl: record.ttl
-        };
-        switch (record.type) {
-            case "A":
-                new ARecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "AAAA":
-                new AaaaRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "CNAME":
-                new CnameRecord(scope, constructId, {
-                    ...common,
-                    domainName: record.value
-                });
-                break;
-            case "MX":
-                new MxRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            hostName: record.value,
-                            priority: record.priority ?? 10
-                        }
-                    ]
-                });
-                break;
-            case "TXT":
-                new TxtRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "NS":
-                new NsRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "SRV":
-                new SrvRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            hostName: record.value,
-                            priority: record.priority ?? 10,
-                            weight: record.weight ?? 0,
-                            port: record.port ?? 443
-                        }
-                    ]
-                });
-                break;
-            case "CAA":
-                new CaaRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            flag: 0,
-                            tag: record.value.includes("issuewild")
-                                ? CaaTag.ISSUEWILD
-                                : record.value.includes("iodef")
-                                    ? CaaTag.IODEF
-                                    : CaaTag.ISSUE,
-                            value: record.value
-                        }
-                    ]
-                });
-                break;
-        }
-    });
-}
-/**
- * Typed composer consumed by the new `Domain` construct. Accepts the
+ * Typed composer consumed by the `Domain` construct. Accepts the
  * discriminated `DnsRecord` union (`StandardRecord | AliasRecord`).
  *
  * `AliasRecord` entries MUST carry a `target` produced by `fjallApp()`,

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

@@ -7,8 +7,9 @@ import type { DomainProps, ManualRecord } from "./interfaces/domain.js";
  * User-facing Route53-oriented domain construct. Dispatches on
  * `props.registrar` to one of three per-registrar patterns:
  *
- *   - `route53` → `composeApexDomain` (apex HZ + delegations)
- *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ only)
+ *   - `route53` → `composeApexDomain` (apex HZ + org-gated DelegationRole)
+ *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ; D8
+ *     child-writes NS delegation via `parentDelegationRoleArn`)
  *   - `external-records` → `composeExternalRecords` (no HZ, manual records)
  *
  * Applies gold-plating tags (`fjall:description`, three

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

@@ -11,8 +11,9 @@ import { applyCostAllocationTags } from "../../utils/costAllocationTags.js";
  * User-facing Route53-oriented domain construct. Dispatches on
  * `props.registrar` to one of three per-registrar patterns:
  *
- *   - `route53` → `composeApexDomain` (apex HZ + delegations)
- *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ only)
+ *   - `route53` → `composeApexDomain` (apex HZ + org-gated DelegationRole)
+ *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ; D8
+ *     child-writes NS delegation via `parentDelegationRoleArn`)
  *   - `external-records` → `composeExternalRecords` (no HZ, manual records)
  *
  * Applies gold-plating tags (`fjall:description`, three

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

@@ -1,10 +1,12 @@
-import { Annotations } from "aws-cdk-lib";
+import { Annotations, Token } from "aws-cdk-lib";
 import { DNS_APEX } from "@fjall/util";
+import { isWithinZone, resolveRecordFqdn } from "../../utils/domainTypes.js";
 const VALID_REGISTRARS = [
     "route53",
     "external-delegated",
     "external-records"
 ];
+const VALID_PHASES = ["zone", "full"];
 /**
  * Synchronous synth-time validator for `DomainProps`. Throws on hard errors
  * (CDK catches and surfaces the stack trace pointing at the `new Domain(...)`
@@ -18,7 +20,7 @@ export function validateDomainProps(scope, props) {
     const effectiveZone = resolveEffectiveZoneName(props);
     validateRecords(scope, props, effectiveZone);
     validateCertificates(props, effectiveZone);
-    validateDelegations(props);
+    validateDelegationConfig(props);
 }
 function validateRegistrar(props) {
     const registrar = props.registrar;
@@ -26,11 +28,15 @@ function validateRegistrar(props) {
         !VALID_REGISTRARS.includes(registrar)) {
         throw new Error(`Domain registrar must be one of ${VALID_REGISTRARS.join(", ")}; received: ${String(registrar)}`);
     }
-    // Runtime defence — TS forbids `delegations` on external-records, but a JS
-    // caller could still pass it. Surface the mistake loudly.
-    if (registrar === "external-records" &&
-        props.delegations !== undefined) {
-        throw new Error("Domain: 'delegations' is not supported with registrar: 'external-records' — there is no Fjall-managed hosted zone to cascade from.");
+    // D8/D12 removed-surface defence — the parent-writes `delegations[]` prop
+    // no longer exists on any registrar. TS already rejects it; this catches JS
+    // callers and stale generated code, naming the replacement.
+    if (props.delegations !== undefined) {
+        throw new Error("Domain: 'delegations' was removed (D8 — one delegation direction, child " +
+            "writes NS). Cure: declare the delegated child as its own Domain with " +
+            "registrar: 'external-delegated' and set 'parentDelegationRoleArn' " +
+            "(the CLI injects it via ManagedDomainBinding.delegationRoleArn); the " +
+            "child then UPSERTs its NS records into this zone.");
     }
 }
 function resolveEffectiveZoneName(props) {
@@ -47,10 +53,9 @@ function validateRecords(scope, props, effectiveZone) {
     const records = props.records ?? [];
     const seen = new Map();
     for (const record of records) {
-        const fqdn = recordFqdn(record.name, effectiveZone);
-        if (!isWithinZone(fqdn, effectiveZone)) {
-            throw new Error(`Record '${fqdn}' falls outside managed zone '${effectiveZone}'. Use a separate Domain construct or a SubdomainDelegation.`);
-        }
+        // Rejects wrong-zone absolute names and ambiguous bare-zone-suffixed
+        // names itself; a resolved name is therefore always within the zone.
+        const fqdn = resolveRecordFqdn(record.name, effectiveZone);
         if ("target" in record) {
             if (record.name === DNS_APEX && props.registrar === "external-records") {
                 throw new Error("Apex A records with Fjall targets require registrar: 'route53' or 'external-delegated' because RFC 1035 forbids CNAME at apex. Use a subdomain or change registrar.");
@@ -89,19 +94,61 @@ function validateCertificates(props, effectiveZone) {
         }
     }
 }
-function validateDelegations(props) {
-    if (props.registrar === "external-records") {
+/**
+ * D8 delegation-consistency checks for the child-writes shape.
+ *
+ * `parentDelegationRoleArn` and `phase` belong to the delegated topology
+ * (`external-delegated`) only; on any other registrar their presence is a
+ * hard error rather than a silent no-op. On the delegated topology the role
+ * ARN must be a LITERAL string (VD2-a): an unresolved token means the caller
+ * reached for `Fn.importValue`, which resolves same-account only and is
+ * exactly the trap that sank the legacy `DomainDelegation` pattern.
+ */
+function validateDelegationConfig(props) {
+    const arn = props
+        .parentDelegationRoleArn;
+    const phase = props.phase;
+    if (props.registrar !== "external-delegated") {
+        if (arn !== undefined) {
+            throw new Error(`Domain: 'parentDelegationRoleArn' is only supported with registrar: ` +
+                `'external-delegated' (received registrar: '${props.registrar}'). ` +
+                `Cure: the delegated child zone declares it — move the prop onto ` +
+                `the child Domain, or drop it.`);
+        }
+        if (phase !== undefined) {
+            throw new Error(`Domain: 'phase' is only supported with registrar: ` +
+                `'external-delegated' (received registrar: '${props.registrar}'). ` +
+                `Cure: drop the prop — only delegated child zones need the ` +
+                `two-step zone→full deploy gate.`);
+        }
         return;
     }
-    const delegations = props
-        .delegations;
-    if (!delegations) {
+    if (phase !== undefined &&
+        !VALID_PHASES.includes(phase)) {
+        throw new Error(`Domain: 'phase' must be one of ${VALID_PHASES.map((p) => `'${p}'`).join(", ")}; ` +
+            `received: '${String(phase)}'. Cure: use 'zone' for step 1 of the ` +
+            `two-step delegated deploy, 'full' (or omit) for the complete build.`);
+    }
+    if (arn === undefined) {
         return;
     }
-    for (const delegation of delegations) {
-        if (delegation.auto === true && !delegation.toAccount) {
-            throw new Error(`Delegation '${delegation.subdomain}' has auto: true but no 'toAccount' set. Provide the child Fjall account name.`);
-        }
+    if (typeof arn !== "string") {
+        throw new Error(`Domain: 'parentDelegationRoleArn' must be a string; received: ` +
+            `${typeof arn}. Cure: pass the parent DelegationRole ARN as a ` +
+            `literal string.`);
+    }
+    if (Token.isUnresolved(arn)) {
+        throw new Error("Domain: 'parentDelegationRoleArn' is an unresolved token (e.g. " +
+            "Fn.importValue) — cross-account delegation requires a literal role " +
+            "ARN because Fn::ImportValue resolves same-account only (VD2-a). " +
+            "Cure: deploy via the Fjall CLI, which injects the literal ARN from " +
+            "ManagedDomainBinding.delegationRoleArn, or paste the parent zone's " +
+            "DelegationRoleArn output value directly.");
+    }
+    if (!/^arn:[^:]+:iam::\d{12}:role\/.+$/.test(arn)) {
+        throw new Error(`Domain: 'parentDelegationRoleArn' does not look like an IAM role ARN; ` +
+            `received: '${arn}'. Cure: pass the parent zone's DelegationRoleArn ` +
+            `output (arn:<partition>:iam::<account>:role/<name>).`);
     }
 }
 function normaliseCertificate(cert) {
@@ -113,33 +160,11 @@ function normaliseCertificate(cert) {
         subjectAlternativeNames: cert.subjectAlternativeNames
     };
 }
-function recordFqdn(recordName, zoneName) {
-    if (recordName === DNS_APEX) {
-        return zoneName;
-    }
-    // A user may already provide a FQDN (e.g. "api.example.com") or a single
-    // label ("api"). If the name contains a dot, treat it as an FQDN — the
-    // zone-boundary check then decides whether it is within the managed zone.
-    // A bare label is always appended to the zone.
-    if (recordName.includes(".")) {
-        return recordName;
-    }
-    return `${recordName}.${zoneName}`;
-}
 function assertWithinZone(candidate, zoneName) {
     if (!isWithinZone(candidate, zoneName)) {
-        throw new Error(`'${candidate}' falls outside managed zone '${zoneName}'. Use a separate Domain construct or a SubdomainDelegation.`);
-    }
-}
-/**
- * Dot-boundary suffix matching. Rejects pathological cases where a user-supplied
- * zone appears as a suffix of another zone (e.g. 'evilexample.com' against
- * zone 'example.com' — `endsWith('example.com')` returns true without the
- * leading dot).
- */
-function isWithinZone(candidate, zoneName) {
-    if (candidate === zoneName) {
-        return true;
+        throw new Error(`'${candidate}' falls outside managed zone '${zoneName}'. Use a separate Domain construct or a delegated child Domain (registrar: 'external-delegated').`);
     }
-    return candidate.endsWith(`.${zoneName}`);
 }
+// isWithinZone (dot-boundary suffix matching) and resolveRecordFqdn (the
+// canonical BIND-semantics record-name resolver) live in
+// lib/utils/domainTypes.ts — shared with the resources-layer dnsRecord family.

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

@@ -2,7 +2,7 @@ import { CfnOutput } from "aws-cdk-lib";
 import { Certificate as AcmCertificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { resolveTargetToDnsName } from "./targets/targetResolution.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
-import { DNS_APEX } from "@fjall/util";
+import { resolveRecordFqdn } from "../../utils/domainTypes.js";
 const MANUAL_RECORD_TTL_SECONDS = 300;
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
@@ -60,7 +60,7 @@ export function composeExternalRecords(scope, props) {
     //    entries.
     const records = props.records ?? [];
     records.forEach((record, index) => {
-        const fqdn = toFqdn(record.name, props.zoneName);
+        const fqdn = resolveRecordFqdn(record.name, props.zoneName);
         if ("target" in record) {
             const value = resolveTargetToDnsName(record.target);
             const manual = {
@@ -98,15 +98,6 @@ function normaliseCertificate(cert) {
         transparencyLogging: cert.transparencyLogging
     };
 }
-function toFqdn(recordName, zoneName) {
-    if (recordName === DNS_APEX) {
-        return zoneName;
-    }
-    if (recordName === zoneName || recordName.endsWith(`.${zoneName}`)) {
-        return recordName;
-    }
-    return `${recordName}.${zoneName}`;
-}
 function narrowManualType(type) {
     switch (type) {
         case "A":

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

@@ -7,11 +7,9 @@ export * from "./fivetranProxy.js";
 export * from "./database.js";
 export * from "../../resources/aws/compute/ec2.js";
 export * from "../../resources/aws/networking/hostedZone.js";
-export * from "./domainFactory.js";
-export * from "./domainDelegation.js";
 export { Domain } from "./domain.js";
 export * from "./targets/index.js";
-export { getDomainExportNames, type DnsRecordInput, type DelegationInput, type CertificateInput, type DomainApexProps, type DomainDelegatedProps, type IDomainProps, type ManagedDomainExports, type FjallTarget, type StandardRecord, type DnsRecord, type Certificate, type SubdomainDelegation, type DomainCommonProps, type Route53ApexProps, type ExternalDelegatedProps, type ExternalRecordsProps, type DomainProps, type ManualRecord } from "./interfaces/domain.js";
+export { getDomainExportNames, type ManagedDomainExports, type DomainDeployPhase, type FjallTarget, type StandardRecord, type DnsRecord, type Certificate, type DomainCommonProps, type Route53ApexProps, type ExternalDelegatedProps, type ExternalRecordsProps, type DomainProps, type ManualRecord } from "./interfaces/domain.js";
 export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "./interfaces/database.js";
 export * from "./compute.js";
 export * from "./storage.js";

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

@@ -9,9 +9,8 @@ export * from "./database.js";
 // Resource-layer re-exports — consumed by patterns that compose these primitives
 export * from "../../resources/aws/compute/ec2.js";
 export * from "../../resources/aws/networking/hostedZone.js";
-// Domain patterns
-export * from "./domainFactory.js";
-export * from "./domainDelegation.js";
+// Domain patterns (H13: the legacy DomainFactory/ApexDomain/DomainDelegation
+// layer was deleted in Phase 2 — `Domain` is the only construct surface).
 export { Domain } from "./domain.js";
 export * from "./targets/index.js";
 // Explicit exports from the interfaces barrel — avoids collision between the

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

@@ -1,4 +1,5 @@
-export type { DnsRecordInput, DelegationInput, CertificateInput, DomainApexProps, DomainDelegatedProps, IDomainProps, ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { DomainDeployPhase } from "../../../utils/domainTypes.js";
+export type { ManagedDomainExports, DomainDeployPhase } from "../../../utils/domainTypes.js";
 export { getDomainExportNames } from "../../../utils/domainTypes.js";
 /**
  * Typed marker for the target of an `AliasRecord`. The helpers in
@@ -39,16 +40,10 @@ export type Certificate = string | {
     readonly subjectAlternativeNames?: string[];
     readonly transparencyLogging?: boolean;
 };
-export interface SubdomainDelegation {
-    readonly subdomain: string;
-    readonly toAccount: string;
-    readonly auto?: boolean;
-}
 export interface DomainCommonProps {
     readonly zoneName: string;
     readonly records?: DnsRecord[];
     readonly certificates?: Certificate[];
-    readonly delegations?: SubdomainDelegation[];
     readonly tags?: Record<string, string>;
     readonly description?: string;
     readonly costAllocationEnvironment?: string;
@@ -60,8 +55,27 @@ export interface Route53ApexProps extends DomainCommonProps {
 export interface ExternalDelegatedProps extends DomainCommonProps {
     readonly registrar: "external-delegated";
     readonly delegatedSubdomain: string;
+    /**
+     * D8 — child-writes delegation. LITERAL ARN of the parent zone's
+     * DelegationRole (VD2-a: never `Fn.importValue`, which resolves
+     * same-account only). When present, the child zone UPSERTs its NS records
+     * into the parent zone via `CrossAccountZoneDelegationRecord`. The CLI
+     * injects this from `ManagedDomainBinding.delegationRoleArn` at deploy
+     * time; omit it for an externally-owned parent and add the NS records at
+     * the registrar instead (a synth warning reminds you the zone will not
+     * resolve until delegated).
+     */
+    readonly parentDelegationRoleArn?: string;
+    /**
+     * Two-step deploy gate (R2 cert-hang guard, generalised from
+     * `DevSubstrate.phase`). `"zone"` synthesises the child zone, delegation
+     * record and user records only; `"full"` (default) additionally issues the
+     * certificates — deploy that only after the delegated NS has propagated,
+     * else ACM DNS-validation hangs until CloudFormation rolls back.
+     */
+    readonly phase?: DomainDeployPhase;
 }
-export interface ExternalRecordsProps extends Omit<DomainCommonProps, "delegations"> {
+export interface ExternalRecordsProps extends DomainCommonProps {
     readonly registrar: "external-records";
 }
 export type DomainProps = Route53ApexProps | ExternalDelegatedProps | ExternalRecordsProps;

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

@@ -14,4 +14,3 @@ export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type C
 export { type PatternType, type IPattern, type IPayload, type IPayloadProps, type IPatternProps, type AnyPattern, type PayloadDatabaseConfig, type PayloadComputeConfig, type PayloadCdnConfig, isPayloadPattern, isPattern } from "./pattern.js";
 export { type OrganisationType, type IOrganisation, type IPlatform, type IAccount, type AnyOrganisation, isOrganisation, isPlatform, isAccount, isOrganisationResource } from "./organisation.js";
 export { type IVpcPeer } from "./vpcPeer.js";
-export { type DnsRecordInput, type DelegationInput, type CertificateInput, type DomainApexProps, type DomainDelegatedProps, type IDomainProps } from "./domain.js";

package/dist/lib/patterns/aws/interfaces/index.js

@@ -22,3 +22,6 @@ export { CONNECTION_TYPE, isConnector, isConnectable, isConnectionConfig, isConn
 export { isPayloadPattern, isPattern } from "./pattern.js";
 // Organisation interfaces
 export { isOrganisation, isPlatform, isAccount, isOrganisationResource } from "./organisation.js";
+// Domain interfaces — the legacy `IDomainProps` family was deleted with the
+// H13 BIND-era layer; consumers use the `DomainProps` union exported from
+// the patterns barrel.

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

@@ -23,7 +23,7 @@ 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 { ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { ManagedDomainBinding, ManagedDomainExports } from "../../../utils/domainTypes.js";
 import type { PatternType } from "@fjall/util";
 export type { ProxyConfig, ReadReplicaConfig, CredentialsConfig, EncryptionConfig, AuroraEncryptionConfig, AuroraWriterConfig, AuroraReadersConfig, DatabaseInsightsConfig };
 /**
@@ -287,11 +287,13 @@ export interface PayloadCdnConfig {
  * }));
  *
  * @example
- * // With custom domain (auto-creates certificate + DNS)
+ * // With custom domain (auto-creates certificate + DNS; the zone identity
+ * // is explicit — a CLI-injected managedDomain binding, or zoneName)
  * app.addPattern(PatternFactory.build("PayloadApp", {
  *   type: "payload",
  *   name: "my-cms",
- *   domain: "cms.example.com"
+ *   domain: "cms.example.com",
+ *   zoneName: "example.com"
  * }));
  *
  * @example
@@ -316,18 +318,42 @@ export interface IPayloadProps {
     /**
      * Custom domain for the Payload application.
      * When provided, automatically:
-     * - Looks up the Route53 hosted zone
-     * - Creates an ACM certificate with DNS validation (in us-east-1)
+     * - Resolves the Route53 hosted zone from the explicit identity
+     *   (`managedDomain` or `zoneName`/`hostedZoneId`) — never guessed from
+     *   the domain's labels
+     * - Provides a us-east-1 ACM certificate for CloudFront: the managed
+     *   binding's literal ARN, or an app-owned DNS-validated certificate
+     *   (in-stack for us-east-1 apps, otherwise in the app's dedicated
+     *   us-east-1 certificate stack consumed via cross-region references)
      * - Configures CloudFront with the certificate
      * - Creates an A record (alias) pointing to CloudFront
      *
-     * Requires: A Route53 hosted zone for the domain must exist.
+     * Requires: `managedDomain` or `zoneName` naming the zone that contains
+     * the domain.
      *
      * @example "cms.example.com"
      */
     domain?: string;
-    /** Import zone and cert from a managed domain stack instead of creating inline */
-    managedDomain?: ManagedDomainExports;
+    /**
+     * Zone and certificate identity from a managed domain stack. The
+     * CLI-injected `ManagedDomainBinding` carries literal values (hosted-zone
+     * ID + us-east-1 certificate ARN) and crosses accounts and regions; the
+     * legacy `ManagedDomainExports` form imports by export name (same account
+     * and region only). Takes priority over `zoneName`.
+     */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /**
+     * Explicit hosted-zone name containing `domain` (BYO zones). Fjall never
+     * derives the zone from the domain's labels — set this when not using a
+     * managed domain. `domain` must sit within this zone (validated at synth).
+     * @example "example.com.au"
+     */
+    zoneName?: string;
+    /**
+     * Literal hosted-zone ID for `zoneName`. Optional — when set, the zone is
+     * referenced directly instead of via a runtime `HostedZone.fromLookup`.
+     */
+    hostedZoneId?: string;
     /** Database configuration */
     database?: PayloadDatabaseConfig;
     /** Compute (Lambda) configuration */
@@ -413,6 +439,7 @@ export interface StaticSiteCdnConfig {
  *   routing: "multipage",
  *   security: { headers: true },
  *   domain: "lbexc.com",
+ *   zoneName: "lbexc.com", // or a CLI-injected `managedDomain` binding
  *   forms: { to: "hello@lbexc.com", corsOrigin: "https://lbexc.com" }
  * }));
  */
@@ -431,8 +458,26 @@ export interface IStaticSiteProps {
     security?: StaticSiteSecurityConfig;
     /** Custom domain (same machinery as payload). Required when `forms` is set. */
     domain?: string;
-    /** Import zone and cert from a managed domain stack instead of creating inline */
-    managedDomain?: ManagedDomainExports;
+    /**
+     * Zone and certificate identity from a managed domain stack. The
+     * CLI-injected `ManagedDomainBinding` carries literal values (hosted-zone
+     * ID + us-east-1 certificate ARN) and crosses accounts and regions; the
+     * legacy `ManagedDomainExports` form imports by export name (same account
+     * and region only). Takes priority over `zoneName`.
+     */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /**
+     * Explicit hosted-zone name containing `domain` (BYO zones). Fjall never
+     * derives the zone from the domain's labels — set this when not using a
+     * managed domain. `domain` must sit within this zone (validated at synth).
+     * @example "example.com.au"
+     */
+    zoneName?: string;
+    /**
+     * Literal hosted-zone ID for `zoneName`. Optional — when set, the zone is
+     * referenced directly instead of via a runtime `HostedZone.fromLookup`.
+     */
+    hostedZoneId?: string;
     /** Optional contact-form endpoint (Lambda → SES). Requires `domain`. */
     forms?: StaticSiteFormsConfig;
     /** CDN configuration - for advanced per-path overrides. */

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

@@ -0,0 +1,77 @@
+/**
+ * Explicit zone identity + CloudFront certificate resolution shared by the
+ * CloudFront-fronted patterns (staticsite, payload).
+ *
+ * Design 2026-07-17 domain-management gold-plating — decisions D2 (synth
+ * side) and D3, findings H2 and H3:
+ *
+ * - Nothing here guesses a hosted zone. The old `extractRootDomain` label
+ *   split resolved every multi-label public suffix wrongly (e.g.
+ *   'littlebearearthworks.com.au' → zone 'com.au') and mis-placed delegated
+ *   sub-zone records; it is deleted. Zone identity now arrives explicitly, in
+ *   priority order: a CLI-injected {@link ManagedDomainBinding} (literal
+ *   values — crosses accounts and regions), the legacy
+ *   {@link ManagedDomainExports} form (Fn.importValue — same-account,
+ *   same-region only), or the pattern's own `zoneName`/`hostedZoneId` props.
+ *   No identity at all is a synth-time error naming the cures.
+ * - Every path validates the requested domain sits within the declared zone
+ *   (dot-boundary `isWithinZone`), so a mismatch throws at synth instead of
+ *   silently synthesising a record for the wrong FQDN.
+ * - CloudFront accepts viewer certificates from us-east-1 only. A binding
+ *   carries the domain stack's us-east-1 certificate ARN as an inspectable
+ *   literal (asserted here at synth); the BYO and legacy-exports paths
+ *   provision an app-owned DNS-validated certificate — in-stack when the app
+ *   itself deploys to us-east-1, otherwise in the app-owned
+ *   `${app}UsEast1Certificates` stack consumed through CDK cross-region
+ *   references.
+ */
+import { type Construct } from "constructs";
+import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type IHostedZone } from "aws-cdk-lib/aws-route53";
+import type App from "../../app.js";
+import { type ManagedDomainBinding, type ManagedDomainExports } from "../../utils/domainTypes.js";
+/**
+ * The explicit zone-identity surface shared by `IStaticSiteProps` and
+ * `IPayloadProps` — resolution priority is `managedDomain` (binding, then
+ * legacy exports) over `zoneName`/`hostedZoneId`.
+ */
+export interface PatternZoneIdentity {
+    readonly managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    readonly zoneName?: string;
+    readonly hostedZoneId?: string;
+}
+/**
+ * One pattern's domain-resolution request. `scope` is the pattern construct
+ * itself; `idPrefix` is its PascalCase name (construct-ID prefix, unique per
+ * scope); `context` prefixes every error, e.g. `Static site 'marketing'`.
+ */
+export interface PatternDomainRequest {
+    readonly scope: Construct;
+    readonly app: App;
+    readonly idPrefix: string;
+    readonly context: string;
+    readonly domain: string;
+    readonly identity: PatternZoneIdentity;
+}
+export interface ResolvedPatternZone {
+    readonly hostedZone: IHostedZone;
+    readonly zoneName: string;
+}
+export declare function resolvePatternZone(request: PatternDomainRequest): ResolvedPatternZone;
+/**
+ * Resolve the CloudFront viewer certificate for a pattern domain (H3/D3).
+ *
+ * - Managed binding: consume the injected us-east-1 ARN as a literal,
+ *   asserting its region component at synth (literal ARNs are inspectable).
+ * - Legacy exports in a us-east-1 or region-unresolved app: keep the
+ *   same-region Fn.importValue path unchanged (the D2 bare-CDK fallback).
+ * - Otherwise (BYO zone identity, or legacy exports in a non-us-east-1 app):
+ *   provision an app-owned DNS-validated certificate — beside the consumer
+ *   when the app already deploys to us-east-1, else in the dedicated
+ *   `${app}UsEast1Certificates` stack, consumed through CDK cross-region
+ *   references. In-app certificates are consumed in-app, so the
+ *   `<domain>-certificate-arn` export is always suppressed
+ *   (exportCertificateArn: false, §12-I) to avoid colliding with a
+ *   managed-domain/apex stack that owns the domain's exports.
+ */
+export declare function resolvePatternCloudFrontCertificate(request: PatternDomainRequest, zone: ResolvedPatternZone): ICertificate;