sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ControlTower/ EnabledControl.ts

import * as controltower from "@distilled.cloud/aws/controltower";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
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 { canonicalParameters, observeControlTowerTags, syncControlTowerTags } from "./internal.ts";

export interface EnabledControlProps {
  /**
   * The identifier (ARN) of the control to enable, e.g.
   * `arn:aws:controltower:us-west-2::control/AWS-GR_ENCRYPTED_VOLUMES` or a
   * Control Catalog ARN. Changing the control replaces the enablement.
   */
  controlIdentifier: string;
  /**
   * The ARN of the organizational unit the control is enabled on.
   * Changing the target replaces the enablement.
   */
  targetIdentifier: string;
  /**
   * Parameters for configurable controls, as `{ key, value }` pairs.
   * Updated in place via `UpdateEnabledControl`.
   */
  parameters?: { key: string; value: any }[];
  /**
   * Tags to apply to the enabled control. Merged with internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface EnabledControl extends Resource<
  "AWS.ControlTower.EnabledControl",
  EnabledControlProps,
  {
    /**
     * The ARN of the enabled control.
     */
    enabledControlArn: string;
    /**
     * The identifier of the enabled control.
     */
    controlIdentifier: string;
    /**
     * The ARN of the organizational unit the control is enabled on.
     */
    targetIdentifier: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Control Tower control (guardrail) enabled on an organizational
 * unit. Enabling a control starts an asynchronous operation that deploys
 * governance resources (SCPs, Config rules, or hooks) to the OU and the
 * accounts it contains.
 *
 * Requires an AWS Control Tower landing zone and can only be managed from
 * the Organizations management account.
 * ### Enabling Controls
 * **Example:** Enable a preventive guardrail on an OU
 * ```typescript
 * import * as ControlTower from "@alchemy.run/aws/ControlTower";
 *
 * const encryptedVolumes = yield* ControlTower.EnabledControl("EncryptedVolumes", {
 *   controlIdentifier:
 *     "arn:aws:controltower:us-west-2::control/AWS-GR_ENCRYPTED_VOLUMES",
 *   targetIdentifier: "arn:aws:organizations::111122223333:ou/o-example/ou-example",
 * });
 * ```
 *
 * **Example:** Enable a configurable control with parameters
 * ```typescript
 * const regionDeny = yield* ControlTower.EnabledControl("RegionDeny", {
 *   controlIdentifier:
 *     "arn:aws:controlcatalog:::control/50utmyu7yqmhr8fpnpo8bnaj1",
 *   targetIdentifier: ouArn,
 *   parameters: [
 *     { key: "AllowedRegions", value: ["us-east-1", "us-west-2"] },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const EnabledControl = Resource<EnabledControl>("AWS.ControlTower.EnabledControl");

/**
 * An asynchronous control operation (ENABLE_CONTROL / DISABLE_CONTROL /
 * UPDATE_ENABLED_CONTROL) converged to the terminal `FAILED` status.
 */
export class ControlOperationFailed extends Data.TaggedError("ControlOperationFailed")<{
  readonly operationIdentifier: string;
  readonly status: string;
  readonly statusMessage: string | undefined;
}> {}

/**
 * `EnableControl` succeeded but the enabled control's ARN could not be
 * resolved from either the operation output or `ListEnabledControls`.
 */
export class EnabledControlArnUnavailable extends Data.TaggedError("EnabledControlArnUnavailable")<{
  readonly controlIdentifier: string;
  readonly targetIdentifier: string;
}> {}

/**
 * Internal signal that a control operation is still `IN_PROGRESS`,
 * consumed by {@link waitForControlOperation}'s bounded schedule.
 */
class ControlOperationPending extends Data.TaggedError("ControlOperationPending")<{
  readonly operationIdentifier: string;
  readonly status: string | undefined;
}> {}

// Explicitly-typed retry wrappers — an inline `Effect.retry` in provider
// lifecycle code leaks `Retry.Return`'s conditional type into declaration
// emit and widens the provider layer to `unknown` for every consumer of
// `AWS.providers()`.
const retryWhileControlOperationPending = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ControlOperationPending",
    // Control operations deploy SCPs/Config rules across an OU's accounts
    // and typically take a few minutes; poll every 10s up to ~15 minutes.
    schedule: Schedule.max([Schedule.spaced("10 seconds"), Schedule.recurs(90)]),
  });

// Control Tower serializes control operations per OU — a concurrent
// operation surfaces as a typed ConflictException. Retry through it on a
// bounded schedule.
const retryWhileControlConflict = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.spaced("15 seconds"), Schedule.recurs(40)]),
  });

const waitForControlOperation = (operationIdentifier: string) =>
  retryWhileControlOperationPending(
    Effect.gen(function* () {
      const { controlOperation } = yield* controltower.getControlOperation({
        operationIdentifier,
      });
      if (controlOperation.status === "SUCCEEDED") {
        return;
      }
      if (controlOperation.status === "FAILED") {
        return yield* new ControlOperationFailed({
          operationIdentifier,
          status: controlOperation.status,
          statusMessage: controlOperation.statusMessage,
        });
      }
      return yield* new ControlOperationPending({
        operationIdentifier,
        status: controlOperation.status,
      });
    }),
  );

const readEnabledControl = (enabledControlArn: string) =>
  controltower.getEnabledControl({ enabledControlIdentifier: enabledControlArn }).pipe(
    Effect.map((r) => r.enabledControlDetails),
    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
  );

// Find an enabled control by (controlIdentifier, targetIdentifier) —
// covers the create-race and lost-output cases where we don't have the
// ARN cached.
const findEnabledControlArn = (controlIdentifier: string, targetIdentifier: string) =>
  controltower.listEnabledControls.pages({ targetIdentifier }).pipe(
    Stream.runCollect,
    Effect.map(
      (chunk) =>
        Array.from(chunk)
          .flatMap((page) => page.enabledControls)
          .find((summary) => summary.controlIdentifier === controlIdentifier)?.arn,
    ),
    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
  );

export const EnabledControlProvider = () =>
  Provider.effect(
    EnabledControl,
    Effect.gen(function* () {
      return EnabledControl.Provider.of({
        stables: ["enabledControlArn", "controlIdentifier", "targetIdentifier"],
        // Enumeration requires a target OU — there is no org-wide listing
        // that returns the full attribute shape without the management
        // account's OU tree, so nuke discovery is not supported.
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ id, olds, output }) {
          const arn =
            output?.enabledControlArn ??
            (olds !== undefined
              ? yield* findEnabledControlArn(olds.controlIdentifier, olds.targetIdentifier)
              : undefined);
          if (arn === undefined) return undefined;
          const details = yield* readEnabledControl(arn);
          if (details === undefined) return undefined;
          const attrs = {
            enabledControlArn: arn,
            controlIdentifier: details.controlIdentifier ?? olds?.controlIdentifier ?? "",
            targetIdentifier: details.targetIdentifier ?? olds?.targetIdentifier ?? "",
          };
          const tags = yield* observeControlTowerTags(arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (
            news.controlIdentifier !== olds.controlIdentifier ||
            news.targetIdentifier !== olds.targetIdentifier
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // 1. Observe — cloud state is authoritative; output is only an
          //    ARN cache.
          let arn = output?.enabledControlArn;
          let details = arn === undefined ? undefined : yield* readEnabledControl(arn);
          if (details === undefined) {
            arn = yield* findEnabledControlArn(news.controlIdentifier, news.targetIdentifier);
            details = arn === undefined ? undefined : yield* readEnabledControl(arn);
          }

          // 2. Ensure — enable if missing and wait for the asynchronous
          //    operation to converge.
          if (details === undefined) {
            const internalTags = yield* createInternalTags(id);
            const enabled = yield* retryWhileControlConflict(
              controltower.enableControl({
                controlIdentifier: news.controlIdentifier,
                targetIdentifier: news.targetIdentifier,
                parameters: news.parameters,
                tags: { ...news.tags, ...internalTags },
              }),
            );
            yield* session.note(`control operation ${enabled.operationIdentifier}`);
            yield* waitForControlOperation(enabled.operationIdentifier);
            arn =
              enabled.arn ??
              (yield* findEnabledControlArn(news.controlIdentifier, news.targetIdentifier));
            if (arn === undefined) {
              return yield* new EnabledControlArnUnavailable({
                controlIdentifier: news.controlIdentifier,
                targetIdentifier: news.targetIdentifier,
              });
            }
            details = yield* readEnabledControl(arn);
          } else if (news.parameters !== undefined) {
            // 3. Sync — parameters are the only in-place-mutable aspect.
            //    Diff observed parameter summaries against desired; skip
            //    the API on a no-op. Parameters cannot be cleared (the
            //    update API requires them), so an absent `parameters` prop
            //    leaves observed parameters alone.
            const observed = canonicalParameters(details.parameters);
            const desired = canonicalParameters(news.parameters);
            if (observed !== desired) {
              const updated = yield* retryWhileControlConflict(
                controltower.updateEnabledControl({
                  enabledControlIdentifier: arn!,
                  parameters: news.parameters,
                }),
              );
              yield* session.note(`control operation ${updated.operationIdentifier}`);
              yield* waitForControlOperation(updated.operationIdentifier);
            }
          }

          // 3b. Sync tags against observed cloud tags.
          yield* syncControlTowerTags(arn!, id, news.tags);

          // 4. Return fresh attributes.
          return {
            enabledControlArn: arn!,
            controlIdentifier: news.controlIdentifier,
            targetIdentifier: news.targetIdentifier,
          };
        }),
        delete: Effect.fn(function* ({ output, session }) {
          const result = yield* retryWhileControlConflict(
            controltower.disableControl({
              enabledControlIdentifier: output.enabledControlArn,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          if (result !== undefined) {
            yield* session.note(`control operation ${result.operationIdentifier}`);
            yield* waitForControlOperation(result.operationIdentifier);
          }
        }),
      });
    }),
  );