sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Organizations/ TenantRoot.ts

import * as organizations from "@distilled.cloud/aws/organizations";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { ServiceControlPolicyDocument } from "../IAM/Policy.ts";
import * as IdentityCenter from "../IdentityCenter/index.ts";
import type { Account, AccountProps } from "./Account.ts";
import { Account as OrganizationAccount } from "./Account.ts";
import type { DelegatedAdministrator } from "./DelegatedAdministrator.ts";
import { DelegatedAdministrator as OrganizationsDelegatedAdministrator } from "./DelegatedAdministrator.ts";
import type { Organization, OrganizationProps } from "./Organization.ts";
import { Organization as AwsOrganization } from "./Organization.ts";
import type { OrganizationalUnit, OrganizationalUnitProps } from "./OrganizationalUnit.ts";
import { OrganizationalUnit as AwsOrganizationalUnit } from "./OrganizationalUnit.ts";
import type { Policy } from "./Policy.ts";
import { Policy as OrganizationsPolicy } from "./Policy.ts";
import type { PolicyAttachment } from "./PolicyAttachment.ts";
import { PolicyAttachment as OrganizationsPolicyAttachment } from "./PolicyAttachment.ts";
import type { Root, RootProps } from "./Root.ts";
import { Root as OrganizationRoot } from "./Root.ts";
import type { RootPolicyType } from "./RootPolicyType.ts";
import { RootPolicyType as OrganizationsRootPolicyType } from "./RootPolicyType.ts";
import type { TrustedServiceAccess } from "./TrustedServiceAccess.ts";
import { TrustedServiceAccess as OrganizationsTrustedServiceAccess } from "./TrustedServiceAccess.ts";

export class TenantRootInvalidProps extends Data.TaggedError("TenantRootInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type TenantTargetKey = string;

export interface TenantAccountSpec extends Omit<AccountProps, "parentId" | "name" | "email"> {
  /** Stable key identifying the account within the tenant (used in logical IDs and `targetKeys`). */
  key: string;
  /** Friendly account name. */
  name: string;
  /** Globally unique email address for the account. */
  email: string;
}

export interface TenantOrganizationalUnitSpec extends Omit<
  OrganizationalUnitProps,
  "parentId" | "name"
> {
  /** Stable key identifying the OU within the tenant (used in logical IDs and `targetKeys`). */
  key: string;
  /**
   * OU name.
   * @default the spec `key`
   */
  name?: string;
  /** Member accounts vended directly under this OU. */
  accounts?: TenantAccountSpec[];
  /** Nested child OUs. */
  children?: TenantOrganizationalUnitSpec[];
}

export interface TenantPolicySpec {
  /** Stable key identifying the policy within the tenant. */
  key: string;
  /** Policy name. If omitted, Alchemy generates one. */
  name?: string;
  /** Policy description. */
  description?: string;
  /**
   * Organizations policy type.
   * @default "SERVICE_CONTROL_POLICY"
   */
  type?: organizations.PolicyType;
  /**
   * Policy content — a typed {@link ServiceControlPolicyDocument} for
   * SCP/RCP policies, or a raw JSON `string` for other policy types
   * (tag, backup, ...) and as the escape hatch.
   */
  document: ServiceControlPolicyDocument | string;
  /** Keys of the roots/OUs/accounts to attach the policy to (`"root"` or a spec key). */
  targetKeys: TenantTargetKey[];
  /** Tags applied to the policy, merged with tenant-wide tags. */
  tags?: Record<string, string>;
}

export interface TenantIdentityCenterGroupSpec {
  /** Stable key identifying the group within the tenant. */
  key: string;
  /** Display name of the Identity Center group. */
  displayName: string;
  /** Group description. */
  description?: string;
}

export interface TenantIdentityCenterPermissionSetSpec {
  /** Stable key identifying the permission set within the tenant. */
  key: string;
  /** Name of the permission set. */
  name: string;
  /** Permission set description. */
  description?: string;
  /**
   * Optional session duration, e.g. `"8 hours"` or `Duration.hours(8)`.
   * Sent to Identity Center as an ISO-8601 string such as `PT8H` (a bare
   * number is milliseconds).
   */
  sessionDuration?: Duration.Input;
  /** URL the user lands on after federating into the account. */
  relayState?: string;
}

export interface TenantIdentityCenterAssignmentSpec {
  /** Stable key for the assignment. Defaults to a key derived from the other fields. */
  key?: string;
  /** Key of the permission set to assign. */
  permissionSetKey: string;
  /** Key of the account the principal is granted access to. */
  accountKey: string;
  /**
   * Kind of principal being assigned.
   * @default "GROUP"
   */
  principalType?: "USER" | "GROUP";
  /** Key of the Identity Center group to assign (when `principalType` is `GROUP`). */
  groupKey?: string;
  /** Explicit principal ID (e.g. an existing user) instead of a group key. */
  principalId?: string;
}

export interface TenantIdentityCenterSpec {
  /**
   * Whether to adopt the org's existing Identity Center instance
   * (`existing`) or create an account instance (`account`).
   * @default "existing"
   */
  mode?: "existing" | "account";
  /** ARN of an existing Identity Center instance to use explicitly. */
  instanceArn?: string;
  /** Name for the Identity Center instance. */
  name?: string;
  /** Account key to register as the Identity Center delegated administrator. */
  delegatedAdminAccountKey?: string;
  /** Identity Center groups to create. */
  groups?: TenantIdentityCenterGroupSpec[];
  /** Permission sets to create. */
  permissionSets?: TenantIdentityCenterPermissionSetSpec[];
  /** Account assignments binding groups/users to permission sets. */
  assignments?: TenantIdentityCenterAssignmentSpec[];
}

export interface TenantRootProps {
  /** Organization settings (feature set). Defaults to `featureSet: "ALL"`. */
  organization?: OrganizationProps;
  /** Root import settings (explicit root ID, tags). */
  root?: RootProps;
  /**
   * Policy types to enable on the root.
   * @default ["SERVICE_CONTROL_POLICY"]
   */
  policyTypes?: organizations.PolicyType[];
  /** Service principals granted trusted access (Identity Center's is added automatically). */
  trustedServicePrincipals?: string[];
  /** OU tree to create under the root. Defaults to a security/infrastructure/workloads baseline. */
  organizationalUnits?: TenantOrganizationalUnitSpec[];
  /** Organizations policies to create and attach via `targetKeys`. */
  policies?: TenantPolicySpec[];
  /** IAM Identity Center groups, permission sets, and assignments. */
  identityCenter?: TenantIdentityCenterSpec;
  /** Tags applied to every taggable resource in the tenant. */
  tags?: Record<string, string>;
}

export interface TenantRootResult {
  organization: Organization;
  root: Root;
  policyTypes: RootPolicyType[];
  trustedServiceAccess: TrustedServiceAccess[];
  delegatedAdministrators: DelegatedAdministrator[];
  organizationalUnits: Record<string, OrganizationalUnit>;
  accounts: Record<string, Account>;
  policies: Record<string, Policy>;
  policyAttachments: PolicyAttachment[];
  identityCenter?: {
    instance: IdentityCenter.Instance;
    groups: Record<string, IdentityCenter.Group>;
    permissionSets: Record<string, IdentityCenter.PermissionSet>;
    assignments: Record<string, IdentityCenter.AccountAssignment>;
  };
}

const defaultTenantOrganizationalUnits = (): TenantOrganizationalUnitSpec[] => [
  {
    key: "security",
    name: "security",
    accounts: [
      {
        key: "security",
        name: "security",
        email: "security@example.com",
      },
      {
        key: "log-archive",
        name: "log-archive",
        email: "log-archive@example.com",
      },
    ],
  },
  {
    key: "infrastructure",
    name: "infrastructure",
    accounts: [
      {
        key: "shared-services",
        name: "shared-services",
        email: "shared-services@example.com",
      },
    ],
  },
  {
    key: "workloads",
    name: "workloads",
    accounts: [
      {
        key: "prod",
        name: "prod",
        email: "prod@example.com",
      },
    ],
  },
];

const toLogicalIdSegment = (value: string) =>
  value
    .split(/[^A-Za-z0-9]+/)
    .filter(Boolean)
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
    .join("");

/**
 * Compose an opinionated single-tenant landing zone inside the current AWS
 * Organizations management account.
 *
 * This helper intentionally stays aligned to native AWS semantics:
 * one real Organization, one root, nested OUs, and accounts beneath that
 * tenant root. The broader `RootRoot` concept is an Alchemy control-plane
 * abstraction over many such tenant roots deployed into separate management
 * accounts, not a nested AWS Organizations feature.
 * ### Creating A Tenant Root
 * **Example:** Tenant With Baseline Accounts
 * ```typescript
 * const tenant = yield* TenantRoot("CustomerA", {
 *   identityCenter: {
 *     mode: "existing",
 *     groups: [
 *       { key: "platform", displayName: "platform-engineers" },
 *     ],
 *     permissionSets: [
 *       {
 *         key: "admin",
 *         name: "AdministratorAccess",
 *         sessionDuration: "8 hours",
 *       },
 *     ],
 *     assignments: [
 *       {
 *         permissionSetKey: "admin",
 *         groupKey: "platform",
 *         accountKey: "prod",
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const TenantRoot = Effect.fn(function* (id: string, props: TenantRootProps = {}) {
  const sharedTags = props.tags ?? {};
  const organization = yield* AwsOrganization(`${id}Organization`, {
    featureSet: "ALL",
    ...props.organization,
  });
  const root = yield* OrganizationRoot(`${id}Root`, {
    ...props.root,
    tags: mergeTags(sharedTags, props.root?.tags),
  });

  const policyTypes = yield* Effect.forEach(
    props.policyTypes ?? ["SERVICE_CONTROL_POLICY"],
    (policyType) =>
      OrganizationsRootPolicyType(`${id}${toLogicalIdSegment(policyType)}PolicyType`, {
        rootId: root.rootId,
        policyType,
      }),
    { concurrency: "unbounded" },
  );

  const trustedServicePrincipals = [
    ...(props.trustedServicePrincipals ?? []),
    ...(props.identityCenter ? ["sso.amazonaws.com"] : []),
  ];
  const trustedServiceAccess = yield* Effect.forEach(
    [...new Set(trustedServicePrincipals)],
    (servicePrincipal) =>
      OrganizationsTrustedServiceAccess(
        `${id}${toLogicalIdSegment(servicePrincipal)}TrustedAccess`,
        { servicePrincipal },
      ),
    { concurrency: "unbounded" },
  );

  const organizationalUnits: Record<string, OrganizationalUnit> = {};
  const accounts: Record<string, Account> = {};
  const targets: Record<TenantTargetKey, { targetId: any }> = {
    root: { targetId: root.rootId as any },
  };

  yield* createOrganizationalUnits({
    id,
    parentId: root.rootId,
    sharedTags,
    specs: props.organizationalUnits ?? defaultTenantOrganizationalUnits(),
    organizationalUnits,
    accounts,
    targets,
  });

  const delegatedAdministrators: DelegatedAdministrator[] = [];
  const identityCenter = props.identityCenter
    ? yield* createTenantIdentityCenter({
        id,
        spec: props.identityCenter,
        accounts,
        sharedTags,
        delegatedAdministrators,
      })
    : undefined;

  const policies: Record<string, Policy> = {};
  const policyAttachments: PolicyAttachment[] = [];
  for (const policySpec of props.policies ?? []) {
    const policy = yield* OrganizationsPolicy(`${id}${toLogicalIdSegment(policySpec.key)}Policy`, {
      name: policySpec.name,
      description: policySpec.description,
      type: policySpec.type ?? "SERVICE_CONTROL_POLICY",
      document: policySpec.document,
      tags: mergeTags(sharedTags, policySpec.tags),
    });
    policies[policySpec.key] = policy;

    for (const targetKey of policySpec.targetKeys) {
      const target = targets[targetKey];
      if (!target) {
        return yield* new TenantRootInvalidProps({
          message: `Unknown tenant policy target '${targetKey}' for policy '${policySpec.key}'`,
        });
      }

      policyAttachments.push(
        yield* OrganizationsPolicyAttachment(
          `${id}${toLogicalIdSegment(policySpec.key)}${toLogicalIdSegment(targetKey)}Attachment`,
          {
            policyId: policy.policyId,
            targetId: target.targetId,
          },
        ),
      );
    }
  }

  return {
    organization,
    root,
    policyTypes,
    trustedServiceAccess,
    delegatedAdministrators,
    organizationalUnits,
    accounts,
    policies,
    policyAttachments,
    identityCenter,
  } satisfies TenantRootResult;
});

const createOrganizationalUnits = ({
  id,
  parentId,
  sharedTags,
  specs,
  organizationalUnits,
  accounts,
  targets,
}: {
  id: string;
  parentId: any;
  sharedTags: Record<string, string>;
  specs: TenantOrganizationalUnitSpec[];
  organizationalUnits: Record<string, OrganizationalUnit>;
  accounts: Record<string, Account>;
  targets: Record<TenantTargetKey, { targetId: any }>;
}): Effect.Effect<void, unknown, unknown> =>
  Effect.gen(function* () {
    for (const spec of specs) {
      const ou = yield* AwsOrganizationalUnit(`${id}${toLogicalIdSegment(spec.key)}Ou`, {
        parentId,
        name: spec.name ?? spec.key,
        tags: mergeTags(sharedTags, spec.tags),
      });
      organizationalUnits[spec.key] = ou;
      targets[spec.key] = { targetId: ou.ouId as any };

      for (const accountSpec of spec.accounts ?? []) {
        const account = yield* OrganizationAccount(
          `${id}${toLogicalIdSegment(accountSpec.key)}Account`,
          {
            ...accountSpec,
            parentId: ou.ouId,
            tags: mergeTags(sharedTags, accountSpec.tags),
          },
        );
        accounts[accountSpec.key] = account;
        targets[accountSpec.key] = { targetId: account.accountId as any };
      }

      if (spec.children?.length) {
        yield* createOrganizationalUnits({
          id,
          parentId: ou.ouId as any,
          sharedTags,
          specs: spec.children,
          organizationalUnits,
          accounts,
          targets,
        });
      }
    }
  });

const createTenantIdentityCenter = Effect.fn(function* ({
  id,
  spec,
  accounts,
  delegatedAdministrators,
}: {
  id: string;
  spec: TenantIdentityCenterSpec;
  accounts: Record<string, Account>;
  sharedTags: Record<string, string>;
  delegatedAdministrators: DelegatedAdministrator[];
}) {
  const instance = yield* IdentityCenter.Instance(`${id}IdentityCenter`, {
    mode: spec.mode ?? "existing",
    instanceArn: spec.instanceArn,
    name: spec.name,
  });

  if (spec.delegatedAdminAccountKey) {
    const account = accounts[spec.delegatedAdminAccountKey];
    if (!account) {
      return yield* new TenantRootInvalidProps({
        message: `Unknown delegated admin account '${spec.delegatedAdminAccountKey}'`,
      });
    }
    delegatedAdministrators.push(
      yield* OrganizationsDelegatedAdministrator(
        `${id}${toLogicalIdSegment(spec.delegatedAdminAccountKey)}IdentityCenterDelegatedAdmin`,
        {
          accountId: account.accountId,
          servicePrincipal: "sso.amazonaws.com",
        },
      ),
    );
  }

  const groups: Record<string, IdentityCenter.Group> = {};
  for (const groupSpec of spec.groups ?? []) {
    groups[groupSpec.key] = yield* IdentityCenter.Group(
      `${id}${toLogicalIdSegment(groupSpec.key)}Group`,
      {
        identityStoreId: instance.identityStoreId,
        displayName: groupSpec.displayName,
        description: groupSpec.description,
      },
    );
  }

  const permissionSets: Record<string, IdentityCenter.PermissionSet> = {};
  for (const permissionSetSpec of spec.permissionSets ?? []) {
    permissionSets[permissionSetSpec.key] = yield* IdentityCenter.PermissionSet(
      `${id}${toLogicalIdSegment(permissionSetSpec.key)}PermissionSet`,
      {
        instanceArn: instance.instanceArn,
        name: permissionSetSpec.name,
        description: permissionSetSpec.description,
        sessionDuration: permissionSetSpec.sessionDuration,
        relayState: permissionSetSpec.relayState,
      },
    );
  }

  const assignments: Record<string, IdentityCenter.AccountAssignment> = {};
  for (const assignmentSpec of spec.assignments ?? []) {
    const account = accounts[assignmentSpec.accountKey];
    if (!account) {
      return yield* new TenantRootInvalidProps({
        message: `Unknown assignment account '${assignmentSpec.accountKey}'`,
      });
    }
    const permissionSet = permissionSets[assignmentSpec.permissionSetKey];
    if (!permissionSet) {
      return yield* new TenantRootInvalidProps({
        message: `Unknown assignment permission set '${assignmentSpec.permissionSetKey}'`,
      });
    }
    const principalId =
      assignmentSpec.groupKey !== undefined
        ? groups[assignmentSpec.groupKey]?.groupId
        : assignmentSpec.principalId;
    if (!principalId) {
      return yield* new TenantRootInvalidProps({
        message: `Unable to resolve principal for assignment '${assignmentSpec.key ?? `${assignmentSpec.permissionSetKey}-${assignmentSpec.accountKey}`}'`,
      });
    }

    const key =
      assignmentSpec.key ??
      `${assignmentSpec.permissionSetKey}-${assignmentSpec.accountKey}-${assignmentSpec.groupKey ?? assignmentSpec.principalId}`;

    assignments[key] = yield* IdentityCenter.AccountAssignment(
      `${id}${toLogicalIdSegment(key)}Assignment`,
      {
        instanceArn: instance.instanceArn,
        permissionSetArn: permissionSet.permissionSetArn,
        principalId,
        principalType: assignmentSpec.groupKey ? "GROUP" : (assignmentSpec.principalType ?? "USER"),
        targetId: account.accountId,
      },
    );
  }

  return {
    instance,
    groups,
    permissionSets,
    assignments,
  };
});

const mergeTags = (shared: Record<string, string>, tags: Record<string, string> | undefined) => ({
  ...shared,
  ...tags,
});