sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IAM/ VirtualMFADevice.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 } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { toRedactedBytes, toTagRecord } from "./common.ts";

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

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,
  {
    /** The serial number (ARN) of the virtual MFA device. */
    serialNumber: string;
    /** The user the device is enabled for, if activated. */
    userName: string | undefined;
    /** When the device was activated, if activated. */
    enableDate: Date | undefined;
    /** The base32 seed for configuring an authenticator app. AWS only returns it at creation. */
    base32StringSeed: Redacted.Redacted<Uint8Array<ArrayBufferLike>> | undefined;
    /** A QR-code PNG encoding the seed. AWS only returns it at creation. */
    qrCodePNG: Redacted.Redacted<Uint8Array<ArrayBufferLike>> | undefined;
    /** The tags applied to the device. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * 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.
 * ### 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",
 * });
 * ```
 *
 * @resource
 */
export const VirtualMFADevice = Resource<VirtualMFADevice>("AWS.IAM.VirtualMFADevice");

export const VirtualMFADeviceProvider = () =>
  Provider.effect(
    VirtualMFADevice,
    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 device = yield* iam.listVirtualMFADevices
            .items({ AssignmentStatus: "Unassigned" })
            .pipe(
              Stream.filter((entry) => entry.SerialNumber === serialNumber),
              Stream.runHead,
              Effect.map(Option.getOrUndefined),
            );
          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.undefined));
      });

      return {
        stables: ["serialNumber"],
        list: () =>
          Effect.gen(function* () {
            // Enumerate every virtual MFA device in the account. The list op
            // does not return tags, so hydrate them per-device via
            // listMFADeviceTags (matching the exact shape `read` returns).
            const devices = yield* iam.listVirtualMFADevices.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) => page.VirtualMFADevices ?? []),
              ),
            );
            return yield* Effect.forEach(
              devices,
              (device) =>
                Effect.gen(function* () {
                  const tags = yield* iam
                    .listMFADeviceTags({
                      SerialNumber: device.SerialNumber,
                    })
                    .pipe(
                      Effect.map((resp) => resp.Tags),
                      // The device may vanish between listing and tag lookup.
                      Effect.catchTag("NoSuchEntityException", () => Effect.succeed<iam.Tag[]>([])),
                    );
                  return {
                    serialNumber: device.SerialNumber,
                    userName: device.User?.UserName,
                    enableDate: device.EnableDate,
                    // The seed and QR code are only returned at creation time
                    // and are never available from enumeration.
                    base32StringSeed: undefined,
                    qrCodePNG: undefined,
                    tags: toTagRecord(tags),
                  };
                }),
              { concurrency: 10 },
            );
          }),
        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),
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...news.tags,
          };

          // Observe — virtual MFA devices have AWS-generated serial
          // numbers, so we can only locate the existing device when we
          // already have its serial from a prior output.
          const observed = output
            ? yield* readDevice({
                serialNumber: output.serialNumber,
                userName: output.userName,
              })
            : undefined;

          // Ensure — create the device when missing. The seed and QR
          // code are only returned on creation, so on adoption the best
          // we can do is preserve the existing redacted values.
          let serialNumber = observed?.SerialNumber ?? output?.serialNumber;
          let base32StringSeed = output?.base32StringSeed;
          let qrCodePNG = output?.qrCodePNG;

          if (!observed?.SerialNumber) {
            const deviceName = yield* toName(id, news);
            const created = yield* iam.createVirtualMFADevice({
              Path: news.path,
              VirtualMFADeviceName: deviceName,
              Tags: createTagsList(desiredTags),
            });
            if (!created.VirtualMFADevice.SerialNumber) {
              return yield* new VirtualMFADeviceUnexpectedResponse({
                message: `createVirtualMFADevice returned no serial number`,
              });
            }
            serialNumber = created.VirtualMFADevice.SerialNumber;
            base32StringSeed = toRedactedBytes(created.VirtualMFADevice.Base32StringSeed);
            qrCodePNG = toRedactedBytes(created.VirtualMFADevice.QRCodePNG);

            // The device was just created, so it is unassigned. Activate
            // it for the user when activation codes are provided. After
            // first activation the codes lose their meaning (`diff`
            // triggers replacement on code change).
            if (news.userName && news.authenticationCode1 && news.authenticationCode2) {
              yield* iam.enableMFADevice({
                UserName: news.userName,
                SerialNumber: serialNumber,
                AuthenticationCode1: news.authenticationCode1,
                AuthenticationCode2: news.authenticationCode2,
              });
            }
          }

          if (!serialNumber) {
            return yield* new VirtualMFADeviceUnexpectedResponse({
              message: `Virtual MFA device has no serial number`,
            });
          }

          // Sync tags against the cloud's actual tags.
          const observedTagsResp = yield* iam.listMFADeviceTags({
            SerialNumber: serialNumber,
          });
          const observedTags = toTagRecord(observedTagsResp.Tags);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* iam.tagMFADevice({
              SerialNumber: serialNumber,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* iam.untagMFADevice({
              SerialNumber: serialNumber,
              TagKeys: removed,
            });
          }

          // Re-read for fresh `EnableDate` / `UserName` after activation.
          const fresh = yield* readDevice({
            serialNumber,
            userName: news.userName ?? output?.userName,
          });

          yield* session.note(serialNumber);
          return {
            serialNumber,
            userName: fresh?.UserName ?? news.userName ?? output?.userName,
            enableDate: fresh?.EnableDate ?? output?.enableDate,
            base32StringSeed,
            qrCodePNG,
            tags: desiredTags,
          };
        }),
        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));
        }),
      };
    }),
  );