sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ EmailIdentity.ts

import * as sesv2 from "@distilled.cloud/aws/sesv2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/**
 * The length of the RSA key pair SES generates for Easy DKIM signing.
 */
export type DkimSigningKeyLength = "RSA_1024_BIT" | "RSA_2048_BIT";

export interface EmailIdentityProps {
  /**
   * The email address or domain to verify with SES, e.g. `hello@example.com`
   * or `example.com`. Changing this replaces the identity.
   *
   * - **Email address** — SES sends a verification email to the address; the
   *   identity stays `PENDING` until the link is clicked.
   * - **Domain** — SES generates Easy DKIM tokens (see the `dkimTokens`
   *   attribute) that must be published as CNAME records; the identity stays
   *   `PENDING` until the DNS records propagate.
   */
  emailIdentity: string;
  /**
   * The configuration set to apply by default to messages sent from this
   * identity. The configuration set must exist in the same region.
   */
  configurationSetName?: string;
  /**
   * The length of the private key SES uses for Easy DKIM signing. Only
   * applies to domain identities.
   * @default "RSA_2048_BIT"
   */
  dkimSigningKeyLength?: DkimSigningKeyLength;
  /**
   * Whether Easy DKIM signing is enabled for the identity. Leave undefined to
   * keep SES's current setting.
   */
  dkimSigningEnabled?: boolean;
  /**
   * Whether SES forwards bounce and complaint feedback to the identity's email
   * address. Leave undefined to keep SES's current setting.
   * @default true
   */
  feedbackForwardingEnabled?: boolean;
  /**
   * A custom MAIL FROM domain (a verified subdomain of the identity) SES uses
   * in the message envelope. Publish the required MX and SPF records for the
   * subdomain to complete setup. Leave undefined to keep SES's current
   * setting — there is no removal path once one is configured.
   */
  mailFromDomain?: string;
  /**
   * What SES does when the custom MAIL FROM domain's MX record can't be read:
   * fall back to the SES default (`USE_DEFAULT_VALUE`) or reject the message
   * (`REJECT_MESSAGE`).
   * @default "USE_DEFAULT_VALUE"
   */
  mailFromBehaviorOnMxFailure?: sesv2.BehaviorOnMxFailure;
  /**
   * Tags to apply to the identity. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface EmailIdentity extends Resource<
  "AWS.SES.EmailIdentity",
  EmailIdentityProps,
  {
    emailIdentity: string;
    identityArn: string;
    identityType: sesv2.IdentityType;
    verifiedForSendingStatus: boolean;
    verificationStatus: sesv2.VerificationStatus | undefined;
    /**
     * The Easy DKIM CNAME tokens for a domain identity. Publish each token as
     * `{token}._domainkey.{domain} CNAME {token}.dkim.amazonses.com` to
     * complete verification. Empty for email-address identities.
     */
    dkimTokens: string[];
    dkimStatus: sesv2.DkimStatus | undefined;
    /**
     * Default configuration set, the declared DKIM, feedback-forwarding and
     * MAIL FROM settings, and the tags, as observed. Lets `alchemy drift`
     * detect out-of-band changes.
     */
    configuration?: {
      configurationSetName?: string;
      dkimSigningEnabled?: boolean;
      dkimSigningKeyLength?: string;
      feedbackForwardingEnabled?: boolean;
      mailFromDomain?: string;
      mailFromBehaviorOnMxFailure?: string;
      tags: Record<string, string>;
    };
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 email identity — a verified email address or domain that
 * you send email from.
 *
 * Creating the identity starts verification: email-address identities receive
 * a verification email, and domain identities get Easy DKIM tokens (exposed
 * as the `dkimTokens` attribute) to publish as CNAME records. The identity
 * is usable for sending once `verificationStatus` is `SUCCESS`.
 * ### Creating Identities
 * **Example:** Domain Identity
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.example.com",
 * });
 * // publish identity.dkimTokens as CNAME records to verify
 * ```
 *
 * **Example:** Email Address Identity
 * ```typescript
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "hello@example.com",
 * });
 * // SES emails hello@example.com a verification link
 * ```
 *
 * ### Configuration Set Association
 * **Example:** Apply a Configuration Set by Default
 * ```typescript
 * const configSet = yield* SES.ConfigurationSet("Tracking", {});
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.example.com",
 *   configurationSetName: configSet.configurationSetName,
 * });
 * ```
 *
 * ### DKIM and Feedback
 * **Example:** Turn Easy DKIM Signing Off
 * ```typescript
 * // Omit the prop entirely to leave SES's current setting alone.
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.example.com",
 *   dkimSigningEnabled: false,
 * });
 * ```
 *
 * **Example:** Stop Forwarding Bounces and Complaints by Email
 * ```typescript
 * // Turn this off once a configuration set event destination is handling
 * // bounces and complaints, so they stop arriving as mail.
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.example.com",
 *   feedbackForwardingEnabled: false,
 * });
 * ```
 *
 * ### Custom MAIL FROM Domain
 * **Example:** Send with Your Own Envelope Domain
 * ```typescript
 * // mailFromDomain must be a subdomain of the identity, and needs MX and
 * // SPF records published before SES will use it.
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.example.com",
 *   mailFromDomain: "bounce.mail.example.com",
 *   // Reject rather than silently falling back to the SES default when the
 *   // MX record cannot be read.
 *   mailFromBehaviorOnMxFailure: "REJECT_MESSAGE",
 * });
 * ```
 *
 * ### Sending Email at Runtime
 * **Example:** Send Through the Identity from a Lambda Function
 * ```typescript
 * // init
 * const sendEmail = yield* SES.SendEmail(identity);
 *
 * // runtime
 * const result = yield* sendEmail({
 *   FromEmailAddress: "hello@mail.example.com",
 *   Destination: { ToAddresses: ["customer@example.com"] },
 *   Content: {
 *     Simple: {
 *       Subject: { Data: "Welcome!" },
 *       Body: { Text: { Data: "Hello from SES." } },
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const EmailIdentity = Resource<EmailIdentity>("AWS.SES.EmailIdentity");

const toTagRecord = (
  tags: ReadonlyArray<{ Key: string; Value: string }> | undefined,
): Record<string, string> => Object.fromEntries((tags ?? []).map((tag) => [tag.Key, tag.Value]));

const identityArnOf = (region: string, accountId: string, name: string) =>
  `arn:aws:ses:${region}:${accountId}:identity/${name}`;

const toAttributes = (
  name: string,
  identityArn: string,
  identity: sesv2.GetEmailIdentityResponse,
) => ({
  emailIdentity: name,
  identityArn,
  identityType: identity.IdentityType ?? "DOMAIN",
  verifiedForSendingStatus: identity.VerifiedForSendingStatus ?? false,
  verificationStatus: identity.VerificationStatus,
  dkimTokens: [...(identity.DkimAttributes?.Tokens ?? [])],
  dkimStatus: identity.DkimAttributes?.Status,
});

/**
 * The settings reconcile converges, as observed. Settings reconcile only
 * applies when declared are only observed when declared. `read` and
 * `reconcile` share it so a converged identity reads unchanged.
 */
const observeIdentityConfiguration = (
  identity: sesv2.GetEmailIdentityResponse,
  props: EmailIdentityProps | undefined,
  tags: Record<string, string>,
) => ({
  configurationSetName: identity.ConfigurationSetName,
  dkimSigningEnabled:
    props?.dkimSigningEnabled === undefined
      ? undefined
      : (identity.DkimAttributes?.SigningEnabled ?? false),
  dkimSigningKeyLength:
    props?.dkimSigningKeyLength === undefined
      ? undefined
      : identity.DkimAttributes?.NextSigningKeyLength,
  feedbackForwardingEnabled:
    props?.feedbackForwardingEnabled === undefined
      ? undefined
      : (identity.FeedbackForwardingStatus ?? true),
  mailFromDomain:
    props?.mailFromDomain === undefined ? undefined : identity.MailFromAttributes?.MailFromDomain,
  mailFromBehaviorOnMxFailure:
    props?.mailFromDomain === undefined || props.mailFromBehaviorOnMxFailure === undefined
      ? undefined
      : identity.MailFromAttributes?.BehaviorOnMxFailure,
  tags,
});

export const EmailIdentityProvider = () =>
  Provider.effect(
    EmailIdentity,
    Effect.gen(function* () {
      const getIdentity = Effect.fn(function* (name: string) {
        return yield* sesv2
          .getEmailIdentity({ EmailIdentity: name })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
      });

      return EmailIdentity.Provider.of({
        stables: ["emailIdentity", "identityArn"],

        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            const pages = yield* sesv2.listEmailIdentities.pages({}).pipe(Stream.runCollect);
            const infos = Array.from(pages).flatMap((page) => page.EmailIdentities ?? []);
            const attrs = yield* Effect.forEach(
              infos.filter(
                (info): info is typeof info & { IdentityName: string } => info.IdentityName != null,
              ),
              (info) =>
                Effect.gen(function* () {
                  const identity = yield* getIdentity(info.IdentityName);
                  return identity === undefined
                    ? undefined
                    : toAttributes(
                        info.IdentityName,
                        identityArnOf(region, accountId, info.IdentityName),
                        identity,
                      );
                }),
              { concurrency: 2 },
            );
            return attrs.filter((a) => a !== undefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.emailIdentity ?? olds?.emailIdentity;
          if (name === undefined) return undefined;
          const found = yield* getIdentity(name);
          if (!found) return undefined;
          const tags = toTagRecord(found.Tags);
          const attrs = {
            ...toAttributes(name, identityArnOf(region, accountId, name), found),
            configuration: observeIdentityConfiguration(found, olds, tags),
          };
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (
            olds?.emailIdentity !== undefined &&
            news?.emailIdentity !== undefined &&
            olds.emailIdentity !== news.emailIdentity
          ) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.emailIdentity ?? news.emailIdentity;
          const identityArn = identityArnOf(region, accountId, name);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative; `output` is only a
          //    cache of the identity name.
          let observed = yield* getIdentity(name);

          // 2. ENSURE — create if missing; AlreadyExists is a race, not a
          //    failure. Creation kicks off verification (email or DKIM DNS).
          if (observed === undefined) {
            yield* sesv2
              .createEmailIdentity({
                EmailIdentity: name,
                ConfigurationSetName: news.configurationSetName,
                DkimSigningAttributes:
                  news.dkimSigningKeyLength !== undefined
                    ? { NextSigningKeyLength: news.dkimSigningKeyLength }
                    : undefined,
                Tags: createTagsList(desiredTags),
              })
              .pipe(Effect.catchTag("AlreadyExistsException", () => Effect.succeed({})));
            observed = yield* sesv2.getEmailIdentity({ EmailIdentity: name });
          }

          // 3. SYNC configuration-set association — compare observed against
          //    desired; passing undefined removes the association.
          if (observed.ConfigurationSetName !== news.configurationSetName) {
            yield* sesv2.putEmailIdentityConfigurationSetAttributes({
              EmailIdentity: name,
              ConfigurationSetName: news.configurationSetName,
            });
          }

          // 3b. SYNC Easy DKIM signing key length (domain identities). Only
          //     applied when explicitly requested and observably different —
          //     rotating the key regenerates the DKIM tokens.
          if (
            news.dkimSigningKeyLength !== undefined &&
            observed.DkimAttributes?.NextSigningKeyLength !== undefined &&
            observed.DkimAttributes.NextSigningKeyLength !== news.dkimSigningKeyLength
          ) {
            yield* sesv2.putEmailIdentityDkimSigningAttributes({
              EmailIdentity: name,
              SigningAttributesOrigin: "AWS_SES",
              SigningAttributes: {
                NextSigningKeyLength: news.dkimSigningKeyLength,
              },
            });
          }

          // 3c. SYNC Easy DKIM signing enablement — only applied when
          //     explicitly requested and observably different.
          if (
            news.dkimSigningEnabled !== undefined &&
            (observed.DkimAttributes?.SigningEnabled ?? false) !== news.dkimSigningEnabled
          ) {
            yield* sesv2.putEmailIdentityDkimAttributes({
              EmailIdentity: name,
              SigningEnabled: news.dkimSigningEnabled,
            });
          }

          // 3d. SYNC feedback forwarding — only applied when explicitly
          //     requested and observably different (SES defaults it to on).
          if (
            news.feedbackForwardingEnabled !== undefined &&
            (observed.FeedbackForwardingStatus ?? true) !== news.feedbackForwardingEnabled
          ) {
            yield* sesv2.putEmailIdentityFeedbackAttributes({
              EmailIdentity: name,
              EmailForwardingEnabled: news.feedbackForwardingEnabled,
            });
          }

          // 3e. SYNC custom MAIL FROM domain — only applied when explicitly
          //     requested and observably different.
          if (
            news.mailFromDomain !== undefined &&
            (observed.MailFromAttributes?.MailFromDomain !== news.mailFromDomain ||
              (news.mailFromBehaviorOnMxFailure !== undefined &&
                observed.MailFromAttributes?.BehaviorOnMxFailure !==
                  news.mailFromBehaviorOnMxFailure))
          ) {
            yield* sesv2.putEmailIdentityMailFromAttributes({
              EmailIdentity: name,
              MailFromDomain: news.mailFromDomain,
              BehaviorOnMxFailure: news.mailFromBehaviorOnMxFailure,
            });
          }

          // 3f. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges.
          const observedTags = toTagRecord(observed.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* sesv2.tagResource({
              ResourceArn: identityArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* sesv2.untagResource({
              ResourceArn: identityArn,
              TagKeys: removed,
            });
          }

          // 4. RETURN — re-read so DKIM tokens/status reflect any sync above.
          const final = yield* sesv2.getEmailIdentity({ EmailIdentity: name });
          yield* session.note(identityArn);
          return {
            ...toAttributes(name, identityArn, final),
            configuration: observeIdentityConfiguration(final, news, desiredTags),
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* sesv2
            .deleteEmailIdentity({ EmailIdentity: output.emailIdentity })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );