sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IAM/ Group.ts

import * as iam from "@distilled.cloud/aws/iam";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { parsePolicyDocument, stringifyPolicyDocument } from "./common.ts";
import type { PolicyDocument } from "./Policy.ts";

export interface GroupProps {
  /**
   * Group name. If omitted, a deterministic name is generated.
   */
  groupName?: string;
  /**
   * Optional IAM path prefix.
   * @default "/"
   */
  path?: string;
  /**
   * Managed policy ARNs attached to the group.
   */
  managedPolicyArns?: string[];
  /**
   * Inline policies embedded in the group.
   */
  inlinePolicies?: Record<string, PolicyDocument>;
}

export interface Group extends Resource<
  "AWS.IAM.Group",
  GroupProps,
  {
    /** The ARN of the group. */
    groupArn: string;
    /** The name of the group. */
    groupName: string;
    /** The stable unique ID of the group. */
    groupId: string | undefined;
    /** The IAM path of the group. */
    path: string | undefined;
    /** Managed policy ARNs attached to the group. */
    managedPolicyArns: string[];
    /** Inline policies embedded in the group, keyed by policy name. */
    inlinePolicies: Record<string, PolicyDocument>;
  },
  never,
  Providers
> {}

/**
 * An IAM group that can own managed and inline policies.
 *
 * `Group` manages a shared authorization container for IAM users, including
 * attached managed policies and embedded inline policies.
 * ### Creating IAM Groups
 * **Example:** Group with an Inline Policy
 * ```typescript
 * const group = yield* Group("SupportGroup", {
 *   groupName: "support",
 *   inlinePolicies: {
 *     SupportReadOnly: {
 *       Version: "2012-10-17",
 *       Statement: [{
 *         Effect: "Allow",
 *         Action: ["cloudwatch:Get*", "cloudwatch:List*"],
 *         Resource: ["*"],
 *       }],
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Group = Resource<Group>("AWS.IAM.Group");

export const GroupProvider = () =>
  Provider.effect(
    Group,
    Effect.gen(function* () {
      const toName = (id: string, props: GroupProps) =>
        props.groupName
          ? Effect.succeed(props.groupName)
          : createPhysicalName({ id, maxLength: 128 });

      const readInlinePolicies = Effect.fn(function* (groupName: string) {
        const policyNames = yield* iam.listGroupPolicies.items({ GroupName: groupName }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
        const entries = yield* Effect.forEach(policyNames, (policyName) =>
          iam
            .getGroupPolicy({
              GroupName: groupName,
              PolicyName: policyName,
            })
            .pipe(
              Effect.map(
                (response) => [policyName, parsePolicyDocument(response.PolicyDocument)] as const,
              ),
              Effect.catchTag("NoSuchEntityException", () =>
                Effect.succeed([policyName, undefined] as const),
              ),
            ),
        );
        return Object.fromEntries(
          entries.filter((entry): entry is [string, PolicyDocument] => entry[1] !== undefined),
        );
      });

      const readManagedPolicies = Effect.fn(function* (groupName: string) {
        const attached = yield* iam.listAttachedGroupPolicies.items({ GroupName: groupName }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
        return attached
          .map((policy) => policy.PolicyArn)
          .filter((policyArn): policyArn is string => typeof policyArn === "string");
      });

      const syncManagedPolicies = Effect.fn(function* ({
        groupName,
        olds,
        news,
      }: {
        groupName: string;
        olds: string[];
        news: string[];
      }) {
        const oldSet = new Set(olds);
        const newSet = new Set(news);
        for (const policyArn of news) {
          if (!oldSet.has(policyArn)) {
            yield* iam.attachGroupPolicy({
              GroupName: groupName,
              PolicyArn: policyArn,
            });
          }
        }
        for (const policyArn of olds) {
          if (!newSet.has(policyArn)) {
            yield* iam
              .detachGroupPolicy({
                GroupName: groupName,
                PolicyArn: policyArn,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
          }
        }
      });

      const syncInlinePolicies = Effect.fn(function* ({
        groupName,
        olds,
        news,
      }: {
        groupName: string;
        olds: Record<string, PolicyDocument>;
        news: Record<string, PolicyDocument>;
      }) {
        for (const [policyName, document] of Object.entries(news)) {
          if (JSON.stringify(olds[policyName] ?? null) !== JSON.stringify(document)) {
            yield* iam.putGroupPolicy({
              GroupName: groupName,
              PolicyName: policyName,
              PolicyDocument: stringifyPolicyDocument(document),
            });
          }
        }
        for (const policyName of Object.keys(olds)) {
          if (!(policyName in news)) {
            yield* iam
              .deleteGroupPolicy({
                GroupName: groupName,
                PolicyName: policyName,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
          }
        }
      });

      return {
        stables: ["groupArn", "groupName", "groupId"],
        // IAM is global (no region). Enumerate every group via the paginated
        // `listGroups`, then hydrate each into the full `read` Attributes shape
        // by reading its attached managed policies and embedded inline policies.
        list: () =>
          Effect.gen(function* () {
            const groups = yield* iam.listGroups.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Groups ?? [])),
            );
            const hydrated = yield* Effect.forEach(
              groups,
              (group) =>
                Effect.gen(function* () {
                  const [managedPolicyArns, inlinePolicies] = yield* Effect.all([
                    readManagedPolicies(group.GroupName),
                    readInlinePolicies(group.GroupName),
                  ]);
                  return {
                    groupArn: group.Arn,
                    groupName: group.GroupName,
                    groupId: group.GroupId,
                    path: group.Path,
                    managedPolicyArns,
                    inlinePolicies,
                  };
                }).pipe(
                  // A group can be deleted between `listGroups` and this
                  // per-group hydration (e.g. a sibling test tearing its group
                  // down) — `NoSuchEntityException` here just means it's gone,
                  // so drop it rather than failing the whole enumeration.
                  Effect.catchTag("NoSuchEntityException", () => Effect.undefined),
                ),
              { concurrency: 10 },
            );
            return hydrated.filter((g) => g !== undefined);
          }),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? ({} as GroupProps))) !== (yield* toName(id, news))) {
            return { action: "replace" } as const;
          }
          if ((olds?.path ?? "/") !== (news.path ?? "/")) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const groupName = output?.groupName ?? (yield* toName(id, olds ?? ({} as GroupProps)));
          const response = yield* iam
            .getGroup({
              GroupName: groupName,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));
          if (!response?.Group?.Arn) {
            return undefined;
          }
          const [managedPolicyArns, inlinePolicies] = yield* Effect.all([
            readManagedPolicies(groupName),
            readInlinePolicies(groupName),
          ]);
          return {
            groupArn: response.Group.Arn,
            groupName: response.Group.GroupName,
            groupId: response.Group.GroupId,
            path: response.Group.Path,
            managedPolicyArns,
            inlinePolicies,
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const groupName = output?.groupName ?? (yield* toName(id, news));

          // Observe — fetch the live group. `getGroup` returns
          // `NoSuchEntityException` when the group has not been created or
          // was deleted out-of-band, in which case we fall through to the
          // ensure step below.
          let observed = yield* iam
            .getGroup({ GroupName: groupName })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));

          // Ensure — create the group when it is missing. A concurrent
          // peer reconciler may win the race, so tolerate
          // `EntityAlreadyExistsException` and reload.
          if (!observed?.Group?.Arn) {
            observed = yield* iam
              .createGroup({
                GroupName: groupName,
                Path: news.path,
              })
              .pipe(
                Effect.catchTag("EntityAlreadyExistsException", () =>
                  iam.getGroup({ GroupName: groupName }),
                ),
                Effect.map((response) => ({
                  Group: response.Group,
                  Users: [],
                  IsTruncated: false,
                })),
              );
          }

          // Sync — for each mutable aspect, diff observed against desired
          // and apply only the delta. We trust the cloud as the source of
          // truth instead of relying on `olds`.
          const [observedManagedPolicies, observedInlinePolicies] = yield* Effect.all([
            readManagedPolicies(groupName),
            readInlinePolicies(groupName),
          ]);

          yield* syncManagedPolicies({
            groupName,
            olds: observedManagedPolicies,
            news: news.managedPolicyArns ?? [],
          });
          yield* syncInlinePolicies({
            groupName,
            olds: observedInlinePolicies,
            news: news.inlinePolicies ?? {},
          });

          const groupArn = observed.Group?.Arn ?? groupName;
          yield* session.note(groupArn);
          return {
            groupArn,
            groupName,
            groupId: observed.Group?.GroupId,
            path: observed.Group?.Path ?? news.path ?? "/",
            managedPolicyArns: news.managedPolicyArns ?? [],
            inlinePolicies: news.inlinePolicies ?? {},
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* iam.getGroup.items({ GroupName: output.groupName }).pipe(
            Stream.mapEffect((user) =>
              user.UserName
                ? iam
                    .removeUserFromGroup({
                      GroupName: output.groupName,
                      UserName: user.UserName,
                    })
                    .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void))
                : Effect.void,
            ),
            Stream.runDrain,
            // The group itself may already be gone.
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );
          yield* iam.listGroupPolicies.items({ GroupName: output.groupName }).pipe(
            Stream.mapEffect((policyName) =>
              iam
                .deleteGroupPolicy({
                  GroupName: output.groupName,
                  PolicyName: policyName,
                })
                .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
            ),
            Stream.runDrain,
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );
          yield* iam.listAttachedGroupPolicies.items({ GroupName: output.groupName }).pipe(
            Stream.mapEffect((policy) =>
              policy.PolicyArn
                ? iam
                    .detachGroupPolicy({
                      GroupName: output.groupName,
                      PolicyArn: policy.PolicyArn,
                    })
                    .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void))
                : Effect.void,
            ),
            Stream.runDrain,
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );
          yield* iam
            .deleteGroup({
              GroupName: output.groupName,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
        }),
      };
    }),
  );