@fjall/deploy-core 2.33.0 → 3.0.0

package/dist/src/orchestration/dockerInterface.d.ts

@@ -91,6 +91,16 @@ export interface DockerBuildParams {
      * both for the whole group rather than trying to push two variants.
      */
     targetsLambda?: boolean;
+    /**
+     * Caller abort signal (deploy cancel, worker SIGTERM, wave sibling-failure
+     * controller). CANONICAL RATIONALE — providers thread this to the underlying
+     * buildx subprocess so an in-flight build/push can be interrupted instead of
+     * running minutes past the cancellation. Killing buildx mid-push is safe:
+     * ECR deduplicates blobs so a retry re-uploads only what is missing, and the
+     * registry cache tag is mutable by design. Absent → the build runs to
+     * completion (pre-2.34 behaviour).
+     */
+    abortSignal?: AbortSignal;
 }
 export interface DockerBuildResult {
     imageUri: string;
@@ -178,6 +188,12 @@ export interface DockerProvider {
     beginEcrSession?(params: {
         accountId: string;
         region: string;
+        /**
+         * Declared from birth per robustness-standards § "Optional-capability seam
+         * methods carry `abortSignal?`" — implementers compose it with their SDK
+         * timeouts via `composeSdkAbortSignal`; ignoring it is permitted.
+         */
+        abortSignal?: AbortSignal;
     }): Promise<Result<void>>;
     endEcrSession?(): Promise<void>;
     buildAndPush(params: DockerBuildParams, onProgress?: DockerProgressCallback, onBuildxEvent?: (event: BuildxProgressEvent) => void): Promise<Result<DockerBuildResult>>;

package/dist/src/orchestration/domain/caaPreflight.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CAA preflight — run before the FIRST certificate issuance for a delegated
+ * child domain (D8; dev-substrate design gap D1). ACM consults CAA up the
+ * parent chain regardless of where the validation records live: a parent CAA
+ * record set that does not authorise Amazon's CA makes ACM REFUSE issuance
+ * even when the NS delegation is perfect, so the `phase: "full"` deploy would
+ * hang exactly like an unpropagated delegation.
+ *
+ * RFC 8659 semantics: the RELEVANT record set is the closest ancestor (or the
+ * name itself) that has any CAA records — once a set is found the walk stops.
+ * No CAA records anywhere ⇒ issuance is permitted by spec ⇒ pass.
+ */
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+import { DomainDelegationError, type PublicCaaRecord, type PublicDnsResolver } from "./types.js";
+/**
+ * The CA domains ACM issues under (AWS documented set). A CAA `issue` /
+ * `issuewild` value naming any of these authorises ACM.
+ */
+export declare const ACM_CAA_ISSUERS: readonly ["amazon.com", "amazontrust.com", "awstrust.com", "amazonawstrust.com"];
+export interface CaaPreflightParams {
+    /** The domain certificates will be requested for (the child zone name). */
+    certificateDomain: string;
+    /** Injectable resolvers (tests use fakes); defaults to 1.1.1.1 + 8.8.8.8. */
+    resolvers?: readonly PublicDnsResolver[];
+    abortSignal?: AbortSignal;
+    callbacks?: DeployCallbacks;
+}
+export type CaaPreflightVerdict = 
+/** No CAA record set exists anywhere up the chain — issuance permitted. */
+{
+    authorised: true;
+    reason: "no-caa-found";
+}
+/** The relevant set authorises ACM (or restricts nothing). */
+ | {
+    authorised: true;
+    reason: "acm-authorised" | "no-issue-restriction";
+    /** The name carrying the relevant CAA record set. */
+    caaName: string;
+    records: string[];
+};
+/** `certificateDomain` and every ancestor down to the registrable pair. */
+export declare function caaAncestorChain(certificateDomain: string): string[];
+/** Render a CAA record in zone-file form for value-echoing errors. */
+export declare function formatCaaRecord(record: PublicCaaRecord): string;
+/**
+ * Walk the parent chain and evaluate the relevant CAA record set. Read-only.
+ *
+ * Fail-closed polarity (fail-closed ADR): a restrictive set fails with the
+ * EXACT records found and the cure (add an ACM-authorising CAA record, or
+ * issue certificates outside ACM); a chain that cannot be READ also fails
+ * closed — issuance cannot be proven safe — naming the `skipCaaPreflight`
+ * pre-answer for an operator who has verified the chain out of band.
+ */
+export declare function runCaaPreflight(params: CaaPreflightParams): Promise<Result<CaaPreflightVerdict, DomainDelegationError>>;

package/dist/src/orchestration/domain/caaPreflight.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var o=(e,r)=>w(e,"name",{value:r,configurable:!0});import{success as d,failure as l}from"@fjall/generator";import{getErrorMessage as $,maskSensitiveOutput as k}from"@fjall/util";import{isAborted as y}from"../../aws/organisations/types.js";import{createPublicResolvers as b,isDnsEmptyAnswer as D,normaliseDnsName as m,DomainDelegationError as h}from"./types.js";const A=["amazon.com","amazontrust.com","awstrust.com","amazonawstrust.com"];function v(e){const r=[];let t=m(e);for(;t.split(".").length>=2;)r.push(t),t=t.split(".").slice(1).join(".");return r}o(v,"caaAncestorChain");function M(e){const r=e.issue!==void 0?["issue",e.issue]:e.issuewild!==void 0?["issuewild",e.issuewild]:["iodef",e.iodef??""];return`${e.critical} ${r[0]} "${r[1]}"`}o(M,"formatCaaRecord");function S(e){const r=e.split(";")[0]??"";return m(r)}o(S,"issuerDomain");function g(e){const r=new Set(A);return e.some(t=>r.has(S(t)))}o(g,"authorisesAcm");async function P(e,r){const t=[];for(const c of r)try{const i=await c.resolveCaa(e);return i.length===0?{kind:"empty"}:{kind:"records",records:i}}catch(i){if(D(i))return{kind:"empty"};t.push(`${c.address}: ${k($(i))}`)}return{kind:"unverifiable",detail:t.join("; ")}}o(P,"queryCaaAcrossResolvers");async function E(e){const r=e.resolvers??b(),t=r.map(i=>i.address).join(", "),c=v(e.certificateDomain);for(const i of c){if(y(e.abortSignal))return l(new h(`CAA preflight for ${e.certificateDomain} aborted before ${i} was checked \u2014 no certificate was requested. Re-run the deploy to resume.`,"aborted",{certificateDomain:e.certificateDomain},!0));const n=await P(i,r);if(n.kind==="unverifiable")return l(new h(`CAA preflight for ${e.certificateDomain}: could not read CAA records for ${i} from any public resolver (${t}): ${n.detail}. ACM issuance cannot be proven safe, so the certificate phase is withheld (fail closed). Cure: retry once DNS resolution recovers, or verify the chain yourself (\`dig +short CAA ${i}\`) and pre-answer this check with skipCaaPreflight (CLI: --skip-caa-preflight).`,"caa_unverifiable",{certificateDomain:e.certificateDomain,name:i},!0));if(n.kind==="empty")continue;const a=n.records.map(M),f=n.records.map(s=>s.issue).filter(s=>s!==void 0),u=n.records.map(s=>s.issuewild).filter(s=>s!==void 0);if(f.length===0&&u.length===0)return e.callbacks?.onProgress?.({type:"info",message:`CAA preflight: ${i} carries CAA records but no issue/issuewild restriction \u2014 ACM issuance permitted`}),d({authorised:!0,reason:"no-issue-restriction",caaName:i,records:a});const p=f.length===0||g(f),C=u.length===0||g(u);return p&&C?(e.callbacks?.onProgress?.({type:"info",message:`CAA preflight: ${i} authorises ACM issuance (${a.join("; ")})`}),d({authorised:!0,reason:"acm-authorised",caaName:i,records:a})):l(new h(`CAA preflight for ${e.certificateDomain}: the CAA record set at ${i} does not authorise ACM \u2014 found [${a.join("; ")}]. ACM issues via ${A.join("/")} and will refuse issuance regardless of NS delegation, so the certificate phase is withheld before it can hang. Cure: add a CAA record authorising ACM at ${i} (e.g. \`${i}. CAA 0 issue "amazon.com"\`${u.length>0?` and \`${i}. CAA 0 issuewild "amazon.com"\``:""}), then re-run; or issue certificates outside ACM and set skipCaaPreflight (CLI: --skip-caa-preflight).`,"caa_restrictive",{certificateDomain:e.certificateDomain,name:i,records:a}))}return e.callbacks?.onProgress?.({type:"info",message:`CAA preflight: no CAA records anywhere up the chain from ${e.certificateDomain} \u2014 ACM issuance permitted by spec`}),d({authorised:!0,reason:"no-caa-found"})}o(E,"runCaaPreflight");export{A as ACM_CAA_ISSUERS,v as caaAncestorChain,M as formatCaaRecord,E as runCaaPreflight};

package/dist/src/orchestration/domain/delegatedDomainDeploy.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Two-phase delegated-domain deploy orchestration (D8): deploy the domain
+ * stack at `phase: "zone"` (child zone + child-writes NS delegation, NO
+ * certificates), hold at the bounded public-resolver propagation gate, run
+ * the CAA preflight, then deploy `phase: "full"`. Generalises the
+ * dev-substrate design's R2 two-step gate (design :104-121) for every
+ * delegated child domain.
+ *
+ * The construct side of the contract is `composeDelegatedDomain`'s `phase`
+ * prop; the caller (Phase-3 CLI / worker) supplies the deployer that maps a
+ * phase onto its CDK invocation. deploy-core owns the ordering, the gate and
+ * the fail-closed stops — orchestration ships here, not in docs.
+ *
+ * Idempotent resume: when the zone phase already succeeded, a re-run skips
+ * straight to the propagation gate — "zone exists, no cert" is an explicit
+ * retryable intermediate, never an error state.
+ */
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+import { type NsPropagationVerdict } from "./nsPropagationGate.js";
+import { DomainDelegationError, type DomainDeployPhase, type PublicDnsResolver } from "./types.js";
+/** What the caller's zone-phase probe reports for idempotent resume. */
+export interface DelegatedZonePhaseState {
+    /** True when the zone phase has already deployed successfully. */
+    complete: boolean;
+    /**
+     * The child zone's authoritative name servers, when the caller can read
+     * them (domain-stack outputs). Fed to the propagation gate so a STALE
+     * parent delegation (pointing at a previous zone's NS set) is not
+     * mistaken for propagation.
+     */
+    nameServers?: readonly string[];
+}
+/**
+ * Caller-supplied deploy seam for ONE delegated domain — the delegated-domain
+ * mirror of `DomainDeployProvider.deployDomain`, split by phase. The CLI maps
+ * `deployPhase` onto its CDK deploy with the `phase` context injected;
+ * `zonePhaseState` probes the deployed stack (DescribeStacks + outputs).
+ */
+export interface DelegatedDomainDeployer {
+    /** Fully-qualified child zone name, e.g. `dev.example.com`. */
+    readonly zoneName: string;
+    deployPhase(phase: DomainDeployPhase, callbacks: DeployCallbacks): Promise<Result<void, Error>>;
+    zonePhaseState(): Promise<Result<DelegatedZonePhaseState, Error>>;
+}
+export interface DeployDelegatedDomainParams {
+    deployer: DelegatedDomainDeployer;
+    callbacks: DeployCallbacks;
+    /**
+     * Pre-answer for the CAA preflight (fail-closed ADR shape): skip the check
+     * when the operator has verified the chain out of band. The skip is loud —
+     * a warning names it — never silent.
+     */
+    skipCaaPreflight?: boolean;
+    propagation?: {
+        maxAttempts?: number;
+        intervalMs?: number;
+    };
+    /** Injectable resolvers shared by the gate and the CAA preflight. */
+    resolvers?: readonly PublicDnsResolver[];
+    /** Injectable clock for the propagation gate. */
+    sleepFn?: (ms: number) => Promise<void>;
+    abortSignal?: AbortSignal;
+    /** Cure spelling for resume — defaults to `fjall domain deploy <zone>`. */
+    retryCommand?: string;
+}
+export interface DelegatedDomainDeployOutcome {
+    /** "resumed" when the zone phase was already deployed and was skipped. */
+    zonePhase: "deployed" | "resumed";
+    propagation: NsPropagationVerdict;
+    caaPreflight: "passed" | "skipped";
+    fullPhase: "deployed";
+}
+/**
+ * Run the full two-phase delegated-domain deploy. Every stop is fail-closed
+ * with a cure; every success path reports which steps ran so surfaces can
+ * render resume vs fresh honestly.
+ */
+export declare function deployDelegatedDomain(params: DeployDelegatedDomainParams): Promise<Result<DelegatedDomainDeployOutcome, DomainDelegationError>>;

package/dist/src/orchestration/domain/delegatedDomainDeploy.js

@@ -0,0 +1 @@
+var $=Object.defineProperty;var d=(e,r)=>$(e,"name",{value:r,configurable:!0});import{success as v,failure as p}from"@fjall/generator";import{getErrorMessage as f,maskSensitiveOutput as c}from"@fjall/util";import{isAborted as b}from"../../aws/organisations/types.js";import{waitForNsPropagation as z}from"./nsPropagationGate.js";import{runCaaPreflight as w}from"./caaPreflight.js";import{DomainDelegationError as g}from"./types.js";const C=4;function i(e,r,o){e.onProgress?.({type:"step",message:o,metadata:{source:"domain-delegation",stepIndex:r,totalSteps:C}})}d(i,"step");async function F(e){const{deployer:r,callbacks:o}=e,t=r.zoneName,a=e.retryCommand??`fjall domain deploy ${t}`;let h="deployed",l;const n=await r.zonePhaseState();if(n.success&&n.data.complete)h="resumed",l=n.data.nameServers,i(o,0,`Zone phase for ${t} already deployed \u2014 resuming at the propagation gate`);else{n.success||o.onProgress?.({type:"info",message:`Could not probe the zone-phase state for ${t} (${c(f(n.error))}) \u2014 deploying the zone phase (idempotent)`}),i(o,0,`Deploying ${t} zone phase (phase: "zone" \u2014 child zone + NS delegation, no certificates)`);const s=await r.deployPhase("zone",o);if(!s.success)return p(new g(`Delegated-domain deploy for ${t}: the zone-phase deploy failed: ${c(f(s.error))}. No certificate was requested. Cure: fix the reported stack failure and re-run \`${a}\` \u2014 a completed zone phase is skipped on resume.`,"zone_phase_failed",{zoneName:t}));const S=await r.zonePhaseState();S.success&&(l=S.data.nameServers)}if(b(e.abortSignal))return p(P(t,a));i(o,1,`Waiting for the NS delegation of ${t} to propagate (public resolvers)`);const u=await z({zoneName:t,...l!==void 0?{expectedNameServers:l}:{},...e.propagation?.maxAttempts!==void 0?{maxAttempts:e.propagation.maxAttempts}:{},...e.propagation?.intervalMs!==void 0?{intervalMs:e.propagation.intervalMs}:{},...e.resolvers!==void 0?{resolvers:e.resolvers}:{},...e.sleepFn!==void 0?{sleepFn:e.sleepFn}:{},...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{},callbacks:o,retryCommand:a});if(!u.success)return u;let m="passed";if(e.skipCaaPreflight===!0)m="skipped",o.onProgress?.({type:"warning",message:`CAA preflight for ${t} SKIPPED (skipCaaPreflight) \u2014 if a parent CAA record restricts issuance, ACM will hang until CloudFormation rolls back`});else{i(o,2,`CAA preflight for ${t} (parent chain, public resolvers)`);const s=await w({certificateDomain:t,...e.resolvers!==void 0?{resolvers:e.resolvers}:{},...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{},callbacks:o});if(!s.success)return s}if(b(e.abortSignal))return p(P(t,a));i(o,3,`Deploying ${t} full phase (phase: "full" \u2014 certificates)`);const y=await r.deployPhase("full",o);return y.success?v({zonePhase:h,propagation:u.data,caaPreflight:m,fullPhase:"deployed"}):p(new g(`Delegated-domain deploy for ${t}: the full-phase deploy failed: ${c(f(y.error))}. The zone phase is deployed and the delegation is live. Cure: fix the reported stack failure and re-run \`${a}\` \u2014 the deploy resumes at the propagation gate and re-runs only the full phase.`,"full_phase_failed",{zoneName:t}))}d(F,"deployDelegatedDomain");function P(e,r){return new g(`Delegated-domain deploy for ${e} aborted between phases \u2014 the zone phase (when deployed) is retained. Re-run \`${r}\` to resume.`,"aborted",{zoneName:e},!0)}d(P,"abortedMidDeploy");export{F as deployDelegatedDomain};

package/dist/src/orchestration/domain/delegationDestroyMirror.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Destroy mirror for delegated child domains (D8; dev-substrate design :121):
+ * the child's NS record is deleted from the PARENT zone BEFORE the CFN
+ * destroy. Destroying first releases the child zone's name-server set back to
+ * the Route53 pool while the parent still delegates to it — a
+ * subdomain-takeover window. Delete-first trades a harmless orphaned-child-
+ * zone leak (if the subsequent destroy fails) for eliminating that window.
+ *
+ * Ownership detection: when the NS record is CFN-owned by the child stack's
+ * `CrossAccountZoneDelegationRecord` custom resource, the CFN destroy deletes
+ * it in-stack — the manual delete is SKIPPED (deleting it out-of-band first
+ * would fail the custom resource's own Delete). Only an out-of-stack record
+ * (written by an earlier orchestration or by hand) is deleted here.
+ *
+ * Consent: the deletion is destructive-adjacent and is NEVER a silent side
+ * effect — it is named as a row on the destruction ticket for the stack
+ * destroy and evaluated through the SAME `evaluateDestructionConsents` +
+ * digest TOCTOU path as every other ceremony (destruction-ceremony ADR: one
+ * primitive, five renderings). Consent withheld ⇒ nothing is deleted and the
+ * destroy does not start (exit-4 semantics at the surface).
+ */
+import { Route53Client } from "@aws-sdk/client-route-53";
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+import type { DestructionConsent, DestructionConsentGate, DestructionConsentReport, DestructionOutcome, DestructionTicket } from "../../types/destruction.js";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import { DomainDelegationError } from "./types.js";
+/**
+ * The custom-resource type CDK's `CrossAccountZoneDelegationRecord` emits —
+ * its presence in the child stack's deployed template proves the NS record is
+ * CFN-owned and will be deleted by the stack destroy itself.
+ */
+export declare const CROSS_ACCOUNT_DELEGATION_RESOURCE_TYPE = "Custom::CrossAccountZoneDelegation";
+/**
+ * Inspect a deployed CloudFormation template (JSON — the only form CDK
+ * emits) for the delegation custom resource. An unreadable template is a
+ * failure, not a guess: mis-detecting ownership either leaves a dangling
+ * delegation (takeover window) or breaks the custom resource's own Delete.
+ */
+export declare function templateOwnsDelegationRecord(templateBody: string): Result<boolean, Error>;
+export type NsDeleteOutcome = {
+    kind: "deleted";
+    recordValues: readonly string[];
+}
+/** The record was already gone — NotFound on delete is success. */
+ | {
+    kind: "record-absent";
+}
+/** The parent zone itself is gone — nothing can dangle. */
+ | {
+    kind: "parent-zone-absent";
+};
+export interface DeleteChildNsParams {
+    /** Base provider; the delegation role is assumed from it by literal ARN. */
+    aws: AwsProvider;
+    /** Parent DelegationRole ARN — always a literal (VD2-a), never an import. */
+    delegationRoleArn: string;
+    parentZoneName: string;
+    childZoneName: string;
+    abortSignal?: AbortSignal;
+    callbacks?: DeployCallbacks;
+    /** Test seam: replaces the assume-role + client construction. */
+    route53ClientFactory?: (roleArn: string) => Promise<Result<Pick<Route53Client, "send">, Error>>;
+}
+/**
+ * Delete the child zone's NS record from the parent zone via the parent
+ * DelegationRole (assumed by literal ARN). Idempotent: an absent record or an
+ * absent parent zone is success, so the mirror self-heals across retries.
+ * Every SDK call composes the caller's abort signal with the per-call
+ * timeout (robustness standards).
+ */
+export declare function deleteChildNsFromParent(params: DeleteChildNsParams): Promise<Result<NsDeleteOutcome, DomainDelegationError>>;
+/** How the NS delegation was handled ahead of the stack destroy. */
+export type DelegationDestroyNsOutcome = NsDeleteOutcome
+/** In-stack custom resource — the CFN destroy deletes it itself. */
+ | {
+    kind: "cfn-owned";
+}
+/**
+ * Case-3 externally-owned parent: fjall cannot delete the record; the
+ * operator consented `forget` (the record survives until removed by hand).
+ */
+ | {
+    kind: "external-forget";
+};
+export type DelegatedDomainDestroyOutcome = {
+    kind: "destroyed";
+    nsDelegation: DelegationDestroyNsOutcome;
+}
+/** Consent withheld — nothing was deleted, the destroy did not start. */
+ | {
+    kind: "withheld";
+    outcome: DestructionOutcome;
+    ticket: DestructionTicket;
+    report?: DestructionConsentReport;
+    reasons: string[];
+};
+export interface DelegatedDomainDestroyParams {
+    /** The delegated child zone being destroyed, e.g. `dev.example.com`. */
+    childZoneName: string;
+    /** The parent zone holding the NS delegation, e.g. `example.com`. */
+    parentZoneName: string;
+    /**
+     * Parent DelegationRole ARN (literal, from the managed-domain binding).
+     * Absent ⇒ Case-3 externally-owned parent: the record cannot be deleted by
+     * fjall, and proceeding requires an explicit `forget` consent.
+     */
+    delegationRoleArn?: string;
+    /** The child domain stack's name (ticket addressing + template fetch). */
+    stackName: string;
+    /**
+     * Fetch the child stack's deployed template for ownership detection.
+     * `undefined` data ⇒ the stack no longer exists (a previous destroy got
+     * further than this step) — the mirror still runs, because the NS record
+     * may be the surviving half.
+     */
+    getTemplate: (abortSignal?: AbortSignal) => Promise<Result<string | undefined, Error>>;
+    /** Executes the CFN destroy — invoked ONLY after the mirror step. */
+    destroyStack: (callbacks: DeployCallbacks) => Promise<Result<void, Error>>;
+    aws: AwsProvider;
+    callbacks: DeployCallbacks;
+    /** Flag-supplied consents (`--remediate <physicalName>=<verb>`). */
+    consents?: readonly DestructionConsent[];
+    /** Digest the consents were minted against (TOCTOU binding). */
+    consentDigest?: string;
+    /** Interactive ceremony resolver — consulted only when no flags came. */
+    consentGate?: DestructionConsentGate;
+    abortSignal?: AbortSignal;
+    /** Test seam forwarded to `deleteChildNsFromParent`. */
+    route53ClientFactory?: DeleteChildNsParams["route53ClientFactory"];
+}
+/** The exact consent string for the NS row: `<childZone>/NS`. */
+export declare function nsDelegationPhysicalName(childZoneName: string): string;
+/**
+ * Orchestrate the destroy of a delegated child domain stack: ownership
+ * detection → destruction-consent ceremony (the NS deletion named on the
+ * ticket) → NS delete (delete-first, idempotent) → CFN destroy. The
+ * ordering is structural — `destroyStack` is only reachable after the mirror
+ * step resolved — so no caller can destroy first by accident.
+ */
+export declare function runDelegatedDomainDestroy(params: DelegatedDomainDestroyParams): Promise<Result<DelegatedDomainDestroyOutcome, Error>>;

package/dist/src/orchestration/domain/delegationDestroyMirror.js

@@ -0,0 +1 @@
+var T=Object.defineProperty;var u=(e,t)=>T(e,"name",{value:t,configurable:!0});import{Route53Client as E,ListHostedZonesByNameCommand as Z,ListResourceRecordSetsCommand as x,ChangeResourceRecordSetsCommand as I}from"@aws-sdk/client-route-53";import{success as l,failure as d}from"@fjall/generator";import{getErrorMessage as y,maskSensitiveOutput as f}from"@fjall/util";import{SimpleAwsProvider as O}from"../../aws/SimpleAwsProvider.js";import{parseArn as L}from"../../aws/utils/arnParser.js";import{composeSdkAbortSignal as P,isAborted as F}from"../../aws/organisations/types.js";import{computeTicketDigest as _,evaluateDestructionConsents as D,renderConsentVerdictLines as j,renderDestructionTicketLines as z}from"../application/destructionGate.js";import{DomainDelegationError as b,normaliseDnsName as S}from"./types.js";const C="Custom::CrossAccountZoneDelegation";function M(e){let t;try{t=JSON.parse(e)}catch(a){return d(new Error(`Delegation destroy mirror: the child stack template is not readable JSON (${f(y(a))}) \u2014 NS-record ownership cannot be determined.`))}if(typeof t!="object"||t===null)return d(new Error("Delegation destroy mirror: the child stack template parsed to a non-object \u2014 NS-record ownership cannot be determined."));const n=t.Resources;if(n===void 0||typeof n!="object")return l(!1);const i=Object.values(n).some(a=>typeof a=="object"&&a!==null&&a.Type===C);return l(i)}u(M,"templateOwnsDelegationRecord");async function B(e,t){if(e.assumeRole===void 0)return d(new Error("the AWS provider does not support assumeRole"));const n=L(t)?.accountId;if(n===void 0||n==="")return d(new Error(`'${t}' is not a valid IAM role ARN`));try{const i=await e.assumeRole(t,"fjall-domain-destroy-mirror"),a=new O({accessKeyId:i.accessKeyId,secretAccessKey:i.secretAccessKey,...i.sessionToken!==void 0?{sessionToken:i.sessionToken}:{},region:"us-east-1",accountId:n});return l(a.getClient(E))}catch(i){return d(new Error(f(y(i))))}}u(B,"defaultRoute53ClientFactory");function H(e){if(!(e instanceof Error))return!1;const t=e.name,n=e.message.toLowerCase();return t==="InvalidChangeBatch"&&(n.includes("not found")||n.includes("does not exist"))}u(H,"isRecordNotFoundChange");async function K(e){const{parentZoneName:t,childZoneName:n}=e,i=u(s=>d(new b(`Destroy mirror for ${n}: deleting the NS delegation record from parent zone ${t} failed: ${s}. The stack destroy was NOT started \u2014 delete-first is the rule, because a dangling delegation is a subdomain-takeover window. Cure: re-run the destroy, or delete the ${n} NS record in ${t} yourself and re-run.`,"ns_delete_failed",{parentZoneName:t,childZoneName:n},!0)),"fail"),a=e.route53ClientFactory!==void 0?await e.route53ClientFactory(e.delegationRoleArn):await B(e.aws,e.delegationRoleArn);if(!a.success)return d(new b(`Destroy mirror for ${n}: could not assume the parent DelegationRole ${e.delegationRoleArn}: ${f(y(a.error))}. The stack destroy was NOT started. Cure: verify the role exists and trusts this account (it is created by the parent Domain stack), or delete the ${n} NS record in ${t} yourself and re-run.`,"delegation_role_unusable",{delegationRoleArn:e.delegationRoleArn}));const w=a.data,g={abortSignal:P(e.abortSignal)};let h;try{const r=((await w.send(new Z({DNSName:t,MaxItems:100}),g)).HostedZones??[]).filter(m=>m.Name!==void 0&&S(m.Name)===S(t));h=(r.find(m=>m.Config?.PrivateZone!==!0)??r[0])?.Id?.replace("/hostedzone/","")}catch(s){return i(f(y(s)))}if(h===void 0)return e.callbacks?.onProgress?.({type:"info",message:`Destroy mirror: parent zone ${t} was not found \u2014 no delegation record can dangle, continuing to the stack destroy`}),l({kind:"parent-zone-absent"});let c;try{const r=((await w.send(new x({HostedZoneId:h,StartRecordName:n,StartRecordType:"NS",MaxItems:1}),g)).ResourceRecordSets??[])[0];c=r!==void 0&&r.Name!==void 0&&S(r.Name)===S(n)&&r.Type==="NS"?r:void 0}catch(s){return i(f(y(s)))}if(c===void 0)return e.callbacks?.onProgress?.({type:"info",message:`Destroy mirror: no NS record for ${n} exists in ${t} \u2014 already deleted (idempotent), continuing to the stack destroy`}),l({kind:"record-absent"});try{await w.send(new I({HostedZoneId:h,ChangeBatch:{Comment:`fjall destroy mirror: remove NS delegation for ${n} before the stack destroy`,Changes:[{Action:"DELETE",ResourceRecordSet:c}]}}),g)}catch(s){return H(s)?l({kind:"record-absent"}):i(f(y(s)))}const R=(c.ResourceRecords??[]).map(s=>s.Value).filter(s=>s!==void 0);return e.callbacks?.onProgress?.({type:"info",message:`Destroy mirror: deleted the NS delegation for ${n} from ${t} (was: ${R.join(", ")})`}),l({kind:"deleted",recordValues:R})}u(K,"deleteChildNsFromParent");function v(e){return`${S(e)}/NS`}u(v,"nsDelegationPhysicalName");function V(e,t){const n={stack:e.stackName,logicalId:"ParentZoneNsDelegation",resourceType:"AWS::Route53::RecordSet",physicalName:v(e.childZoneName),finding:"data-loss-delete",cause:t==="deletable"?`NS delegation for ${e.childZoneName} in parent zone ${e.parentZoneName} is not CloudFormation-owned \u2014 it is deleted from the parent BEFORE the stack destroy (destroying first releases the child zone's name servers back to the Route53 pool while the parent still delegates: a subdomain-takeover window)`:`NS delegation for ${e.childZoneName} lives in the externally-owned parent ${e.parentZoneName} \u2014 fjall cannot delete it; consent 'forget' to destroy the stack anyway, then remove the record at the parent yourself (until removed it is a dangling delegation)`,offendingProperties:[],verdictSource:"change-set",dataLossRisk:t==="deletable",verbs:t==="deletable"?["abort","recreate"]:["abort","forget"]};return{ticketDigest:_(`domain-destroy:${e.stackName}:${e.childZoneName}`,[n]),resources:[n]}}u(V,"buildNsTicket");async function te(e){const{callbacks:t,childZoneName:n,parentZoneName:i}=e,a=await e.getTemplate(e.abortSignal);if(!a.success)return d(new b(`Destroy mirror for ${n}: could not read the deployed template of ${e.stackName} to determine NS-record ownership: ${f(y(a.error))}. Nothing was destroyed. Cure: retry the destroy; if the failure persists, inspect the stack with \`aws cloudformation get-template --stack-name ${e.stackName}\`.`,"template_unreadable",{stackName:e.stackName},!0));let w=!1;if(a.data!==void 0){const o=M(a.data);if(!o.success)return d(new b(`${f(o.error.message)} Nothing was destroyed. Cure: retry the destroy; if the failure persists, inspect the stack with \`aws cloudformation get-template --stack-name ${e.stackName}\`.`,"template_unreadable",{stackName:e.stackName},!0));w=o.data}if(w){t.onProgress?.({type:"info",message:`NS delegation for ${n} is CloudFormation-owned (${C}) \u2014 the stack destroy removes it in-stack, no pre-destroy delete needed`});const o=await e.destroyStack(t);return o.success?l({kind:"destroyed",nsDelegation:{kind:"cfn-owned"}}):d(o.error)}const g=e.delegationRoleArn,h=g!==void 0?"deletable":"external",c=V(e,h),R=h==="deletable"?"recreate":"forget",s=e.consents??[];let r=D({ticket:c,consents:s,...e.consentDigest!==void 0?{consentDigest:e.consentDigest}:{}});const N=[];if(!r.satisfied&&e.consentGate!==void 0&&s.length===0&&e.consentDigest===void 0){const o=await e.consentGate.resolve({target:e.stackName,ticket:c});o.kind==="abort"?N.push("declined at the interactive destruction ceremony \u2014 nothing was deleted, nothing was destroyed"):r=D({ticket:c,consents:o.consents,consentDigest:o.ticketDigest})}const m=r.satisfied&&r.rows.some(o=>o.verdict==="matched"&&o.verb==="abort");if(!r.satisfied||m||N.length>0){const o=N.length>0||m?"declined":r.rows.length>0||r.digestMismatch?"consents-invalid":"awaiting-consent",A=o==="declined"?`Destroy of ${e.stackName} declined \u2014 the NS-delegation removal was not consented; nothing was deleted, nothing was destroyed`:`Destroying ${e.stackName} deletes the NS delegation for ${n} from ${i} \u2014 named consent required; nothing was deleted, nothing was destroyed`;t.onLog?.(A,"warn");for(const k of z(c))t.onLog?.(k,"warn");for(const k of j(r))t.onLog?.(k,"warn");for(const k of N)t.onLog?.(k,"warn");return o!=="declined"&&t.onLog?.(`Consent with --remediate ${v(n)}=${R} (exact, case-sensitive). No blanket flag exists: --auto-approve, --skip-confirmation and approval tokens never satisfy this gate.`,"warn"),l({kind:"withheld",outcome:o,ticket:c,report:r,reasons:N})}if(F(e.abortSignal))return d(new b(`Destroy of ${e.stackName} aborted before the NS-delegation removal \u2014 nothing was deleted, nothing was destroyed. Re-run the destroy to resume.`,"aborted",{stackName:e.stackName},!0));let $;if(g!==void 0){const o=await K({aws:e.aws,delegationRoleArn:g,parentZoneName:i,childZoneName:n,...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{},callbacks:t,...e.route53ClientFactory!==void 0?{route53ClientFactory:e.route53ClientFactory}:{}});if(!o.success)return d(o.error);$=o.data}else $={kind:"external-forget"},t.onProgress?.({type:"warning",message:`NS delegation for ${n} remains in the externally-owned parent ${i} (consented 'forget') \u2014 remove it at the parent to close the dangling delegation`});const p=await e.destroyStack(t);return p.success?l({kind:"destroyed",nsDelegation:$}):d(p.error)}u(te,"runDelegatedDomainDestroy");export{C as CROSS_ACCOUNT_DELEGATION_RESOURCE_TYPE,K as deleteChildNsFromParent,v as nsDelegationPhysicalName,te as runDelegatedDomainDestroy,M as templateOwnsDelegationRecord};

package/dist/src/orchestration/domain/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Delegated-domain orchestration (D8, domain gold-plating): two-phase
+ * zone → propagation-gate → CAA-preflight → full deploy, and the
+ * delete-NS-before-destroy mirror with its consent ceremony.
+ */
+export { DOMAIN_DELEGATION_ERROR_TYPES, DomainDelegationError, DEFAULT_PUBLIC_RESOLVER_ADDRESSES, PUBLIC_DNS_QUERY_TIMEOUT_MS, createPublicResolvers, normaliseDnsName, isDnsEmptyAnswer, type DomainDeployPhase, type DomainDelegationErrorType, type PublicCaaRecord, type PublicDnsResolver } from "./types.js";
+export { NS_PROPAGATION_DEFAULT_MAX_ATTEMPTS, NS_PROPAGATION_DEFAULT_INTERVAL_MS, waitForNsPropagation, type NsPropagationGateParams, type NsPropagationVerdict } from "./nsPropagationGate.js";
+export { ACM_CAA_ISSUERS, caaAncestorChain, formatCaaRecord, runCaaPreflight, type CaaPreflightParams, type CaaPreflightVerdict } from "./caaPreflight.js";
+export { deployDelegatedDomain, type DelegatedDomainDeployer, type DelegatedZonePhaseState, type DeployDelegatedDomainParams, type DelegatedDomainDeployOutcome } from "./delegatedDomainDeploy.js";
+export { CROSS_ACCOUNT_DELEGATION_RESOURCE_TYPE, templateOwnsDelegationRecord, deleteChildNsFromParent, nsDelegationPhysicalName, runDelegatedDomainDestroy, type NsDeleteOutcome, type DeleteChildNsParams, type DelegationDestroyNsOutcome, type DelegatedDomainDestroyOutcome, type DelegatedDomainDestroyParams } from "./delegationDestroyMirror.js";

package/dist/src/orchestration/domain/index.js

@@ -0,0 +1 @@
+import{DOMAIN_DELEGATION_ERROR_TYPES as r,DomainDelegationError as a,DEFAULT_PUBLIC_RESOLVER_ADDRESSES as _,PUBLIC_DNS_QUERY_TIMEOUT_MS as E,createPublicResolvers as t,normaliseDnsName as A,isDnsEmptyAnswer as D}from"./types.js";import{NS_PROPAGATION_DEFAULT_MAX_ATTEMPTS as R,NS_PROPAGATION_DEFAULT_INTERVAL_MS as S,waitForNsPropagation as T}from"./nsPropagationGate.js";import{ACM_CAA_ISSUERS as m,caaAncestorChain as l,formatCaaRecord as s,runCaaPreflight as N}from"./caaPreflight.js";import{deployDelegatedDomain as P}from"./delegatedDomainDeploy.js";import{CROSS_ACCOUNT_DELEGATION_RESOURCE_TYPE as I,templateOwnsDelegationRecord as U,deleteChildNsFromParent as p,nsDelegationPhysicalName as L,runDelegatedDomainDestroy as c}from"./delegationDestroyMirror.js";export{m as ACM_CAA_ISSUERS,I as CROSS_ACCOUNT_DELEGATION_RESOURCE_TYPE,_ as DEFAULT_PUBLIC_RESOLVER_ADDRESSES,r as DOMAIN_DELEGATION_ERROR_TYPES,a as DomainDelegationError,S as NS_PROPAGATION_DEFAULT_INTERVAL_MS,R as NS_PROPAGATION_DEFAULT_MAX_ATTEMPTS,E as PUBLIC_DNS_QUERY_TIMEOUT_MS,l as caaAncestorChain,t as createPublicResolvers,p as deleteChildNsFromParent,P as deployDelegatedDomain,s as formatCaaRecord,D as isDnsEmptyAnswer,A as normaliseDnsName,L as nsDelegationPhysicalName,N as runCaaPreflight,c as runDelegatedDomainDestroy,U as templateOwnsDelegationRecord,T as waitForNsPropagation};

package/dist/src/orchestration/domain/nsPropagationGate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * NS propagation gate — the bounded public-recursive-resolver check between
+ * the `phase: "zone"` and `phase: "full"` deploys of a delegated child domain
+ * (D8; dev-substrate design R2 refinement). A bare `GetHostedZone` proves the
+ * child zone EXISTS; only a public resolver proves the parent's delegation
+ * has PROPAGATED — and issuing a DNS-validated certificate before then hangs
+ * ACM until CloudFormation rolls back (~1 h).
+ *
+ * Fail-closed on bound-expiry with `delegation_unreachable` (the design's 422
+ * vocabulary), naming the retry command and the manual-NS option (Case-3
+ * externally-owned parent) per the fail-closed ADR.
+ */
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+import { DomainDelegationError, type PublicDnsResolver } from "./types.js";
+/** ~2 minutes of polling by default: 12 attempts x 10s interval. */
+export declare const NS_PROPAGATION_DEFAULT_MAX_ATTEMPTS = 12;
+export declare const NS_PROPAGATION_DEFAULT_INTERVAL_MS = 10000;
+export interface NsPropagationGateParams {
+    /** Fully-qualified delegated child zone, e.g. `dev.example.com`. */
+    zoneName: string;
+    /**
+     * The child zone's authoritative name servers, when the caller knows them
+     * (domain-stack outputs). Supplied ⇒ a public NS answer must overlap this
+     * set — an answer pointing at a DIFFERENT NS set is a STALE delegation (a
+     * prior zone's name servers still answering), exactly the state that hangs
+     * certificate validation, so the gate keeps polling rather than passing.
+     */
+    expectedNameServers?: readonly string[];
+    maxAttempts?: number;
+    intervalMs?: number;
+    /** Injectable resolvers (tests use fakes); defaults to 1.1.1.1 + 8.8.8.8. */
+    resolvers?: readonly PublicDnsResolver[];
+    /** Injectable clock (tests make the interval instant). */
+    sleepFn?: (ms: number) => Promise<void>;
+    abortSignal?: AbortSignal;
+    callbacks?: DeployCallbacks;
+    /**
+     * The command the cure names for resuming after propagation completes.
+     * Phase-3 surfaces pass their own spelling; the default is the CLI verb.
+     */
+    retryCommand?: string;
+}
+export interface NsPropagationVerdict {
+    /** The name servers the succeeding resolver returned. */
+    nameServers: string[];
+    /** 1-based attempt count at success. */
+    attempts: number;
+    /** Which public resolver observed the delegation. */
+    resolverAddress: string;
+}
+/**
+ * Poll the public resolvers until the child zone's NS delegation is visible,
+ * up to `maxAttempts` x `intervalMs`. Read-only; safe to re-run any number of
+ * times. Expiry returns `delegation_unreachable` — the zone phase stays
+ * deployed and retained, so the cure is a re-run (which resumes at this gate),
+ * never a rollback.
+ */
+export declare function waitForNsPropagation(params: NsPropagationGateParams): Promise<Result<NsPropagationVerdict, DomainDelegationError>>;

package/dist/src/orchestration/domain/nsPropagationGate.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var d=(e,t)=>S(e,"name",{value:t,configurable:!0});import{success as b,failure as c}from"@fjall/generator";import{getErrorMessage as y,maskSensitiveOutput as z,sleep as w}from"@fjall/util";import{isAborted as g}from"../../aws/organisations/types.js";import{createPublicResolvers as x,normaliseDnsName as p,DomainDelegationError as h}from"./types.js";const A=12,P=1e4;function k(e,t){const n=new Set(t.map(p));return e.some(a=>n.has(p(a)))}d(k,"overlaps");async function j(e){const t=e.maxAttempts??A,n=e.intervalMs??P,a=e.resolvers??x(),f=e.sleepFn??w,i=e.retryCommand??`fjall domain deploy ${e.zoneName}`,u=a.map(o=>o.address);let l;for(let o=1;o<=t;o++){if(g(e.abortSignal))return c(m(e.zoneName,i));for(const s of a){let r;try{r=await s.resolveNs(e.zoneName)}catch(v){e.callbacks?.onProgress?.({type:"debug",message:`NS propagation check ${o}/${t} for ${e.zoneName} via ${s.address}: ${z(y(v))}`});continue}if(r.length!==0){if(e.expectedNameServers!==void 0&&e.expectedNameServers.length>0&&!k(r,e.expectedNameServers)){l=r,e.callbacks?.onProgress?.({type:"debug",message:`NS propagation check ${o}/${t} for ${e.zoneName} via ${s.address}: answer [${r.join(", ")}] does not overlap the child zone's name servers yet (stale delegation still cached)`});continue}return e.callbacks?.onProgress?.({type:"info",message:`NS delegation for ${e.zoneName} is publicly resolvable (attempt ${o}/${t}, via ${s.address})`}),b({nameServers:r,attempts:o,resolverAddress:s.address})}}o<t&&(e.callbacks?.onProgress?.({type:"spinner",message:`Waiting for NS delegation of ${e.zoneName} to propagate (attempt ${o}/${t}, next check in ${Math.round(n/1e3)}s)`}),await f(n))}if(g(e.abortSignal))return c(m(e.zoneName,i));const N=l!==void 0&&e.expectedNameServers!==void 0?`; the parent currently delegates to [${l.join(", ")}] but the child zone's name servers are [${e.expectedNameServers.join(", ")}] \u2014 a stale delegation from an earlier zone`:"",$=Math.round(t*n/1e3);return c(new h(`NS propagation gate for ${e.zoneName}: the delegation did not become publicly resolvable within ${t} attempts over ~${$}s (resolvers: ${u.join(", ")})${N}. The zone phase is deployed and retained \u2014 nothing was rolled back and no certificate was requested. Cure: once the parent delegation has propagated, re-run \`${i}\` (the zone phase is skipped on resume and the deploy continues from this gate); if the parent zone is externally owned (Case 3), add the child zone's NS records at the parent registrar manually, then re-run \`${i}\`.`,"delegation_unreachable",{zoneName:e.zoneName,maxAttempts:t,intervalMs:n,resolvers:u},!0))}d(j,"waitForNsPropagation");function m(e,t){return new h(`NS propagation gate for ${e} aborted \u2014 the zone phase remains deployed and no certificate was requested. Re-run \`${t}\` to resume at this gate.`,"aborted",{zoneName:e},!0)}d(m,"abortedError");export{P as NS_PROPAGATION_DEFAULT_INTERVAL_MS,A as NS_PROPAGATION_DEFAULT_MAX_ATTEMPTS,j as waitForNsPropagation};

package/dist/src/orchestration/domain/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared contracts for the delegated-domain orchestration (D8 of the domain
+ * gold-plating design, 2026-07-17): the two-phase zone → propagation-gate →
+ * full deploy, the CAA preflight before first certificate issuance, and the
+ * destroy mirror that removes the child NS from the parent BEFORE the CFN
+ * destroy.
+ *
+ * `DomainDeployPhase` is deploy-core's copy of the construct-side wire
+ * contract (`components/infrastructure/lib/utils/domainTypes.ts`, shared with
+ * `DevSubstrate.phase`): the CLI injects `phase` into synth and
+ * `composeDelegatedDomain` early-returns before certificate issuance when the
+ * phase is `"zone"`. deploy-core does not depend on components-infrastructure
+ * (layer boundary), so the two-literal union is re-declared here; both sides
+ * document the other as the counterpart.
+ */
+import { BaseServiceError } from "../../types/errors/ServiceError.js";
+/** Two-step deploy phase — the construct-side gate's wire vocabulary. */
+export type DomainDeployPhase = "zone" | "full";
+/**
+ * Typed failure vocabulary for the delegation orchestration. The codes are
+ * part of the surface contract: `delegation_unreachable` mirrors the
+ * dev-substrate design's 422 reason (design :104-121), and Phase-3 CLI verbs
+ * map them to exit codes / TOON blocks without string-matching messages.
+ */
+export declare const DOMAIN_DELEGATION_ERROR_TYPES: readonly ["delegation_unreachable", "caa_restrictive", "caa_unverifiable", "zone_phase_failed", "full_phase_failed", "delegation_role_unusable", "template_unreadable", "ns_delete_failed", "aborted"];
+export type DomainDelegationErrorType = (typeof DOMAIN_DELEGATION_ERROR_TYPES)[number];
+/**
+ * Delegation-orchestration error. Messages are pre-masked at construction
+ * (identifier-only content plus `maskSensitiveOutput`-routed SDK text) and
+ * every non-interactive stop names its cure per the fail-closed ADR
+ * (decisions/2026-07-12-fail-closed-default-policy.md).
+ */
+export declare class DomainDelegationError extends BaseServiceError {
+    readonly errorType: DomainDelegationErrorType;
+    constructor(message: string, errorType: DomainDelegationErrorType, details?: unknown, recoverable?: boolean);
+}
+/**
+ * One CAA record as node's resolver returns it. Structurally compatible with
+ * `dns.CaaRecord` — declared here so fakes in tests and non-node resolvers
+ * need no dns import.
+ */
+export interface PublicCaaRecord {
+    critical: number;
+    issue?: string;
+    issuewild?: string;
+    iodef?: string;
+}
+/**
+ * A recursive resolver pinned to ONE public address. The propagation gate and
+ * the CAA preflight take these by injection so tests run against fakes; the
+ * default set queries Cloudflare and Google (the answer must be visible to
+ * the public internet, not merely to the deployer's split-horizon resolver).
+ */
+export interface PublicDnsResolver {
+    readonly address: string;
+    resolveNs(name: string): Promise<string[]>;
+    resolveCaa(name: string): Promise<PublicCaaRecord[]>;
+}
+export declare const DEFAULT_PUBLIC_RESOLVER_ADDRESSES: readonly ["1.1.1.1", "8.8.8.8"];
+/** Per-query timeout — mirrors DomainService.verifyDomain's 10s bound. */
+export declare const PUBLIC_DNS_QUERY_TIMEOUT_MS = 10000;
+/**
+ * Build one `node:dns` resolver per public address, each bounded by the
+ * shared 10s query timeout with a single try (the gate's outer loop owns
+ * retrying — stacking resolver-level retries on top would stretch the bound).
+ */
+export declare function createPublicResolvers(addresses?: readonly string[]): PublicDnsResolver[];
+/** Case/trailing-dot-insensitive DNS name comparison form. */
+export declare function normaliseDnsName(name: string): string;
+/**
+ * True when a resolver error is a DEFINITIVE empty answer (the name or RRset
+ * does not exist) rather than a lookup failure. The CAA preflight treats only
+ * these as "no CAA here"; anything else is unverifiable and fails closed.
+ */
+export declare function isDnsEmptyAnswer(error: unknown): boolean;

package/dist/src/orchestration/domain/types.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var t=(e,r)=>a(e,"name",{value:r,configurable:!0});import{Resolver as l}from"node:dns/promises";import{BaseServiceError as i}from"../../types/errors/ServiceError.js";const D=["delegation_unreachable","caa_restrictive","caa_unverifiable","zone_phase_failed","full_phase_failed","delegation_role_unusable","template_unreadable","ns_delete_failed","aborted"];class S extends i{static{t(this,"DomainDelegationError")}errorType;constructor(r,o,s,n=!1){super(`DOMAIN_${o.toUpperCase()}`,r,s,n),this.errorType=o}}const _=["1.1.1.1","8.8.8.8"],c=1e4;function m(e=_){return e.map(r=>{const o=new l({timeout:c,tries:1});return o.setServers([r]),{address:r,resolveNs:t(s=>o.resolveNs(s),"resolveNs"),resolveCaa:t(s=>o.resolveCaa(s),"resolveCaa")}})}t(m,"createPublicResolvers");function N(e){return e.trim().toLowerCase().replace(/\.$/,"")}t(N,"normaliseDnsName");const p=new Set(["ENODATA","ENOTFOUND"]);function v(e){if(!(e instanceof Error))return!1;const r=e.code;return typeof r=="string"&&p.has(r)}t(v,"isDnsEmptyAnswer");export{_ as DEFAULT_PUBLIC_RESOLVER_ADDRESSES,D as DOMAIN_DELEGATION_ERROR_TYPES,S as DomainDelegationError,c as PUBLIC_DNS_QUERY_TIMEOUT_MS,m as createPublicResolvers,v as isDnsEmptyAnswer,N as normaliseDnsName};

package/dist/src/orchestration/domainInterface.d.ts

@@ -1,5 +1,6 @@
 import type { Result } from "@fjall/generator";
 import type { DeployCallbacks } from "../types/callbacks.js";
+import type { DelegatedDomainDeployer } from "./domain/delegatedDomainDeploy.js";
 /**
  * Configuration for a single domain to deploy.
  */
@@ -34,4 +35,13 @@ export interface DomainDeployProvider {
      * roles; delegated domains create NS records in the parent zone.
      */
     deployDomain(domainName: string, callbacks: DeployCallbacks): Promise<Result<void>>;
+    /**
+     * Optional phase-aware seam for delegated child domains (D8). Returning a
+     * deployer routes the domain through the engine's two-phase orchestration
+     * (`deployDelegatedDomain`: zone deploy → bounded NS-propagation gate →
+     * CAA preflight → full deploy) instead of the single-shot `deployDomain`.
+     * Return `undefined` (or omit the method) for domains that carry no
+     * child-writes delegation — they keep the legacy single-shot path.
+     */
+    delegatedDeployer?(domainName: string): DelegatedDomainDeployer | undefined;
 }

package/dist/src/orchestration/drift/classifyDriftFailure.js

@@ -1 +1 @@
-import{CloudFormationClient as p,DescribeStackEventsCommand as m}from"@aws-sdk/client-cloudformation";import{success as a,failure as d}from"@fjall/generator";import{getErrorMessage as g,maskSensitiveOutput as l}from"@fjall/util";import{classifyDriftSuspectEvents as y,isOperationOpeningEvent as R}from"@fjall/util/aws";import{logger as E}from"@fjall/util/logger";import{composeSdkAbortSignal as S,isAborted as v}from"../../aws/organisations/types.js";const I="DriftClassify",h=5;function T(e){return e.includes("FAILED")}function D(e){return e.LogicalResourceId===void 0||e.ResourceType===void 0||e.ResourceStatus===void 0?null:{logicalId:e.LogicalResourceId,resourceType:e.ResourceType,status:e.ResourceStatus,timestamp:e.Timestamp??new Date(0),...e.PhysicalResourceId!==void 0&&e.PhysicalResourceId!==""?{physicalId:e.PhysicalResourceId}:{},...e.ResourceStatusReason!==void 0?{statusReason:e.ResourceStatusReason}:{}}}async function L(e,n,r){const t=e.getClient(p),o=[];let s,u=0;try{do{if(v(r))return d(new Error(`Drift event scan aborted for ${n}`));const i=await t.send(new m({StackName:n,...s!==void 0?{NextToken:s}:{}}),{abortSignal:S(r)});u+=1;for(const f of i.StackEvents??[]){const c=D(f);if(c!==null&&(o.push(c),R(c,n)))return a(o)}if(s=i.NextToken,u>=h&&s!==void 0)return E.debug(I,"Event scan truncated at page budget",{stackName:n,pages:u,eventsCollected:o.length}),a(o)}while(s!==void 0);return a(o)}catch(i){return d(new Error(`Failed to read stack events for ${n}: ${l(g(i))}`))}}function O(e,n){const r=n.filter(t=>T(t.status));return y(r).map(t=>({stackName:e,logicalId:t.logicalId,resourceType:t.resourceType,...t.physicalId!==void 0?{physicalId:t.physicalId}:{},failedStatus:t.failedStatus,statusReason:l(t.statusReason)}))}export{O as classifyDriftFailure,L as fetchLastOperationEvents};
+var m=Object.defineProperty;var r=(e,n)=>m(e,"name",{value:n,configurable:!0});import{CloudFormationClient as g,DescribeStackEventsCommand as y}from"@aws-sdk/client-cloudformation";import{success as d,failure as l}from"@fjall/generator";import{getErrorMessage as R,maskSensitiveOutput as f}from"@fjall/util";import{classifyDriftSuspectEvents as E,isOperationOpeningEvent as S}from"@fjall/util/aws";import{logger as v}from"@fjall/util/logger";import{composeSdkAbortSignal as I,isAborted as h}from"../../aws/organisations/types.js";const T="DriftClassify",D=5;function b(e){return e.includes("FAILED")}r(b,"isFailedStatus");function C(e){return e.LogicalResourceId===void 0||e.ResourceType===void 0||e.ResourceStatus===void 0?null:{logicalId:e.LogicalResourceId,resourceType:e.ResourceType,status:e.ResourceStatus,timestamp:e.Timestamp??new Date(0),...e.PhysicalResourceId!==void 0&&e.PhysicalResourceId!==""?{physicalId:e.PhysicalResourceId}:{},...e.ResourceStatusReason!==void 0?{statusReason:e.ResourceStatusReason}:{}}}r(C,"toResourceEvent");async function $(e,n,i){const t=e.getClient(g),o=[];let s,c=0;try{do{if(h(i))return l(new Error(`Drift event scan aborted for ${n}`));const u=await t.send(new y({StackName:n,...s!==void 0?{NextToken:s}:{}}),{abortSignal:I(i)});c+=1;for(const p of u.StackEvents??[]){const a=C(p);if(a!==null&&(o.push(a),S(a,n)))return d(o)}if(s=u.NextToken,c>=D&&s!==void 0)return v.debug(T,"Event scan truncated at page budget",{stackName:n,pages:c,eventsCollected:o.length}),d(o)}while(s!==void 0);return d(o)}catch(u){return l(new Error(`Failed to read stack events for ${n}: ${f(R(u))}`))}}r($,"fetchLastOperationEvents");function G(e,n){const i=n.filter(t=>b(t.status));return E(i).map(t=>({stackName:e,logicalId:t.logicalId,resourceType:t.resourceType,...t.physicalId!==void 0?{physicalId:t.physicalId}:{},failedStatus:t.failedStatus,statusReason:f(t.statusReason)}))}r(G,"classifyDriftFailure");export{G as classifyDriftFailure,$ as fetchLastOperationEvents};

package/dist/src/orchestration/drift/detectStackDrift.js

@@ -1 +1 @@
-import{STACK_NOT_FOUND_PATTERN as b}from"@fjall/util/aws";import{success as g,failure as S}from"@fjall/generator";import{classifyDriftFailure as D,fetchLastOperationEvents as h}from"./classifyDriftFailure.js";import{clearDriftSuspects as j,readDriftSuspects as _,recordDriftSuspects as I}from"./driftSuspectJournal.js";async function E(e,m){const{stackName:t,abortSignal:o}=m,n=e.aws.getAccountId(),a=e.aws.getRegion(),r=await h(e.aws,t,o);let c=[];if(r.success)c=D(t,r.data);else if(!r.error.message.includes(b))return S(r.error);const l=await _(n,a,t,e.journal),v=new Set(c.map(s=>s.logicalId)),f=(l?.suspects??[]).filter(s=>!v.has(s.logicalId)),i=[...c,...f];if(i.length===0)return g({stackName:t,suspects:[],findings:[],suspectSources:{events:0,journal:0}});const u=await e.probe.probeSuspects({stackName:t,suspects:i,...o!==void 0?{abortSignal:o}:{}});if(!u.success)return S(u.error);const d=u.data,p=d.filter(s=>s.verdict==="confirmed-deleted"||s.verdict==="unconfirmed").map(({verdict:s,verdictDetail:R,probeMethod:A,verbs:N,...w})=>w);return p.length>0?await I({accountId:n,region:a,stackName:t,recordedAt:(e.now?.()??new Date).toISOString(),suspects:p},e.journal):l!==null&&await j(n,a,t,e.journal),g({stackName:t,suspects:i,findings:d,suspectSources:{events:c.length,journal:f.length}})}export{E as detectStackDrift};
+var D=Object.defineProperty;var S=(e,o)=>D(e,"name",{value:o,configurable:!0});import{STACK_NOT_FOUND_PATTERN as h}from"@fjall/util/aws";import{success as m,failure as v}from"@fjall/generator";import{classifyDriftFailure as j,fetchLastOperationEvents as _}from"./classifyDriftFailure.js";import{clearDriftSuspects as I,readDriftSuspects as R,recordDriftSuspects as A}from"./driftSuspectJournal.js";async function x(e,o){const{stackName:t,abortSignal:n}=o,a=e.aws.getAccountId(),i=e.aws.getRegion(),r=await _(e.aws,t,n);let c=[];if(r.success)c=j(t,r.data);else if(!r.error.message.includes(h))return v(r.error);const f=await R(a,i,t,e.journal),w=new Set(c.map(s=>s.logicalId)),d=(f?.suspects??[]).filter(s=>!w.has(s.logicalId)),u=[...c,...d];if(u.length===0)return m({stackName:t,suspects:[],findings:[],suspectSources:{events:0,journal:0}});const l=await e.probe.probeSuspects({stackName:t,suspects:u,...n!==void 0?{abortSignal:n}:{}});if(!l.success)return v(l.error);const p=l.data,g=p.filter(s=>s.verdict==="confirmed-deleted"||s.verdict==="unconfirmed").map(({verdict:s,verdictDetail:N,probeMethod:O,verbs:T,...b})=>b);return g.length>0?await A({accountId:a,region:i,stackName:t,recordedAt:(e.now?.()??new Date).toISOString(),suspects:g},e.journal):f!==null&&await I(a,i,t,e.journal),m({stackName:t,suspects:u,findings:p,suspectSources:{events:c.length,journal:d.length}})}S(x,"detectStackDrift");export{x as detectStackDrift};

package/dist/src/orchestration/drift/driftPreFlight.js

@@ -1,7 +1,7 @@
-import{success as g}from"@fjall/generator";import{detectStackDrift as $}from"./detectStackDrift.js";import{readDriftSuspects as v}from"./driftSuspectJournal.js";const y=new Set(["UPDATE_ROLLBACK_COMPLETE","UPDATE_ROLLBACK_FAILED","UPDATE_FAILED"]),b=9e4;async function D(i,l){const n=l.budgetMs??b,c=l.abortSignal!==void 0?AbortSignal.any([l.abortSignal,AbortSignal.timeout(n)]):AbortSignal.any([AbortSignal.timeout(n)]),r={confirmed:[],unconfirmed:[],probedStacks:[]},u=await Promise.all(l.stackNames.map(async o=>{const a=await l.cfnService.getStackStatus(o,void 0,c);return{stackName:o,status:a.success?a.data?.status??null:null}}));for(const{stackName:o,status:a}of u){if(!(a!==null&&y.has(a))){const t=await v(i.aws.getAccountId(),i.aws.getRegion(),o,i.journal);if(t===null||t.suspects.length===0)continue}r.probedStacks.push(o);const d=await $(i,{stackName:o,abortSignal:c});if(d.success)for(const t of d.data.findings)t.verdict==="confirmed-deleted"?r.confirmed.push(t):(t.verdict==="unconfirmed"||t.verdict==="stack-missing")&&r.unconfirmed.push(t)}return g(r)}function I(i,l=[],n={}){const c=i.map(e=>`  ${e.stackName} \u203A ${e.logicalId} (${e.resourceType})${e.physicalId!==void 0?` [${e.physicalId}]`:""} \u2014 ${e.verdictDetail}`),r=l.map(e=>`Remediation ${e} is in progress \u2014 run 'fjall drift resume ${e}' to continue it.`),u=(n.flipNotLive??[]).map(({finding:e,opId:s})=>`Remediation ${s} recorded its Retain flip on ${e.stackName} \u203A ${e.logicalId}, but the flip is no longer live on the stack \u2014 re-run 'fjall drift repair' to re-verify before deploying.`),o=(n.flipUnverified??[]).map(({finding:e,opId:s,message:h})=>`Remediation ${s} should complete with this deploy, but ${e.stackName} \u203A ${e.logicalId} could not be verified: the live template could not be read to confirm the Retain flip is still live \u2014 ${h}. Retry the deploy.`),a=(n.stillDeclared??[]).map(({finding:e,opId:s})=>`Remediation ${s} is ready to converge, but ${e.stackName} \u203A ${e.logicalId} is still declared in your fjall config \u2014 remove the resource from the config, then deploy to complete the forget.`),f=[...r,...u,...o,...a],d=new Set((n.flipUnverified??[]).map(({finding:e})=>`${e.stackName}/${e.logicalId}`)),t=i.length>0&&i.every(e=>d.has(`${e.stackName}/${e.logicalId}`)),m=t?`Deploy blocked: the Retain-flip state of ${i.length} mid-remediation resource(s) could not be verified (the live template could not be read):
-`:`Deploy blocked: CloudFormation still tracks ${i.length} resource(s) deleted outside CloudFormation \u2014 deploying would fail and re-wedge the stack:
-`,p=t?"Retry the deploy \u2014 verification is transient when the live template read fails; if it keeps failing, check CloudFormation access to the stack template.":"Run 'fjall drift detect' for the full report, then 'fjall drift repair --remediate <physicalName>=<verb>' to remediate confirmed deletions.";return m+`${c.join(`
+var $=Object.defineProperty;var m=(t,o)=>$(t,"name",{value:o,configurable:!0});import{success as v}from"@fjall/generator";import{detectStackDrift as y}from"./detectStackDrift.js";import{readDriftSuspects as b}from"./driftSuspectJournal.js";const k=new Set(["UPDATE_ROLLBACK_COMPLETE","UPDATE_ROLLBACK_FAILED","UPDATE_FAILED"]),S=9e4;async function A(t,o){const n=o.budgetMs??S,c=o.abortSignal!==void 0?AbortSignal.any([o.abortSignal,AbortSignal.timeout(n)]):AbortSignal.any([AbortSignal.timeout(n)]),r={confirmed:[],unconfirmed:[],probedStacks:[]},u=await Promise.all(o.stackNames.map(async l=>{const a=await o.cfnService.getStackStatus(l,void 0,c);return{stackName:l,status:a.success?a.data?.status??null:null}}));for(const{stackName:l,status:a}of u){if(!(a!==null&&k.has(a))){const i=await b(t.aws.getAccountId(),t.aws.getRegion(),l,t.journal);if(i===null||i.suspects.length===0)continue}r.probedStacks.push(l);const d=await y(t,{stackName:l,abortSignal:c});if(d.success)for(const i of d.data.findings)i.verdict==="confirmed-deleted"?r.confirmed.push(i):(i.verdict==="unconfirmed"||i.verdict==="stack-missing")&&r.unconfirmed.push(i)}return v(r)}m(A,"runDriftPreFlight");function w(t,o=[],n={}){const c=t.map(e=>`  ${e.stackName} \u203A ${e.logicalId} (${e.resourceType})${e.physicalId!==void 0?` [${e.physicalId}]`:""} \u2014 ${e.verdictDetail}`),r=o.map(e=>`Remediation ${e} is in progress \u2014 run 'fjall drift resume ${e}' to continue it.`),u=(n.flipNotLive??[]).map(({finding:e,opId:s})=>`Remediation ${s} recorded its Retain flip on ${e.stackName} \u203A ${e.logicalId}, but the flip is no longer live on the stack \u2014 re-run 'fjall drift repair' to re-verify before deploying.`),l=(n.flipUnverified??[]).map(({finding:e,opId:s,message:g})=>`Remediation ${s} should complete with this deploy, but ${e.stackName} \u203A ${e.logicalId} could not be verified: the live template could not be read to confirm the Retain flip is still live \u2014 ${g}. Retry the deploy.`),a=(n.stillDeclared??[]).map(({finding:e,opId:s})=>`Remediation ${s} is ready to converge, but ${e.stackName} \u203A ${e.logicalId} is still declared in your fjall config \u2014 remove the resource from the config, then deploy to complete the forget.`),f=[...r,...u,...l,...a],d=new Set((n.flipUnverified??[]).map(({finding:e})=>`${e.stackName}/${e.logicalId}`)),i=t.length>0&&t.every(e=>d.has(`${e.stackName}/${e.logicalId}`)),p=i?`Deploy blocked: the Retain-flip state of ${t.length} mid-remediation resource(s) could not be verified (the live template could not be read):
+`:`Deploy blocked: CloudFormation still tracks ${t.length} resource(s) deleted outside CloudFormation \u2014 deploying would fail and re-wedge the stack:
+`,h=i?"Retry the deploy \u2014 verification is transient when the live template read fails; if it keeps failing, check CloudFormation access to the stack template.":"Run 'fjall drift detect' for the full report, then 'fjall drift repair --remediate <physicalName>=<verb>' to remediate confirmed deletions.";return p+`${c.join(`
 `)}
-${p}${f.length>0?`
+${h}${f.length>0?`
 ${f.join(`
-`)}`:""}`}export{b as DRIFT_PREFLIGHT_BUDGET_MS,y as DRIFT_PREFLIGHT_TRIGGER_STATUSES,I as formatDriftPreFlightBlock,D as runDriftPreFlight};
+`)}`:""}`}m(w,"formatDriftPreFlightBlock");export{S as DRIFT_PREFLIGHT_BUDGET_MS,k as DRIFT_PREFLIGHT_TRIGGER_STATUSES,w as formatDriftPreFlightBlock,A as runDriftPreFlight};