sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ KeyPair.ts

import * as ec2 from "@distilled.cloud/aws/ec2";
import { Unowned } from "alchemy/AdoptPolicy";
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 Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import type { Providers } from "../Providers.ts";

export type KeyPairId<ID extends string = string> = `key-${ID}`;

/** Key algorithm for a generated EC2 key pair. */
export type KeyPairType = "rsa" | "ed25519";

/** Private-key file format for a generated EC2 key pair. */
export type KeyPairFormat = "pem" | "ppk";

export interface KeyPairProps {
  /**
   * Name of the key pair. If omitted, a unique name is generated from the
   * stack, stage, and logical id. Changing it replaces the key pair.
   */
  keyName?: string;
  /**
   * Algorithm used when Alchemy generates the key pair. Ignored when
   * {@link publicKeyMaterial} is supplied (an imported key keeps its own type).
   * Changing it replaces the key pair.
   * @default "rsa"
   */
  keyType?: KeyPairType;
  /**
   * Format of the returned private key material. Only meaningful when Alchemy
   * generates the key pair. Changing it replaces the key pair.
   * @default "pem"
   */
  keyFormat?: KeyPairFormat;
  /**
   * Public key material (PEM or OpenSSH) to import instead of generating a new
   * key pair. When set, AWS stores only the public key — no `privateKey` is
   * returned. Changing it replaces the key pair.
   */
  publicKeyMaterial?: string;
  /**
   * Tags to assign to the key pair. Merged with the alchemy auto-tags.
   */
  tags?: Record<string, string>;
}

export interface KeyPair extends Resource<
  "AWS.EC2.KeyPair",
  KeyPairProps,
  {
    /** The ID of the key pair (e.g. `key-0123456789abcdef0`). */
    keyPairId: KeyPairId;
    /** The name of the key pair. */
    keyName: string;
    /** SHA-1/MD5 fingerprint of the key pair. */
    keyFingerprint: string;
    /** The algorithm of the key pair. */
    keyType: KeyPairType;
    /**
     * The unencrypted PEM/PPK private key material. Only present when Alchemy
     * generated the key pair (not when {@link KeyPairProps.publicKeyMaterial}
     * was imported). AWS returns this exactly once, at create time; it is then
     * persisted as a secret in alchemy state.
     */
    privateKey?: Redacted.Redacted<string>;
  },
  never,
  Providers
> {}

/**
 * An EC2 key pair used to grant SSH access to instances launched with its
 * `keyName`.
 *
 * By default Alchemy asks EC2 to generate the key pair and captures the
 * private key (returned only once, at create time) as a secret in state. Pass
 * {@link KeyPairProps.publicKeyMaterial} to import your own public key instead,
 * in which case no private key is stored.
 *
 * ### Creating a Key Pair
 * **Example:** Generated key pair
 * ```typescript
 * const keyPair = yield* AWS.EC2.KeyPair("DeployKey", {
 *   keyType: "ed25519",
 * });
 * // keyPair.keyName       -> pass to AWS.EC2.Instance({ keyName })
 * // keyPair.privateKey    -> Redacted<string> (the PEM private key)
 * ```
 *
 * **Example:** Imported public key
 * ```typescript
 * const keyPair = yield* AWS.EC2.KeyPair("ImportedKey", {
 *   publicKeyMaterial: "ssh-ed25519 AAAAC3Nz... user@host",
 * });
 * ```
 *
 * @resource
 */
export const KeyPair = Resource<KeyPair>("AWS.EC2.KeyPair");

const toKeyName = (id: string, props: { keyName?: string } = {}) =>
  props.keyName ? Effect.succeed(props.keyName) : createPhysicalName({ id, maxLength: 255 });

const asRedacted = (
  material: string | Redacted.Redacted<string> | undefined,
): Redacted.Redacted<string> | undefined =>
  material === undefined
    ? undefined
    : Redacted.isRedacted(material)
      ? material
      : Redacted.make(material);

export const KeyPairProvider = () =>
  Provider.effect(
    KeyPair,
    Effect.gen(function* () {
      const describeByName = (keyName: string) =>
        ec2.describeKeyPairs({ KeyNames: [keyName] }).pipe(
          Effect.catchTag("InvalidKeyPair.NotFound", () => Effect.succeed({ KeyPairs: [] })),
          Effect.map((r) => r.KeyPairs?.[0]),
        );

      return {
        stables: ["keyPairId", "keyName", "keyType"],

        // Generated key pairs are immutable except for tags. A changed name /
        // type / format / imported material means a different key pair.
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          const oldName = yield* toKeyName(id, olds ?? {});
          const newName = yield* toKeyName(id, news);
          if (
            oldName !== newName ||
            (olds?.keyType ?? "rsa") !== (news.keyType ?? "rsa") ||
            (olds?.keyFormat ?? "pem") !== (news.keyFormat ?? "pem") ||
            olds?.publicKeyMaterial !== news.publicKeyMaterial
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const keyName = output?.keyName ?? (yield* toKeyName(id, olds ?? {}));
          const info = yield* describeByName(keyName);
          if (!info?.KeyPairId) return undefined;
          const tags = yield* createInternalTags(id);
          const observedTags: Record<string, string | undefined> = Object.fromEntries(
            (info.Tags ?? []).map((t) => [t.Key ?? "", t.Value]),
          );
          if (!hasTags(tags, observedTags)) {
            // Exists but unbranded — let the engine gate adoption behind --adopt.
            return Unowned({
              keyPairId: info.KeyPairId as KeyPairId,
              keyName: info.KeyName ?? keyName,
              keyFingerprint: info.KeyFingerprint ?? "",
              keyType: (info.KeyType ?? "rsa") as KeyPairType,
              // Private key is only available at create time; keep any cached
              // copy from prior state.
              privateKey: output?.privateKey,
            });
          }
          return {
            keyPairId: info.KeyPairId as KeyPairId,
            keyName: info.KeyName ?? keyName,
            keyFingerprint: info.KeyFingerprint ?? output?.keyFingerprint ?? "",
            keyType: (info.KeyType ?? output?.keyType ?? "rsa") as KeyPairType,
            privateKey: output?.privateKey,
          };
        }),

        list: () =>
          Effect.gen(function* () {
            const result = yield* ec2.describeKeyPairs({});
            return (result.KeyPairs ?? [])
              .filter(
                (
                  kp,
                ): kp is ec2.KeyPairInfo & {
                  KeyPairId: string;
                  KeyName: string;
                } => kp.KeyPairId != null && kp.KeyName != null,
              )
              .filter((kp) => (kp.Tags ?? []).some((t) => t.Key === "alchemy::stack"))
              .map((kp) => ({
                keyPairId: kp.KeyPairId as KeyPairId,
                keyName: kp.KeyName,
                keyFingerprint: kp.KeyFingerprint ?? "",
                keyType: (kp.KeyType ?? "rsa") as KeyPairType,
                privateKey: undefined,
              }));
          }),

        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const keyName = output?.keyName ?? (yield* toKeyName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — is the key pair already present?
          let info = yield* describeByName(keyName);
          let privateKey = output?.privateKey;

          // Ensure — import or generate when missing.
          if (!info?.KeyPairId) {
            if (news.publicKeyMaterial !== undefined) {
              const imported = yield* ec2
                .importKeyPair({
                  KeyName: keyName,
                  PublicKeyMaterial: new TextEncoder().encode(news.publicKeyMaterial),
                  TagSpecifications: [
                    {
                      ResourceType: "key-pair",
                      Tags: createTagsList(desiredTags),
                    },
                  ],
                })
                .pipe(Effect.catchTag("InvalidKeyPair.Duplicate", () => Effect.undefined));
              if (imported?.KeyPairId) {
                info = {
                  KeyPairId: imported.KeyPairId,
                  KeyName: imported.KeyName,
                  KeyFingerprint: imported.KeyFingerprint,
                  KeyType: "rsa",
                };
              } else {
                info = yield* describeByName(keyName);
              }
            } else {
              const created = yield* ec2
                .createKeyPair({
                  KeyName: keyName,
                  KeyType: news.keyType ?? "rsa",
                  KeyFormat: news.keyFormat ?? "pem",
                  TagSpecifications: [
                    {
                      ResourceType: "key-pair",
                      Tags: createTagsList(desiredTags),
                    },
                  ],
                })
                .pipe(Effect.catchTag("InvalidKeyPair.Duplicate", () => Effect.undefined));
              if (created?.KeyPairId) {
                privateKey = asRedacted(created.KeyMaterial) ?? privateKey;
                info = {
                  KeyPairId: created.KeyPairId,
                  KeyName: created.KeyName,
                  KeyFingerprint: created.KeyFingerprint,
                  KeyType: (news.keyType ?? "rsa") as KeyPairType,
                };
              } else {
                info = yield* describeByName(keyName);
              }
            }
          }

          if (!info?.KeyPairId) {
            return yield* Effect.die(new Error(`Failed to resolve EC2 key pair '${keyName}'`));
          }
          const keyPairId = info.KeyPairId as KeyPairId;

          // Sync tags — observed cloud tags vs desired.
          const observedTags = Object.fromEntries(
            (info.Tags ?? []).map((t) => [t.Key!, t.Value!]),
          ) as Record<string, string>;
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (removed.length > 0) {
            yield* ec2.deleteTags({
              Resources: [keyPairId],
              Tags: removed.map((key) => ({ Key: key })),
            });
          }
          if (upsert.length > 0) {
            yield* ec2.createTags({ Resources: [keyPairId], Tags: upsert });
          }

          yield* session.note(`Key pair ${keyName} (${keyPairId})`);
          return {
            keyPairId,
            keyName: info.KeyName ?? keyName,
            keyFingerprint: info.KeyFingerprint ?? "",
            keyType: (info.KeyType ?? news.keyType ?? "rsa") as KeyPairType,
            privateKey,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // `deleteKeyPair` is idempotent — deleting a missing key pair
          // succeeds, so there is no NotFound error to catch.
          yield* ec2.deleteKeyPair({ KeyPairId: output.keyPairId });
        }),
      };
    }),
  );