@fjall/components-infrastructure 2.23.0 → 2.24.0

package/dist/lib/config/aws/identityCenter.d.ts

@@ -1,28 +1,40 @@
 import { type Construct } from "constructs";
 import { NestedStack, type NestedStackProps } from "aws-cdk-lib";
 import { type KeyValue } from "../../types.js";
+import { type IdentityCentreConfig } from "./identityCentreConfig.js";
 interface IdentityCenterProps extends NestedStackProps {
+    /** Workload accounts (management excluded by the Organisation construct). */
     accounts: KeyValue;
+    /** Required only when a permission set opts into the management account. */
+    managementAccountId?: string;
+    config?: IdentityCentreConfig;
     tags?: KeyValue[];
 }
-export interface PermissionSetConfig {
-    managedPolicies: string[];
-    description?: string;
-    sessionDuration?: string;
-}
-export type CustomPermissionSets = Record<string, PermissionSetConfig>;
 export declare class IdentityCenter extends NestedStack {
     identityStoreId: string;
     identityCenterArn: string;
     private listInstancesRole;
     private accountsConfig;
     private customTags?;
+    private readonly config?;
+    private readonly managementAccountId?;
+    private groupConstructs;
     private groupIds;
+    private declaredUsers;
+    private lookupUserIds;
     constructor(scope: Construct, id: string, props: IdentityCenterProps);
-    declarePermissionSets(customs: CustomPermissionSets): void;
-    assignGroupMembers(members: Record<string, string[]>): void;
     private createListInstancesRole;
     private listIdentityCenterInstance;
+    private createGroup;
+    private createDeclaredUsers;
+    /** Maps the shared name derivation to account ids. Only the appended
+     * "management" pseudo-account lacks an ACCOUNTS entry. */
+    private resolveTargetAccounts;
     private createPermissionSetAndAssignments;
+    private createMemberships;
+    /** One lookup CR per email, shared across groups. `resolutionVersion` is
+     * baked into the physical id so bumping it re-runs every resolution —
+     * the UUID-rotation heal (`fjall user rebind`). */
+    private lookupUserId;
 }
 export {};

package/dist/lib/config/aws/identityCenter.js

@@ -1,83 +1,60 @@
+import { createHash } from "node:crypto";
 import * as customResources from "aws-cdk-lib/custom-resources";
 import { PolicyDocument, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
-import { CfnOutput, NestedStack } from "aws-cdk-lib";
+import { Annotations, CfnOutput, NestedStack } from "aws-cdk-lib";
 import { AwsCustomResource } from "../../resources/aws/utilities/awsCustomResource.js";
-import { stripAndCamelCase } from "../../utils/stripAndCamelCase.js";
-import { Group, PermissionSet, Assignment } from "../../resources/aws/iam/identityCenter/index.js";
+import { Group, GroupMembership, PermissionSet, Assignment, IdentityStoreUser, IdentityStoreUserProvider, identityStoreUserArnPattern } from "../../resources/aws/iam/identityCenter/index.js";
 import { ManagedPolicy, Role } from "../../resources/aws/iam/index.js";
-import { IdentityCenterMembership } from "./identityCenterMembership.js";
-const defaultPermissionSets = {
-    AdministratorAccess: {
-        Policy: "arn:aws:iam::aws:policy/AdministratorAccess",
-        Description: "Permission set for associated AdministratorAccess policy"
-    },
-    ReadOnlyAccess: {
-        Policy: "arn:aws:iam::aws:policy/ReadOnlyAccess",
-        Description: "Permission set for associated ReadOnlyAccess policy"
-    },
-    Billing: {
-        Policy: "arn:aws:iam::aws:policy/AWSBillingReadOnlyAccess",
-        Description: "Permission set for associated Billing policy"
-    }
-};
+import { allGroupNames, assignmentConstructId, boundGroupsForSet, effectivePermissionSets, implicitGroupNames, resolveTargetAccountNames, validateIdentityCentreConfig } from "./identityCentreConfig.js";
 // CreateAccountAssignment has a 15-outstanding-async limit. Batching at 8
 // keeps headroom for CFN's internal retries within the same backoff window.
 const ASSIGNMENT_BATCH_SIZE = 8;
+/** 8-char content hash — construct-id suffix safe for any email (full address,
+ * so same-local-part addresses at different domains never collide). */
+function emailHash(email) {
+    return createHash("sha256").update(email).digest("hex").slice(0, 8);
+}
 export class IdentityCenter extends NestedStack {
     identityStoreId;
     identityCenterArn;
     listInstancesRole;
     accountsConfig;
     customTags;
+    config;
+    managementAccountId;
+    groupConstructs = {};
     groupIds = {};
+    declaredUsers = {};
+    lookupUserIds = {};
     constructor(scope, id, props) {
         super(scope, id, props);
         this.accountsConfig = props.accounts;
         this.customTags = props.tags;
-        this.createListInstancesRole();
-        this.listIdentityCenterInstance();
-        for (const [name, config] of Object.entries(defaultPermissionSets)) {
-            this.createPermissionSetAndAssignments(name, config, {
-                managedPolicies: [config.Policy]
+        this.config = props.config;
+        this.managementAccountId = props.managementAccountId;
+        if (props.config !== undefined) {
+            const { warnings, infos } = validateIdentityCentreConfig(props.config, {
+                workloadAccountNames: Object.keys(props.accounts)
             });
-        }
-    }
-    declarePermissionSets(customs) {
-        for (const [name, config] of Object.entries(customs)) {
-            if (this.groupIds[name] !== undefined) {
-                throw new Error(`Permission set "${name}" already declared (collision with default or prior declaration)`);
+            for (const warning of warnings) {
+                Annotations.of(this).addWarningV2(`fjall:identity-centre:${warning.code}`, warning.message);
             }
-            const primaryPolicy = config.managedPolicies[0];
-            if (primaryPolicy === undefined) {
-                throw new Error(`Permission set "${name}" must declare at least one managed policy.`);
+            for (const info of infos) {
+                Annotations.of(this).addInfo(info.message);
             }
-            this.createPermissionSetAndAssignments(name, {
-                Policy: primaryPolicy,
-                ...(config.description !== undefined && {
-                    Description: config.description
-                })
-            }, {
-                managedPolicies: config.managedPolicies,
-                ...(config.sessionDuration !== undefined && {
-                    sessionDuration: config.sessionDuration
-                })
-            });
         }
-    }
-    assignGroupMembers(members) {
-        for (const [groupName, emails] of Object.entries(members)) {
-            if (emails.length === 0)
-                continue;
-            const groupId = this.groupIds[groupName];
-            if (groupId === undefined) {
-                throw new Error(`Cannot assign members to undeclared group "${groupName}". Declare via declarePermissionSets() first, or use one of the defaults: AdministratorAccess, ReadOnlyAccess, Billing.`);
-            }
-            new IdentityCenterMembership(this, `${groupName}Members`, {
-                identityStoreId: this.identityStoreId,
-                groupId,
-                groupMembers: emails
-            });
+        this.createListInstancesRole();
+        this.listIdentityCenterInstance();
+        const sets = effectivePermissionSets(this.config);
+        const implicitGroups = new Set(implicitGroupNames(sets));
+        for (const name of allGroupNames(this.config)) {
+            this.createGroup(name, implicitGroups.has(name));
+        }
+        this.createDeclaredUsers();
+        for (const [name, spec] of Object.entries(sets)) {
+            this.createPermissionSetAndAssignments(name, spec);
         }
+        this.createMemberships();
     }
     createListInstancesRole() {
         this.listInstancesRole = new Role(this, "IdentityCenterCustomResourceRole", {
@@ -126,49 +103,181 @@ export class IdentityCenter extends NestedStack {
             exportName: "identityStoreId"
         });
     }
-    createPermissionSetAndAssignments(name, config, permissionSetOverrides) {
+    createGroup(name, isImplicitSetGroup) {
+        const description = this.config?.groups?.[name]?.description ??
+            (isImplicitSetGroup
+                ? `Group for associated ${name} permission set`
+                : "Fjall-managed Identity Centre group");
         const group = new Group(this, `${name}Group`, {
             displayName: name,
             identityStoreId: this.identityStoreId,
-            description: `Group for associated ${name} permission set`
+            description
         });
+        this.groupConstructs[name] = group;
         this.groupIds[name] = group.getGroupId();
+        new CfnOutput(this, `${name}GroupId`, {
+            key: `${name}GroupId`,
+            value: group.getGroupId(),
+            exportName: `${name}GroupId`
+        });
+    }
+    createDeclaredUsers() {
+        const users = this.config !== undefined && "users" in this.config
+            ? (this.config.users ?? {})
+            : {};
+        if (Object.keys(users).length === 0) {
+            return;
+        }
+        const provider = new IdentityStoreUserProvider(this, "UserProvider", {
+            identityStoreId: this.identityStoreId
+        });
+        for (const [email, spec] of Object.entries(users)) {
+            this.declaredUsers[email] = new IdentityStoreUser(this, `User${emailHash(email)}`, {
+                serviceToken: provider.serviceToken,
+                identityStoreId: this.identityStoreId,
+                email,
+                givenName: spec.givenName,
+                familyName: spec.familyName,
+                ...(spec.displayName !== undefined && {
+                    displayName: spec.displayName
+                })
+            });
+        }
+    }
+    /** Maps the shared name derivation to account ids. Only the appended
+     * "management" pseudo-account lacks an ACCOUNTS entry. */
+    resolveTargetAccounts(name, spec) {
+        const targets = [];
+        for (const accountName of resolveTargetAccountNames(spec, Object.keys(this.accountsConfig))) {
+            const accountId = this.accountsConfig[accountName];
+            if (accountId !== undefined) {
+                targets.push([accountName, accountId]);
+                continue;
+            }
+            if (this.managementAccountId === undefined) {
+                throw new Error(`permissionSets["${name}"] sets includeManagementAccount but no managementAccountId was provided to IdentityCenter`);
+            }
+            targets.push([accountName, this.managementAccountId]);
+        }
+        return targets;
+    }
+    createPermissionSetAndAssignments(name, spec) {
+        const boundGroups = boundGroupsForSet(name, spec);
         const permissionSet = new PermissionSet(this, `PermissionSet${name}`, {
             name: name,
             instanceArn: this.identityCenterArn,
-            ...(config.Description !== undefined && {
-                description: config.Description
+            ...(spec.description !== undefined && {
+                description: spec.description
+            }),
+            ...(spec.managedPolicies !== undefined &&
+                spec.managedPolicies.length > 0 && {
+                managedPolicies: spec.managedPolicies
+            }),
+            ...(spec.sessionDuration !== undefined && {
+                sessionDuration: spec.sessionDuration
+            }),
+            ...(spec.inlinePolicy !== undefined && {
+                inlinePolicy: spec.inlinePolicy
+            }),
+            ...(spec.customerManagedPolicies !== undefined &&
+                spec.customerManagedPolicies.length > 0 && {
+                customerManagedPolicies: spec.customerManagedPolicies
             }),
-            managedPolicies: permissionSetOverrides.managedPolicies,
-            ...(permissionSetOverrides.sessionDuration !== undefined && {
-                sessionDuration: permissionSetOverrides.sessionDuration
+            ...(spec.permissionsBoundary !== undefined && {
+                permissionsBoundary: spec.permissionsBoundary
             }),
             ...(this.customTags !== undefined && { tags: this.customTags })
         });
-        permissionSet.node.addDependency(group);
-        new CfnOutput(this, `${name}GroupId`, {
-            key: `${name}GroupId`,
-            value: group.getGroupId(),
-            exportName: `${name}GroupId`
-        });
+        for (const groupName of boundGroups) {
+            const group = this.groupConstructs[groupName];
+            if (group !== undefined) {
+                permissionSet.node.addDependency(group);
+            }
+        }
         const assignments = [];
-        for (const [accountName, accountId] of Object.entries(this.accountsConfig)) {
-            const assignment = new Assignment(this, `${stripAndCamelCase(accountName)}${name}Assignment`, {
-                instanceArn: this.identityCenterArn,
-                permissionSetArn: permissionSet.getPermissionSetArn(),
-                principalType: "GROUP",
-                principalId: group.getGroupId(),
-                targetType: "AWS_ACCOUNT",
-                targetId: accountId
-            });
-            assignment.node.addDependency(permissionSet);
-            if (assignments.length >= ASSIGNMENT_BATCH_SIZE) {
-                const dependency = assignments[assignments.length - ASSIGNMENT_BATCH_SIZE];
-                if (dependency !== undefined) {
-                    assignment.node.addDependency(dependency);
+        for (const [accountName, accountId] of this.resolveTargetAccounts(name, spec)) {
+            for (const groupName of boundGroups) {
+                const idSuffix = assignmentConstructId(accountName, name, groupName);
+                const groupId = this.groupIds[groupName];
+                if (groupId === undefined) {
+                    throw new Error(`Internal: group "${groupName}" missing for permission set "${name}" — validation should have caught this`);
                 }
+                const assignment = new Assignment(this, idSuffix, {
+                    instanceArn: this.identityCenterArn,
+                    permissionSetArn: permissionSet.getPermissionSetArn(),
+                    principalType: "GROUP",
+                    principalId: groupId,
+                    targetType: "AWS_ACCOUNT",
+                    targetId: accountId
+                });
+                assignment.node.addDependency(permissionSet);
+                if (assignments.length >= ASSIGNMENT_BATCH_SIZE) {
+                    const dependency = assignments[assignments.length - ASSIGNMENT_BATCH_SIZE];
+                    if (dependency !== undefined) {
+                        assignment.node.addDependency(dependency);
+                    }
+                }
+                assignments.push(assignment);
+            }
+        }
+    }
+    createMemberships() {
+        for (const [groupName, emails] of Object.entries(this.config?.memberships ?? {})) {
+            const groupId = this.groupIds[groupName];
+            if (groupId === undefined || emails.length === 0) {
+                continue;
             }
-            assignments.push(assignment);
+            for (const email of emails) {
+                const declared = this.declaredUsers[email];
+                const userId = declared !== undefined ? declared.userId : this.lookupUserId(email);
+                new GroupMembership(this, `${groupName}Membership${emailHash(email)}`, {
+                    identityStoreId: this.identityStoreId,
+                    groupId,
+                    userId
+                });
+            }
+        }
+    }
+    /** One lookup CR per email, shared across groups. `resolutionVersion` is
+     * baked into the physical id so bumping it re-runs every resolution —
+     * the UUID-rotation heal (`fjall user rebind`). */
+    lookupUserId(email) {
+        const existing = this.lookupUserIds[email];
+        if (existing !== undefined) {
+            return existing;
         }
+        const resolutionVersion = this.config?.resolutionVersion ?? 1;
+        const getUserIdCall = {
+            service: "@aws-sdk/client-identitystore",
+            action: "GetUserId",
+            parameters: {
+                IdentityStoreId: this.identityStoreId,
+                AlternateIdentifier: {
+                    UniqueAttribute: {
+                        AttributePath: "emails.value",
+                        AttributeValue: email
+                    }
+                }
+            },
+            physicalResourceId: customResources.PhysicalResourceId.of(`fjallGetUserId:${email}:v${resolutionVersion}`)
+        };
+        const identityStoreArn = `arn:${this.partition}:identitystore::${this.account}:identitystore/${this.identityStoreId}`;
+        const lookup = new AwsCustomResource(this, `UserLookup${emailHash(email)}`, {
+            onCreate: getUserIdCall,
+            onUpdate: getUserIdCall,
+            resourceType: "Custom::FjallIdentityStoreUserLookup",
+            policy: customResources.AwsCustomResourcePolicy.fromStatements([
+                new PolicyStatement({
+                    actions: ["identitystore:GetUserId"],
+                    resources: [
+                        identityStoreArn,
+                        identityStoreUserArnPattern(this.partition)
+                    ]
+                })
+            ])
+        });
+        const userId = lookup.getResponseField("UserId");
+        this.lookupUserIds[email] = userId;
+        return userId;
     }
 }

package/dist/lib/config/aws/identityCentreConfig.d.ts

@@ -0,0 +1,147 @@
+import { type DefaultPermissionSetName } from "@fjall/generator";
+/**
+ * Customer-facing `identityCentre` configuration for the Organisation
+ * construct. The discriminated union on `source` mirrors AWS ground truth:
+ * the identity source of an Identity Center instance is neither readable nor
+ * settable via any supported API, so the mode is user-declared and
+ * authoritative. Design: aiDocs/designs/2026-07-04-org-user-management-design.md
+ *
+ * The source vocabulary is canonical in @fjall/generator
+ * (organisationSchemas.ts) — re-exported here so existing consumers keep
+ * their import path.
+ */
+export { IDENTITY_CENTRE_SOURCES, type IdentityCentreSource } from "@fjall/generator";
+export interface IdentityCentreUserSpec {
+    givenName: string;
+    familyName: string;
+    /** Defaults to `${givenName} ${familyName}`. */
+    displayName?: string;
+    /**
+     * ISO date (e.g. "2026-09-30"). A past-expiry user still holding any
+     * membership fails synth, naming the user and the groups to detach.
+     */
+    expires?: string;
+}
+export interface CustomerManagedPolicyRef {
+    name: string;
+    path?: string;
+}
+export type PermissionsBoundarySpec = {
+    managedPolicyArn: string;
+} | {
+    customerManagedPolicy: CustomerManagedPolicyRef;
+};
+export interface PermissionSetSpec {
+    managedPolicies?: string[];
+    /** Raw IAM policy document (escape hatch — passed through to CFN verbatim). */
+    inlinePolicy?: Record<string, unknown>;
+    customerManagedPolicies?: CustomerManagedPolicyRef[];
+    permissionsBoundary?: PermissionsBoundarySpec;
+    /** ISO-8601 duration, e.g. "PT12H". */
+    sessionDuration?: string;
+    description?: string;
+    /**
+     * ACCOUNTS-map names this set is assigned to. Default "all" (every
+     * workload account). The management account is reachable only via
+     * `includeManagementAccount`.
+     */
+    accounts?: string[] | "all";
+    /** Management-account opt-in — the only route to it. Default false. */
+    includeManagementAccount?: boolean;
+    /**
+     * Groups bound to this set (many-to-many). Omitted or empty = an implicit
+     * same-named group is created and bound.
+     */
+    groups?: string[];
+}
+export interface IdentityCentreGroupSpec {
+    description?: string;
+}
+interface IdentityCentreBase {
+    /** Custom groups beyond the per-set implicit ones. */
+    groups?: Record<string, IdentityCentreGroupSpec>;
+    /**
+     * Custom permission sets. An entry named after a built-in default merges
+     * over that default's spec (tune sessionDuration/accounts/groups of a
+     * built-in without restating its policy).
+     */
+    permissionSets?: Record<string, PermissionSetSpec>;
+    /** Group name -> member emails. */
+    memberships?: Record<string, string[]>;
+    /**
+     * Bump to force every external email lookup to re-resolve — heals
+     * memberships after an IdP deletes and recreates a user (UUID rotation).
+     * Default 1.
+     */
+    resolutionVersion?: number;
+    /** false suppresses the three built-in permission sets. Default true. */
+    defaultPermissionSets?: boolean;
+}
+export type IdentityCentreConfig = (IdentityCentreBase & {
+    source: "fjall-managed";
+    users: Record<string, IdentityCentreUserSpec>;
+}) | (IdentityCentreBase & {
+    source: "external";
+    users?: never;
+}) | (IdentityCentreBase & {
+    source: "external-manual";
+    users?: Record<string, IdentityCentreUserSpec>;
+});
+export interface DefaultPermissionSetDefinition {
+    managedPolicyArn: string;
+    description: string;
+}
+export declare const DEFAULT_PERMISSION_SETS: Record<DefaultPermissionSetName, DefaultPermissionSetDefinition>;
+export interface ResolvedPermissionSet extends PermissionSetSpec {
+    isDefault: boolean;
+}
+/**
+ * Defaults (unless suppressed) with same-named config entries merged over
+ * them, plus the remaining custom sets. Consumed by both the validator and
+ * the IdentityCenter construct — the two MUST agree on this derivation.
+ */
+export declare function effectivePermissionSets(config?: IdentityCentreConfig): Record<string, ResolvedPermissionSet>;
+/**
+ * Canonical names of the accounts a permission set is assigned to, in
+ * declaration order: explicit `accounts` entries resolve case-insensitively
+ * to the workload ACCOUNTS names (unknown entries drop out — Rule 4 reports
+ * them), otherwise every workload account; the management opt-in appends the
+ * "management" pseudo-account. Duplicate entries are preserved so the
+ * validator's duplicate-declaration detection still fires. Consumed by both
+ * the validator (Rule 8 collision detection) and the IdentityCenter
+ * construct — the two MUST agree on this derivation.
+ */
+export declare function resolveTargetAccountNames(spec: PermissionSetSpec, workloadAccountNames: readonly string[]): string[];
+/** Groups bound to a set: explicit list, else the implicit same-named group. */
+export declare function boundGroupsForSet(name: string, spec: PermissionSetSpec): string[];
+export declare function implicitGroupNames(sets: Record<string, ResolvedPermissionSet>): string[];
+/**
+ * Assignment construct-id derivation shared by the validator (collision
+ * detection) and the IdentityCenter construct — the two MUST agree. The
+ * implicit same-named group omits the group segment to keep the legacy id
+ * shape, so existing deployments do not replace their assignments.
+ */
+export declare function assignmentConstructId(accountName: string, setName: string, groupName: string): string;
+/** Every group the config will create: implicit per-set groups + custom groups. */
+export declare function allGroupNames(config?: IdentityCentreConfig): string[];
+export interface IdentityCentreValidationIssue {
+    code: string;
+    message: string;
+}
+export interface IdentityCentreValidationResult {
+    warnings: IdentityCentreValidationIssue[];
+    infos: IdentityCentreValidationIssue[];
+}
+export interface IdentityCentreValidationContext {
+    /** Workload account names from the ACCOUNTS map (management excluded). */
+    workloadAccountNames: string[];
+    /** Injectable clock for expiry checks; defaults to the wall clock. */
+    now?: Date;
+}
+/**
+ * Synth-time validation — every rule fires before any CloudFormation call so
+ * a typo never surfaces as a mid-deploy custom-resource failure. Collects
+ * every violation and throws once; warnings/infos are returned for the
+ * construct to surface via CDK Annotations.
+ */
+export declare function validateIdentityCentreConfig(config: IdentityCentreConfig, context: IdentityCentreValidationContext): IdentityCentreValidationResult;