sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OpenSearchServerless/ SecurityConfig.ts

import * as aoss from "@distilled.cloud/aws/opensearchserverless";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { toWireMinutes } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { retryWhileConflict } from "./internal.ts";

/**
 * The kind of security configuration:
 * - `saml` — SAML federation with an external identity provider.
 * - `iamidentitycenter` — AWS IAM Identity Center integration.
 * - `iamfederation` — IAM federation via session attributes.
 */
export type SecurityConfigType = "saml" | "iamidentitycenter" | "iamfederation";

export interface SamlOptions {
  /**
   * The XML IdP metadata document generated by the identity provider.
   */
  metadata: string;
  /**
   * A user attribute for the SAML assertion.
   */
  userAttribute?: string;
  /**
   * A group attribute for the SAML assertion.
   */
  groupAttribute?: string;
  /**
   * Custom entity ID used as the audience restriction of the SAML assertion.
   */
  openSearchServerlessEntityId?: string;
  /**
   * How long a SAML session remains valid. Accepts any `Duration.Input`
   * (e.g. `"2 hours"`, `Duration.minutes(90)`; a bare number is milliseconds);
   * the wire unit is minutes.
   * @default 60 minutes (maximum 12 hours)
   */
  sessionTimeout?: Duration.Input;
}

export interface IamIdentityCenterOptions {
  /**
   * ARN of the IAM Identity Center instance.
   */
  instanceArn: string;
  /**
   * The user attribute to map (e.g. `UserId`, `UserName`, `Email`).
   */
  userAttribute?: string;
  /**
   * The group attribute to map (e.g. `GroupId`, `GroupName`).
   */
  groupAttribute?: string;
}

export interface IamFederationOptions {
  /**
   * The session attribute that carries the user identity.
   */
  userAttribute?: string;
  /**
   * The session attribute that carries the user's groups.
   */
  groupAttribute?: string;
}

export interface SecurityConfigProps {
  /**
   * Name of the security configuration (3-32 characters, lowercase). Changing
   * the name replaces the configuration.
   * @default a generated physical name
   */
  configName?: string;
  /**
   * The configuration kind (`saml`, `iamidentitycenter`, or `iamfederation`).
   * Changing the type replaces the configuration.
   */
  type: SecurityConfigType;
  /**
   * A human-readable description of the configuration.
   */
  description?: string;
  /**
   * SAML options — required when `type` is `saml`.
   */
  samlOptions?: SamlOptions;
  /**
   * IAM Identity Center options — required when `type` is
   * `iamidentitycenter`. `instanceArn` is create-only.
   */
  iamIdentityCenterOptions?: IamIdentityCenterOptions;
  /**
   * IAM federation options — required when `type` is `iamfederation`.
   */
  iamFederationOptions?: IamFederationOptions;
}

export interface SecurityConfig extends Resource<
  "AWS.OpenSearchServerless.SecurityConfig",
  SecurityConfigProps,
  {
    /**
     * Unique identifier of the security configuration, in the format
     * `{type}/{accountId}/{name}`. Use this as the `Principal` in a data
     * access policy to grant federated identities access.
     */
    configId: string;
    /**
     * Name of the security configuration.
     */
    configName: string;
    /**
     * Configuration type (`saml`, `iamidentitycenter`, or `iamfederation`).
     */
    type: string;
    /**
     * Version of the configuration, used for optimistic-concurrency updates.
     */
    configVersion: string;
    /**
     * Description of the security configuration.
     */
    description?: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon OpenSearch Serverless security configuration. Security
 * configurations federate OpenSearch Dashboards sign-in with SAML identity
 * providers, AWS IAM Identity Center, or IAM federation, so human users can
 * access collections without IAM credentials.
 *
 * The configuration's `configId` (format `saml/{accountId}/{name}`) is what a
 * data {@link AccessPolicy} references as a `Principal` to grant the federated
 * identities index- and collection-level permissions.
 *
 * ### SAML Authentication
 * **Example:** Federate Dashboards with a SAML Identity Provider
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const saml = yield* AWS.OpenSearchServerless.SecurityConfig("Saml", {
 *   configName: "my-idp",
 *   type: "saml",
 *   samlOptions: {
 *     metadata: idpMetadataXml,
 *     groupAttribute: "groups",
 *     sessionTimeout: "4 hours",
 *   },
 * });
 * // Reference saml.configId as a Principal in a data access policy
 * ```
 *
 * ### IAM Federation
 * **Example:** Map Session Attributes to Identities
 * ```typescript
 * const federation = yield* AWS.OpenSearchServerless.SecurityConfig("Federation", {
 *   configName: "my-federation",
 *   type: "iamfederation",
 *   iamFederationOptions: {
 *     userAttribute: "user",
 *     groupAttribute: "groups",
 *   },
 * });
 * ```
 *
 * @resource
 */
export const SecurityConfig = Resource<SecurityConfig>("AWS.OpenSearchServerless.SecurityConfig");

export const SecurityConfigProvider = () =>
  Provider.effect(
    SecurityConfig,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { configName?: string | undefined },
      ) {
        return (
          props.configName ?? (yield* createPhysicalName({ id, maxLength: 32, lowercase: true }))
        );
      });

      // A security config's id is deterministic: {type}/{accountId}/{name}.
      const computeConfigId = Effect.fn(function* (type: string, name: string) {
        const { accountId } = yield* AWSEnvironment.current;
        return `${type}/${accountId}/${name}`;
      });

      const toName = (configId: string) => configId.split("/").at(-1)!;

      const toAttributes = (detail: aoss.SecurityConfigDetail) => ({
        configId: detail.id!,
        configName: toName(detail.id!),
        type: detail.type!,
        configVersion: detail.configVersion!,
        description: detail.description,
      });

      const toWireSamlOptions = (saml: SamlOptions | undefined) =>
        saml === undefined
          ? undefined
          : {
              metadata: saml.metadata,
              userAttribute: saml.userAttribute,
              groupAttribute: saml.groupAttribute,
              openSearchServerlessEntityId: saml.openSearchServerlessEntityId,
              sessionTimeout: toWireMinutes(saml.sessionTimeout),
            };

      const observe = Effect.fn(function* (configId: string) {
        return yield* aoss.getSecurityConfig({ id: configId }).pipe(
          Effect.map((r) => r.securityConfigDetail),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      return SecurityConfig.Provider.of({
        stables: ["configId", "configName", "type"],

        list: () =>
          Effect.gen(function* () {
            const types: SecurityConfigType[] = ["saml", "iamidentitycenter", "iamfederation"];
            const results: {
              configId: string;
              configName: string;
              type: string;
              configVersion: string;
              description?: string;
            }[] = [];
            for (const type of types) {
              const pages = yield* aoss.listSecurityConfigs.pages({ type }).pipe(Stream.runCollect);
              for (const page of pages) {
                for (const s of page.securityConfigSummaries ?? []) {
                  if (s.id !== undefined && s.type !== undefined && s.configVersion !== undefined) {
                    results.push({
                      configId: s.id,
                      configName: toName(s.id),
                      type: s.type,
                      configVersion: s.configVersion,
                      description: s.description,
                    });
                  }
                }
              }
            }
            return results;
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const type = output?.type ?? olds?.type;
          if (type === undefined) {
            return undefined;
          }
          const configId =
            output?.configId ?? (yield* computeConfigId(type, yield* createName(id, olds ?? {})));
          const detail = yield* observe(configId);
          if (detail?.id === undefined) {
            return undefined;
          }
          // Security configs carry no tags, so an existing same-name config is
          // adopted.
          return toAttributes(detail);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds.type !== news.type) {
            return { action: "replace" } as const;
          }
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // description/options fall through to the default update path
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const type = news.type;
          const name = output?.configName ?? (yield* createName(id, news));
          const configId = output?.configId ?? (yield* computeConfigId(type, name));
          const desiredSaml = toWireSamlOptions(news.samlOptions);

          // 1. OBSERVE
          let detail = yield* observe(configId);

          // 2. ENSURE — create if missing; tolerate a concurrent create race
          if (detail?.id === undefined) {
            detail = yield* aoss
              .createSecurityConfig({
                type,
                name,
                description: news.description,
                samlOptions: desiredSaml,
                iamIdentityCenterOptions: news.iamIdentityCenterOptions,
                iamFederationOptions: news.iamFederationOptions,
              })
              .pipe(
                Effect.map((r) => r.securityConfigDetail),
                Effect.catchTag("ConflictException", () => observe(configId)),
              );
          } else {
            // 3. SYNC — update when observed drifts from desired
            const samlDrift =
              desiredSaml !== undefined &&
              (desiredSaml.metadata !== detail.samlOptions?.metadata ||
                desiredSaml.userAttribute !== detail.samlOptions?.userAttribute ||
                desiredSaml.groupAttribute !== detail.samlOptions?.groupAttribute ||
                (desiredSaml.sessionTimeout !== undefined &&
                  desiredSaml.sessionTimeout !== detail.samlOptions?.sessionTimeout));
            const federationDrift =
              news.iamFederationOptions !== undefined &&
              (news.iamFederationOptions.userAttribute !==
                detail.iamFederationOptions?.userAttribute ||
                news.iamFederationOptions.groupAttribute !==
                  detail.iamFederationOptions?.groupAttribute);
            const identityCenterDrift =
              news.iamIdentityCenterOptions !== undefined &&
              (news.iamIdentityCenterOptions.userAttribute !==
                detail.iamIdentityCenterOptions?.userAttribute ||
                news.iamIdentityCenterOptions.groupAttribute !==
                  detail.iamIdentityCenterOptions?.groupAttribute);
            const descriptionDrift =
              news.description !== undefined && news.description !== detail.description;
            if (samlDrift || federationDrift || identityCenterDrift || descriptionDrift) {
              detail = yield* aoss
                .updateSecurityConfig({
                  id: detail.id,
                  configVersion: detail.configVersion!,
                  description: descriptionDrift ? news.description : undefined,
                  samlOptions: samlDrift ? desiredSaml : undefined,
                  iamIdentityCenterOptionsUpdates: identityCenterDrift
                    ? {
                        userAttribute: news.iamIdentityCenterOptions?.userAttribute,
                        groupAttribute: news.iamIdentityCenterOptions?.groupAttribute,
                      }
                    : undefined,
                  iamFederationOptions: federationDrift ? news.iamFederationOptions : undefined,
                })
                .pipe(Effect.map((r) => r.securityConfigDetail));
            }
          }

          if (detail?.id === undefined) {
            return yield* aoss.ResourceNotFoundException.make({
              message: `security config ${configId} not visible after reconcile`,
            });
          }
          yield* session.note(detail.id);
          return toAttributes(detail);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileConflict(aoss.deleteSecurityConfig({ id: output.configId })).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );