sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IAM/ SAMLProvider.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, diffTags, hasTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { toTagRecord, unwrapRedactedString } from "./common.ts";

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

export interface SAMLProviderProps {
  /**
   * The friendly SAML provider name. If omitted, a unique name is
   * generated from the stack, stage, and logical id.
   */
  name?: string;
  /**
   * The provider metadata document.
   */
  samlMetadataDocument: string;
  /**
   * Optional assertion encryption mode.
   */
  assertionEncryptionMode?: iam.AssertionEncryptionModeType;
  /**
   * Optional private key added during creation/update.
   */
  addPrivateKey?: Redacted.Redacted<string> | string;
  /**
   * User-defined tags.
   */
  tags?: Record<string, string>;
}

export interface SAMLProvider extends Resource<
  "AWS.IAM.SAMLProvider",
  SAMLProviderProps,
  {
    /** The ARN of the SAML provider. */
    samlProviderArn: string;
    /** The name of the SAML provider. */
    name: string;
    /** The unique ID AWS assigns to the provider. */
    samlProviderUUID: string | undefined;
    /** The SAML metadata document from the identity provider. */
    samlMetadataDocument: string | undefined;
    /** Whether SAML assertions must be encrypted (`Required` / `Allowed`). */
    assertionEncryptionMode: iam.AssertionEncryptionModeType | undefined;
    /** The tags applied to the provider. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An IAM SAML identity provider.
 *
 * `SAMLProvider` registers a SAML metadata document so IAM roles can trust an
 * external workforce or application identity provider.
 * ### Federating with SAML
 * **Example:** Create a SAML Identity Provider
 * ```typescript
 * const provider = yield* SAMLProvider("WorkforceSaml", {
 *   samlMetadataDocument: "<EntityDescriptor>...</EntityDescriptor>",
 * });
 * ```
 *
 * @resource
 */
export const SAMLProvider = Resource<SAMLProvider>("AWS.IAM.SAMLProvider");

// IAM is eventually consistent. Recreating a SAML provider immediately after a
// same-named one was deleted (the destroy-then-deploy test flow) can transiently
// surface a content-less `ValidationError` (or `ConcurrentModificationException`)
// until the prior delete settles. A bounded retry rides out that window; a
// well-formed metadata document never fails persistently, so this never masks a
// genuine bad-input error for longer than the small budget.
const transientWriteSchedule = Schedule.max([
  Schedule.exponential(500).pipe(Schedule.jittered),
  Schedule.recurs(6),
]);
const isEmptyUpdateError = (error: { _tag: string; message?: string }) =>
  error._tag === "ValidationError" && (error.message?.includes("No updates are defined") ?? false);

const isTransientWriteError = (error: {
  _tag: "ValidationError" | "ConcurrentModificationException" | (string & {});
  message?: string;
}) =>
  error._tag === "ConcurrentModificationException" ||
  (error._tag === "ValidationError" && !isEmptyUpdateError(error));

const toName = (id: string, props: { name?: string }) =>
  props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 128 });

export const SAMLProviderProvider = () =>
  Provider.succeed(SAMLProvider, {
    stables: ["samlProviderArn", "name"],
    diff: Effect.fn(function* ({ id, olds, news }) {
      if (!isResolved(news)) return;
      if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news))) {
        return { action: "replace" } as const;
      }
    }),
    read: Effect.fn(function* ({ output }) {
      if (!output) {
        return undefined;
      }
      const response = yield* iam
        .getSAMLProvider({ SAMLProviderArn: output.samlProviderArn })
        .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));
      if (!response) {
        return undefined;
      }
      const tags = yield* iam.listSAMLProviderTags({ SAMLProviderArn: output.samlProviderArn });
      return {
        samlProviderArn: output.samlProviderArn,
        name: output.name,
        samlProviderUUID: response.SAMLProviderUUID,
        samlMetadataDocument: response.SAMLMetadataDocument,
        assertionEncryptionMode: response.AssertionEncryptionMode,
        tags: toTagRecord(tags.Tags),
      };
    }),
    list: Effect.fn(function* () {
      // IAM is global; `listSAMLProviders` enumerates every provider in the
      // account but only returns the ARN, so hydrate each via
      // `getSAMLProvider` + `listSAMLProviderTags` for the full Attributes.
      const { SAMLProviderList } = yield* iam.listSAMLProviders({});
      const arns = (SAMLProviderList ?? []).flatMap((entry) => (entry.Arn ? [entry.Arn] : []));
      const rows = yield* Effect.forEach(
        arns,
        (samlProviderArn) =>
          Effect.gen(function* () {
            const response = yield* iam.getSAMLProvider({ SAMLProviderArn: samlProviderArn });
            const tags = yield* iam.listSAMLProviderTags({ SAMLProviderArn: samlProviderArn });
            return {
              samlProviderArn,
              name: samlProviderArn.split("saml-provider/").pop() ?? "",
              samlProviderUUID: response.SAMLProviderUUID,
              samlMetadataDocument: response.SAMLMetadataDocument,
              assertionEncryptionMode: response.AssertionEncryptionMode,
              tags: toTagRecord(tags.Tags),
            };
          }).pipe(
            // A provider can disappear between listing, reading and tag lookup.
            Effect.catchTag("NoSuchEntityException", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row) => row !== undefined);
    }),
    reconcile: Effect.fn(function* ({ id, news, output, session }) {
      const internalTags = yield* createInternalTags(id);
      const desiredTags = { ...internalTags, ...news.tags };
      const name = output?.name ?? (yield* toName(id, news));
      const accountId = (yield* AWSEnvironment.current).accountId;
      const samlProviderArn =
        output?.samlProviderArn ?? `arn:aws:iam::${accountId}:saml-provider/${name}`;

      // Observe — `getSAMLProvider` returns the metadata, encryption
      // mode, and UUID; absence is `NoSuchEntityException`.
      let observed = yield* iam
        .getSAMLProvider({ SAMLProviderArn: samlProviderArn })
        .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined));

      // Ensure — create when missing. Race with a peer is recovered by
      // verifying alchemy ownership tags on the existing provider.
      if (!observed) {
        const created = yield* iam
          .createSAMLProvider({
            Name: name,
            SAMLMetadataDocument: news.samlMetadataDocument,
            AssertionEncryptionMode: news.assertionEncryptionMode,
            AddPrivateKey: news.addPrivateKey
              ? unwrapRedactedString(news.addPrivateKey)
              : undefined,
            Tags: Object.entries(desiredTags).map(([Key, Value]) => ({ Key, Value })),
          })
          .pipe(
            Effect.retry({ while: isTransientWriteError, schedule: transientWriteSchedule }),
            Effect.catchTag("EntityAlreadyExistsException", () =>
              Effect.gen(function* () {
                const existingTags = yield* iam.listSAMLProviderTags({
                  SAMLProviderArn: samlProviderArn,
                });
                if (!hasTags(internalTags, existingTags.Tags)) {
                  return yield* new SAMLProviderConflict({
                    message: `SAML provider '${name}' already exists and is not managed by alchemy`,
                  });
                }
                return { SAMLProviderArn: samlProviderArn };
              }),
            ),
          );
        observed = yield* iam.getSAMLProvider({
          SAMLProviderArn: created.SAMLProviderArn ?? samlProviderArn,
        });
      } else {
        // Sync metadata / encryption mode — `updateSAMLProvider` rejects
        // a call with no fields set ("No updates are defined…"). Only
        // send fields that actually changed; skip the API on a no-op
        // (greenfield adopt of a leftover provider, or a tags-only
        // reconcile).
        const metadataChanged =
          (observed.SAMLMetadataDocument ?? undefined) !== news.samlMetadataDocument;
        const encryptionChanged =
          news.assertionEncryptionMode !== undefined &&
          observed.AssertionEncryptionMode !== news.assertionEncryptionMode;
        const addPrivateKey = news.addPrivateKey
          ? unwrapRedactedString(news.addPrivateKey)
          : undefined;
        if (metadataChanged || encryptionChanged || addPrivateKey !== undefined) {
          yield* iam
            .updateSAMLProvider({
              SAMLProviderArn: samlProviderArn,
              SAMLMetadataDocument: metadataChanged ? news.samlMetadataDocument : undefined,
              AssertionEncryptionMode: encryptionChanged ? news.assertionEncryptionMode : undefined,
              AddPrivateKey: addPrivateKey,
            })
            .pipe(
              Effect.retry({ while: isTransientWriteError, schedule: transientWriteSchedule }),
              Effect.catchIf(isEmptyUpdateError, () => Effect.void),
            );
        }
      }

      // Sync tags against the cloud's actual tags.
      const observedTagsResp = yield* iam.listSAMLProviderTags({
        SAMLProviderArn: samlProviderArn,
      });
      const observedTags = toTagRecord(observedTagsResp.Tags);
      const { removed, upsert } = diffTags(observedTags, desiredTags);
      if (upsert.length > 0) {
        yield* iam.tagSAMLProvider({ SAMLProviderArn: samlProviderArn, Tags: upsert });
      }
      if (removed.length > 0) {
        yield* iam.untagSAMLProvider({ SAMLProviderArn: samlProviderArn, TagKeys: removed });
      }

      yield* session.note(samlProviderArn);
      return {
        samlProviderArn,
        name,
        samlProviderUUID: observed?.SAMLProviderUUID ?? output?.samlProviderUUID,
        samlMetadataDocument: news.samlMetadataDocument,
        assertionEncryptionMode: news.assertionEncryptionMode,
        tags: desiredTags,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* iam
        .deleteSAMLProvider({ SAMLProviderArn: output.samlProviderArn })
        .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
    }),
  });