import * as cloudhsm from "@distilled.cloud/aws/cloudhsm-v2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { reapLogGroupsByPrefix } from "../Logs/reapLogGroups.ts";
import type { Providers } from "../Providers.ts";
import { findClusterById, sameStringSet, toTagRecord } from "./internal.ts";
export class CloudHSMV2ClusterNotReady extends Data.TaggedError("CloudHSMV2ClusterNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class CloudHSMV2ClusterUnexpectedResponse extends Data.TaggedError(
"CloudHSMV2ClusterUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface ClusterProps {
/**
* Type of HSM the cluster hosts, e.g. `"hsm2m.medium"` (current
* generation) or `"hsm1.medium"` (legacy). Changing the HSM type replaces
* the cluster.
*/
hsmType: string;
/**
* IDs of the subnets the cluster's HSMs may be placed into. Each subnet
* must be in a different Availability Zone of the same VPC. Changing the
* subnets replaces the cluster.
*/
subnetIds: string[];
/**
* ID (or, cross-account, the full ARN) of a cluster backup to restore the
* new cluster from. Changing the source backup replaces the cluster.
*/
sourceBackupId?: string;
/**
* IP address type of the cluster's endpoints — `"IPV4"` or `"DUALSTACK"`.
* Changing the network type replaces the cluster.
* @default "IPV4"
*/
networkType?: cloudhsm.NetworkType;
/**
* Whether the cluster runs in `"FIPS"` or `"NON_FIPS"` mode. Required by
* AWS for `hsm2m.*` HSM types, so Alchemy sends `"FIPS"` when omitted
* (legacy `hsm1.*` clusters are FIPS-only and omit it). Changing the mode
* replaces the cluster.
* @default "FIPS"
*/
mode?: cloudhsm.ClusterMode;
/**
* How long automatic backups of the cluster are retained (e.g. `"30 days"`
* or `Duration.days(30)`; a bare number is milliseconds). Converted to
* whole days on the wire. Updated in place via ModifyCluster.
* @default 90 days
*/
backupRetention?: Duration.Input;
/**
* User-defined tags for the cluster.
*/
tags?: Record<string, string>;
}
export interface Cluster extends Resource<
"AWS.CloudHSMV2.Cluster",
ClusterProps,
{
/**
* The unique identifier of the cluster.
*/
clusterId: string;
/**
* Current state of the cluster (e.g. `UNINITIALIZED`, `ACTIVE`).
*/
state: string;
/**
* The type of HSM in the cluster (e.g. `hsm2m.medium`).
*/
hsmType: string;
/**
* The FIPS mode of the cluster (`FIPS` or `NON_FIPS`).
*/
mode: string | undefined;
/**
* The network type of the cluster (`IPV4` or `DUALSTACK`).
*/
networkType: string | undefined;
/**
* The VPC the cluster's HSMs live in.
*/
vpcId: string | undefined;
/**
* The security group CloudHSM created for the cluster's ENIs.
*/
securityGroup: string | undefined;
/**
* The subnets (one per AZ) the cluster spans.
*/
subnetIds: string[];
/**
* The certificate signing request to sign when initializing the cluster
* (present while `UNINITIALIZED`).
*/
clusterCsr: string | undefined;
/**
* How many days backups are retained.
*/
backupRetentionDays: number | undefined;
/**
* Current tags on the cluster.
*/
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An AWS CloudHSM cluster — a fleet of FIPS-validated, single-tenant
* hardware security modules (HSMs) inside your VPC.
*
* A fresh cluster provisions to the `UNINITIALIZED` state in a few minutes
* and holds no HSMs; add {@link Hsm} resources to place HSMs into its
* subnets' Availability Zones (each HSM is billed hourly). Activating the
* cluster (signing the cluster CSR and calling InitializeCluster) is an
* offline certificate-authority ceremony that stays out of band — the
* `clusterCsr` attribute exposes the CSR to sign.
* ### Creating a Cluster
* **Example:** Cluster Spanning Two Availability Zones
* ```typescript
* const cluster = yield* Cluster("HsmCluster", {
* hsmType: "hsm2m.medium",
* subnetIds: [subnetA.subnetId, subnetB.subnetId],
* });
* ```
*
* **Example:** Non-FIPS Cluster with Custom Backup Retention
* ```typescript
* const cluster = yield* Cluster("HsmCluster", {
* hsmType: "hsm2m.medium",
* subnetIds: [subnetA.subnetId, subnetB.subnetId],
* mode: "NON_FIPS",
* backupRetention: "30 days",
* });
* ```
*
* ### Adding HSMs
* **Example:** Cluster with One HSM
* ```typescript
* const cluster = yield* Cluster("HsmCluster", {
* hsmType: "hsm2m.medium",
* subnetIds: [subnetA.subnetId, subnetB.subnetId],
* });
* const hsm = yield* Hsm("Primary", {
* clusterId: cluster.clusterId,
* availabilityZone: "us-west-2a",
* });
* ```
*
* @resource
*/
export const Cluster = Resource<Cluster>("AWS.CloudHSMV2.Cluster");
/** Cluster states that mean "gone" for reconciliation purposes. */
const isGone = (cluster: cloudhsm.Cluster | undefined) =>
cluster === undefined || cluster.State === "DELETED" || cluster.State === "DELETE_IN_PROGRESS";
export const ClusterProvider = () =>
Provider.effect(
Cluster,
Effect.gen(function* () {
// Read the observed tags for a cluster. A cluster mid-transition can
// transiently reject listTags; treat failure as "no observed tags" so
// tag reconciliation re-runs on the next pass.
const readClusterTags = Effect.fn(function* (clusterId: string) {
const response = yield* cloudhsm
.listTags({ ResourceId: clusterId })
.pipe(Effect.orElseSucceed(() => undefined));
return toTagRecord(response?.TagList);
});
// CloudHSM clusters have no caller-chosen name — the id is
// auto-assigned. When we have no cached id (state persistence failed
// mid-reconcile), recover ownership by scanning for the cluster
// carrying our alchemy tags.
const findClusterByAlchemyTags = Effect.fn(function* (id: string) {
const pages = yield* cloudhsm.describeClusters.pages({}).pipe(Stream.runCollect);
for (const page of pages) {
for (const cluster of page.Clusters ?? []) {
if (isGone(cluster)) continue;
if (yield* hasAlchemyTags(id, toTagRecord(cluster.TagList))) {
return cluster;
}
}
}
return undefined;
});
// Bounded settle wait: creation and modification park the cluster in a
// *_IN_PROGRESS state; the cluster itself settles in a few minutes
// (budget 10 min = 40 * 15s).
const waitUntilSettled = Effect.fn(function* (clusterId: string) {
const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(40)]);
return yield* findClusterById(clusterId).pipe(
Effect.flatMap((cluster) => {
if (cluster === undefined) {
return Effect.fail(
new CloudHSMV2ClusterNotReady({
message: `CloudHSM cluster '${clusterId}' not found`,
}),
);
}
if (cluster.State?.endsWith("_IN_PROGRESS")) {
return Effect.fail(
new CloudHSMV2ClusterNotReady({
message: `CloudHSM cluster '${clusterId}' still settling (state: ${cluster.State})`,
}),
);
}
return Effect.succeed(cluster);
}),
Effect.retry({ schedule: policy }),
);
});
const toAttrs = Effect.fn(function* (cluster: cloudhsm.Cluster) {
if (!cluster.ClusterId) {
return yield* new CloudHSMV2ClusterUnexpectedResponse({
message: "CloudHSM cluster is missing its ClusterId",
});
}
return {
clusterId: cluster.ClusterId,
state: cluster.State ?? "UNINITIALIZED",
hsmType: cluster.HsmType ?? "",
mode: cluster.Mode,
networkType: cluster.NetworkType,
vpcId: cluster.VpcId,
securityGroup: cluster.SecurityGroup,
subnetIds: Object.values(cluster.SubnetMapping ?? {}).filter(
(s): s is string => s !== undefined,
),
clusterCsr: cluster.Certificates?.ClusterCsr,
backupRetentionDays:
cluster.BackupRetentionPolicy?.Value !== undefined
? Number(cluster.BackupRetentionPolicy.Value)
: undefined,
tags: toTagRecord(cluster.TagList),
};
});
return {
stables: ["clusterId", "vpcId", "securityGroup"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return undefined;
const n = news ?? { hsmType: "", subnetIds: [] };
const o = olds ?? { hsmType: "", subnetIds: [] };
// Create-only properties force a replacement.
if (n.hsmType !== o.hsmType) {
return { action: "replace" } as const;
}
if (!sameStringSet(n.subnetIds, o.subnetIds)) {
return { action: "replace" } as const;
}
if (n.sourceBackupId !== o.sourceBackupId) {
return { action: "replace" } as const;
}
if ((n.networkType ?? "IPV4") !== (o.networkType ?? "IPV4")) {
return { action: "replace" } as const;
}
if ((n.mode ?? undefined) !== (o.mode ?? undefined)) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, output }) {
const cluster = output?.clusterId
? yield* findClusterById(output.clusterId)
: yield* findClusterByAlchemyTags(id);
if (cluster === undefined || cluster.State === "DELETED") {
return undefined;
}
const attrs = yield* toAttrs(cluster);
return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const props = news!;
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...props.tags };
const backupRetentionDays = toWireDays(props.backupRetention);
// 1. Observe — cloud state is authoritative; output is only an id
// cache. Without one, recover by alchemy tags (crash recovery /
// adoption both land here).
let observed = output?.clusterId
? yield* findClusterById(output.clusterId)
: yield* findClusterByAlchemyTags(id);
// 2. Ensure — create if missing (or terminally deleted).
if (isGone(observed)) {
const created = yield* cloudhsm.createCluster({
HsmType: props.hsmType,
SubnetIds: props.subnetIds,
SourceBackupId: props.sourceBackupId,
NetworkType: props.networkType,
// hsm2m.* types require an explicit Mode ("Mode is a required
// argument for this hsm type"); default to FIPS as documented.
// Legacy hsm1.* types predate the parameter and are FIPS-only.
Mode: props.mode ?? (props.hsmType.startsWith("hsm1") ? undefined : "FIPS"),
BackupRetentionPolicy:
backupRetentionDays !== undefined
? { Type: "DAYS", Value: String(backupRetentionDays) }
: undefined,
TagList: createTagsList(desiredTags),
});
observed = created.Cluster;
}
const clusterId = observed?.ClusterId;
if (!clusterId) {
return yield* new CloudHSMV2ClusterUnexpectedResponse({
message: "CreateCluster returned no ClusterId",
});
}
// Creation/modification park the cluster in *_IN_PROGRESS; wait
// (bounded) so subsequent modify calls do not race the transition.
observed = yield* waitUntilSettled(clusterId);
// 3. Sync backup retention — diff OBSERVED policy against desired.
if (
backupRetentionDays !== undefined &&
String(backupRetentionDays) !== observed.BackupRetentionPolicy?.Value
) {
yield* cloudhsm.modifyCluster({
ClusterId: clusterId,
BackupRetentionPolicy: {
Type: "DAYS",
Value: String(backupRetentionDays),
},
});
observed = yield* waitUntilSettled(clusterId);
}
// 3b. Sync tags — diff against OBSERVED cloud tags.
const observedTags = yield* readClusterTags(clusterId);
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* cloudhsm.tagResource({
ResourceId: clusterId,
TagList: upsert,
});
}
if (removed.length > 0) {
yield* cloudhsm.untagResource({
ResourceId: clusterId,
TagKeyList: removed,
});
}
yield* session.note(clusterId);
return yield* toAttrs(observed);
}),
delete: Effect.fn(function* ({ output }) {
const clusterId = output.clusterId;
const observed = yield* findClusterById(clusterId);
if (isGone(observed)) return;
// Before a cluster can be deleted all of its HSMs must be gone;
// HSM deletion initiated by dependent resources may still be
// propagating, which surfaces as CloudHsmInvalidRequestException.
// Bounded retry through that window (10 min = 40 * 15s).
yield* cloudhsm.deleteCluster({ ClusterId: clusterId }).pipe(
Effect.retry({
while: (e) => e._tag === "CloudHsmInvalidRequestException",
schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(40)]),
}),
Effect.catchTag("CloudHsmResourceNotFoundException", () => Effect.void),
);
// CloudHSM writes audit logs to `/aws/cloudhsm/<clusterId>` and
// never deletes the group. Wait (bounded) for the deletion to
// finish so no late flush recreates it, then reap it.
yield* findClusterById(clusterId).pipe(
Effect.repeat({
schedule: Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(18)]),
until: (cluster) => cluster === undefined || cluster.State === "DELETED",
}),
Effect.catch(() => Effect.void),
);
yield* reapLogGroupsByPrefix(`/aws/cloudhsm/${clusterId}`);
}),
list: () =>
Effect.gen(function* () {
const pages = yield* cloudhsm.describeClusters.pages({}).pipe(Stream.runCollect);
const clusters = Array.from(pages)
.flatMap((page) => page.Clusters ?? [])
.filter((cluster) => cluster.ClusterId !== undefined && cluster.State !== "DELETED");
return yield* Effect.forEach(clusters, (cluster) => toAttrs(cluster));
}),
};
}),
);