sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Cognito/ User.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 * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import type { Providers } from "../Providers.ts";

export interface UserProps {
  /**
   * The ID of the user pool the user belongs to. Changing this triggers a
   * replacement.
   */
  userPoolId: string;
  /**
   * The username. If omitted, a deterministic physical name is generated
   * from the app, stage, and logical ID. Changing this triggers a
   * replacement. For pools with `usernameAttributes` this must be a value
   * of one of those attributes (e.g. an email address).
   */
  username?: string;
  /**
   * User attributes as name → value pairs (e.g.
   * `{ email: "a@b.com", email_verified: "true" }`). Attributes declared
   * here are kept in sync; removing a previously declared attribute deletes
   * it from the user.
   */
  attributes?: Record<string, string>;
  /**
   * A permanent password for the user, set via `AdminSetUserPassword`
   * (`Permanent: true`), which moves the user to `CONFIRMED`. Without it
   * the user is created in `FORCE_CHANGE_PASSWORD` state. Must satisfy the
   * pool's password policy. Wrap with `Redacted.make(...)` so the value
   * never leaks into logs or state output.
   */
  password?: Redacted.Redacted<string>;
  /**
   * Whether the user account is enabled.
   * @default true
   */
  enabled?: boolean;
}

export interface User extends Resource<
  "AWS.Cognito.User",
  UserProps,
  {
    /** The username. */
    username: string;
    /** The ID of the user pool the user belongs to. */
    userPoolId: string;
    /** The user's stable unique identifier (the `sub` attribute). */
    sub: string;
    /** The user's status, e.g. `CONFIRMED` or `FORCE_CHANGE_PASSWORD`. */
    userStatus: string;
  },
  never,
  Providers
> {}

/**
 * A user within an Amazon Cognito user pool, created administratively via
 * `AdminCreateUser`. The invitation message is always suppressed
 * (`MessageAction: SUPPRESS`) — declaratively managed users never trigger
 * invite emails/SMS; set a permanent `password` to make the account usable
 * immediately.
 * ### Creating Users
 * **Example:** Basic User
 * ```typescript
 * import * as Cognito from "@alchemy.run/aws/Cognito";
 *
 * const pool = yield* Cognito.UserPool("Users", {});
 * const user = yield* Cognito.User("Admin", {
 *   userPoolId: pool.userPoolId,
 *   attributes: { email: "admin@example.com", email_verified: "true" },
 * });
 * ```
 *
 * **Example:** Confirmed User with a Permanent Password
 * ```typescript
 * import * as Redacted from "effect/Redacted";
 *
 * const user = yield* Cognito.User("ServiceAccount", {
 *   userPoolId: pool.userPoolId,
 *   username: "service-account",
 *   password: Redacted.make("A-Str0ng-Passw0rd!"),
 *   attributes: { email: "svc@example.com", email_verified: "true" },
 * });
 * // user.userStatus === "CONFIRMED"
 * ```
 *
 * @resource
 */
export const User = Resource<User>("AWS.Cognito.User");

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

/** Observed user attributes as a plain name → value record. */
const attributeRecordOf = (attributes: cip.AttributeType[] | undefined): Record<string, string> =>
  Object.fromEntries(
    (attributes ?? []).flatMap((attribute) => {
      const value = plain(attribute.Value);
      return value === undefined ? [] : [[attribute.Name, value] as const];
    }),
  );

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

      const getUser = Effect.fn(function* (userPoolId: string, username: string) {
        return yield* cip
          .adminGetUser({ UserPoolId: userPoolId, Username: username })
          .pipe(
            Effect.catchTag(
              ["UserNotFoundException", "ResourceNotFoundException"],
              () => Effect.undefined,
            ),
          );
      });

      const attributesOf = (
        username: string,
        userPoolId: string,
        observed: cip.AdminGetUserResponse,
      ) => ({
        username,
        userPoolId,
        sub: attributeRecordOf(observed.UserAttributes).sub ?? "",
        userStatus: observed.UserStatus ?? "UNKNOWN",
      });

      return User.Provider.of({
        stables: ["username", "userPoolId", "sub"],

        // Sub-resource keyed entirely by its user pool (userPoolId) with no
        // global enumeration API of its own — nuke reaches it through the
        // parent'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 username = output?.username ?? (yield* createName(id, olds ?? {}));
          const observed = yield* getUser(userPoolId, username);
          return observed === undefined ? undefined : attributesOf(username, userPoolId, observed);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (oldName !== newName || olds?.userPoolId !== news?.userPoolId) {
            return { action: "replace" } as const;
          }
        }),

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

          // 1. OBSERVE — cloud state is authoritative.
          let observed = yield* getUser(userPoolId, username);

          // 2. ENSURE — create when missing (invitation always suppressed);
          //    tolerate the create race.
          if (observed === undefined) {
            yield* cip
              .adminCreateUser({
                UserPoolId: userPoolId,
                Username: username,
                MessageAction: "SUPPRESS",
                UserAttributes: Object.entries(desiredAttributes).map(([Name, Value]) => ({
                  Name,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("UsernameExistsException", () => Effect.void));
            observed = yield* getUser(userPoolId, username);
          } else {
            // 3. SYNC ATTRIBUTES — upsert declared attributes that drifted
            //    from the OBSERVED values; delete attributes that were
            //    previously declared but no longer are (`olds` is only the
            //    hint for which attributes we manage — never for values).
            const observedAttributes = attributeRecordOf(observed.UserAttributes);
            const upsert = Object.entries(desiredAttributes).filter(
              ([name, value]) => observedAttributes[name] !== value,
            );
            if (upsert.length > 0) {
              yield* cip.adminUpdateUserAttributes({
                UserPoolId: userPoolId,
                Username: username,
                UserAttributes: upsert.map(([Name, Value]) => ({
                  Name,
                  Value,
                })),
              });
            }
            const removed = Object.keys(olds?.attributes ?? {}).filter(
              (name) =>
                desiredAttributes[name] === undefined && observedAttributes[name] !== undefined,
            );
            if (removed.length > 0) {
              yield* cip.adminDeleteUserAttributes({
                UserPoolId: userPoolId,
                Username: username,
                UserAttributeNames: removed,
              });
            }
          }

          if (observed === undefined) {
            return yield* Effect.die(`Cognito user ${username} not observable after create`);
          }

          // 3b. SYNC PASSWORD — a permanent password confirms the account.
          //    Passwords are write-only, so `olds` is the only drift signal;
          //    fresh creates and adoptions always apply it.
          if (
            news.password !== undefined &&
            (output === undefined ||
              olds === undefined ||
              plain(olds.password) !== plain(news.password))
          ) {
            yield* cip.adminSetUserPassword({
              UserPoolId: userPoolId,
              Username: username,
              Password: news.password,
              Permanent: true,
            });
          }

          // 3c. SYNC ENABLED — diff against the OBSERVED flag.
          const desiredEnabled = news.enabled ?? true;
          if ((observed.Enabled ?? true) !== desiredEnabled) {
            yield* desiredEnabled
              ? cip.adminEnableUser({
                  UserPoolId: userPoolId,
                  Username: username,
                })
              : cip.adminDisableUser({
                  UserPoolId: userPoolId,
                  Username: username,
                });
          }

          // 4. RETURN fresh attributes (status/attributes may have changed
          //    during sync).
          const final = (yield* getUser(userPoolId, username)) ?? observed;
          yield* session.note(username);
          return attributesOf(username, userPoolId, final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* cip
            .adminDeleteUser({
              UserPoolId: output.userPoolId,
              Username: output.username,
            })
            .pipe(
              Effect.catchTag(
                ["UserNotFoundException", "ResourceNotFoundException"],
                () => Effect.void,
              ),
            );
        }),
      });
    }),
  );