@beesolve/aws-accounts 1.0.7 → 1.2.0

package/README.md

@@ -11,7 +11,12 @@ Config-driven management for AWS Organizations and IAM Identity Center. Define y
 npm install @beesolve/aws-accounts
 ```
 
-Requires Node.js 24+ and valid AWS credentials (via environment, profile, or SSO).
+## Prerequisites
+
+- **Node.js 24+**
+- **AWS Organization** with all features enabled
+- **IAM Identity Center** enabled in the organization's management account (or delegated admin account)
+- **AWS credentials** with access to the management account (via environment, profile, or SSO)
 
 ## Quick Start
 
@@ -20,7 +25,7 @@ Requires Node.js 24+ and valid AWS credentials (via environment, profile, or SSO
 mkdir my-org && cd my-org
 npm init -y
 npm pkg set type=module
-npm install @beesolve/aws-accounts
+npm install @beesolve/aws-accounts typescript
 
 # 2. Initialize git and add a .gitignore
 git init
@@ -54,7 +59,9 @@ After `init`, `aws.config.ts` is your source of truth. Edit it to add accounts,
 | `apply` | Executes planned operations via Lambda |
 | `upgrade` | Updates the deployed Lambda function code |
 | `scan` | Refreshes remote state in S3 (advanced/recovery use) |
+| `validate` | Validates `aws.config.ts` locally without hitting AWS |
 | `graveyard` | Lists accounts parked in the Graveyard OU |
+| `profile` | Generates an AWS CLI SSO profile block from local state |
 
 ## Workflow
 
@@ -72,6 +79,20 @@ After `init`, your project contains:
 - **`aws.config.ts`** — your desired state: OUs, accounts, users, groups, permission sets, assignments
 - **`aws.config.types.ts`** — generated types and helpers for IDE autocomplete
 
+### Permission Sets
+
+```ts
+permissionSets: [
+  {
+    name: "AdminAccess",
+    description: "Full administrator access",
+    sessionDuration: "PT8H", // ISO-8601 duration; omit to use the AWS default of 1h (max 12h)
+    awsManagedPolicies: ["arn:aws:iam::aws:policy/AdministratorAccess"],
+    customerManagedPolicies: [],
+  },
+],
+```
+
 ### IAM Policy Helpers
 
 `aws.config.types.ts` exports `iam` helpers with service-scoped action autocomplete:
@@ -102,10 +123,32 @@ When `init` generates your config, recognized IAM actions in inline policies are
 - Update group descriptions
 - Manage group memberships
 - Create, update, and delete permission sets
+- Set permission set session duration (ISO-8601, e.g. `"PT8H"` — default 1h, max 12h)
 - Manage inline policies, AWS managed policies, and customer-managed policy references
 - Grant and revoke account assignments
 - Reprovision changed permission sets
 
+## Validating your config
+
+Run `validate` before `plan` to catch mistakes locally without making any AWS API calls:
+
+```bash
+npx aws-accounts validate
+```
+
+It checks two layers:
+
+**Schema and reference errors** — caught by compiling `aws.config.ts` against the generated types in `aws.config.types.ts`:
+- Type mismatches and missing required fields
+- References to unknown OUs, accounts, groups, users, or permission sets (enforced by the generated picklist types)
+
+**Semantic errors** — additional checks run after the schema passes:
+- Circular OU parent references (e.g. OU A has `parentName: "B"` and B has `parentName: "A"`)
+- Assignments with no principal or with both `group` and `user` set
+- Permission set inline policies exceeding the 10,240 character limit
+
+Exits with code 1 if any errors are found, making it safe to use in CI before running `plan`.
+
 ## Plan/Apply Safety
 
 - `plan` fetches current remote state from S3 before computing the diff.
@@ -140,20 +183,46 @@ npx aws-accounts plan        # review remaining diff
 npx aws-accounts apply       # re-apply (add --allow-destructive if needed)
 ```
 
+## Generating AWS CLI profiles
+
+The `profile` command reads your local state cache and presents an interactive picker of every account/permission-set combination you have access to, then prints a ready-to-paste `~/.aws/config` block:
+
+```bash
+npx aws-accounts profile --sso-start-url https://d-xxxxxxxxxx.awsapps.com/start
+```
+
+```ini
+[profile my-account-admin-access]
+sso_session = sso
+sso_account_id = 123456789012
+sso_role_name = AdminAccess
+
+[sso-session sso]
+sso_start_url = https://d-xxxxxxxxxx.awsapps.com/start
+sso_region = eu-central-1
+sso_registration_scopes = sso:account:access
+```
+
+The SSO start URL is not returned by the AWS API — set it via the flag or the `AWS_SSO_START_URL` environment variable to avoid typing it every time. Use `--sso-session <name>` to customise the session name (default: `sso`).
+
+Requires a populated local state cache — run `plan` or `scan` first if the cache is empty.
+
 ## CLI Options
 
 ```
 npx aws-accounts <command> [options]
 
 Options:
-  --profile <name>       AWS profile (fallback: AWS_PROFILE)
-  --region <region>      AWS region (fallback: AWS_REGION, AWS_DEFAULT_REGION)
-  --yes                  Skip interactive confirmations
-  --json                 Output plan as JSON (plan command)
-  --allow-destructive    Allow destructive operations (apply command)
-  --ignore-unsupported   Proceed with non-destructive unsupported diffs (apply command)
-  --refresh              Force state refresh before planning (plan command)
-  --help                 Show help
+  --profile <name>          AWS profile (fallback: AWS_PROFILE)
+  --region <region>         AWS region (fallback: AWS_REGION, AWS_DEFAULT_REGION)
+  --yes                     Skip interactive confirmations
+  --json                    Output plan as JSON (plan command)
+  --allow-destructive       Allow destructive operations (apply command)
+  --ignore-unsupported      Proceed with non-destructive unsupported diffs (apply command)
+  --refresh                 Force state refresh before planning (plan command)
+  --sso-start-url <url>     IAM Identity Center access portal URL (fallback: AWS_SSO_START_URL)
+  --sso-session <name>      SSO session name for profile output (default: sso)
+  --help                    Show help
 ```
 
 ## IAM Permissions
@@ -173,7 +242,7 @@ The CLI delegates all AWS operations to a deployed Lambda. Day-to-day usage requ
 
 `bootstrap` and `upgrade` require broader permissions for deploying infrastructure (S3, IAM, Lambda, SSO). See the full policy in the [docs](./docs/adr/002-architecture-and-technology-choices.md).
 
-Commands that need no AWS permissions: `regenerate` (local codegen only), `graveyard` (reads local cache only).
+Commands that need no AWS permissions: `regenerate` (local codegen only), `validate` (local config checks only), `graveyard` (reads local cache only).
 
 ## FAQ
 

package/dist/applyLogic.js

@@ -1,15 +1,22 @@
 import {
-  PutAccountNameCommand
+  DeleteAlternateContactCommand,
+  PutAccountNameCommand,
+  PutAlternateContactCommand
 } from "@aws-sdk/client-account";
 import {
+  AttachPolicyCommand,
   CreateOrganizationalUnitCommand,
+  CreatePolicyCommand,
   DeleteOrganizationalUnitCommand,
+  DeletePolicyCommand,
+  DetachPolicyCommand,
   ListAccountsForParentCommand,
   ListOrganizationalUnitsForParentCommand,
   MoveAccountCommand,
   TagResourceCommand,
   UntagResourceCommand,
-  UpdateOrganizationalUnitCommand
+  UpdateOrganizationalUnitCommand,
+  UpdatePolicyCommand
 } from "@aws-sdk/client-organizations";
 import {
   CreateGroupMembershipCommand,
@@ -37,6 +44,7 @@ import {
   DetachManagedPolicyFromPermissionSetCommand,
   ProvisionPermissionSetCommand,
   PutInlinePolicyToPermissionSetCommand,
+  UpdateInstanceAccessControlAttributeConfigurationCommand,
   UpdatePermissionSetCommand
 } from "@aws-sdk/client-sso-admin";
 import { createAccountAndMoveToOu } from "./accountCreation.js";
@@ -44,6 +52,7 @@ import { assertUnreachable, delay } from "./helpers.js";
 import {
   addGroupMembershipToWorkingState,
   addAccountAssignmentToWorkingState,
+  addOrgPolicyAttachmentToWorkingState,
   createGroupMembershipKey,
   moveAccountInWorkingState,
   removeAccountAssignmentFromWorkingState,
@@ -52,12 +61,15 @@ import {
   removeIdcPermissionSetFromWorkingState,
   removeIdcUserFromWorkingState,
   removeOrganizationalUnitFromWorkingState,
+  removeOrgPolicyAttachmentFromWorkingState,
+  removeOrgPolicyFromWorkingState,
   renameOrganizationalUnitInWorkingState,
   upsertIdcGroupInWorkingState,
   upsertIdcPermissionSetInWorkingState,
   upsertIdcUserInWorkingState,
   upsertAccountInWorkingState,
-  upsertOrganizationalUnitInWorkingState
+  upsertOrganizationalUnitInWorkingState,
+  upsertOrgPolicyInWorkingState
 } from "./state.js";
 async function executeOperation(props) {
   const operation = props.operation;
@@ -204,7 +216,10 @@ async function executeOperation(props) {
       workingState: props.state,
       account: {
         ...account,
-        tags: Object.entries(operation.tags).map(([key, value]) => ({ key, value }))
+        tags: Object.entries(operation.tags).map(([key, value]) => ({
+          key,
+          value
+        }))
       }
     });
   }
@@ -246,7 +261,9 @@ async function executeOperation(props) {
         DestinationParentId: operation.toOuId
       })
     );
-    props.logger.log(`Done: "${operation.accountName}" -> ${operation.toOuName}`);
+    props.logger.log(
+      `Done: "${operation.accountName}" -> ${operation.toOuName}`
+    );
     return moveAccountInWorkingState({
       workingState: props.state,
       accountId: operation.accountId,
@@ -473,7 +490,8 @@ async function executeOperation(props) {
       new CreatePermissionSetCommand({
         InstanceArn: props.state.identityCenter.instanceArn,
         Name: operation.permissionSetName,
-        Description: operation.description.length > 0 ? operation.description : void 0
+        Description: operation.description.length > 0 ? operation.description : void 0,
+        SessionDuration: operation.sessionDuration ?? void 0
       })
     );
     const permissionSetArn = response.PermissionSet?.PermissionSetArn;
@@ -489,6 +507,7 @@ async function executeOperation(props) {
         permissionSetArn,
         name: operation.permissionSetName,
         description: operation.description,
+        sessionDuration: operation.sessionDuration,
         inlinePolicy: null,
         awsManagedPolicies: [],
         customerManagedPolicies: []
@@ -519,6 +538,30 @@ async function executeOperation(props) {
       }
     });
   }
+  if (operation.kind === "updateIdcPermissionSetSessionDuration") {
+    const permissionSet = resolvePermissionSetByName({
+      state: props.state,
+      permissionSetName: operation.permissionSetName
+    });
+    props.logger.log(
+      `Updating IdC permission set session duration for "${operation.permissionSetName}"...`
+    );
+    await props.ssoAdminClient.send(
+      new UpdatePermissionSetCommand({
+        InstanceArn: props.state.identityCenter.instanceArn,
+        PermissionSetArn: permissionSet.permissionSetArn,
+        SessionDuration: operation.sessionDuration ?? void 0
+      })
+    );
+    props.logger.log(`Done: "${operation.permissionSetName}"`);
+    return upsertIdcPermissionSetInWorkingState({
+      workingState: props.state,
+      permissionSet: {
+        ...permissionSet,
+        sessionDuration: operation.sessionDuration
+      }
+    });
+  }
   if (operation.kind === "deleteIdcPermissionSet") {
     const permissionSet = resolvePermissionSetByName({
       state: props.state,
@@ -880,6 +923,218 @@ async function executeOperation(props) {
       }
     });
   }
+  if (operation.kind === "createOrgPolicy") {
+    props.logger.log(
+      `Creating org policy "${operation.policyName}" (${operation.policyType})...`
+    );
+    const response = await props.organizationsClient.send(
+      new CreatePolicyCommand({
+        Name: operation.policyName,
+        Description: operation.description.length > 0 ? operation.description : void 0,
+        Content: operation.content,
+        Type: operation.policyType
+      })
+    );
+    const policy = response.Policy?.PolicySummary;
+    if (policy?.Id == null || policy.Arn == null) {
+      throw new Error(
+        `CreatePolicy for "${operation.policyName}" returned incomplete data.`
+      );
+    }
+    props.logger.log(`Done: "${operation.policyName}"`);
+    return upsertOrgPolicyInWorkingState({
+      workingState: props.state,
+      policy: {
+        id: policy.Id,
+        arn: policy.Arn,
+        name: operation.policyName,
+        description: operation.description,
+        type: operation.policyType,
+        content: operation.content
+      }
+    });
+  }
+  if (operation.kind === "updateOrgPolicyContent") {
+    props.logger.log(`Updating org policy content "${operation.policyName}"...`);
+    await props.organizationsClient.send(
+      new UpdatePolicyCommand({
+        PolicyId: operation.policyId,
+        Content: operation.content
+      })
+    );
+    props.logger.log(`Done: "${operation.policyName}"`);
+    const currentPolicy = props.state.organization.policiesById[operation.policyId];
+    if (currentPolicy == null) {
+      return props.state;
+    }
+    return upsertOrgPolicyInWorkingState({
+      workingState: props.state,
+      policy: { ...currentPolicy, content: operation.content }
+    });
+  }
+  if (operation.kind === "updateOrgPolicyDescription") {
+    props.logger.log(
+      `Updating org policy description "${operation.policyName}"...`
+    );
+    await props.organizationsClient.send(
+      new UpdatePolicyCommand({
+        PolicyId: operation.policyId,
+        Description: operation.description
+      })
+    );
+    props.logger.log(`Done: "${operation.policyName}"`);
+    const currentPolicy = props.state.organization.policiesById[operation.policyId];
+    if (currentPolicy == null) {
+      return props.state;
+    }
+    return upsertOrgPolicyInWorkingState({
+      workingState: props.state,
+      policy: { ...currentPolicy, description: operation.description }
+    });
+  }
+  if (operation.kind === "attachOrgPolicy") {
+    props.logger.log(
+      `Attaching org policy "${operation.policyName}" to "${operation.targetName}"...`
+    );
+    const resolvedPolicyId = resolvePolicyId({
+      state: props.state,
+      policyId: operation.policyId,
+      policyName: operation.policyName
+    });
+    await props.organizationsClient.send(
+      new AttachPolicyCommand({
+        PolicyId: resolvedPolicyId,
+        TargetId: operation.targetId
+      })
+    );
+    props.logger.log(`Done: "${operation.policyName}" -> "${operation.targetName}"`);
+    const targetType = operation.targetId === props.context.organization.rootId ? "ROOT" : props.state.organization.organizationalUnitsById[operation.targetId] != null ? "ORGANIZATIONAL_UNIT" : "ACCOUNT";
+    return addOrgPolicyAttachmentToWorkingState({
+      workingState: props.state,
+      attachment: {
+        policyId: resolvedPolicyId,
+        targetId: operation.targetId,
+        targetType
+      }
+    });
+  }
+  if (operation.kind === "detachOrgPolicy") {
+    props.logger.log(
+      `Detaching org policy "${operation.policyName}" from "${operation.targetName}"...`
+    );
+    await props.organizationsClient.send(
+      new DetachPolicyCommand({
+        PolicyId: operation.policyId,
+        TargetId: operation.targetId
+      })
+    );
+    props.logger.log(`Done: "${operation.policyName}" x "${operation.targetName}"`);
+    return removeOrgPolicyAttachmentFromWorkingState({
+      workingState: props.state,
+      policyId: operation.policyId,
+      targetId: operation.targetId
+    });
+  }
+  if (operation.kind === "deleteOrgPolicy") {
+    props.logger.log(`Deleting org policy "${operation.policyName}"...`);
+    await props.organizationsClient.send(
+      new DeletePolicyCommand({ PolicyId: operation.policyId })
+    );
+    props.logger.log(`Done: "${operation.policyName}"`);
+    return removeOrgPolicyFromWorkingState({
+      workingState: props.state,
+      policyId: operation.policyId
+    });
+  }
+  if (operation.kind === "putAlternateContact") {
+    props.logger.log(
+      `Setting ${operation.contactType} alternate contact for "${operation.accountName}" (${operation.accountId})...`
+    );
+    await props.accountClient.send(
+      new PutAlternateContactCommand({
+        AccountId: operation.accountId,
+        AlternateContactType: operation.contactType,
+        Name: operation.name,
+        EmailAddress: operation.email,
+        PhoneNumber: operation.phone,
+        Title: operation.title
+      })
+    );
+    props.logger.log(`Done: ${operation.contactType} contact for "${operation.accountName}"`);
+    const account = props.state.organization.accountsById[operation.accountId];
+    if (account == null) {
+      throw new Error(
+        `Could not resolve account (${operation.accountId}) in working state.`
+      );
+    }
+    const updatedContacts = [
+      ...(account.alternateContacts ?? []).filter(
+        (c) => c.contactType !== operation.contactType
+      ),
+      {
+        contactType: operation.contactType,
+        name: operation.name,
+        email: operation.email,
+        phone: operation.phone,
+        title: operation.title
+      }
+    ];
+    return upsertAccountInWorkingState({
+      workingState: props.state,
+      account: { ...account, alternateContacts: updatedContacts }
+    });
+  }
+  if (operation.kind === "deleteAlternateContact") {
+    props.logger.log(
+      `Deleting ${operation.contactType} alternate contact for "${operation.accountName}" (${operation.accountId})...`
+    );
+    await props.accountClient.send(
+      new DeleteAlternateContactCommand({
+        AccountId: operation.accountId,
+        AlternateContactType: operation.contactType
+      })
+    );
+    props.logger.log(`Done: removed ${operation.contactType} contact for "${operation.accountName}"`);
+    const account = props.state.organization.accountsById[operation.accountId];
+    if (account == null) {
+      throw new Error(
+        `Could not resolve account (${operation.accountId}) in working state.`
+      );
+    }
+    return upsertAccountInWorkingState({
+      workingState: props.state,
+      account: {
+        ...account,
+        alternateContacts: (account.alternateContacts ?? []).filter(
+          (c) => c.contactType !== operation.contactType
+        )
+      }
+    });
+  }
+  if (operation.kind === "setIdcAccessControlAttributes") {
+    props.logger.log(
+      `Setting IdC access control attributes (${operation.attributes.length} attribute(s))...`
+    );
+    await props.ssoAdminClient.send(
+      new UpdateInstanceAccessControlAttributeConfigurationCommand({
+        InstanceArn: props.state.identityCenter.instanceArn,
+        InstanceAccessControlAttributeConfiguration: {
+          AccessControlAttributes: operation.attributes.map((attr) => ({
+            Key: attr.key,
+            Value: { Source: attr.source }
+          }))
+        }
+      })
+    );
+    props.logger.log(`Done: access control attributes updated`);
+    return {
+      ...props.state,
+      identityCenter: {
+        ...props.state.identityCenter,
+        accessControlAttributes: operation.attributes
+      }
+    };
+  }
   assertUnreachable(operation, "Unsupported operation kind in apply.");
 }
 function resolveAssignmentDependencies(props) {
@@ -940,6 +1195,16 @@ function resolveGroupByDisplayName(props) {
   }
   return group;
 }
+function resolvePolicyId(props) {
+  if (props.policyId !== "__pending_creation__") return props.policyId;
+  const policy = props.state.organization.policiesByName[props.policyName];
+  if (policy == null) {
+    throw new Error(
+      `Could not resolve policy "${props.policyName}" in working state.`
+    );
+  }
+  return policy.id;
+}
 function resolvePermissionSetByName(props) {
   const permissionSet = props.state.identityCenter.permissionSetsByName[props.permissionSetName];
   if (permissionSet == null) {
@@ -959,9 +1224,9 @@ function upsertPermissionSetPolicyState(props) {
     workingState: props.state,
     permissionSet: {
       ...nextPermissionSet,
-      awsManagedPolicies: [...new Set(nextPermissionSet.awsManagedPolicies)].sort(
-        (left, right) => left.localeCompare(right)
-      ),
+      awsManagedPolicies: [
+        ...new Set(nextPermissionSet.awsManagedPolicies)
+      ].sort((left, right) => left.localeCompare(right)),
       customerManagedPolicies: [
         ...nextPermissionSet.customerManagedPolicies
       ].sort((left, right) => {
@@ -992,11 +1257,13 @@ async function assertOrganizationalUnitIsEmpty(props) {
   });
   if (childOrganizationalUnit != null) {
     throw new Error(
-      `Refusing to delete OU "${props.organizationalUnitName}": live AWS preflight failed [child-ou-present]: ${formatLivePreflightResource({
-        resourceType: "child OU",
-        name: childOrganizationalUnit.Name,
-        id: childOrganizationalUnit.Id
-      })} is still attached.`
+      `Refusing to delete OU "${props.organizationalUnitName}": live AWS preflight failed [child-ou-present]: ${formatLivePreflightResource(
+        {
+          resourceType: "child OU",
+          name: childOrganizationalUnit.Name,
+          id: childOrganizationalUnit.Id
+        }
+      )} is still attached.`
     );
   }
   const account = await listFirstAccountForParent({
@@ -1005,11 +1272,13 @@ async function assertOrganizationalUnitIsEmpty(props) {
   });
   if (account != null) {
     throw new Error(
-      `Refusing to delete OU "${props.organizationalUnitName}": live AWS preflight failed [account-present]: ${formatLivePreflightResource({
-        resourceType: "account",
-        name: account.Name,
-        id: account.Id
-      })} is still attached.`
+      `Refusing to delete OU "${props.organizationalUnitName}": live AWS preflight failed [account-present]: ${formatLivePreflightResource(
+        {
+          resourceType: "account",
+          name: account.Name,
+          id: account.Id
+        }
+      )} is still attached.`
     );
   }
 }