feat(ses): sending-side builders — ConfigurationSet + event destinations, send grants, account reputation alarms

[laazyj]

Problem / use case

@composurecdk/ses today covers only the receiving path (email identities,
receipt rule sets, filters, actions — #279). The README says as much: "Sending-side
builders (configuration sets, dedicated IP pools, VDM, reputation alarms) will
follow." This issue is that follow-up.

A production sender needs three things the package doesn't yet give you, all of
which are currently raw aws-cdk-lib:

1. A configuration set — the unit that tracks every send: TLS enforcement,
   reputation-metric publishing, suppression, event routing. Without one you fly
   blind and can't segment transactional vs marketing reputation.
2. Event routing for Bounce/Complaint/Reject/… to SNS or EventBridge so a
   downstream workflow can suppress bad addresses. AWS requires you to track
   bounces and complaints.
3. Least-privilege send grants to the Lambda/task role that calls
   SendEmail, and an account-level reputation safety net — the Versioning strategy #1 SES footgun
   is an account paused for a bounce/complaint rate over threshold.

Research

CDK L2 support for the sending path (verified against aws-cdk-lib source + the 2.216.0 floor tarball)

All sending constructs live in the AWS::SES::* CFN namespace (there is no
AWS::SESv2 CFN namespace — "v2" is only the API). Present and confirmed at our
ses floor (2.216.0, gated by route53):

• ConfigurationSet / ConfigurationSetProps — tlsPolicy
  (ConfigurationSetTlsPolicy.REQUIRE|OPTIONAL), reputationMetrics,
  sendingEnabled, suppressionReasons
  (BOUNCES_AND_COMPLAINTS|BOUNCES_ONLY|COMPLAINTS_ONLY), disableSuppressionList,
  dedicatedIpPool, vdmOptions (engagementMetrics/optimizedSharedDelivery),
  customTrackingRedirectDomain, maxDeliveryDuration. Method
  addEventDestination(id, options). No grant*, no metric*, no Tags.
• ConfigurationSetEventDestination / EventDestination — static destination
  factories snsTopic(ITopic), eventBus(IEventBus), cloudWatchDimensions(...),
  firehoseDeliveryStream(...); event filter enum EmailSendingEvent
  (SEND, REJECT, BOUNCE, COMPLAINT, DELIVERY, OPEN, CLICK, RENDERING_FAILURE, DELIVERY_DELAY, SUBSCRIPTION).
• DedicatedIpPool / ScalingMode (STANDARD|MANAGED) and account-level
  VdmAttributes — both present (deferred, see Scope).
• EmailIdentity — already has configurationSet?: IConfigurationSet prop, and
  grantSendEmail(grantee) (grants ses:SendEmail + ses:SendRawEmail on the
  identity ARN) plus generic grant(grantee, ...actions). Both present at 2.216.0.
• No L2 for email templates (AWS::SES::Template is L1-only) — out of scope.
• Account-level sandbox→production access, sending quota, account suppression
  list have no CFN resource (SDK-only) — out of scope, future domain actions
  (ADR-0016).

Sending is available in all commercial regions (unlike receiving), so no
region-gating is needed for these builders.

AWS-recommended alarms & Well-Architected (SES Developer Guide — not the CloudWatch recommended-alarms doc, which omits SES)

SES is not in the CloudWatch "Best Practice Alarm Recommendations" doc. The
authoritative source is the SES Developer Guide,
Creating reputation monitoring alarms using CloudWatch:

Metric (AWS/SES)	Threshold	Comparison	Stat	Period	Missing data
Reputation.BounceRate	0.05 (5%)	>=	Average	1 hr	IGNORE (maintain state)
Reputation.ComplaintRate	0.001 (0.1%)	>=	Average	1 hr	IGNORE

Enforcement thresholds SES itself uses (sender reputation /
account pausing):
bounce ≥5% → under review, ≥10% → may pause; complaint ≥0.1% → under
review, ≥0.5% → may pause. The recommended alarm thresholds sit at the
review boundary, giving headroom before a pause.

Critical: Reputation.BounceRate / Reputation.ComplaintRate are
account-level, dimensionless metrics. An alarm on them is account-scoped —
attaching a configuration-set dimension yields an alarm that never receives data.
This drives design decision #1 below.

Well-Architected mapping: Operational Excellence (publish + alarm on reputation
metrics, route events), Reliability (bounce/complaint handling + suppression
keep you able to send), Security (least-privilege ses:SendEmail scoped by
ses:FromAddress; DKIM/SPF/DMARC — DKIM already handled by the identity builder).

Exemplary AWS examples & idiomatic OSS

• SESv2 SendEmail is the recommended send API; least-privilege sender policy is
  ses:SendEmail on the identity ARN, optionally scoped with a ses:FromAddress
  StringLike condition (policy examples).
• The dominant real-world shape: EmailIdentity (+DKIM) → ConfigurationSet
  (TLS require, reputation metrics, VDM) → event destination (SNS/EventBridge) →
  bounce/complaint Lambda → suppression list, exposing a grantSendEmail-style
  method to the app role. Community constructs
  (@seeebiii/ses-verify-identities,
  mkrn/cdk-ses-template-mailer,
  markilott/aws-cdk-configure-ses)
  converge on this. Separate config sets (and subdomains) per stream so one
  stream's reputation can't sink another; tag messages to split CloudWatch metrics.
• Idioms worth mirroring: configuration-set association as a prop on the identity;
  event destinations via a chainable addEventDestination(id, {destination, events})
  with a destination-factory union; suppression/reputation/VDM as config-set
  booleans, not separate resources.

Recommended design (for @composurecdk/ses)

import {
  createConfigurationSetBuilder,
  snsDestination, eventBusDestination,
  createReputationAlarmBuilder,
  identityGrants,
  createEmailIdentityBuilder,
} from "@composurecdk/ses";
import { EmailSendingEvent } from "aws-cdk-lib/aws-ses";
import { compose, ref } from "@composurecdk/core";

compose(
  {
    // Where bounces/complaints go for suppression processing.
    events: createTopicBuilder(),

    // The sending configuration set — TLS + reputation metrics on by default.
    mailConfig: createConfigurationSetBuilder().addEventDestination("feedback", {
      destination: snsDestination(ref("events", (r) => r.topic)),
      events: [EmailSendingEvent.BOUNCE, EmailSendingEvent.COMPLAINT, EmailSendingEvent.REJECT],
    }),

    // Identity associated with the config set so every send is tracked.
    identity: createEmailIdentityBuilder()
      .domain("mail.example.com")
      .configurationSet(ref("mailConfig", (r) => r.configurationSet)),

    // The app that sends — least-privilege ses:SendEmail on the identity.
    sender: createFunctionBuilder()
      .code(Code.fromAsset("sender"))
      .grant(identityGrants.send(ref("identity", (r) => r.emailIdentity))),

    // Account-level reputation safety net (bounce 5% / complaint 0.1%).
    reputation: createReputationAlarmBuilder(),
  },
  {
    events: [], mailConfig: ["events"], identity: ["mailConfig"],
    sender: ["identity"], reputation: [],
  },
);

Scope for this PR: configuration-set builder + event-destination helpers +
consumer-side send grants + account reputation-alarm builder + identity↔config-set
wiring. Deferred to follow-ups: dedicated IP pool builder, account VdmAttributes
builder, SES templates (L1-only), production-access/quota/suppression-list domain
actions (SDK-only, ADR-0016). An example stack under packages/examples/ will follow
once the surface lands.

The detailed implementation plan and the key design decisions (each compared to two
alternatives) are in the comment below — those are the points I'd value your input on
before/while the PR is in review.

[laazyj]

Implementation plan

New files in packages/ses/src/:

• configuration-set-builder.ts — createConfigurationSetBuilder(). Untagged
  builder (AWS::SES::ConfigurationSet has no Tags, like EmailIdentity/ReceiptRuleSet).
  .addEventDestination(key, { destination, events?, enabled? }) accumulates entries
  (duplicate-key guard, COPY_STATE), resolved and wired via
  configSet.addEventDestination(...) at build. Result:
  { configurationSet, eventDestinations: Record<string, ConfigurationSetEventDestination> }.
• configuration-set-defaults.ts — CONFIGURATION_SET_DEFAULTS: Partial<ConfigurationSetProps>
  merged { ...DEFAULTS, ...props }, each with an @see:
  • tlsPolicy: REQUIRE — encrypt in transit (W-A Security; mirrors the receiving
    tlsPolicy REQUIRE default). Migration note in README (CFN default is OPTIONAL).
  • reputationMetrics: true — publish per-config-set bounce/complaint metrics
    (W-A Operational Excellence; CFN default is off).
• event-destinations/ — snsDestination(Resolvable<ITopic>),
  eventBusDestination(Resolvable<IEventBus>), cloudWatchDestination(CloudWatchDimension[]),
  each returning Resolvable<EventDestination> — exact mirror of the receiving
  actions/ helpers, so a destination can ref() a sibling topic/bus.
• grants.ts — identityGrants via grantVia (ADR-0013): send →
  emailIdentity.grantSendEmail(grantee) (ses:SendEmail+ses:SendRawEmail);
  sendFrom(ref, fromAddresses) → grant(grantee, "ses:SendEmail","ses:SendRawEmail")
  with a ses:FromAddress StringLike condition for least privilege.
• reputation-alarm-builder.ts / reputation-alarms.ts / reputation-alarm-config.ts
  / reputation-alarm-defaults.ts — createReputationAlarmBuilder(), account-scoped,
  no target resource. Builds Reputation.BounceRate (≥0.05) and
  Reputation.ComplaintRate (≥0.001) alarms on AWS/SES, Average, 1 hr,
  treatMissingData: IGNORE, GREATER_THAN_OR_EQUAL_TO_THRESHOLD, no dimensions.
  Reuses @composurecdk/cloudwatch (createAlarms, resolveAlarmConfig,
  AlarmDefinitionBuilder, .addAlarm()), matching the SNS recommendedAlarms
  shape. Result { alarms }. Adds @composurecdk/cloudwatch as a peer dep.
• email-identity-builder.ts (edit) — add a Resolvable-aware
  .configurationSet() method (Omit it from passthrough props, resolve at build) so
  the identity can associate a sibling-built config set by ref().
• index.ts / README.md — exports + a "Sending" section.

Tests mirror existing ones (Template.fromStack assertions): config-set defaults &
event wiring, each destination helper, identityGrants (it.each over capabilities,
plus a ref-resolution case like grants.test.ts), reputation alarms (thresholds,
dimensionless metric, IGNORE, disable/override), and the new identity wiring.
npm run verify (build, check:exports, lint, test) before push.

Key decisions — recommended vs alternatives

1. Reputation alarms live in a dedicated account-level builder, not on the config set

Reputation.BounceRate/ComplaintRate are account-level dimensionless metrics.

• ✅ Recommended — createReputationAlarmBuilder() with no target. Honest about
  scope; one set of alarms per account/region regardless of how many config sets exist.
  Consistent with the account-level VdmAttributes precedent and the ADR-0004 spirit
  (a "recommended" alarm must actually be able to fire).
• ❌ Alt A — recommendedAlarms on the ConfigurationSet builder (like the SNS
  topic builder). Rejected: N config sets → N identical account alarms (duplicate
  names, redundant), and it implies a per-config-set scope the metric doesn't have.
• ❌ Alt B — no alarms, README only. Rejected: violates secure-by-default; a
  bounce/complaint breach is the single most damaging SES failure (account pause).

Where I'd value input: is a standalone reputation-alarm builder the right home, or
would you rather these hang off a future account-level createSesAccountBuilder()
(alongside VDM + suppression settings)? I lean standalone now, foldable later.

2. Event destinations = addEventDestination(key, {destination, events}) + Resolvable destination helpers

• ✅ Recommended — flat options object mirroring CDK's own addEventDestination,
  with snsDestination/eventBusDestination/cloudWatchDestination helpers that
  accept Resolvables. Identical shape to the shipped receiving actions/ helpers →
  zero new concepts, and destinations wire to sibling components via ref().
• ❌ Alt A — accept raw CDK EventDestination only. Rejected: EventDestination.snsTopic(topic)
  can't take a Ref, breaking compose wiring — the exact reason snsAction et al. exist.
• ❌ Alt B — a nested per-destination sub-builder (.eventDestination(key, d => d.sns(topic).events(...))).
  Rejected: more ceremony, no extra capability; the flat object matches CDK and the
  action-helper precedent.

3. Send permission = consumer-side identityGrants.send(ref) (ADR-0013)

• ✅ Recommended — identityGrants.send / .sendFrom via grantVia, delegating
  to the identity's native grantSendEmail / grant. Matches topicGrants,
  bucketGrants, … and keeps the grant edge pointing consumer→resource.
• ❌ Alt A — a .grantSend(role) method on the identity builder (resource-side).
  Rejected by ADR-0013: inverts the compose edge, cycle-prone when the sender also
  consumes the identity.
• ❌ Alt B — grant on the ConfigurationSet. Rejected: the config set has no ARN and
  no grant; SES authorizes sending on the identity resource.

Where I'd value input: should .send scope to ses:FromAddress by default (tighter,
but surprises callers who send from multiple addresses), or stay unconditional like
CDK's grantSendEmail with .sendFrom(...) as the opt-in tightening? Plan takes the
latter.

I'll open the PR against this issue with the recommended design implemented.

---

Generated by Claude Code

[laazyj]

Opened #304 with the recommended implementation (configuration set + event destinations, identityGrants.send/.sendFrom, account-level createReputationAlarmBuilder, and the Resolvable .configurationSet() on the identity builder). npm run verify is green across all packages; 79 tests in @composurecdk/ses at 100% coverage of the new files.

The three key decisions above are the ones I'd value your call on — particularly (1) whether the reputation-alarm builder should stay standalone or eventually fold into an account-level createSesAccountBuilder(), and (3) whether .send should scope to ses:FromAddress by default. Happy to adjust in review.

---

Generated by Claude Code

[laazyj]

Follow-up: while reviewing #304 we found the reputation-alarm builder silently dropped custom .addAlarm() alarms when recommendedAlarms was disabled (false or { enabled: false }). Fixed in #304 (commit eaa978a) to match the ADR-0004 split-builder behaviour — disabling the recommended set now suppresses only the recommended alarms; custom alarms always materialize. Regression tests cover both disable paths.

The same footgun exists in ~12 pre-existing combined-builder alarm helpers (sns, sqs, s3, dynamodb, lambda, events, acm, apigateway, neptune, ec2×3) — tracked separately in #305.

---

Generated by Claude Code