alchemy-effect 0.5.0 → 0.6.2

package/src/AWS/IAM/VirtualMFADevice.ts

@@ -0,0 +1,259 @@
+import * as iam from "@distilled.cloud/aws/iam";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import { Resource } from "../../Resource.ts";
+import { createInternalTags, createTagsList, diffTags } from "../../Tags.ts";
+import { toRedactedBytes, toTagRecord } from "./common.ts";
+
+export interface VirtualMFADeviceProps {
+  /**
+   * Name of the virtual MFA device. If omitted, a deterministic name is generated.
+   */
+  virtualMFADeviceName?: string;
+  /**
+   * Optional IAM path prefix.
+   * @default "/"
+   */
+  path?: string;
+  /**
+   * Optional user to activate the device for.
+   */
+  userName?: string;
+  /**
+   * First authentication code used when activating the device.
+   */
+  authenticationCode1?: string;
+  /**
+   * Second authentication code used when activating the device.
+   */
+  authenticationCode2?: string;
+  /**
+   * User-defined tags.
+   */
+  tags?: Record<string, string>;
+}
+
+export interface VirtualMFADevice extends Resource<
+  "AWS.IAM.VirtualMFADevice",
+  VirtualMFADeviceProps,
+  {
+    serialNumber: string;
+    userName: string | undefined;
+    enableDate: Date | undefined;
+    base32StringSeed:
+      | Redacted.Redacted<Uint8Array<ArrayBufferLike>>
+      | undefined;
+    qrCodePNG: Redacted.Redacted<Uint8Array<ArrayBufferLike>> | undefined;
+    tags: Record<string, string>;
+  }
+> {}
+
+/**
+ * An IAM virtual MFA device.
+ *
+ * `VirtualMFADevice` creates a software MFA device and can optionally activate
+ * it for a user during creation when the initial authentication codes are
+ * provided.
+ *
+ * @section Managing MFA Devices
+ * @example Create and Activate a Virtual MFA Device
+ * ```typescript
+ * const user = yield* User("AdminUser", {
+ *   userName: "admin-user",
+ * });
+ *
+ * const device = yield* VirtualMFADevice("AdminMfa", {
+ *   userName: user.userName,
+ *   authenticationCode1: "123456",
+ *   authenticationCode2: "654321",
+ * });
+ * ```
+ */
+export const VirtualMFADevice = Resource<VirtualMFADevice>(
+  "AWS.IAM.VirtualMFADevice",
+);
+
+export const VirtualMFADeviceProvider = () =>
+  VirtualMFADevice.provider.effect(
+    Effect.gen(function* () {
+      const toName = (id: string, props: VirtualMFADeviceProps) =>
+        props.virtualMFADeviceName
+          ? Effect.succeed(props.virtualMFADeviceName)
+          : createPhysicalName({ id, maxLength: 226 });
+
+      const readDevice = Effect.fn(function* ({
+        serialNumber,
+        userName,
+      }: {
+        serialNumber: string;
+        userName: string | undefined;
+      }) {
+        if (!userName) {
+          const listed = yield* iam.listVirtualMFADevices({
+            AssignmentStatus: "Unassigned",
+          });
+          const device = listed.VirtualMFADevices.find(
+            (entry) => entry.SerialNumber === serialNumber,
+          );
+          return device
+            ? {
+                SerialNumber: device.SerialNumber,
+                UserName: device.User?.UserName,
+                EnableDate: device.EnableDate,
+              }
+            : undefined;
+        }
+        return yield* iam
+          .getMFADevice({
+            SerialNumber: serialNumber,
+            UserName: userName,
+          })
+          .pipe(
+            Effect.catchTag("NoSuchEntityException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+      });
+
+      return {
+        stables: ["serialNumber"],
+        diff: Effect.fn(function* ({ id, olds, news }) {
+          if (!isResolved(news)) return;
+          if (
+            (yield* toName(id, olds ?? ({} as VirtualMFADeviceProps))) !==
+              (yield* toName(id, news)) ||
+            (olds.path ?? "/") !== (news.path ?? "/") ||
+            (olds.userName ?? undefined) !== (news.userName ?? undefined) ||
+            (olds.authenticationCode1 ?? undefined) !==
+              (news.authenticationCode1 ?? undefined) ||
+            (olds.authenticationCode2 ?? undefined) !==
+              (news.authenticationCode2 ?? undefined)
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output) {
+            return undefined;
+          }
+          const response = yield* readDevice({
+            serialNumber: output.serialNumber,
+            userName: output.userName,
+          });
+          if (!response?.SerialNumber) {
+            return undefined;
+          }
+          const tags = yield* iam.listMFADeviceTags({
+            SerialNumber: output.serialNumber,
+          });
+          return {
+            serialNumber: response.SerialNumber,
+            userName: response.UserName ?? output.userName,
+            enableDate: response.EnableDate,
+            base32StringSeed: output.base32StringSeed,
+            qrCodePNG: output.qrCodePNG,
+            tags: toTagRecord(tags.Tags),
+          };
+        }),
+        create: Effect.fn(function* ({ id, news, session }) {
+          const deviceName = yield* toName(id, news);
+          const tags = {
+            ...(yield* createInternalTags(id)),
+            ...news.tags,
+          };
+          const created = yield* iam.createVirtualMFADevice({
+            Path: news.path,
+            VirtualMFADeviceName: deviceName,
+            Tags: createTagsList(tags),
+          });
+          if (!created.VirtualMFADevice.SerialNumber) {
+            return yield* Effect.fail(
+              new Error(`createVirtualMFADevice returned no serial number`),
+            );
+          }
+          if (
+            news.userName &&
+            news.authenticationCode1 &&
+            news.authenticationCode2
+          ) {
+            yield* iam.enableMFADevice({
+              UserName: news.userName,
+              SerialNumber: created.VirtualMFADevice.SerialNumber,
+              AuthenticationCode1: news.authenticationCode1,
+              AuthenticationCode2: news.authenticationCode2,
+            });
+          }
+          const response = yield* readDevice({
+            serialNumber: created.VirtualMFADevice.SerialNumber,
+            userName: news.userName,
+          });
+          yield* session.note(created.VirtualMFADevice.SerialNumber);
+          return {
+            serialNumber: created.VirtualMFADevice.SerialNumber,
+            userName: response?.UserName ?? news.userName,
+            enableDate: response?.EnableDate,
+            base32StringSeed: toRedactedBytes(
+              created.VirtualMFADevice.Base32StringSeed,
+            ),
+            qrCodePNG: toRedactedBytes(created.VirtualMFADevice.QRCodePNG),
+            tags,
+          };
+        }),
+        update: Effect.fn(function* ({ id, news, olds, output, session }) {
+          const oldTags = {
+            ...(yield* createInternalTags(id)),
+            ...olds.tags,
+          };
+          const newTags = {
+            ...(yield* createInternalTags(id)),
+            ...news.tags,
+          };
+          const { removed, upsert } = diffTags(oldTags, newTags);
+          if (upsert.length > 0) {
+            yield* iam.tagMFADevice({
+              SerialNumber: output.serialNumber,
+              Tags: upsert,
+            });
+          }
+          if (removed.length > 0) {
+            yield* iam.untagMFADevice({
+              SerialNumber: output.serialNumber,
+              TagKeys: removed,
+            });
+          }
+          const response = yield* readDevice({
+            serialNumber: output.serialNumber,
+            userName: output.userName,
+          });
+          yield* session.note(output.serialNumber);
+          return {
+            serialNumber: output.serialNumber,
+            userName: response?.UserName ?? output.userName,
+            enableDate: response?.EnableDate ?? output.enableDate,
+            base32StringSeed: output.base32StringSeed,
+            qrCodePNG: output.qrCodePNG,
+            tags: newTags,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          if (output.userName) {
+            yield* iam
+              .deactivateMFADevice({
+                UserName: output.userName,
+                SerialNumber: output.serialNumber,
+              })
+              .pipe(
+                Effect.catchTag("NoSuchEntityException", () => Effect.void),
+              );
+          }
+          yield* iam
+            .deleteVirtualMFADevice({
+              SerialNumber: output.serialNumber,
+            })
+            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/AWS/IAM/common.ts

@@ -0,0 +1,89 @@
+import type * as iam from "@distilled.cloud/aws/iam";
+import * as Redacted from "effect/Redacted";
+import type { PolicyDocument } from "./Policy.ts";
+
+export const toTagRecord = (
+  tags: Array<{ Key?: string; Value?: string }> | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    (tags ?? [])
+      .filter(
+        (tag): tag is { Key: string; Value: string } =>
+          typeof tag.Key === "string" && typeof tag.Value === "string",
+      )
+      .map((tag) => [tag.Key, tag.Value]),
+  );
+
+const decodePolicyString = (value: string) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+export const parsePolicyDocument = (
+  value: string | undefined,
+): PolicyDocument | undefined => {
+  if (!value) {
+    return undefined;
+  }
+
+  const decoded = decodePolicyString(value);
+  return JSON.parse(decoded) as PolicyDocument;
+};
+
+export const stringifyPolicyDocument = (value: PolicyDocument) =>
+  JSON.stringify(value);
+
+export const normalizeIamPath = (value: string | undefined) => {
+  const path = value ?? "/";
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+  return withLeadingSlash.endsWith("/")
+    ? withLeadingSlash
+    : `${withLeadingSlash}/`;
+};
+
+export const policyArnFromParts = ({
+  accountId,
+  path,
+  policyName,
+}: {
+  accountId: string;
+  path: string | undefined;
+  policyName: string;
+}) => `arn:aws:iam::${accountId}:policy${normalizeIamPath(path)}${policyName}`;
+
+export const oldestNondefaultPolicyVersion = (
+  versions: iam.PolicyVersion[] | undefined,
+) =>
+  [...(versions ?? [])]
+    .filter((version) => !version.IsDefaultVersion && version.VersionId)
+    .sort(
+      (a, b) => (a.CreateDate?.getTime() ?? 0) - (b.CreateDate?.getTime() ?? 0),
+    )[0];
+
+export const toRedactedString = (
+  value: string | Redacted.Redacted<string> | undefined,
+): Redacted.Redacted<string> | undefined =>
+  value === undefined
+    ? undefined
+    : typeof value === "string"
+      ? Redacted.make(value)
+      : value;
+
+export const toRedactedBytes = (
+  value:
+    | Uint8Array<ArrayBufferLike>
+    | Redacted.Redacted<Uint8Array<ArrayBufferLike>>
+    | undefined,
+): Redacted.Redacted<Uint8Array<ArrayBufferLike>> | undefined =>
+  value === undefined
+    ? undefined
+    : value instanceof Uint8Array
+      ? Redacted.make(value)
+      : value;
+
+export const unwrapRedactedString = (
+  value: string | Redacted.Redacted<string>,
+): string => (typeof value === "string" ? value : Redacted.value(value));

package/src/AWS/IAM/index.ts

@@ -0,0 +1,40 @@
+export { AccessKey, AccessKeyProvider } from "./AccessKey.ts";
+export { AccountAlias, AccountAliasProvider } from "./AccountAlias.ts";
+export {
+  AccountPasswordPolicy,
+  AccountPasswordPolicyProvider,
+} from "./AccountPasswordPolicy.ts";
+export { Group, GroupProvider } from "./Group.ts";
+export { GroupMembership, GroupMembershipProvider } from "./GroupMembership.ts";
+export { InstanceProfile, InstanceProfileProvider } from "./InstanceProfile.ts";
+export { LoginProfile, LoginProfileProvider } from "./LoginProfile.ts";
+export {
+  OpenIDConnectProvider,
+  OpenIDConnectProviderProvider,
+} from "./OpenIDConnectProvider.ts";
+export {
+  Policy,
+  PolicyProvider,
+  type PolicyDocument,
+  type PolicyStatement,
+} from "./Policy.ts";
+export { Role, RoleProvider } from "./Role.ts";
+export { SAMLProvider, SAMLProviderProvider } from "./SAMLProvider.ts";
+export {
+  ServerCertificate,
+  ServerCertificateProvider,
+} from "./ServerCertificate.ts";
+export {
+  ServiceSpecificCredential,
+  ServiceSpecificCredentialProvider,
+} from "./ServiceSpecificCredential.ts";
+export {
+  SigningCertificate,
+  SigningCertificateProvider,
+} from "./SigningCertificate.ts";
+export { SSHPublicKey, SSHPublicKeyProvider } from "./SSHPublicKey.ts";
+export { User, UserProvider } from "./User.ts";
+export {
+  VirtualMFADevice,
+  VirtualMFADeviceProvider,
+} from "./VirtualMFADevice.ts";

package/src/AWS/IdentityCenter/AccountAssignment.ts

@@ -0,0 +1,290 @@
+import * as ssoAdmin from "@distilled.cloud/aws/sso-admin";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { isResolved } from "../../Diff.ts";
+import { Resource } from "../../Resource.ts";
+import { resolveInstance, retryIdentityCenter } from "./common.ts";
+
+export interface AccountAssignmentProps {
+  /**
+   * Explicit Identity Center instance ARN.
+   * If omitted, Alchemy adopts the only visible instance.
+   */
+  instanceArn?: string;
+  /**
+   * Permission set ARN to assign.
+   */
+  permissionSetArn: string;
+  /**
+   * Principal ID from the IAM Identity Center identity store.
+   */
+  principalId: string;
+  /**
+   * Principal type.
+   */
+  principalType: "USER" | "GROUP";
+  /**
+   * Target AWS account ID.
+   */
+  targetId: string;
+}
+
+export interface AccountAssignment extends Resource<
+  "AWS.IdentityCenter.AccountAssignment",
+  AccountAssignmentProps,
+  {
+    instanceArn: string;
+    permissionSetArn: string;
+    principalId: string;
+    principalType: "USER" | "GROUP";
+    targetId: string;
+    targetType: "AWS_ACCOUNT";
+  }
+> {}
+
+/**
+ * Assigns an IAM Identity Center permission set to a user or group in an AWS
+ * account.
+ *
+ * @section Creating Assignments
+ * @example Assign A Group To A Workload Account
+ * ```typescript
+ * const assignment = yield* AccountAssignment("ProdAdminAssignment", {
+ *   permissionSetArn: admin.permissionSetArn,
+ *   principalType: "GROUP",
+ *   principalId: engineers.groupId,
+ *   targetId: prod.accountId,
+ * });
+ * ```
+ */
+export const AccountAssignment = Resource<AccountAssignment>(
+  "AWS.IdentityCenter.AccountAssignment",
+);
+
+export const AccountAssignmentProvider = () =>
+  AccountAssignment.provider.effect(
+    Effect.gen(function* () {
+      return {
+        stables: [
+          "instanceArn",
+          "permissionSetArn",
+          "principalId",
+          "principalType",
+          "targetId",
+          "targetType",
+        ],
+        diff: Effect.fn(function* ({ olds, news }) {
+          if (!isResolved(news)) return;
+          if (
+            olds?.instanceArn !== news.instanceArn ||
+            olds?.permissionSetArn !== news.permissionSetArn ||
+            olds?.principalId !== news.principalId ||
+            olds?.principalType !== news.principalType ||
+            olds?.targetId !== news.targetId
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ olds, output }) {
+          if (output?.instanceArn) {
+            return yield* readAssignment({
+              instanceArn: output.instanceArn,
+              permissionSetArn: output.permissionSetArn,
+              principalId: output.principalId,
+              principalType: output.principalType,
+              targetId: output.targetId,
+            });
+          }
+
+          if (!olds) {
+            return undefined;
+          }
+
+          return yield* readAssignment(olds);
+        }),
+        create: Effect.fn(function* ({ news, session }) {
+          const existing = yield* readAssignment(news);
+          if (existing) {
+            yield* session.note(
+              `${existing.targetId}:${existing.permissionSetArn}:${existing.principalId}`,
+            );
+            return existing;
+          }
+
+          const instance = yield* resolveInstance(news.instanceArn);
+          const response = yield* retryIdentityCenter(
+            ssoAdmin.createAccountAssignment({
+              InstanceArn: instance.InstanceArn!,
+              PermissionSetArn: news.permissionSetArn,
+              PrincipalId: news.principalId,
+              PrincipalType: news.principalType,
+              TargetId: news.targetId,
+              TargetType: "AWS_ACCOUNT",
+            }),
+          );
+
+          const requestId =
+            response.AccountAssignmentCreationStatus?.RequestId ?? undefined;
+          if (requestId) {
+            yield* waitForAssignmentCreation(instance.InstanceArn!, requestId);
+          }
+
+          const created = yield* readAssignment({
+            ...news,
+            instanceArn: instance.InstanceArn,
+          });
+          if (!created) {
+            return yield* Effect.fail(
+              new Error("account assignment not found after create"),
+            );
+          }
+
+          yield* session.note(
+            `${created.targetId}:${created.permissionSetArn}:${created.principalId}`,
+          );
+          return created;
+        }),
+        update: Effect.fn(function* ({ output, session }) {
+          yield* session.note(
+            `${output.targetId}:${output.permissionSetArn}:${output.principalId}`,
+          );
+          return output;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          if (!(yield* readAssignment(output))) {
+            return;
+          }
+
+          const response = yield* retryIdentityCenter(
+            ssoAdmin
+              .deleteAccountAssignment({
+                InstanceArn: output.instanceArn,
+                PermissionSetArn: output.permissionSetArn,
+                PrincipalId: output.principalId,
+                PrincipalType: output.principalType,
+                TargetId: output.targetId,
+                TargetType: "AWS_ACCOUNT",
+              })
+              .pipe(
+                Effect.catchTag("ResourceNotFoundException", () =>
+                  Effect.succeed(undefined),
+                ),
+              ),
+          );
+
+          const requestId =
+            response?.AccountAssignmentDeletionStatus?.RequestId ?? undefined;
+          if (requestId) {
+            yield* waitForAssignmentDeletion(output.instanceArn, requestId);
+          }
+        }),
+      };
+    }),
+  );
+
+const readAssignment = Effect.fn(function* ({
+  instanceArn,
+  permissionSetArn,
+  principalId,
+  principalType,
+  targetId,
+}: AccountAssignmentProps) {
+  const instance = yield* resolveInstance(instanceArn);
+  const assignments = yield* ssoAdmin.listAccountAssignments
+    .items({
+      InstanceArn: instance.InstanceArn!,
+      AccountId: targetId,
+      PermissionSetArn: permissionSetArn,
+      MaxResults: 100,
+    })
+    .pipe(
+      Stream.runCollect,
+      Effect.map((items) => Array.from(items) as ssoAdmin.AccountAssignment[]),
+    );
+
+  const match = assignments.find(
+    (assignment) =>
+      assignment.PrincipalId === principalId &&
+      assignment.PrincipalType === principalType,
+  );
+
+  return match
+    ? ({
+        instanceArn: instance.InstanceArn!,
+        permissionSetArn,
+        principalId,
+        principalType,
+        targetId,
+        targetType: "AWS_ACCOUNT",
+      } satisfies AccountAssignment["Attributes"])
+    : undefined;
+});
+
+const waitForAssignmentCreation = (instanceArn: string, requestId: string) =>
+  Effect.gen(function* () {
+    const response = yield* retryIdentityCenter(
+      ssoAdmin.describeAccountAssignmentCreationStatus({
+        InstanceArn: instanceArn,
+        AccountAssignmentCreationRequestId: requestId,
+      }),
+    );
+    const status = response.AccountAssignmentCreationStatus;
+
+    if (!status?.Status || status.Status === "IN_PROGRESS") {
+      return yield* Effect.fail({
+        _tag: "AssignmentCreationInProgress" as const,
+      });
+    }
+
+    if (status.Status === "FAILED") {
+      return yield* Effect.fail(
+        new Error(
+          `account assignment creation failed: ${status.FailureReason ?? "unknown failure"}`,
+        ),
+      );
+    }
+
+    return status;
+  }).pipe(
+    Effect.retry({
+      while: (error: any) => error?._tag === "AssignmentCreationInProgress",
+      schedule: Schedule.spaced("2 seconds").pipe(
+        Schedule.both(Schedule.recurs(120)),
+      ),
+    }),
+  );
+
+const waitForAssignmentDeletion = (instanceArn: string, requestId: string) =>
+  Effect.gen(function* () {
+    const response = yield* retryIdentityCenter(
+      ssoAdmin.describeAccountAssignmentDeletionStatus({
+        InstanceArn: instanceArn,
+        AccountAssignmentDeletionRequestId: requestId,
+      }),
+    );
+    const status = response.AccountAssignmentDeletionStatus;
+
+    if (!status?.Status || status.Status === "IN_PROGRESS") {
+      return yield* Effect.fail({
+        _tag: "AssignmentDeletionInProgress" as const,
+      });
+    }
+
+    if (status.Status === "FAILED") {
+      return yield* Effect.fail(
+        new Error(
+          `account assignment deletion failed: ${status.FailureReason ?? "unknown failure"}`,
+        ),
+      );
+    }
+
+    return status;
+  }).pipe(
+    Effect.retry({
+      while: (error: any) => error?._tag === "AssignmentDeletionInProgress",
+      schedule: Schedule.spaced("2 seconds").pipe(
+        Schedule.both(Schedule.recurs(120)),
+      ),
+    }),
+  );