sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudHSMV2/ Hsm.ts

import * as cloudhsm from "@distilled.cloud/aws/cloudhsm-v2";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { findClusterById } from "./internal.ts";

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

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

export interface HsmProps {
  /**
   * ID of the {@link Cluster} the HSM is created in. Changing the cluster
   * replaces the HSM.
   */
  clusterId: string;
  /**
   * Availability Zone the HSM is placed into, e.g. `"us-west-2a"`. Must be
   * one of the AZs covered by the cluster's subnets. Changing the AZ
   * replaces the HSM.
   */
  availabilityZone: string;
  /**
   * IP address for the HSM's elastic network interface. Must be free in the
   * subnet of the chosen Availability Zone. Changing the address replaces
   * the HSM.
   * @default an address picked by AWS from the subnet
   */
  ipAddress?: string;
}

export interface Hsm extends Resource<
  "AWS.CloudHSMV2.Hsm",
  HsmProps,
  {
    /**
     * The unique identifier of the HSM.
     */
    hsmId: string;
    /**
     * The cluster the HSM belongs to.
     */
    clusterId: string;
    /**
     * The Availability Zone the HSM was placed in.
     */
    availabilityZone: string | undefined;
    /**
     * The subnet the HSM's ENI lives in.
     */
    subnetId: string | undefined;
    /**
     * The elastic network interface attached to the HSM.
     */
    eniId: string | undefined;
    /**
     * The IP address of the HSM's ENI.
     */
    eniIp: string | undefined;
    /**
     * Current state of the HSM (e.g. `ACTIVE`).
     */
    state: string;
  },
  never,
  Providers
> {}

/**
 * A hardware security module (HSM) inside an AWS CloudHSM {@link Cluster}.
 *
 * HSMs take roughly 10-20 minutes to provision and are billed hourly while
 * they exist. The cluster must be in the `UNINITIALIZED`, `ACTIVE`, or
 * `DEGRADED` state to accept a new HSM. Destroy HSMs you are not using.
 * ### Creating an HSM
 * **Example:** HSM in a Cluster's Availability Zone
 * ```typescript
 * const hsm = yield* Hsm("Primary", {
 *   clusterId: cluster.clusterId,
 *   availabilityZone: "us-west-2a",
 * });
 * ```
 *
 * **Example:** HSM with a Fixed ENI Address
 * ```typescript
 * const hsm = yield* Hsm("Primary", {
 *   clusterId: cluster.clusterId,
 *   availabilityZone: "us-west-2a",
 *   ipAddress: "10.0.1.20",
 * });
 * ```
 *
 * @resource
 */
export const Hsm = Resource<Hsm>("AWS.CloudHSMV2.Hsm");

export const HsmProvider = () =>
  Provider.effect(
    Hsm,
    Effect.gen(function* () {
      // HSMs are enumerated through their cluster — describeClusters embeds
      // each cluster's Hsms.
      const findHsm = Effect.fn(function* (clusterId: string, hsmId: string) {
        const cluster = yield* findClusterById(clusterId);
        return cluster?.Hsms?.find((hsm) => hsm.HsmId === hsmId && hsm.State !== "DELETED");
      });

      // Bounded readiness wait. HSM provisioning typically completes in
      // 10-20 minutes; budget ~25 min (100 * 15s).
      const waitForActive = Effect.fn(function* (clusterId: string, hsmId: string) {
        const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(100)]);
        return yield* findHsm(clusterId, hsmId).pipe(
          Effect.flatMap((hsm) => {
            if (hsm === undefined) {
              return Effect.fail(
                new HsmNotReady({ message: `HSM '${hsmId}' not found in cluster '${clusterId}'` }),
              );
            }
            if (hsm.State !== "ACTIVE") {
              return Effect.fail(
                new HsmNotReady({ message: `HSM '${hsmId}' not active (state: ${hsm.State})` }),
              );
            }
            return Effect.succeed(hsm);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      // Bounded wait-until-gone after delete initiation (~15 min = 60 * 15s).
      // The whole cluster disappearing counts as gone too.
      const waitUntilGone = Effect.fn(function* (clusterId: string, hsmId: string) {
        const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
        yield* findHsm(clusterId, hsmId).pipe(
          Effect.flatMap((hsm) =>
            hsm === undefined
              ? Effect.void
              : Effect.fail(
                  new HsmNotReady({
                    message: `HSM '${hsmId}' still deleting (state: ${hsm.State})`,
                  }),
                ),
          ),
          Effect.retry({ schedule: policy }),
        );
      });

      const toAttrs = Effect.fn(function* (hsm: cloudhsm.Hsm) {
        if (!hsm.ClusterId) {
          return yield* new HsmUnexpectedResponse({
            message: `HSM '${hsm.HsmId}' is missing its ClusterId`,
          });
        }
        return {
          hsmId: hsm.HsmId,
          clusterId: hsm.ClusterId,
          availabilityZone: hsm.AvailabilityZone,
          subnetId: hsm.SubnetId,
          eniId: hsm.EniId,
          eniIp: hsm.EniIp,
          state: hsm.State ?? "ACTIVE",
        };
      });

      return {
        stables: ["hsmId", "clusterId", "availabilityZone"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? { clusterId: "", availabilityZone: "" };
          const o = olds ?? { clusterId: "", availabilityZone: "" };
          // Every HSM property is create-only.
          if (n.clusterId !== o.clusterId) {
            return { action: "replace" } as const;
          }
          if (n.availabilityZone !== o.availabilityZone) {
            return { action: "replace" } as const;
          }
          if (n.ipAddress !== o.ipAddress) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ output }) {
          // HSMs have no name, no tags, and an auto-assigned id — without a
          // cached id there is nothing to correlate on.
          if (output === undefined) return undefined;
          const hsm = yield* findHsm(output.clusterId, output.hsmId);
          if (hsm === undefined) return undefined;
          return yield* toAttrs(hsm);
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const props = news!;

          // 1. Observe — the cached id is only a hint; the cluster's HSM
          //    list is authoritative.
          let observed = output ? yield* findHsm(output.clusterId, output.hsmId) : undefined;

          // 2. Ensure — create if missing.
          if (observed === undefined) {
            const created = yield* cloudhsm.createHsm({
              ClusterId: props.clusterId,
              AvailabilityZone: props.availabilityZone,
              IpAddress: props.ipAddress,
            });
            observed = created.Hsm;
          }
          const hsmId = observed?.HsmId;
          if (!hsmId) {
            return yield* new HsmUnexpectedResponse({ message: "CreateHsm returned no HsmId" });
          }

          // 3. Wait for the HSM to become ACTIVE (nothing else is mutable).
          const active = yield* waitForActive(props.clusterId, hsmId);

          yield* session.note(hsmId);
          return yield* toAttrs(active);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* cloudhsm
            .deleteHsm({ ClusterId: output.clusterId, HsmId: output.hsmId })
            .pipe(Effect.catchTag("CloudHsmResourceNotFoundException", () => Effect.void));
          // Deletion is asynchronous and the parent cluster cannot be
          // deleted until the HSM is gone — wait it out (bounded).
          yield* waitUntilGone(output.clusterId, output.hsmId);
        }),

        list: () =>
          Effect.gen(function* () {
            const pages = yield* cloudhsm.describeClusters.pages({}).pipe(Stream.runCollect);
            const hsms = Array.from(pages)
              .flatMap((page) => page.Clusters ?? [])
              .flatMap((cluster) => cluster.Hsms ?? [])
              .filter((hsm) => hsm.State !== "DELETED");
            return yield* Effect.forEach(hsms, (hsm) => toAttrs(hsm));
          }),
      };
    }),
  );