sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IAM/ User.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 { createInternalTags, createTagsList, diffTags, hasTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { parsePolicyDocument, stringifyPolicyDocument, toTagRecord } from "./common.ts";
import type { PolicyDocument } from "./Policy.ts";

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

export interface UserProps {
  /**
   * User name. If omitted, a deterministic name is generated.
   */
  userName?: string;
  /**
   * Optional IAM path prefix.
   * @default "/"
   */
  path?: string;
  /**
   * Optional permissions boundary policy ARN.
   */
  permissionsBoundary?: string;
  /**
   * Managed policy ARNs attached to the user.
   */
  managedPolicyArns?: string[];
  /**
   * Inline policies embedded in the user.
   */
  inlinePolicies?: Record<string, PolicyDocument>;
  /**
   * User-defined tags to apply to the user.
   */
  tags?: Record<string, string>;
}

export interface User extends Resource<
  "AWS.IAM.User",
  UserProps,
  {
    /** The ARN of the user. */
    userArn: string;
    /** The name of the user. */
    userName: string;
    /** The stable unique ID of the user. */
    userId: string | undefined;
    /** The IAM path of the user. */
    path: string | undefined;
    /** The managed policy ARN used as the permissions boundary, if any. */
    permissionsBoundary: string | undefined;
    /** Managed policy ARNs attached to the user. */
    managedPolicyArns: string[];
    /** Inline policies embedded in the user, keyed by policy name. */
    inlinePolicies: Record<string, PolicyDocument>;
    /** The tags applied to the user. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An IAM user with optional inline policies, managed policies, and tags.
 *
 * `User` manages a long-lived IAM identity together with its attached managed
 * policies, inline policies, permissions boundary, and tags.
 * ### Creating IAM Users
 * **Example:** User with Managed Policies
 * ```typescript
 * const user = yield* User("AppUser", {
 *   userName: "app-user",
 *   managedPolicyArns: [
 *     "arn:aws:iam::aws:policy/ReadOnlyAccess",
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const User = Resource<User>("AWS.IAM.User");

export const UserProvider = () =>
  Provider.effect(
    User,
    Effect.gen(function* () {
      const toName = (id: string, props: UserProps) =>
        props.userName ? Effect.succeed(props.userName) : createPhysicalName({ id, maxLength: 64 });

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

      const readInlinePolicies = Effect.fn(function* (userName: string) {
        const policyNames = yield* iam.listUserPolicies.items({ UserName: userName }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
        const entries = yield* Effect.forEach(policyNames, (policyName) =>
          iam
            .getUserPolicy({
              UserName: userName,
              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 readTags = Effect.fn(function* (userName: string) {
        const listed = yield* iam.listUserTags({
          UserName: userName,
        });
        return toTagRecord(listed.Tags);
      });

      const syncManagedPolicies = Effect.fn(function* ({
        userName,
        olds,
        news,
      }: {
        userName: 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.attachUserPolicy({
              UserName: userName,
              PolicyArn: policyArn,
            });
          }
        }
        for (const policyArn of olds) {
          if (!newSet.has(policyArn)) {
            yield* iam
              .detachUserPolicy({
                UserName: userName,
                PolicyArn: policyArn,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
          }
        }
      });

      const syncInlinePolicies = Effect.fn(function* ({
        userName,
        olds,
        news,
      }: {
        userName: 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.putUserPolicy({
              UserName: userName,
              PolicyName: policyName,
              PolicyDocument: stringifyPolicyDocument(document),
            });
          }
        }
        for (const policyName of Object.keys(olds)) {
          if (!(policyName in news)) {
            yield* iam
              .deleteUserPolicy({
                UserName: userName,
                PolicyName: policyName,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
          }
        }
      });

      return {
        stables: ["userArn", "userName", "userId"],
        list: () =>
          Effect.gen(function* () {
            // IAM is global; `listUsers` enumerates every user in the
            // account. Paginate exhaustively, then hydrate each user's
            // managed/inline policies and tags (the list summary omits
            // them) to produce the same Attributes shape `read` returns.
            const users = yield* iam.listUsers.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Users ?? [])),
            );

            const hydrated = yield* Effect.forEach(
              users,
              (user) =>
                Effect.gen(function* () {
                  const [managedPolicyArns, inlinePolicies, tags] = yield* Effect.all([
                    readManagedPolicies(user.UserName),
                    readInlinePolicies(user.UserName),
                    readTags(user.UserName),
                  ]);
                  return {
                    userArn: user.Arn,
                    userName: user.UserName,
                    userId: user.UserId,
                    path: user.Path,
                    permissionsBoundary: user.PermissionsBoundary?.PermissionsBoundaryArn,
                    managedPolicyArns,
                    inlinePolicies,
                    tags,
                  };
                }).pipe(
                  // A user may be deleted concurrently mid-hydration.
                  Effect.catchTag("NoSuchEntityException", () => Effect.undefined),
                ),
              { concurrency: 10 },
            );

            return hydrated.filter(
              (attrs): attrs is NonNullable<typeof attrs> => attrs !== undefined,
            );
          }),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? ({} as UserProps))) !== (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 userName = output?.userName ?? (yield* toName(id, olds ?? ({} as UserProps)));
          const response = yield* iam
            .getUser({
              UserName: userName,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));
          if (!response?.User?.Arn) {
            return undefined;
          }
          const [managedPolicyArns, inlinePolicies, tags] = yield* Effect.all([
            readManagedPolicies(userName),
            readInlinePolicies(userName),
            readTags(userName),
          ]);
          return {
            userArn: response.User.Arn,
            userName: response.User.UserName,
            userId: response.User.UserId,
            path: response.User.Path,
            permissionsBoundary: response.User.PermissionsBoundary?.PermissionsBoundaryArn,
            managedPolicyArns,
            inlinePolicies,
            tags,
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const userName = output?.userName ?? (yield* toName(id, news));
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...news.tags,
          };

          // Observe — read the live user (or absence).
          const observedResponse = yield* iam
            .getUser({ UserName: userName })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));
          let observedUser = observedResponse?.User;

          // Ensure — create the user when missing. On race, verify
          // ownership tags before adopting.
          if (!observedUser?.Arn) {
            const created = yield* iam
              .createUser({
                UserName: userName,
                Path: news.path,
                PermissionsBoundary: news.permissionsBoundary,
                Tags: createTagsList(desiredTags),
              })
              .pipe(
                Effect.catchTag("EntityAlreadyExistsException", () =>
                  iam.getUser({ UserName: userName }).pipe(
                    Effect.filterOrFail(
                      (existing) => hasTags(desiredTags, existing.User?.Tags),
                      () =>
                        new UserConflict({
                          message: `User '${userName}' already exists and is not managed by alchemy`,
                        }),
                    ),
                  ),
                ),
              );
            observedUser = created.User;
          }

          // Sync permissions boundary against observed.
          const observedBoundary = observedUser?.PermissionsBoundary?.PermissionsBoundaryArn;
          if (news.permissionsBoundary !== observedBoundary) {
            if (news.permissionsBoundary) {
              yield* iam.putUserPermissionsBoundary({
                UserName: userName,
                PermissionsBoundary: news.permissionsBoundary,
              });
            } else if (observedBoundary) {
              yield* iam
                .deleteUserPermissionsBoundary({
                  UserName: userName,
                })
                .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
            }
          }

          // Sync managed and inline policies — observe live state and
          // apply only the delta.
          const [observedManagedPolicies, observedInlinePolicies] = yield* Effect.all([
            readManagedPolicies(userName),
            readInlinePolicies(userName),
          ]);
          yield* syncManagedPolicies({
            userName,
            olds: observedManagedPolicies,
            news: news.managedPolicyArns ?? [],
          });
          yield* syncInlinePolicies({
            userName,
            olds: observedInlinePolicies,
            news: news.inlinePolicies ?? {},
          });

          // Sync tags against the cloud's actual tags.
          const observedTags = yield* readTags(userName);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* iam.tagUser({
              UserName: userName,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* iam.untagUser({
              UserName: userName,
              TagKeys: removed,
            });
          }

          // Re-read for fresh attributes after all mutations.
          const user = yield* iam.getUser({ UserName: userName });
          const userArn = user.User?.Arn ?? observedUser?.Arn ?? userName;

          yield* session.note(userArn);
          return {
            userArn,
            userName: user.User?.UserName ?? userName,
            userId: user.User?.UserId ?? observedUser?.UserId,
            path: user.User?.Path ?? observedUser?.Path ?? news.path ?? "/",
            permissionsBoundary:
              user.User?.PermissionsBoundary?.PermissionsBoundaryArn ?? news.permissionsBoundary,
            managedPolicyArns: news.managedPolicyArns ?? [],
            inlinePolicies: news.inlinePolicies ?? {},
            tags: desiredTags,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* iam
            .deleteUserPermissionsBoundary({
              UserName: output.userName,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));

          yield* iam.listUserPolicies.items({ UserName: output.userName }).pipe(
            Stream.mapEffect((policyName) =>
              iam
                .deleteUserPolicy({
                  UserName: output.userName,
                  PolicyName: policyName,
                })
                .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
            ),
            Stream.runDrain,
            // The user itself may already be gone.
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );

          yield* iam.listAttachedUserPolicies.items({ UserName: output.userName }).pipe(
            Stream.mapEffect((policy) =>
              policy.PolicyArn
                ? iam
                    .detachUserPolicy({
                      UserName: output.userName,
                      PolicyArn: policy.PolicyArn,
                    })
                    .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void))
                : Effect.void,
            ),
            Stream.runDrain,
            // The user itself may already be gone.
            Effect.catchTag("NoSuchEntityException", () => Effect.void),
          );

          yield* iam
            .deleteUser({
              UserName: output.userName,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
        }),
      };
    }),
  );