sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Cognito/ UserPoolClient.ts

import * as cip from "@distilled.cloud/aws/cognito-identity-provider";
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 Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * The authentication flows an app client is allowed to use.
 */
export type ExplicitAuthFlow =
  | "ALLOW_USER_PASSWORD_AUTH"
  | "ALLOW_ADMIN_USER_PASSWORD_AUTH"
  | "ALLOW_USER_SRP_AUTH"
  | "ALLOW_USER_AUTH"
  | "ALLOW_CUSTOM_AUTH"
  | "ALLOW_REFRESH_TOKEN_AUTH";

/** Units for the token validity durations. */
export type TokenValidityUnit = "seconds" | "minutes" | "hours" | "days";

export interface UserPoolClientProps {
  /**
   * The ID of the user pool the client belongs to. Changing this triggers a
   * replacement.
   */
  userPoolId: string;
  /**
   * Name of the app client. If omitted, a deterministic physical name is
   * generated from the app, stage, and logical ID.
   */
  clientName?: string;
  /**
   * Whether to generate a client secret. Confidential (server-side) clients
   * should use a secret; public (browser/mobile) clients must not.
   * Changing this triggers a replacement.
   * @default false
   */
  generateSecret?: boolean;
  /**
   * The authentication flows this client may use, e.g.
   * `ALLOW_USER_PASSWORD_AUTH` for direct username/password sign-in or
   * `ALLOW_USER_SRP_AUTH` for the SRP protocol.
   * @default ALLOW_USER_SRP_AUTH, ALLOW_CUSTOM_AUTH, ALLOW_REFRESH_TOKEN_AUTH
   */
  explicitAuthFlows?: ExplicitAuthFlow[];
  /**
   * Refresh token validity (in `tokenValidityUnits.refreshToken`, default days).
   * @default 30 days
   */
  refreshTokenValidity?: number;
  /**
   * Access token validity (in `tokenValidityUnits.accessToken`, default hours).
   * @default 1 hour
   */
  accessTokenValidity?: number;
  /**
   * ID token validity (in `tokenValidityUnits.idToken`, default hours).
   * @default 1 hour
   */
  idTokenValidity?: number;
  /**
   * Units for the three token validity numbers.
   */
  tokenValidityUnits?: {
    accessToken?: TokenValidityUnit;
    idToken?: TokenValidityUnit;
    refreshToken?: TokenValidityUnit;
  };
  /**
   * User attributes this client may read.
   */
  readAttributes?: string[];
  /**
   * User attributes this client may write.
   */
  writeAttributes?: string[];
  /**
   * Identity providers this client supports, e.g. `COGNITO` or the names of
   * configured `IdentityProvider`s.
   */
  supportedIdentityProviders?: string[];
  /**
   * Allowed OAuth callback (redirect) URLs.
   */
  callbackUrls?: string[];
  /**
   * Allowed OAuth sign-out URLs.
   */
  logoutUrls?: string[];
  /**
   * Default redirect URI; must be listed in `callbackUrls`.
   */
  defaultRedirectUri?: string;
  /**
   * Allowed OAuth flows (`code`, `implicit`, `client_credentials`).
   */
  allowedOAuthFlows?: ("code" | "implicit" | "client_credentials")[];
  /**
   * Allowed OAuth scopes, e.g. `openid`, `email`, or resource-server scopes.
   */
  allowedOAuthScopes?: string[];
  /**
   * Must be `true` for the OAuth settings above to take effect.
   * @default false
   */
  allowedOAuthFlowsUserPoolClient?: boolean;
  /**
   * `ENABLED` returns a generic error for sign-in attempts against
   * non-existent users (prevents user enumeration); `LEGACY` returns the
   * original errors.
   * @default "ENABLED"
   */
  preventUserExistenceErrors?: "ENABLED" | "LEGACY";
  /**
   * Whether issued tokens can be revoked with `RevokeToken`.
   * @default true
   */
  enableTokenRevocation?: boolean;
  /**
   * Duration of the session token in auth challenge flows, e.g.
   * `"5 minutes"` (3-15 minutes). Rounded to whole minutes on the wire.
   * @default 3 minutes
   */
  authSessionValidity?: Duration.Input;
}

export interface UserPoolClient extends Resource<
  "AWS.Cognito.UserPoolClient",
  UserPoolClientProps,
  {
    /** The generated app client ID. */
    clientId: string;
    /** The client secret; defined only when `generateSecret` is true. */
    clientSecret: Redacted.Redacted<string> | undefined;
    /** The name of the app client. */
    clientName: string;
    /** The ID of the user pool the client belongs to. */
    userPoolId: string;
  },
  never,
  Providers
> {}

/**
 * An app client of an Amazon Cognito user pool. Applications authenticate
 * against the pool through a client, which controls the allowed auth flows,
 * token lifetimes, and OAuth settings.
 * ### Creating an App Client
 * **Example:** Public Client with Password Auth
 * ```typescript
 * import * as Cognito from "@alchemy.run/aws/Cognito";
 *
 * const pool = yield* Cognito.UserPool("Users", {});
 * const client = yield* Cognito.UserPoolClient("Web", {
 *   userPoolId: pool.userPoolId,
 *   explicitAuthFlows: ["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
 * });
 * ```
 *
 * **Example:** Confidential Client with a Secret
 * ```typescript
 * const server = yield* Cognito.UserPoolClient("Server", {
 *   userPoolId: pool.userPoolId,
 *   generateSecret: true,
 *   explicitAuthFlows: ["ALLOW_ADMIN_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
 * });
 * ```
 *
 * ### Token Configuration
 * **Example:** Short-Lived Access Tokens
 * ```typescript
 * const client = yield* Cognito.UserPoolClient("Web", {
 *   userPoolId: pool.userPoolId,
 *   accessTokenValidity: 30,
 *   idTokenValidity: 30,
 *   refreshTokenValidity: 7,
 *   tokenValidityUnits: {
 *     accessToken: "minutes",
 *     idToken: "minutes",
 *     refreshToken: "days",
 *   },
 * });
 * ```
 *
 * ### OAuth
 * **Example:** Authorization Code Flow
 * ```typescript
 * const client = yield* Cognito.UserPoolClient("Web", {
 *   userPoolId: pool.userPoolId,
 *   allowedOAuthFlowsUserPoolClient: true,
 *   allowedOAuthFlows: ["code"],
 *   allowedOAuthScopes: ["openid", "email"],
 *   callbackUrls: ["https://example.com/callback"],
 *   supportedIdentityProviders: ["COGNITO"],
 * });
 * ```
 *
 * @resource
 */
export const UserPoolClient = Resource<UserPoolClient>("AWS.Cognito.UserPoolClient");

const plain = (value: string | Redacted.Redacted<string> | undefined): string | undefined =>
  value === undefined ? undefined : typeof value === "string" ? value : Redacted.value(value);

/** The mutable desired state, in wire shape — used both as the update body
 * and (against the observed client) for drift detection. */
const desiredConfig = (news: UserPoolClientProps) => ({
  ExplicitAuthFlows: news.explicitAuthFlows,
  RefreshTokenValidity: news.refreshTokenValidity,
  AccessTokenValidity: news.accessTokenValidity,
  IdTokenValidity: news.idTokenValidity,
  TokenValidityUnits:
    news.tokenValidityUnits === undefined
      ? undefined
      : {
          AccessToken: news.tokenValidityUnits.accessToken,
          IdToken: news.tokenValidityUnits.idToken,
          RefreshToken: news.tokenValidityUnits.refreshToken,
        },
  ReadAttributes: news.readAttributes,
  WriteAttributes: news.writeAttributes,
  SupportedIdentityProviders: news.supportedIdentityProviders,
  CallbackURLs: news.callbackUrls,
  LogoutURLs: news.logoutUrls,
  DefaultRedirectURI: news.defaultRedirectUri,
  AllowedOAuthFlows: news.allowedOAuthFlows,
  AllowedOAuthScopes: news.allowedOAuthScopes,
  AllowedOAuthFlowsUserPoolClient: news.allowedOAuthFlowsUserPoolClient,
  PreventUserExistenceErrors: news.preventUserExistenceErrors,
  EnableTokenRevocation: news.enableTokenRevocation,
  // The Cognito wire unit for AuthSessionValidity is whole minutes.
  AuthSessionValidity: toWireMinutes(news.authSessionValidity),
});

/** True when any prop the user specified differs from the observed client.
 * Unspecified props are "don't care". */
const hasDrift = (
  news: UserPoolClientProps,
  clientName: string,
  observed: cip.UserPoolClientType,
) => {
  if (observed.ClientName !== clientName) return true;
  const desired = desiredConfig(news);
  const observedSubset: Record<string, unknown> = {
    ExplicitAuthFlows: [...(observed.ExplicitAuthFlows ?? [])].sort(),
    RefreshTokenValidity: observed.RefreshTokenValidity,
    AccessTokenValidity: observed.AccessTokenValidity,
    IdTokenValidity: observed.IdTokenValidity,
    TokenValidityUnits: {
      AccessToken: observed.TokenValidityUnits?.AccessToken,
      IdToken: observed.TokenValidityUnits?.IdToken,
      RefreshToken: observed.TokenValidityUnits?.RefreshToken,
    },
    ReadAttributes: [...(observed.ReadAttributes ?? [])].sort(),
    WriteAttributes: [...(observed.WriteAttributes ?? [])].sort(),
    SupportedIdentityProviders: [...(observed.SupportedIdentityProviders ?? [])].sort(),
    CallbackURLs: [...(observed.CallbackURLs ?? [])].sort(),
    LogoutURLs: [...(observed.LogoutURLs ?? [])].sort(),
    DefaultRedirectURI: observed.DefaultRedirectURI,
    AllowedOAuthFlows: [...(observed.AllowedOAuthFlows ?? [])].sort(),
    AllowedOAuthScopes: [...(observed.AllowedOAuthScopes ?? [])].sort(),
    AllowedOAuthFlowsUserPoolClient: observed.AllowedOAuthFlowsUserPoolClient,
    PreventUserExistenceErrors: observed.PreventUserExistenceErrors,
    EnableTokenRevocation: observed.EnableTokenRevocation,
    AuthSessionValidity: observed.AuthSessionValidity,
  };
  for (const [key, desiredValue] of Object.entries(desired)) {
    if (desiredValue === undefined) continue;
    const observedValue = observedSubset[key];
    const normalizedDesired = Array.isArray(desiredValue) ? [...desiredValue].sort() : desiredValue;
    if (JSON.stringify(normalizedDesired) !== JSON.stringify(observedValue)) {
      return true;
    }
  }
  return false;
};

export const UserPoolClientProvider = () =>
  Provider.effect(
    UserPoolClient,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<UserPoolClientProps, "clientName">,
      ) {
        return props.clientName ?? (yield* createPhysicalName({ id, maxLength: 128 }));
      });

      const describeClient = Effect.fn(function* (userPoolId: string, clientId: string) {
        return yield* cip
          .describeUserPoolClient({
            UserPoolId: userPoolId,
            ClientId: clientId,
          })
          .pipe(
            Effect.map((r) => r.UserPoolClient),
            Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
          );
      });

      /** Find a client of the pool by exact name (used when state was lost).
       * The physical name embeds app/stage/id, so a match is ours. */
      const findClientByName = Effect.fn(function* (userPoolId: string, clientName: string) {
        const pages = yield* cip.listUserPoolClients
          .pages({ UserPoolId: userPoolId, MaxResults: 60 })
          .pipe(
            Stream.runCollect,
            Effect.catchTag("ResourceNotFoundException", () =>
              Effect.succeed([] as cip.ListUserPoolClientsResponse[]),
            ),
          );
        const match = Array.from(pages)
          .flatMap((page) => page.UserPoolClients ?? [])
          .find((client) => client.ClientName === clientName);
        if (match?.ClientId === undefined) return undefined;
        return yield* describeClient(userPoolId, plain(match.ClientId)!);
      });

      const attributesOf = (client: cip.UserPoolClientType) => {
        const secret = plain(client.ClientSecret);
        return {
          clientId: plain(client.ClientId)!,
          clientSecret: secret === undefined ? undefined : Redacted.make(secret),
          clientName: client.ClientName!,
          userPoolId: client.UserPoolId!,
        };
      };

      return UserPoolClient.Provider.of({
        stables: ["clientId", "userPoolId"],

        // Sub-resource keyed entirely by its user pool (userPoolId) with no
        // global enumeration API of its own — nuke reaches it through the
        // parent pool's deletion, so enumeration returns empty per the
        // ProviderService doctrine.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          const userPoolId = output?.userPoolId ?? olds?.userPoolId;
          if (userPoolId === undefined) return undefined;
          const observed =
            output?.clientId !== undefined
              ? yield* describeClient(userPoolId, output.clientId)
              : yield* findClientByName(userPoolId, yield* createName(id, olds ?? {}));
          return observed === undefined ? undefined : attributesOf(observed);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          if ((olds?.generateSecret ?? false) !== (news?.generateSecret ?? false)) {
            return { action: "replace" } as const;
          }
          if (olds?.userPoolId !== news?.userPoolId) {
            return { action: "replace" } as const;
          }
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (oldName !== newName) {
            // ClientName is mutable via UpdateUserPoolClient — fall through
            // to the default update path.
            return undefined;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const clientName = output?.clientName ?? (yield* createName(id, news));
          const userPoolId = news.userPoolId;

          // 1. OBSERVE — output.clientId is only a cache.
          let observed =
            output?.clientId !== undefined
              ? yield* describeClient(userPoolId, output.clientId)
              : undefined;
          if (observed === undefined) {
            observed = yield* findClientByName(userPoolId, clientName);
          }

          // 2. ENSURE — create when missing.
          if (observed === undefined) {
            observed = yield* cip
              .createUserPoolClient({
                UserPoolId: userPoolId,
                ClientName: clientName,
                GenerateSecret: news.generateSecret,
                ...desiredConfig(news),
              })
              .pipe(Effect.map((r) => r.UserPoolClient!));
          } else if (hasDrift(news, clientName, observed)) {
            // 3. SYNC — UpdateUserPoolClient resets omitted fields to
            //    defaults, so the body is the full desired state; skip the
            //    call when nothing drifted.
            observed = yield* cip
              .updateUserPoolClient({
                UserPoolId: userPoolId,
                ClientId: plain(observed.ClientId)!,
                ClientName: clientName,
                ...desiredConfig(news),
              })
              .pipe(Effect.map((r) => r.UserPoolClient!));
          }

          const attrs = attributesOf(observed);
          yield* session.note(attrs.clientId);
          return attrs;
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* cip
            .deleteUserPoolClient({
              UserPoolId: output.userPoolId,
              ClientId: output.clientId,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );