Phase 1: Sending Foundation — Integrations-backed email credentials, per-integration delivery, V143

[timujinne]

Phase 1 "Sending Foundation" — core half

Moves all email credentials into PhoenixKit.Integrations (encrypted, keys only) and adds a delivery path that can send through any configured integration. This is the core half of a three-repo change (see Merge order below).

What's in here

Integration providers (integrations/providers.ex)

• aws_ses (:key_secret) — access key / secret / region.
• smtp (:credentials) — one universal SMTP provider: any vendor is just a named connection ("SMTP 1", "Brevo SMTP", …). Multiple connections of the same provider coexist.
• brevo_api (:api_key) — Brevo transactional API, with a real validation map (GET /v3/account) so Test Connection actually checks the key.

Credential gate (integrations/integrations.ex)

• has_flat_credential_fields?/2 — :credentials providers store fields flat, so the old nested-"credentials"-map-only gate left them permanently "disconnected" and get_credentials/1 failed. Now data-driven off each provider's own required: true fields (numeric fields included; empty required-list guarded).

Encryption (integrations/encryption.ex)

• ⚠️ Behavior change / security fix. encryption_key/0 read only the flat :phoenix_kit, :secret_key_base, which the installer never sets — so in real host apps enabled?() was false and every integration secret was stored in plaintext. Now falls back to the host app's Endpoint secret_key_base (via Config.get_parent_endpoint/0); the flat key keeps precedence, so existing installs derive the identical key. Pre-existing plaintext values still read back fine (only enc:v1:-prefixed values are decrypted) and are re-encrypted on next save.
• "password" added to @sensitive_fields (SMTP passwords now encrypt).
• Docs: the KDF is a single SHA-256, not PBKDF2 (was mis-documented); rotating secret_key_base makes existing enc:v1: blobs undecryptable — there is no re-wrap path.

Mailer (mailer.ex)

• deliver_via_integration/3 + swoosh_config_for/1 — builds the Swoosh adapter/config from an integration's decrypted credentials (SES / SMTP / Brevo) and replicates the Email.Provider seam directly (intercept_before_send → deliver → handle_after_send). It deliberately does not go through deliver_email/2, whose runtime-config path is SES-only. It injects provider: into the tracking opts so integration sends aren't mis-attributed to the host's static mailer adapter.
• SMTP transport: 465 → ssl: true (implicit TLS). gen_smtp picks the protocol solely from the ssl option — tls: :always on 465 opens a plaintext socket to an SMTPS port and hangs. Other ports → tls: :always when credentials are present (fail closed, no STARTTLS-strip downgrade), :if_available when there are none (local relays like MailHog:1025). An unparseable port is rejected instead of silently becoming gen_smtp's default 25.
• ⚠️ Behavior change. Recipients blocklisted by the optional emails module (to/cc/bcc) are now refused before any tracking or delivery, on both delivery paths. This covers all app mail, so a user whose address was auto-blocklisted (hard bounce) can no longer receive e.g. a magic link — which is the intent. Soft dependency: no-op when the emails package isn't installed. Send-rate limits are deliberately not enforced here (they are un-gated and would cap bulk sends / throttle auth mail); pacing belongs to the newsletters send profiles.

Migration V143 — phoenix_kit_newsletters_send_profiles + broadcasts.send_profile_uuid. Idempotent, prefix-aware, TIMESTAMPTZ, partial unique index enforcing a single default profile. @current_version 142 → 143.

Verification

• mix test test/phoenix_kit/{mailer_test.exs,integrations,migrations} → 158 tests, 0 failures; --warnings-as-errors, credo --strict, dialyzer clean (pre-commit hook ran on every commit).
• Live on a real app (Hydroforce dev): SES-via-Integrations send after the legacy plaintext creds were blanked; Brevo-API send; universal-SMTP (Brevo relay) send; V143 applied 142 → 143; blocklisted recipient refused on both delivery paths and delivered again after removal.
• Reviewed by two independent GLM-5.2 agents (architecture + code review); every finding is either fixed here or listed below.

Known follow-ups (not blockers)

• aws_ses and smtp still have no validation — Test Connection returns OK without checking them (SigV4 / a real SMTP handshake are needed). Only brevo_api validates for real.
• Rotating secret_key_base silently breaks decryption of all integration secrets; no re-wrap tooling yet.

⚠️ Merge order (hard dependency)

This PR must merge and be published to hex FIRST. phoenix_kit_emails and phoenix_kit_newsletters both depend on code introduced here — newsletters calls Mailer.deliver_via_integration/3 and needs V143, and will not compile against any released phoenix_kit. Order: core (this) → hex release → emails → newsletters.

[timujinne]

Code review record — GLM-5.2, 4 rounds × 2 independent agents

Every round was run as two independent GLM-5.2 agents (component-architect + reviewer, --effort max), reading the real diffs and the surrounding code. Every load-bearing claim was re-verified against the source before it was acted on. Full transcripts are committed in the newsletters repo under docs/superpowers/specs/reviews/ (spec → plan → Stage B+C implementation → final).

Findings against this repo, and how each was resolved

#	Severity	Finding	Resolution
1	🔴	SMTP port 465 hung. tls: :always was used for implicit TLS, but gen_smtp picks the protocol solely from the ssl option (gen_smtp_client.erl:854) — tls: only drives a STARTTLS upgrade after a plaintext connect. So 465 opened a plaintext socket to an SMTPS port. Verified against the gen_smtp source.	5cda9ee6 — 465 → ssl: true; unparseable port → {:error, {:invalid_smtp_port, _}} instead of silently becoming gen_smtp's default 25
2	🟠	Tracking mis-attributed the provider. deliver_via_integration/3 didn't pass provider: into intercept_before_send, so the emails interceptor fell back to the host app's static mailer adapter — SMTP/Brevo sends were logged as aws_ses, plus a warning per send	c5bdcd23 — injects provider: creds["provider"] (put_new, so an explicit caller still wins)
3	🟠	Credential gate. :credentials providers store fields flat, but the gate only recognised a nested "credentials" map → SMTP connections stayed "disconnected" and get_credentials/1 failed. Also present?/1 is binary-only, so a numeric port would fail the gate	a04fd70d + c5bdcd23 — has_flat_credential_fields?/2, data-driven off each provider's own required fields; numbers accepted; empty-required-list footgun guarded
4	🟠	Blocklist bypassable via cc/bcc (only to was inspected) — a suppression list with a hole is a compliance problem	efd2f6b7 — checks to ++ cc ++ bcc
5	🟠	tls: :always broke credential-less relays (local MailHog:1025, internal plaintext smarthosts)	efd2f6b7 — creds present → :always (fail closed); no creds → :if_available (nothing on the wire to protect)
6	🟡	“Test Connection” validated nothing for the three new providers — do_validate/2 fell through to :ok and stamped the connection connected without checking anything	fd034728 — real validation map for brevo_api (GET /v3/account). aws_ses (SigV4) and smtp (real handshake) need bespoke validators → open follow-up
7	🟡	Docs: the KDF is a single SHA-256, not PBKDF2; rotating secret_key_base makes existing enc:v1: blobs undecryptable with no re-wrap path; swoosh_config_for/1 returns decrypted secrets	5cda9ee6 / 7e4ef9ec — documented in-module

Positives the reviewers verified independently (not just claimed)

• The encryption fallback is precedence-safe: the flat :secret_key_base still wins, so existing installs derive the identical key; pre-existing plaintext values read back unchanged (only enc:v1: values are decrypted) and re-encrypt on next save — no data-loss window.
• Secrets are encrypted at rest (confirmed against the live DB) and never logged — mailer.ex contains no Logger call at all.
• The tracking seam in deliver_via_integration/3 faithfully mirrors deliver_email/2 (intercept_before_send → deliver → handle_after_send), so X-PhoenixKit-Log-Id correlation is preserved.
• The gate change has no blast radius: has_flat_credential_fields?/2 is guarded on auth_type: :credentials, and smtp is the only such provider in core.
• V143 is idempotent, prefix-aware, TIMESTAMPTZ, and its partial unique index really does reject a second default.

Verdicts

Final round: Ship-with-changes (both agents) — spec compliance PASS, no architectural rework, no critical defects. All must-fix items above are fixed in this branch; only the aws_ses/smtp connection validators remain as a documented follow-up.

[ddon]

Renumbered V143 → V145 (this is the third same-day PR to claim V143 — new-login-alerts and the manufacturing/warehouse consolidation took V143 and V144 respectively, both already merged to main). Rebased onto current main, renumbered the migration/test/dispatcher wiring throughout.

Also found and fixed a real bug independent of the renumbering: the migration's uuid UUID PRIMARY KEY DEFAULT uuid_generate_v7() was unqualified — the exact bug class fixed in V26 during today's PR #631 prefix-hardening review, and present in every sibling migration but missed here. On a prefixed install whose connecting role's search_path excludes the prefix schema, this fails outright or silently resolves to the wrong schema's function. Now uses Helpers.uuid_v7_call/1.

Independently verified the two security-fix claims (encryption key fallback to the host's Endpoint secret_key_base, and the SMTP TLS/port-465 handling) against the actual code rather than the PR description — both hold up. No further bugs found in encryption.ex/integrations.ex/providers.ex/mailer.ex. mix precommit clean.

Full write-up: dev_docs/pull_requests/2026/633-newsletters-sending-foundation/CLAUDE_REVIEW.md (pushed to this branch).

Ready to merge.