@fjall/deploy-core 2.12.0 → 2.14.0

package/dist/.minified

@@ -1 +1 @@
-121 files minified at 2026-06-09T10:15:43.279Z
+148 files minified at 2026-06-12T01:12:37.959Z

package/dist/src/aws/cloudtrail/orgTrailDelivery.d.ts

@@ -0,0 +1,44 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import { type CloudTrailClient } from "@aws-sdk/client-cloudtrail";
+import { type Result } from "@fjall/generator";
+export interface OrgTrailAccountDelivery {
+    accountId: string;
+    /** At least one log object observed in the recency window's date partitions. */
+    delivered: boolean;
+    /**
+     * An observed object falls inside the recency window. `undefined` when the
+     * facts could not be determined: region discovery was truncated or over the
+     * cap, or a window partition exhausted its page cap before recency was
+     * proven. The reconciler treats `undefined` as "do not advance", never as
+     * verified.
+     */
+    recentDelivery: boolean | undefined;
+    latestObjectAt?: Date;
+}
+export interface OrgTrailDeliveryReport {
+    bucketName: string;
+    perAccount: OrgTrailAccountDelivery[];
+}
+/**
+ * Verify per-member delivery into the organisation trail bucket under the
+ * management account. Region prefixes are discovered with one delimiter
+ * listing of AWSLogs/<orgId>/<accountId>/CloudTrail/, then only the date
+ * partitions covering the recency window are scanned. Read-only; a
+ * NoSuchBucket failure means the org trail has not deployed yet.
+ */
+export declare function verifyOrgTrailDelivery(s3Client: S3Client, options: {
+    bucketName: string;
+    orgId: string;
+    accountIds: string[];
+    recencyWindowMs?: number;
+    abortSignal?: AbortSignal;
+}): Promise<Result<OrgTrailDeliveryReport>>;
+export interface TrailLoggingStatus {
+    isLogging: boolean;
+    latestDeliveryTime?: Date;
+}
+/**
+ * Reverse-path primitive: before leaving the organisation trail (org →
+ * account), the recreated per-account trail must be confirmed logging.
+ */
+export declare function getTrailLoggingStatus(cloudTrailClient: CloudTrailClient, trailName: string, abortSignal?: AbortSignal): Promise<Result<TrailLoggingStatus>>;

package/dist/src/aws/cloudtrail/orgTrailDelivery.js

@@ -0,0 +1 @@
+import{ListObjectsV2Command as M}from"@aws-sdk/client-s3";import{GetTrailStatusCommand as D}from"@aws-sdk/client-cloudtrail";import{success as h,failure as S}from"@fjall/generator";import{getErrorMessage as E,maskSensitiveOutput as P}from"@fjall/util";import{SDK_TIMEOUT_MS as k,extractErrorName as w}from"../organisations/types.js";const f=1440*60*1e3,x=f,v=50,A=2;function b(n){const e=AbortSignal.timeout(k);return n!==void 0?AbortSignal.any([n,e]):e}function N(n,e){const r=[],t=Math.floor((e-n)/f)*f;for(let c=t;c<=e;c+=f){const i=new Date(c),s=String(i.getUTCMonth()+1).padStart(2,"0"),o=String(i.getUTCDate()).padStart(2,"0");r.push(`${i.getUTCFullYear()}/${s}/${o}`)}return r.reverse()}async function I(n,e){let r=!1,t,c=!1,i=!1;const s=a=>{for(const u of a.Contents??[])r=!0,u.LastModified!==void 0&&((t===void 0||u.LastModified>t)&&(t=u.LastModified),u.LastModified.getTime()>=e.recentSinceMs&&(c=!0))},o=a=>({delivered:r,recentDelivery:a,...t!==void 0?{latestObjectAt:t}:{}}),d=await n.send(new M({Bucket:e.bucketName,Prefix:e.accountPrefix,Delimiter:"/"}),{abortSignal:b(e.abortSignal)});s(d);const y=(d.CommonPrefixes??[]).map(a=>a.Prefix).filter(a=>a!==void 0);if(d.IsTruncated===!0||y.length>v)return o(void 0);for(const a of y)for(const u of e.datePaths){let l,g=!1;for(let T=0;T<A&&!g;T++){const m=await n.send(new M({Bucket:e.bucketName,Prefix:`${a}${u}/`,...l!==void 0?{ContinuationToken:l}:{}}),{abortSignal:b(e.abortSignal)});if(s(m),c)return o(!0);m.IsTruncated===!0?l=m.NextContinuationToken:g=!0}g||(i=!0)}return o(i?void 0:!1)}async function O(n,e){const r=e.recencyWindowMs??x,t=Date.now(),c=N(r,t),i=[];for(const s of e.accountIds)try{const o=await I(n,{bucketName:e.bucketName,accountPrefix:`AWSLogs/${e.orgId}/${s}/CloudTrail/`,datePaths:c,recentSinceMs:t-r,...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{}});i.push({accountId:s,...o})}catch(o){return w(o)==="NoSuchBucket"?S(new Error(`Organisation trail bucket ${e.bucketName} does not exist \u2014 the org trail has not been deployed yet.`)):S(new Error(`Failed to verify org-trail delivery for account ${s}: ${P(E(o))}`))}return h({bucketName:e.bucketName,perAccount:i})}async function F(n,e,r){try{const t=await n.send(new D({Name:e}),{abortSignal:b(r)});return h({isLogging:t.IsLogging===!0,...t.LatestDeliveryTime!==void 0?{latestDeliveryTime:t.LatestDeliveryTime}:{}})}catch(t){return S(new Error(`Failed to read trail status for ${e}: ${P(E(t))}`))}}export{F as getTrailLoggingStatus,O as verifyOrgTrailDelivery};

package/dist/src/aws/index.d.ts

@@ -1,6 +1,10 @@
 export type { AwsProvider, AwsProviderCredentials, AwsSdkClientConstructor } from "./AwsProvider.js";
 export { SimpleAwsProvider } from "./SimpleAwsProvider.js";
-export { ensureOrganisationExists, describeOrganisation, enablePolicyTypes, enableServiceAccess, enableRamSharing, activateTrustedAccess, enableIpamDelegatedAdmin, updateBackupGlobalSettings, listAccounts, findAccount, createAccount, ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap, activateCostAllocationTags, checkIdentityCentreStatus, extractErrorName, isOULeaf, registerSecurityDelegates, SECURITY_SERVICE_PRINCIPALS } from "./organisations/index.js";
-export type { OrgDetails, OUMap, OUTree, AccountPlacementResult, AccountInfo, IdentityCentreStatus, BackupGlobalSettings, CostAllocationTag, CreateAccountResult } from "./organisations/index.js";
+export { checkTargetReadiness, describeTargetReadinessReason, buildTargetUnreadyAdvisory } from "./targetReadiness.js";
+export type { TargetReadinessAccount, TargetReadinessClients, TargetReadinessReason, TargetReadinessVerdict } from "./targetReadiness.js";
+export { buildTargetSetUnreadyAdvisory } from "./targetSetAdvisory.js";
+export type { TargetSetUnreadyAdvisoryParams } from "./targetSetAdvisory.js";
+export { ensureOrganisationExists, describeOrganisation, enablePolicyTypes, enableServiceAccess, SERVICE_PRINCIPALS, enableRamSharing, activateTrustedAccess, enableIpamDelegatedAdmin, updateBackupGlobalSettings, listAccounts, findAccount, createAccount, ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap, activateCostAllocationTags, checkIdentityCentreStatus, extractErrorName, isOULeaf, registerSecurityDelegates, SECURITY_SERVICE_PRINCIPALS, enableCentralisedRootAccess, ROOT_ACCESS_FEATURES, RootAccessEnablementError } from "./organisations/index.js";
+export type { OrgDetails, OUMap, OUTree, AccountPlacementResult, AccountInfo, IdentityCentreStatus, BackupGlobalSettings, CostAllocationTag, CreateAccountResult, RootAccessFeature, RootAccessEnablementSummary } from "./organisations/index.js";
 export { CloudFormationEventMonitor } from "./utils/cloudformationEvents.js";
 export type { AwsClientLike, EventLogWriter, EventFailureAnalyser, EventLogWriterFactory, EventMonitorDeps } from "./utils/cloudformationEvents.js";

package/dist/src/aws/index.js

@@ -1 +1 @@
-import{SimpleAwsProvider as a}from"./SimpleAwsProvider.js";import{ensureOrganisationExists as n,describeOrganisation as r,enablePolicyTypes as s,enableServiceAccess as c,enableRamSharing as o,activateTrustedAccess as l,enableIpamDelegatedAdmin as u,updateBackupGlobalSettings as A,listAccounts as d,findAccount as p,createAccount as g,ensureOrganisationalUnitsExist as m,placeAccountsInOUs as S,buildAccountToOUMap as b,activateCostAllocationTags as E,checkIdentityCentreStatus as I,extractErrorName as x,isOULeaf as C,registerSecurityDelegates as O,SECURITY_SERVICE_PRINCIPALS as f}from"./organisations/index.js";import{CloudFormationEventMonitor as T}from"./utils/cloudformationEvents.js";export{T as CloudFormationEventMonitor,f as SECURITY_SERVICE_PRINCIPALS,a as SimpleAwsProvider,E as activateCostAllocationTags,l as activateTrustedAccess,b as buildAccountToOUMap,I as checkIdentityCentreStatus,g as createAccount,r as describeOrganisation,u as enableIpamDelegatedAdmin,s as enablePolicyTypes,o as enableRamSharing,c as enableServiceAccess,n as ensureOrganisationExists,m as ensureOrganisationalUnitsExist,x as extractErrorName,p as findAccount,C as isOULeaf,d as listAccounts,S as placeAccountsInOUs,O as registerSecurityDelegates,A as updateBackupGlobalSettings};
+import{SimpleAwsProvider as a}from"./SimpleAwsProvider.js";import{checkTargetReadiness as s,describeTargetReadinessReason as o,buildTargetUnreadyAdvisory as n}from"./targetReadiness.js";import{buildTargetSetUnreadyAdvisory as c}from"./targetSetAdvisory.js";import{ensureOrganisationExists as d,describeOrganisation as A,enablePolicyTypes as u,enableServiceAccess as S,SERVICE_PRINCIPALS as E,enableRamSharing as g,activateTrustedAccess as R,enableIpamDelegatedAdmin as b,updateBackupGlobalSettings as m,listAccounts as p,findAccount as C,createAccount as T,ensureOrganisationalUnitsExist as I,placeAccountsInOUs as x,buildAccountToOUMap as y,activateCostAllocationTags as O,checkIdentityCentreStatus as U,extractErrorName as f,isOULeaf as v,registerSecurityDelegates as P,SECURITY_SERVICE_PRINCIPALS as _,enableCentralisedRootAccess as h,ROOT_ACCESS_FEATURES as k,RootAccessEnablementError as L}from"./organisations/index.js";import{CloudFormationEventMonitor as D}from"./utils/cloudformationEvents.js";export{D as CloudFormationEventMonitor,k as ROOT_ACCESS_FEATURES,L as RootAccessEnablementError,_ as SECURITY_SERVICE_PRINCIPALS,E as SERVICE_PRINCIPALS,a as SimpleAwsProvider,O as activateCostAllocationTags,R as activateTrustedAccess,y as buildAccountToOUMap,c as buildTargetSetUnreadyAdvisory,n as buildTargetUnreadyAdvisory,U as checkIdentityCentreStatus,s as checkTargetReadiness,T as createAccount,A as describeOrganisation,o as describeTargetReadinessReason,h as enableCentralisedRootAccess,b as enableIpamDelegatedAdmin,u as enablePolicyTypes,g as enableRamSharing,S as enableServiceAccess,d as ensureOrganisationExists,I as ensureOrganisationalUnitsExist,f as extractErrorName,C as findAccount,v as isOULeaf,p as listAccounts,x as placeAccountsInOUs,P as registerSecurityDelegates,m as updateBackupGlobalSettings};

package/dist/src/aws/organisations/accountGlobals.d.ts

@@ -0,0 +1,40 @@
+import { type IAMClient } from "@aws-sdk/client-iam";
+import { type Result } from "@fjall/generator";
+import type { OrgConfig } from "../../types/orgConfig.js";
+export declare const ACCOUNT_GLOBALS_ROLE_NAME = "FjallMonitoring";
+/**
+ * Probe whether the fixed-name account globals exist in this account — the
+ * prerequisite for a non-primary-region deploy, which skips creating them.
+ * IAM is a global service, so a GetRole from any region answers it.
+ *
+ * The design-suggested OIDC provider is a confounded discriminator: the
+ * connect-time quick-create stack creates it before any deploy (false
+ * "exists"), and the account stack skips it under the fjallOidcConfigured /
+ * receivesDeployRole() gates even when the globals branch runs.
+ *
+ * Returns success(false) ONLY on NoSuchEntityException. Every other error
+ * (AccessDenied, throttling) propagates as failure — a mis-read "missing"
+ * refuses a legitimate deploy, a mis-read "exists" silently deploys an
+ * account that cannot work; neither may be guessed.
+ *
+ * Failure messages stay raw — callers mask at their output boundary.
+ */
+export declare function describeAccountGlobalsExist(client: IAMClient, abortSignal?: AbortSignal): Promise<Result<boolean>>;
+/**
+ * Org-vs-solo shape discriminator shared by every guard-step advisory in the
+ * deploy flow (account globals, target readiness) — one drift here would
+ * render contradictory remediation for the same estate.
+ */
+export declare function hasOrganisationTierAccount(providerAccounts: OrgConfig["providerAccounts"] | undefined): boolean;
+/**
+ * Deploy-primary-first advisory for a non-primary deploy whose primary-region
+ * globals are missing (AC2a.2). Shape-branched on whether the provider
+ * accounts carry a tier-organisation account: org estates remediate via the
+ * cascade, solo accounts by deploying the primary region directly.
+ */
+export declare function buildMissingAccountGlobalsAdvisory(params: {
+    target: string;
+    deployRegion: string;
+    primaryRegion: string;
+    providerAccounts?: OrgConfig["providerAccounts"];
+}): string;

package/dist/src/aws/organisations/accountGlobals.js

@@ -0,0 +1 @@
+import{GetRoleCommand as i}from"@aws-sdk/client-iam";import{success as n,failure as a}from"@fjall/generator";import{accountTier as c,getErrorMessage as s}from"@fjall/util";import{ACCOUNT_MONITORING_ROLE_NAME as l}from"@fjall/util/aws";import{composeSdkAbortSignal as u}from"./types.js";const t=l;async function f(o,e){try{return await o.send(new i({RoleName:t}),{abortSignal:u(e)}),n(!0)}catch(r){return r instanceof Error&&r.name==="NoSuchEntityException"?n(!1):a(new Error(`Failed to probe account globals (role "${t}"): ${s(r)}`))}}function p(o){return(o??[]).some(e=>c(e)==="organisation")}function A(o){const r=p(o.providerAccounts)?`run \`fjall deploy organisation\` to provision the primary region (${o.primaryRegion}), then retry this deploy`:`target the primary region (${o.primaryRegion}) and run \`fjall deploy account\`, then retry this deploy`;return`Cannot deploy "${o.target}" into ${o.deployRegion}: the account globals (fixed-name IAM resources such as the ${t} role) are created only in the primary region (${o.primaryRegion}) and were not found in this account. Nothing has been deployed. Deploy the primary region first: ${r}.`}export{t as ACCOUNT_GLOBALS_ROLE_NAME,A as buildMissingAccountGlobalsAdvisory,f as describeAccountGlobalsExist,p as hasOrganisationTierAccount};

package/dist/src/aws/organisations/accounts.d.ts

@@ -17,5 +17,7 @@ export declare function findAccount(client: OrganizationsClient, accountId: stri
  *
  * @param maxAttempts Maximum polling attempts (default: 180 = ~15 minutes at 5s intervals)
  * @param delayMs Delay between polling attempts in milliseconds (default: 5000)
+ * @param abortSignal Optional shutdown signal — short-circuits the poll loop
+ *   and inter-poll sleeps so SIGTERM does not stall for up to ~15 minutes
  */
-export declare function createAccount(client: OrganizationsClient, accountName: string, email: string, maxAttempts?: number, delayMs?: number): Promise<Result<CreateAccountResult>>;
+export declare function createAccount(client: OrganizationsClient, accountName: string, email: string, maxAttempts?: number, delayMs?: number, abortSignal?: AbortSignal): Promise<Result<CreateAccountResult>>;

package/dist/src/aws/organisations/accounts.js

@@ -1 +1 @@
-import{ListAccountsCommand as f,CreateAccountCommand as m,CreateAccountState as E,DescribeCreateAccountStatusCommand as p}from"@aws-sdk/client-organizations";import{success as A,failure as e}from"@fjall/generator";import{sleep as C,getErrorMessage as w}from"@fjall/util";import{extractErrorName as S,SDK_TIMEOUT_MS as d,AWS_ERROR_NAMES as g}from"./types.js";async function x(o){try{const t=await o.send(new f({MaxResults:20}),{abortSignal:AbortSignal.timeout(d)});let r=t.Accounts??[],n=t.NextToken;for(;n;){const s=await o.send(new f({MaxResults:20,NextToken:n}),{abortSignal:AbortSignal.timeout(d)});r=r.concat(s.Accounts??[]),n=s.NextToken}return A(r)}catch(t){return S(t)===g.ORGS_NOT_IN_USE?e(new Error("AWS Organisations is not enabled for this account")):e(new Error(`Failed to list accounts: ${w(t)}`))}}async function $(o,t){const r=await x(o);return r.success?A(r.data.find(n=>n.Id===t)):r}async function D(o,t,r,n=180,s=5e3){try{let i;try{i=await o.send(new m({AccountName:t,Email:r}),{abortSignal:AbortSignal.timeout(d)})}catch(c){const u=S(c);if(u===g.ACCESS_DENIED)return e(new Error(`Access denied when creating account "${t}". Ensure your credentials have organizations:CreateAccount permission.`));if(u==="DuplicateAccountException")return e(new Error(`An account with the email "${r}" already exists in the organisation.`));if(u==="FinalizingOrganizationException")return e(new Error("The organisation is still being initialised. Please wait and try again."));throw c}const l=i.CreateAccountStatus?.Id;if(!l)return e(new Error(`CreateAccount request for "${t}" did not return a status ID`));for(let c=0;c<n;c++){const a=(await o.send(new p({CreateAccountRequestId:l}),{abortSignal:AbortSignal.timeout(d)})).CreateAccountStatus;if(!a)return e(new Error(`No status returned for CreateAccount request ${l}`));if(a.State===E.SUCCEEDED)return a.AccountId?A({accountId:a.AccountId,accountName:t}):e(new Error(`Account creation succeeded but no account ID returned for "${t}"`));if(a.State===E.FAILED)return e(new Error(`Account creation failed for "${t}": ${a.FailureReason}`));await C(s)}return e(new Error(`Account creation for "${t}" timed out after ${n*s/1e3} seconds`))}catch(i){return e(new Error(`Failed to create account "${t}": ${w(i)}`))}}export{D as createAccount,$ as findAccount,x as listAccounts};
+import{ListAccountsCommand as f,CreateAccountCommand as b,CreateAccountState as w,DescribeCreateAccountStatusCommand as $}from"@aws-sdk/client-organizations";import{success as A,failure as r}from"@fjall/generator";import{getErrorMessage as E}from"@fjall/util";import{extractErrorName as p,composeSdkAbortSignal as S,isAborted as m,SDK_TIMEOUT_MS as g,AWS_ERROR_NAMES as C}from"./types.js";import{sleepAbortable as h}from"../../util/sleepAbortable.js";async function x(o){try{const t=await o.send(new f({MaxResults:20}),{abortSignal:AbortSignal.timeout(g)});let e=t.Accounts??[],n=t.NextToken;for(;n;){const c=await o.send(new f({MaxResults:20,NextToken:n}),{abortSignal:AbortSignal.timeout(g)});e=e.concat(c.Accounts??[]),n=c.NextToken}return A(e)}catch(t){return p(t)===C.ORGS_NOT_IN_USE?r(new Error("AWS Organisations is not enabled for this account")):r(new Error(`Failed to list accounts: ${E(t)}`))}}async function _(o,t){const e=await x(o);return e.success?A(e.data.find(n=>n.Id===t)):e}async function O(o,t,e,n=180,c=5e3,a){if(m(a))return r(new Error(`Aborted: account creation for "${t}" cancelled by shutdown signal before starting`));try{let u;try{u=await o.send(new b({AccountName:t,Email:e}),{abortSignal:S(a)})}catch(i){const l=p(i);if(l===C.ACCESS_DENIED)return r(new Error(`Access denied when creating account "${t}". Ensure your credentials have organizations:CreateAccount permission.`));if(l==="DuplicateAccountException")return r(new Error(`An account with the email "${e}" already exists in the organisation.`));if(l==="FinalizingOrganizationException")return r(new Error("The organisation is still being initialised. Please wait and try again."));throw i}const d=u.CreateAccountStatus?.Id;if(!d)return r(new Error(`CreateAccount request for "${t}" did not return a status ID`));for(let i=0;i<n;i++){if(m(a))return r(new Error(`Aborted: account creation polling for "${t}" cancelled by shutdown signal \u2014 AWS request ${d} may still complete server-side`));const s=(await o.send(new $({CreateAccountRequestId:d}),{abortSignal:S(a)})).CreateAccountStatus;if(!s)return r(new Error(`No status returned for CreateAccount request ${d}`));if(s.State===w.SUCCEEDED)return s.AccountId?A({accountId:s.AccountId,accountName:t}):r(new Error(`Account creation succeeded but no account ID returned for "${t}"`));if(s.State===w.FAILED)return r(new Error(`Account creation failed for "${t}": ${s.FailureReason}`));await h(c,a)}return r(new Error(`Account creation for "${t}" timed out after ${n*c/1e3} seconds`))}catch(u){return r(new Error(`Failed to create account "${t}": ${E(u)}`))}}export{O as createAccount,_ as findAccount,x as listAccounts};

package/dist/src/aws/organisations/backup.d.ts

@@ -1,6 +1,7 @@
 import { type BackupClient } from "@aws-sdk/client-backup";
 import { type Result } from "@fjall/generator";
-export declare const BACKUP_VAULT_NAME = "backupVault";
+import { BACKUP_VAULT_NAME } from "@fjall/util";
+export { BACKUP_VAULT_NAME };
 export interface BackupGlobalSettings {
     enableCrossAccountBackup?: boolean;
     enableDelegatedAdministrator?: boolean;

package/dist/src/aws/organisations/backup.js

@@ -1,2 +1,2 @@
-import{DescribeBackupVaultCommand as s,UpdateGlobalSettingsCommand as p}from"@aws-sdk/client-backup";import{success as o,failure as i}from"@fjall/generator";import{getErrorMessage as c,maskSensitiveOutput as l}from"@fjall/util";import{SDK_TIMEOUT_MS as u}from"./types.js";const a="backupVault",m={enableCrossAccountBackup:!0,enableDelegatedAdministrator:!0,enableMpa:!1};async function y(e,t){try{const n={...m,...t},r={isCrossAccountBackupEnabled:n.enableCrossAccountBackup.toString(),isDelegatedAdministratorEnabled:n.enableDelegatedAdministrator.toString(),isMpaEnabled:n.enableMpa.toString()};return await e.send(new p({GlobalSettings:r}),{abortSignal:AbortSignal.timeout(u)}),o(void 0)}catch(n){return i(new Error(`Failed to update backup global settings: ${c(n)}`))}}function S(e,t){return t===void 0||t===""?!1:e==="production"||e==="compliance"}async function A(e){try{return await e.send(new s({BackupVaultName:a}),{abortSignal:AbortSignal.timeout(u)}),o(!0)}catch(t){return t instanceof Error&&t.name==="ResourceNotFoundException"?o(!1):i(new Error(`Failed to describe backup vault "${a}": ${l(c(t))}`))}}async function E(e,t){try{const n=await e.send(new s({BackupVaultName:a}),{abortSignal:AbortSignal.timeout(u)}),r=n.LockDate,d=r!==void 0&&r.getTime()<=Date.now();return o({vaultName:n.BackupVaultName??a,region:t,locked:n.Locked??!1,...r!==void 0&&{lockDate:r},lockPermanent:d,recoveryPointCount:n.NumberOfRecoveryPoints??0,...n.EncryptionKeyArn!==void 0&&{encryptionKeyArn:n.EncryptionKeyArn}})}catch(n){return n instanceof Error&&n.name==="ResourceNotFoundException"?o(null):i(new Error(`Failed to describe surviving backup vault "${a}": ${l(c(n))}`))}}function v(e){const t=e.locked?e.lockPermanent?"compliance-locked, PERMANENT \u2014 cannot be removed by anyone, including AWS or the root user":e.lockDate!==void 0?`compliance-locked, immutable from ${e.lockDate.toISOString().slice(0,10)}`:"governance-locked \u2014 removable by privileged IAM":"unlocked";return[`Backup vault "${e.vaultName}" in ${e.region} SURVIVES this destroy.`,`  \u2022 Lock: ${t}`,`  \u2022 Recovery points retained: ${e.recoveryPointCount}`,...e.encryptionKeyArn!==void 0?[`  \u2022 Retained KMS key (also orphaned): ${e.encryptionKeyArn}`]:[],"  The vault and its KMS key are RemovalPolicy.RETAIN \u2014 destroy cannot delete them."].join(`
-`)}export{a as BACKUP_VAULT_NAME,S as accountHasDisasterRecovery,A as describeBackupVaultExists,E as describeSurvivingBackupVault,v as formatSurvivingVaultWarning,y as updateBackupGlobalSettings};
+import{DescribeBackupVaultCommand as s,UpdateGlobalSettingsCommand as p}from"@aws-sdk/client-backup";import{success as a,failure as i}from"@fjall/generator";import{BACKUP_VAULT_NAME as o,getErrorMessage as c,maskSensitiveOutput as l}from"@fjall/util";import{SDK_TIMEOUT_MS as u}from"./types.js";const m={enableCrossAccountBackup:!0,enableDelegatedAdministrator:!0,enableMpa:!1};async function y(e,t){try{const n={...m,...t},r={isCrossAccountBackupEnabled:n.enableCrossAccountBackup.toString(),isDelegatedAdministratorEnabled:n.enableDelegatedAdministrator.toString(),isMpaEnabled:n.enableMpa.toString()};return await e.send(new p({GlobalSettings:r}),{abortSignal:AbortSignal.timeout(u)}),a(void 0)}catch(n){return i(new Error(`Failed to update backup global settings: ${c(n)}`))}}function S(e,t){return t===void 0||t===""?!1:e==="production"||e==="compliance"}async function A(e){try{return await e.send(new s({BackupVaultName:o}),{abortSignal:AbortSignal.timeout(u)}),a(!0)}catch(t){return t instanceof Error&&t.name==="ResourceNotFoundException"?a(!1):i(new Error(`Failed to describe backup vault "${o}": ${l(c(t))}`))}}async function E(e,t){try{const n=await e.send(new s({BackupVaultName:o}),{abortSignal:AbortSignal.timeout(u)}),r=n.LockDate,d=r!==void 0&&r.getTime()<=Date.now();return a({vaultName:n.BackupVaultName??o,region:t,locked:n.Locked??!1,...r!==void 0&&{lockDate:r},lockPermanent:d,recoveryPointCount:n.NumberOfRecoveryPoints??0,...n.EncryptionKeyArn!==void 0&&{encryptionKeyArn:n.EncryptionKeyArn}})}catch(n){return n instanceof Error&&n.name==="ResourceNotFoundException"?a(null):i(new Error(`Failed to describe surviving backup vault "${o}": ${l(c(n))}`))}}function v(e){const t=e.locked?e.lockPermanent?"compliance-locked, PERMANENT \u2014 cannot be removed by anyone, including AWS or the root user":e.lockDate!==void 0?`compliance-locked, immutable from ${e.lockDate.toISOString().slice(0,10)}`:"governance-locked \u2014 removable by privileged IAM":"unlocked";return[`Backup vault "${e.vaultName}" in ${e.region} SURVIVES this destroy.`,`  \u2022 Lock: ${t}`,`  \u2022 Recovery points retained: ${e.recoveryPointCount}`,...e.encryptionKeyArn!==void 0?[`  \u2022 Retained KMS key (also orphaned): ${e.encryptionKeyArn}`]:[],"  The vault and its KMS key are RemovalPolicy.RETAIN \u2014 destroy cannot delete them."].join(`
+`)}export{o as BACKUP_VAULT_NAME,S as accountHasDisasterRecovery,A as describeBackupVaultExists,E as describeSurvivingBackupVault,v as formatSurvivingVaultWarning,y as updateBackupGlobalSettings};

package/dist/src/aws/organisations/importedAccounts.d.ts

@@ -0,0 +1,16 @@
+import type { Account } from "@aws-sdk/client-organizations";
+/**
+ * Member accounts that joined the organisation by invitation rather than
+ * being created inside it. AWS reports provenance as Account.JoinedMethod
+ * ("CREATED" | "INVITED"): an invited account existed standalone first, so
+ * it holds self-managed root credentials that centralised root access
+ * management takes over — the posture change AC2.8 warns about. The
+ * management account is excluded (central management never applies to it),
+ * as are non-ACTIVE accounts.
+ */
+export declare function selectImportedMemberAccounts(accounts: Account[], managementAccountId: string): Account[];
+/**
+ * Warn-once copy for the enable-root-access phase (AC2.8). Shared so every
+ * adapter surfaces identical wording.
+ */
+export declare function formatImportedAccountsWarning(imported: Account[]): string;

package/dist/src/aws/organisations/importedAccounts.js

@@ -0,0 +1 @@
+function i(n,t){return n.filter(e=>e.JoinedMethod==="INVITED"&&e.Id!==t&&(e.State??e.Status)==="ACTIVE")}const a=5;function l(n){const t=n.slice(0,a).map(o=>`${o.Name??"unnamed"} (${o.Id??"unknown id"})`).join(", "),e=n.length-a,r=e>0?`${t} and ${e} more`:t,s=n.length===1?"account":"accounts";return`Centralised root access now applies to ${n.length} imported member ${s} that joined this organisation by invitation and previously held self-managed root credentials: ${r}. Root credentials for these accounts are now centrally managed.`}export{l as formatImportedAccountsWarning,i as selectImportedMemberAccounts};

package/dist/src/aws/organisations/index.d.ts

@@ -3,9 +3,10 @@ export { extractErrorName, isOULeaf } from "./types.js";
 export type { BackupGlobalSettings } from "./backup.js";
 export type { CostAllocationTag } from "./costAllocation.js";
 export type { CreateAccountResult } from "./accounts.js";
+export type { RootAccessFeature, RootAccessEnablementSummary } from "./rootAccess.js";
 export { ensureOrganisationExists, describeOrganisation } from "./organisation.js";
 export { enablePolicyTypes } from "./policies.js";
-export { enableServiceAccess } from "./serviceAccess.js";
+export { enableServiceAccess, SERVICE_PRINCIPALS } from "./serviceAccess.js";
 export { enableRamSharing } from "./ram.js";
 export { activateTrustedAccess } from "./trustedAccess.js";
 export { enableIpamDelegatedAdmin } from "./ipam.js";
@@ -15,3 +16,4 @@ export { ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap
 export { activateCostAllocationTags } from "./costAllocation.js";
 export { checkIdentityCentreStatus } from "./identityCentre.js";
 export { registerSecurityDelegates, SECURITY_SERVICE_PRINCIPALS } from "./delegatedAdmin.js";
+export { enableCentralisedRootAccess, ROOT_ACCESS_FEATURES, RootAccessEnablementError } from "./rootAccess.js";

package/dist/src/aws/organisations/index.js

@@ -1 +1 @@
-import{extractErrorName as r,isOULeaf as o}from"./types.js";import{ensureOrganisationExists as c,describeOrganisation as s}from"./organisation.js";import{enablePolicyTypes as i}from"./policies.js";import{enableServiceAccess as m}from"./serviceAccess.js";import{enableRamSharing as f}from"./ram.js";import{activateTrustedAccess as u}from"./trustedAccess.js";import{enableIpamDelegatedAdmin as g}from"./ipam.js";import{updateBackupGlobalSettings as S}from"./backup.js";import{listAccounts as I,findAccount as E,createAccount as O}from"./accounts.js";import{ensureOrganisationalUnitsExist as T,placeAccountsInOUs as U,buildAccountToOUMap as y}from"./organisationalUnits.js";import{activateCostAllocationTags as v}from"./costAllocation.js";import{checkIdentityCentreStatus as h}from"./identityCentre.js";import{registerSecurityDelegates as D,SECURITY_SERVICE_PRINCIPALS as L}from"./delegatedAdmin.js";export{L as SECURITY_SERVICE_PRINCIPALS,v as activateCostAllocationTags,u as activateTrustedAccess,y as buildAccountToOUMap,h as checkIdentityCentreStatus,O as createAccount,s as describeOrganisation,g as enableIpamDelegatedAdmin,i as enablePolicyTypes,f as enableRamSharing,m as enableServiceAccess,c as ensureOrganisationExists,T as ensureOrganisationalUnitsExist,r as extractErrorName,E as findAccount,o as isOULeaf,I as listAccounts,U as placeAccountsInOUs,D as registerSecurityDelegates,S as updateBackupGlobalSettings};
+import{extractErrorName as r,isOULeaf as o}from"./types.js";import{ensureOrganisationExists as s,describeOrganisation as c}from"./organisation.js";import{enablePolicyTypes as i}from"./policies.js";import{enableServiceAccess as m,SERVICE_PRINCIPALS as l}from"./serviceAccess.js";import{enableRamSharing as f}from"./ram.js";import{activateTrustedAccess as u}from"./trustedAccess.js";import{enableIpamDelegatedAdmin as S}from"./ipam.js";import{updateBackupGlobalSettings as I}from"./backup.js";import{listAccounts as b,findAccount as d,createAccount as g}from"./accounts.js";import{ensureOrganisationalUnitsExist as T,placeAccountsInOUs as U,buildAccountToOUMap as P}from"./organisationalUnits.js";import{activateCostAllocationTags as y}from"./costAllocation.js";import{checkIdentityCentreStatus as L}from"./identityCentre.js";import{registerSecurityDelegates as h,SECURITY_SERVICE_PRINCIPALS as k}from"./delegatedAdmin.js";import{enableCentralisedRootAccess as V,ROOT_ACCESS_FEATURES as B,RootAccessEnablementError as F}from"./rootAccess.js";export{B as ROOT_ACCESS_FEATURES,F as RootAccessEnablementError,k as SECURITY_SERVICE_PRINCIPALS,l as SERVICE_PRINCIPALS,y as activateCostAllocationTags,u as activateTrustedAccess,P as buildAccountToOUMap,L as checkIdentityCentreStatus,g as createAccount,c as describeOrganisation,V as enableCentralisedRootAccess,S as enableIpamDelegatedAdmin,i as enablePolicyTypes,f as enableRamSharing,m as enableServiceAccess,s as ensureOrganisationExists,T as ensureOrganisationalUnitsExist,r as extractErrorName,d as findAccount,o as isOULeaf,b as listAccounts,U as placeAccountsInOUs,h as registerSecurityDelegates,I as updateBackupGlobalSettings};

package/dist/src/aws/organisations/organisationalUnits.d.ts

@@ -28,7 +28,7 @@ export declare function ensureOrganisationalUnitsExist(client: OrganizationsClie
 export declare function buildAccountToOUMap(tree: OUTree, ouMap: OUMap, prefix?: string): Record<string, string>;
 /**
  * Place accounts into the correct organisational units.
- * Skips accounts with environment "root" and accounts already in the target OU.
+ * Skips organisation-tier accounts (via accountTier) and accounts already in the target OU.
  *
  * When `accountToOU` is provided, looks up the target OU by account name
  * (lowercase) instead of by environment. This supports tree-based placement

package/dist/src/aws/organisations/policies.js

@@ -1 +1 @@
-import{EnablePolicyTypeCommand as f,ListRootsCommand as u,PolicyType as a}from"@aws-sdk/client-organizations";import{success as d,failure as P}from"@fjall/generator";import{getErrorMessage as b}from"@fjall/util";import{extractErrorName as w,SDK_TIMEOUT_MS as y}from"./types.js";const E=[a.SERVICE_CONTROL_POLICY,a.TAG_POLICY,a.BACKUP_POLICY,a.AISERVICES_OPT_OUT_POLICY],_=2e3,L=6e4;async function g(i,t,e={}){try{for(const o of E)try{await i.send(new f({RootId:t,PolicyType:o}),{abortSignal:AbortSignal.timeout(y)})}catch(r){if(w(r)==="PolicyTypeAlreadyEnabledException")continue;throw r}return await I(i,t,e),d(void 0)}catch(o){return P(new Error(`Failed to enable policy types: ${b(o)}`))}}async function I(i,t,e){const o=e.pollIntervalMs??_,r=e.pollTimeoutMs??L,s=new Set(E),m=Date.now();for(;;){const T=(await i.send(new u({}),{abortSignal:AbortSignal.timeout(y)})).Roots?.find(n=>n.Id===t),l=new Set;for(const n of T?.PolicyTypes??[])n.Status==="ENABLED"&&n.Type&&l.add(n.Type);const c=[...s].filter(n=>!l.has(n));if(c.length===0)return;const p=Date.now()-m;if(p>=r)throw new Error(`Policy types still PENDING_ENABLE after ${p}ms: ${c.join(", ")}`);if(o>0&&(await S(o,e.abortSignal),e.abortSignal?.aborted===!0))throw new Error("Aborted while waiting for policy types to enable")}}function S(i,t){return t?.aborted===!0?Promise.resolve():new Promise(e=>{const o=setTimeout(()=>{t?.removeEventListener("abort",r),e()},i),r=()=>{clearTimeout(o),e()};t?.addEventListener("abort",r,{once:!0})})}export{g as enablePolicyTypes};
+import{EnablePolicyTypeCommand as m,ListRootsCommand as P,PolicyType as i}from"@aws-sdk/client-organizations";import{success as _,failure as d}from"@fjall/generator";import{getErrorMessage as w}from"@fjall/util";import{extractErrorName as L,SDK_TIMEOUT_MS as y}from"./types.js";import{sleepAbortable as b}from"../../util/sleepAbortable.js";const E=[i.SERVICE_CONTROL_POLICY,i.TAG_POLICY,i.BACKUP_POLICY,i.AISERVICES_OPT_OUT_POLICY],u=2e3,I=6e4;async function h(r,n,o={}){try{for(const t of E)try{await r.send(new m({RootId:n,PolicyType:t}),{abortSignal:AbortSignal.timeout(y)})}catch(a){if(L(a)==="PolicyTypeAlreadyEnabledException")continue;throw a}return await S(r,n,o),_(void 0)}catch(t){return d(new Error(`Failed to enable policy types: ${w(t)}`))}}async function S(r,n,o){const t=o.pollIntervalMs??u,a=o.pollTimeoutMs??I,s=new Set(E),T=Date.now();for(;;){const f=(await r.send(new P({}),{abortSignal:AbortSignal.timeout(y)})).Roots?.find(e=>e.Id===n),l=new Set;for(const e of f?.PolicyTypes??[])e.Status==="ENABLED"&&e.Type&&l.add(e.Type);const c=[...s].filter(e=>!l.has(e));if(c.length===0)return;const p=Date.now()-T;if(p>=a)throw new Error(`Policy types still PENDING_ENABLE after ${p}ms: ${c.join(", ")}`);if(t>0&&(await b(t,o.abortSignal),o.abortSignal?.aborted===!0))throw new Error("Aborted while waiting for policy types to enable")}}export{h as enablePolicyTypes};

package/dist/src/aws/organisations/rootAccess.d.ts

@@ -0,0 +1,27 @@
+import { type IAMClient } from "@aws-sdk/client-iam";
+import { type Result } from "@fjall/generator";
+export declare const ROOT_ACCESS_FEATURES: readonly ["RootCredentialsManagement", "RootSessions"];
+export type RootAccessFeature = (typeof ROOT_ACCESS_FEATURES)[number];
+export interface RootAccessEnablementSummary {
+    /** Features newly enabled by this call. */
+    enabled: RootAccessFeature[];
+    /** Features that were already enabled before this call. */
+    alreadyEnabled: RootAccessFeature[];
+}
+/**
+ * Failure carrying the features that DID transition before the error, so the
+ * orchestrator's warn gate (AC2.8) fires on partial enablement too. On
+ * pre-flight (list) failures both arrays are empty — `alreadyEnabled` is
+ * unknown, and only `enabled` is load-bearing for the warn gate.
+ */
+export declare class RootAccessEnablementError extends Error {
+    readonly partialSummary: RootAccessEnablementSummary;
+    constructor(message: string, partialSummary: RootAccessEnablementSummary);
+}
+/**
+ * Enable centralised root access management for the organisation: root
+ * credentials management plus root sessions, via the management account's
+ * IAM client. Idempotent — features already enabled are skipped via the
+ * ListOrganizationsFeatures pre-flight, so a re-run is a converging no-op.
+ */
+export declare function enableCentralisedRootAccess(client: IAMClient, abortSignal?: AbortSignal): Promise<Result<RootAccessEnablementSummary, RootAccessEnablementError>>;

package/dist/src/aws/organisations/rootAccess.js

@@ -0,0 +1,3 @@
+import{ListOrganizationsFeaturesCommand as A,EnableOrganizationsRootCredentialsManagementCommand as C,EnableOrganizationsRootSessionsCommand as h}from"@aws-sdk/client-iam";import{success as R,failure as s}from"@fjall/generator";import{composeSdkAbortSignal as d,extractErrorName as u,isAccessDenied as E}from"./types.js";import{getErrorMessage as b,maskSensitiveOutput as p}from"@fjall/util";const w=["RootCredentialsManagement","RootSessions"],y={RootCredentialsManagement:{CommandClass:C,permission:"iam:EnableOrganizationsRootCredentialsManagement"},RootSessions:{CommandClass:h,permission:"iam:EnableOrganizationsRootSessions"}};class o extends Error{partialSummary;constructor(t,e){super(t),this.name="RootAccessEnablementError",this.partialSummary=e}}function g(a){return new o("Trusted access for iam.amazonaws.com is not enabled in Organizations. Re-run organisation setup \u2014 its enable-service-access phase enables it \u2014 or enable it manually (organizations:EnableAWSServiceAccess for iam.amazonaws.com) and retry enabling centralised root access.",a)}async function F(a,t){const e={enabled:[],alreadyEnabled:[]};let c;try{const n=await a.send(new A({}),{abortSignal:d(t)});c=new Set(n.EnabledFeatures??[])}catch(n){const i=u(n);return E(i)?s(new o("Access denied when listing organisation root-access features. Ensure your credentials have iam:ListOrganizationsFeatures permission.",e)):i==="ServiceAccessNotEnabledException"?s(g(e)):s(new o(`Failed to list organisation root-access features: ${p(b(n))}`,e))}const r=[];for(const n of w){if(c.has(n)){e.alreadyEnabled.push(n);continue}const{CommandClass:i,permission:f}=y[n];try{await a.send(new i({}),{abortSignal:d(t)}),e.enabled.push(n)}catch(l){const m=u(l);if(E(m)){const S=r.length>0?`${r.join("; ")}; `:"";return s(new o(`${S}Access denied when enabling ${n}. Ensure your credentials have ${f} permission.`,e))}if(m==="ServiceAccessNotEnabledException")return s(g(e));r.push(`${n}: ${p(b(l))}`)}}return r.length>0?s(new o(`Failed to enable centralised root access:
+  ${r.join(`
+  `)}`,e)):R(e)}export{w as ROOT_ACCESS_FEATURES,o as RootAccessEnablementError,F as enableCentralisedRootAccess};

package/dist/src/aws/organisations/serviceAccess.d.ts

@@ -1,5 +1,11 @@
 import { type OrganizationsClient } from "@aws-sdk/client-organizations";
 import { type Result } from "@fjall/generator";
+/**
+ * Canonical list of Organizations trusted-access service principals fjall
+ * enables. Consumers MUST import this rather than redeclaring it — a mirror
+ * list drifts silently when a principal is added here.
+ */
+export declare const SERVICE_PRINCIPALS: readonly ["account.amazonaws.com", "sso.amazonaws.com", "ipam.amazonaws.com", "ram.amazonaws.com", "backup.amazonaws.com", "member.org.stacksets.cloudformation.amazonaws.com", "guardduty.amazonaws.com", "securityhub.amazonaws.com", "config.amazonaws.com", "inspector2.amazonaws.com", "access-analyzer.amazonaws.com", "cloudtrail.amazonaws.com", "iam.amazonaws.com"];
 /**
  * Enable AWS service access for all required service principals.
  * Idempotent — enabling an already-enabled principal is a no-op.

package/dist/src/aws/organisations/serviceAccess.js

@@ -1 +1 @@
-import{EnableAWSServiceAccessCommand as n}from"@aws-sdk/client-organizations";import{success as s,failure as e}from"@fjall/generator";import{extractErrorName as m,SDK_TIMEOUT_MS as i,AWS_ERROR_NAMES as t}from"./types.js";import{getErrorMessage as o}from"@fjall/util";const u=["account.amazonaws.com","sso.amazonaws.com","ipam.amazonaws.com","ram.amazonaws.com","backup.amazonaws.com","member.org.stacksets.cloudformation.amazonaws.com","guardduty.amazonaws.com","securityhub.amazonaws.com","config.amazonaws.com","inspector2.amazonaws.com","access-analyzer.amazonaws.com"];async function f(c){try{for(const a of u)try{await c.send(new n({ServicePrincipal:a}),{abortSignal:AbortSignal.timeout(i)})}catch(r){if(m(r)===t.ACCESS_DENIED)return e(new Error(`Access denied when enabling service access for ${a}. Ensure your credentials have organizations:EnableAWSServiceAccess permission.`));throw new Error(`Service principal ${a}: ${o(r)}`,{cause:r})}return s(void 0)}catch(a){return e(new Error(`Failed to enable service access: ${o(a)}`))}}export{f as enableServiceAccess};
+import{EnableAWSServiceAccessCommand as n}from"@aws-sdk/client-organizations";import{success as s,failure as o}from"@fjall/generator";import{extractErrorName as m,SDK_TIMEOUT_MS as i,AWS_ERROR_NAMES as t}from"./types.js";import{getErrorMessage as e}from"@fjall/util";const w=["account.amazonaws.com","sso.amazonaws.com","ipam.amazonaws.com","ram.amazonaws.com","backup.amazonaws.com","member.org.stacksets.cloudformation.amazonaws.com","guardduty.amazonaws.com","securityhub.amazonaws.com","config.amazonaws.com","inspector2.amazonaws.com","access-analyzer.amazonaws.com","cloudtrail.amazonaws.com","iam.amazonaws.com"];async function z(c){try{for(const a of w)try{await c.send(new n({ServicePrincipal:a}),{abortSignal:AbortSignal.timeout(i)})}catch(r){if(m(r)===t.ACCESS_DENIED)return o(new Error(`Access denied when enabling service access for ${a}. Ensure your credentials have organizations:EnableAWSServiceAccess permission.`));throw new Error(`Service principal ${a}: ${e(r)}`,{cause:r})}return s(void 0)}catch(a){return o(new Error(`Failed to enable service access: ${e(a)}`))}}export{w as SERVICE_PRINCIPALS,z as enableServiceAccess};

package/dist/src/aws/organisations/types.d.ts

@@ -24,6 +24,12 @@ export interface AccountPlacementResult {
 export interface AccountInfo {
     id: string;
     name: string;
+    /**
+     * OU placement key (the bucket name in the ACCOUNTS config — `root`,
+     * `platform`, or a workload stage), NOT the nullable account STAGE axis.
+     * Callers coalesce stage-less accounts to their tier before building this
+     * (see OrganisationSetupService), so it is always present here.
+     */
     environment: string;
 }
 export interface IdentityCentreStatus {
@@ -44,8 +50,20 @@ export type OUTree = {
 };
 /** Returns true if the value is a list of account names (leaf node). */
 export declare function isOULeaf(value: string[] | OUTree): value is string[];
+/**
+ * Compose the per-request SDK timeout with an optional caller shutdown
+ * signal so SIGTERM is not stalled by an in-flight call (the
+ * `DeployParams.abortSignal` contract).
+ */
+export declare function composeSdkAbortSignal(abortSignal?: AbortSignal): AbortSignal;
+export declare function isAborted(abortSignal?: AbortSignal): boolean;
 /**
  * Extract the error name from an AWS SDK error.
  * AWS SDK v3 errors have a `name` property that identifies the error type.
  */
 export declare function extractErrorName(error: unknown): string;
+/**
+ * IAM, STS, and S3 surface denials as "AccessDenied"; Organizations and most
+ * other services throw "AccessDeniedException" — match both.
+ */
+export declare function isAccessDenied(errorName: string): boolean;

package/dist/src/aws/organisations/types.js

@@ -1 +1 @@
-const t=3e4,e={ACCESS_DENIED:"AccessDeniedException",ACCOUNT_ALREADY_REGISTERED:"AccountAlreadyRegisteredException",ACCOUNT_NOT_FOUND:"AccountNotFoundException",CHILD_NOT_FOUND:"ChildNotFoundException",ORGS_NOT_IN_USE:"AWSOrganizationsNotInUseException"};function o(n){return Array.isArray(n)}function E(n){return typeof n=="object"&&n!==null&&"name"in n&&typeof n.name=="string"?n.name:"UnknownError"}export{e as AWS_ERROR_NAMES,t as SDK_TIMEOUT_MS,E as extractErrorName,o as isOULeaf};
+const o=3e4,e={ACCESS_DENIED:"AccessDeniedException",ACCOUNT_ALREADY_REGISTERED:"AccountAlreadyRegisteredException",ACCOUNT_NOT_FOUND:"AccountNotFoundException",CHILD_NOT_FOUND:"ChildNotFoundException",ORGS_NOT_IN_USE:"AWSOrganizationsNotInUseException"};function i(n){return Array.isArray(n)}function c(n){const t=AbortSignal.timeout(3e4);return n!==void 0?AbortSignal.any([n,t]):t}function r(n){return n?.aborted===!0}function E(n){return typeof n=="object"&&n!==null&&"name"in n&&typeof n.name=="string"?n.name:"UnknownError"}function A(n){return n==="AccessDenied"||n===e.ACCESS_DENIED}export{e as AWS_ERROR_NAMES,o as SDK_TIMEOUT_MS,c as composeSdkAbortSignal,E as extractErrorName,r as isAborted,A as isAccessDenied,i as isOULeaf};

package/dist/src/aws/sts/assumeRoot.d.ts

@@ -0,0 +1,46 @@
+import { type STSClient } from "@aws-sdk/client-sts";
+import { type Result } from "@fjall/generator";
+import type { AwsProviderCredentials } from "../AwsProvider.js";
+/**
+ * The five AWS-managed root-task policies AssumeRoot accepts. Every root
+ * session is bounded by exactly one of these; arbitrary policies are
+ * rejected by STS, so the primitive rejects them before sending.
+ */
+export declare const ROOT_TASK_POLICY_ARNS: readonly ["arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials", "arn:aws:iam::aws:policy/root-task/IAMCreateRootUserPassword", "arn:aws:iam::aws:policy/root-task/IAMDeleteRootUserCredentials", "arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy", "arn:aws:iam::aws:policy/root-task/SQSUnlockQueuePolicy"];
+export type RootTaskPolicyArn = (typeof ROOT_TASK_POLICY_ARNS)[number];
+export declare function isRootTaskPolicyArn(value: string): value is RootTaskPolicyArn;
+/** AssumeRoot hard maximum session duration. */
+export declare const MAX_ROOT_SESSION_SECONDS = 900;
+export interface AssumeRootOptions {
+    /** Member account whose root principal the session acts as. */
+    targetAccountId: string;
+    /** One of the five AWS root-task policy ARNs bounding the session. */
+    taskPolicyArn: string;
+    /** Session duration in seconds, max 900. Omitted → AWS default (900). */
+    durationSeconds?: number;
+    /** Caller shutdown signal, composed with the per-call SDK timeout. */
+    abortSignal?: AbortSignal;
+}
+export interface RootTaskSession {
+    credentials: AwsProviderCredentials & {
+        expiration?: Date;
+    };
+    /** Identity STS records for the root session (CloudTrail audit trail). */
+    sourceIdentity?: string;
+}
+/**
+ * Assume a member account's root principal for a bounded privileged task
+ * via STS AssumeRoot.
+ *
+ * Requires management-account or delegated-admin credentials with
+ * `sts:AssumeRoot`, centralised root access enabled on the organisation
+ * (RootCredentialsManagement), and a client pinned to a regional STS
+ * endpoint — AssumeRoot is not served by the global endpoint. The cascade
+ * role path (`assumeCascadeRole`) is structurally useless against a
+ * quarantine: a quarantine deny policy blocks every role principal, while
+ * an assume-root session bypasses member roles entirely.
+ *
+ * Returned credentials are credential VALUES — callers must never log
+ * them; error messages from this primitive are masked.
+ */
+export declare function assumeRootForTask(client: STSClient, options: AssumeRootOptions): Promise<Result<RootTaskSession>>;

package/dist/src/aws/sts/assumeRoot.js

@@ -0,0 +1 @@
+import{AssumeRootCommand as m}from"@aws-sdk/client-sts";import{success as S,failure as n}from"@fjall/generator";import{getErrorMessage as f,maskSensitiveOutput as A}from"@fjall/util";import{composeSdkAbortSignal as p,extractErrorName as w,isAccessDenied as y}from"../organisations/types.js";const d=["arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials","arn:aws:iam::aws:policy/root-task/IAMCreateRootUserPassword","arn:aws:iam::aws:policy/root-task/IAMDeleteRootUserCredentials","arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy","arn:aws:iam::aws:policy/root-task/SQSUnlockQueuePolicy"],g=new Set(d);function k(t){return g.has(t)}const u=900,T=/^\d{12}$/;async function O(t,i){const{targetAccountId:r,taskPolicyArn:a,durationSeconds:o,abortSignal:l}=i;if(!T.test(r))return n(new Error(`Invalid target account id "${r}": expected a 12-digit AWS account id.`));if(!k(a))return n(new Error(`Task policy "${a}" is not an AWS root-task policy. AssumeRoot accepts only: ${d.join(", ")}.`));if(o!==void 0&&(!Number.isInteger(o)||o<1||o>u))return n(new Error(`Invalid durationSeconds ${o}: AssumeRoot sessions must be a whole number of seconds between 1 and ${u}.`));const c=await R(t);if(c===void 0||c==="")return n(new Error("AssumeRoot requires a regional STS endpoint, but the client has no resolvable region. Construct the STS client with an explicit region."));try{const s=await t.send(new m({TargetPrincipal:r,TaskPolicyArn:{arn:a},...o!==void 0&&{DurationSeconds:o}}),{abortSignal:p(l)}),e=s.Credentials;return e?.AccessKeyId===void 0||e.SecretAccessKey===void 0||e.SessionToken===void 0?n(new Error(`AssumeRoot for account ${r} returned no credentials.`)):S({credentials:{accessKeyId:e.AccessKeyId,secretAccessKey:e.SecretAccessKey,sessionToken:e.SessionToken,...e.Expiration!==void 0&&{expiration:e.Expiration}},...s.SourceIdentity!==void 0&&{sourceIdentity:s.SourceIdentity}})}catch(s){const e=w(s);return y(e)?n(new Error(`Access denied assuming root for account ${r}. Ensure the credentials belong to the management account (or the delegated admin) with sts:AssumeRoot permission, and that centralised root access management is enabled for the organisation.`)):n(new Error(`Failed to assume root for account ${r}: ${A(f(s))}`))}}async function R(t){try{const i=t.config.region;return typeof i=="function"?await i():i}catch{return}}export{u as MAX_ROOT_SESSION_SECONDS,d as ROOT_TASK_POLICY_ARNS,O as assumeRootForTask,k as isRootTaskPolicyArn};

package/dist/src/aws/targetReadiness.d.ts

@@ -0,0 +1,70 @@
+import { type CloudFormationClient } from "@aws-sdk/client-cloudformation";
+import { type EC2Client } from "@aws-sdk/client-ec2";
+import { type Result } from "@fjall/generator";
+import type { OrgConfig } from "../types/orgConfig.js";
+export declare const ACCOUNT_STACK_NAME: string;
+export type TargetReadinessReason = {
+    kind: "missing-account-stack";
+    stackName: string;
+    region: string;
+} | {
+    kind: "missing-ipam-pool";
+    accountId: string;
+    region: string;
+};
+export type TargetReadinessVerdict = {
+    ready: true;
+} | {
+    ready: false;
+    reasons: TargetReadinessReason[];
+    advisory: string;
+};
+/**
+ * Both clients carry the target account's credentials, but their regions
+ * differ: cloudFormation is scoped to the TARGET region (the Account stack
+ * lives where the deploy lands); ec2 is scoped to the IPAM HOME region (the
+ * platform stack's region) — RAM shares are created in the home region and
+ * `DescribeIpamPools` returns nothing for shared pools anywhere else.
+ */
+export interface TargetReadinessClients {
+    cloudFormation: CloudFormationClient;
+    ec2: EC2Client;
+}
+export interface TargetReadinessAccount {
+    id: string;
+    /** Provider-account name when resolved from org config; omit otherwise. */
+    name?: string;
+}
+export declare function describeTargetReadinessReason(reason: TargetReadinessReason): string;
+/**
+ * Shape-branched remediation for an unready deploy target (AC2b.1). Org
+ * estates (a tier-organisation account in providerAccounts) remediate via the
+ * cascade, which provisions every account and creates the IPAM pool; solo
+ * accounts provision the target directly. The solo `target set` command embeds
+ * the derived `{accountName}-{regionAbbrev}` target name — the only form
+ * `target set` resolves — and degrades to `fjall target list` guidance when
+ * the account name could not be resolved from org config.
+ */
+export declare function buildTargetUnreadyAdvisory(params: {
+    accountId: string;
+    accountName?: string;
+    region: string;
+    reasons: TargetReadinessReason[];
+    providerAccounts?: OrgConfig["providerAccounts"];
+}): string;
+/**
+ * Probe whether a deploy target is provisioned before any AWS mutation:
+ * the fixed-name Account stack must exist in the target region (both shapes),
+ * and for org estates (a tier-organisation account in providerAccounts) the
+ * (account, region) IPAM pool must exist. Bootstrap is excluded — both deploy
+ * paths self-heal it.
+ *
+ * Missing resources return an unready verdict carrying structured reasons and
+ * the shape-branched advisory. Every probe error (AccessDenied, throttling,
+ * network) propagates as failure — a mis-read "unready" refuses a legitimate
+ * deploy, a mis-read "ready" lets a deploy fail mid-mutation; neither may be
+ * guessed (mirrors describeAccountGlobalsExist).
+ *
+ * Failure messages stay raw — callers mask at their output boundary.
+ */
+export declare function checkTargetReadiness(clients: TargetReadinessClients, account: TargetReadinessAccount, region: string, orgConfig?: OrgConfig, abortSignal?: AbortSignal): Promise<Result<TargetReadinessVerdict>>;

package/dist/src/aws/targetReadiness.js

@@ -0,0 +1 @@
+import{DescribeStacksCommand as N}from"@aws-sdk/client-cloudformation";import{DescribeIpamPoolsCommand as S}from"@aws-sdk/client-ec2";import{success as i,failure as c}from"@fjall/generator";import{accountTier as A,generateTargetName as g,getErrorMessage as E}from"@fjall/util";import{formatIpamPairTagValue as y,IPAM_OPERATIONS_POOL_TAG_KEY as O,STACK_NOT_FOUND_PATTERN as k}from"@fjall/util/aws";import{getOrganisationStackName as _,ORGANISATION_TYPES as R}from"../types/operations.js";import{hasOrganisationTierAccount as T}from"./organisations/accountGlobals.js";import{composeSdkAbortSignal as I,isAborted as P}from"./organisations/types.js";const m=_(R.ACCOUNT),w=new Set(["CREATE_FAILED","ROLLBACK_IN_PROGRESS","ROLLBACK_COMPLETE","ROLLBACK_FAILED","REVIEW_IN_PROGRESS","DELETE_IN_PROGRESS","DELETE_FAILED"]);function $(e){switch(e.kind){case"missing-account-stack":return`the ${e.stackName} stack was not found in ${e.region}`;case"missing-ipam-pool":return`no IPAM pool exists for account ${e.accountId} in ${e.region}`}}function L(e){const t=e.accountName??e.accountId,n=e.reasons.map($).join(" and "),o=e.accountName!==void 0?`run \`fjall target set ${g(e.accountName,e.region)}\` then \`fjall deploy account\`, then retry this deploy`:"run `fjall target list` to find the target name, `fjall target set <target>`, then `fjall deploy account`, then retry this deploy",r=T(e.providerAccounts)?"run `fjall deploy organisation` (the cascade provisions every account and creates the IPAM pool), then retry this deploy":o;return`Target "${t}" is not ready in ${e.region}: ${n}. Nothing has been deployed. Provision the target first: ${r}.`}function b(e){return e instanceof Error&&e.name==="ValidationError"&&e.message.includes(k)}async function C(e,t,n){try{const r=(await e.send(new N({StackName:m}),{abortSignal:I(n)})).Stacks?.[0]?.StackStatus;return i(r!==void 0&&!w.has(r))}catch(o){return b(o)?i(!1):c(new Error(`Failed to probe the ${m} stack in ${t}: ${E(o)}`))}}function v(e,t,n,o){return e.Locale!==n?!1:o.side==="owner"?(e.Tags??[]).some(r=>r.Key===O&&r.Value===o.pairTagValue):e.OwnerId===t?!1:o.platformAccountId===void 0||e.OwnerId===o.platformAccountId}async function x(e,t,n,o,r){try{let a;do{if(P(r))return c(new Error(`Aborted: IPAM pool probe for account ${t} in ${n} cancelled by shutdown signal`));const s=await e.send(new S({...a!==void 0&&{NextToken:a}}),{abortSignal:I(r)});if((s.IpamPools??[]).some(u=>v(u,t,n,o)))return i(!0);a=s.NextToken}while(a!==void 0);return i(!1)}catch(a){return c(new Error(`Failed to probe IPAM pools for account ${t} in ${n}: ${E(a)}`))}}async function B(e,t,n,o,r){const a=[],s=await C(e.cloudFormation,n,r);if(!s.success)return c(s.error);s.data||a.push({kind:"missing-account-stack",stackName:m,region:n});const d=o?.providerAccounts;if(T(d)){const u=(d??[]).find(l=>l.id===t.id),p=(d??[]).find(l=>A(l)==="platform")?.id,h=u!==void 0&&A(u)==="platform"?{side:"owner",pairTagValue:y(t.id,n)}:{side:"consumer",...p!==void 0&&{platformAccountId:p}},f=await x(e.ec2,t.id,n,h,r);if(!f.success)return c(f.error);f.data||a.push({kind:"missing-ipam-pool",accountId:t.id,region:n})}return a.length===0?i({ready:!0}):i({ready:!1,reasons:a,advisory:L({accountId:t.id,...t.name!==void 0&&{accountName:t.name},region:n,reasons:a,...o!==void 0&&{providerAccounts:o.providerAccounts}})})}export{m as ACCOUNT_STACK_NAME,L as buildTargetUnreadyAdvisory,B as checkTargetReadiness,$ as describeTargetReadinessReason};

package/dist/src/aws/targetSetAdvisory.d.ts

@@ -0,0 +1,24 @@
+import type { OrgConfig } from "../types/orgConfig.js";
+import { type TargetReadinessReason } from "./targetReadiness.js";
+/**
+ * Coupled to buildTargetUnreadyAdvisory at ./targetReadiness.ts — both open
+ * with the identical `Target "X" is not ready in <region>: <reasons>.`
+ * sentence built from describeTargetReadinessReason. Kept as a sibling module
+ * (not a shared-core refactor in targetReadiness.ts) only because that file
+ * carries concurrent in-flight changes; merge into a shared core when it is
+ * next touched.
+ */
+export interface TargetSetUnreadyAdvisoryParams {
+    accountId: string;
+    accountName?: string;
+    region: string;
+    reasons: TargetReadinessReason[];
+    providerAccounts?: OrgConfig["providerAccounts"];
+}
+/**
+ * Shape-branched advisory for `fjall target set` when the just-set target is
+ * unprovisioned (AC2c.1). Advisory only — the target has been saved
+ * regardless, so unlike the deploy-context advisory there is no "Nothing has
+ * been deployed." sentence and no retry tail.
+ */
+export declare function buildTargetSetUnreadyAdvisory(params: TargetSetUnreadyAdvisoryParams): string;

package/dist/src/aws/targetSetAdvisory.js

@@ -0,0 +1 @@
+import{hasOrganisationTierAccount as t}from"./organisations/accountGlobals.js";import{describeTargetReadinessReason as r}from"./targetReadiness.js";function s(o){const n=o.accountName??o.accountId,e=o.reasons.map(r).join(" and "),i=t(o.providerAccounts)?"Run `fjall deploy organisation` \u2014 the cascade provisions every account and creates the IPAM pool":"Run `fjall deploy account` to provision it";return`Target "${n}" is not ready in ${o.region}: ${e}. ${i}.`}export{s as buildTargetSetUnreadyAdvisory};

package/dist/src/events/index.d.ts

@@ -11,3 +11,5 @@
 export { DeploymentEventSchema, DEPLOYMENT_EVENT_TYPES, DEPLOYMENT_EVENT_RESOURCE_CATEGORIES, CASCADE_PHASES, CASCADE_ACCOUNT_STATUSES } from "../types/deploymentEventSchema.js";
 export type { DeploymentEvent, DeploymentEventType, DeploymentEventResourceCategory, DeploymentEventCascadePhase, DeploymentEventCascadeAccountStatus } from "../types/deploymentEventSchema.js";
 export { toCascadePhase } from "../types/deploymentEventSchema.js";
+export { TRAIL_MIGRATION_PHASES, TRAIL_MIGRATION_STATUSES } from "../types/events.js";
+export type { TrailMigrationPhase, TrailMigrationStatus, TrailMigrationPhaseEvent } from "../types/events.js";

package/dist/src/events/index.js

@@ -1 +1 @@
-import{DeploymentEventSchema as C,DEPLOYMENT_EVENT_TYPES as T,DEPLOYMENT_EVENT_RESOURCE_CATEGORIES as e,CASCADE_PHASES as A,CASCADE_ACCOUNT_STATUSES as _}from"../types/deploymentEventSchema.js";import{toCascadePhase as t}from"../types/deploymentEventSchema.js";export{_ as CASCADE_ACCOUNT_STATUSES,A as CASCADE_PHASES,e as DEPLOYMENT_EVENT_RESOURCE_CATEGORIES,T as DEPLOYMENT_EVENT_TYPES,C as DeploymentEventSchema,t as toCascadePhase};
+import{DeploymentEventSchema as T,DEPLOYMENT_EVENT_TYPES as A,DEPLOYMENT_EVENT_RESOURCE_CATEGORIES as _,CASCADE_PHASES as e,CASCADE_ACCOUNT_STATUSES as C}from"../types/deploymentEventSchema.js";import{toCascadePhase as I}from"../types/deploymentEventSchema.js";import{TRAIL_MIGRATION_PHASES as O,TRAIL_MIGRATION_STATUSES as R}from"../types/events.js";export{C as CASCADE_ACCOUNT_STATUSES,e as CASCADE_PHASES,_ as DEPLOYMENT_EVENT_RESOURCE_CATEGORIES,A as DEPLOYMENT_EVENT_TYPES,T as DeploymentEventSchema,O as TRAIL_MIGRATION_PHASES,R as TRAIL_MIGRATION_STATUSES,I as toCascadePhase};