feat(auth): deliver verification, reset, and magic-link emails through the email module

[wmadden-electric]

Wiring the auth module now takes one more dependency — a mail sender from the email module:

// module.ts (the root)
const mail = provision(email(), {
  id: 'mail',
  params: { deliveryMode: envParam('EMAIL_DELIVERY_MODE'), from: envParam('EMAIL_FROM') },
  secrets: { deliveryCredential: envSecret('EMAIL_DELIVERY_CREDENTIAL') },
});
const identity = provision(auth(), {
  id: 'auth',
  deps: { db, email: mail.send },          // ← new in this PR
  params: { baseUrl: envParam('AUTH_BASE_URL') },
});

With that in place, signup sends a verification email, login is refused until the link is followed, password reset and magic-link sign-in deliver real emails, and magic-link login works end to end — locally and on a real Prisma Cloud deploy. This is also the first time one Composer module depends on another, which is why the PR touches packaging as well as the auth package itself.

Linear: TML-3077 · Stacked on #163 (S1, the core auth module)

The decision

Auth treats mail as best-effort, with the email module's outbox as the operational record. A send that fails — delivery error, or a link that fails validation — is logged and dropped; it never fails the signup/reset/login request that triggered it. If you need to know whether an email went out, you ask the outbox, not the auth flow. Every send carries a deterministic idempotency key (sha256(purpose:email:token)), so a retried Better Auth callback can't double-deliver.

How it's built

• Templates (auth/src/templates.ts): the three emails as plain synchronous template functions with fixed subjects. Every interpolated value is HTML-escaped, and each link must match baseUrl's origin (safeLink) — a link pointing anywhere else fails that send instead of reaching a user.
• Send callbacks (auth/src/auth-options.ts): the previous no-op senders replaced with real sends through the wired sender, wrapped in one log-never-throw path. requireEmailVerification flips on.
• Local testing (auth/testing): startLocalAuthServer captures sends in memory by default; pass it a sender hydrated against the email module's own local server and the tests exercise the exact client a deployment uses.
• The proof (examples/auth): the example provisions both modules, and its e2e reads the verification link back out of the email module's outbox port (through a dedicated ops route — the api service never sees admin or send, the ops service never sees send). The deployed smoke runs this for real: 13/13 steps on Prisma Cloud, clean teardown.

What the deploy taught us

Two packaging bugs only a real build/deploy could surface, fixed here:

• Module wiring is checked by object identity: the published auth bundle had inlined its own private copy of the email package, so its send contract was a different object from the one email() exposes, and the two modules refused to wire together on a deployed graph. The auth bundles now import the package's own ./email subpath instead of inlining (composer-prisma-cloud/tsdown.config.ts), so both modules share one instance.
• The declaration build crashed on a rolldown bug in arktype's type re-exports (this is the package's first arktype import). Fixed by leaving arktype unbundled in the declaration output only — the runtime bundles still inline everything, so the deployed artifact stays self-contained.

Alternatives considered

• Fail the auth request when the email fails. Rejected: a down mail path would brick signup and password reset entirely. The outbox already records delivery state, so surfacing the failure there loses nothing.
• Auth owns its own delivery (SMTP client in the auth service). Rejected: duplicates the email module and forfeits its outbox, idempotency, and delivery modes. The boundary dependency is the point of having modules.
• Async / react-email templates. The email contract permits async render, but auth's templates stay sync: react-email would drag a .tsx precompile step into this package's deploy. Consumers can still use react-email for their own templates.
• A second, test-only email client for the local server. Rejected: the tests would then prove a path production never runs. The testing hook takes a real hydrated sender instead.

Verified: root typecheck, 105 auth tests (incl. outbox-readback and magic-link e2e), email suite untouched-green, lint/depcruise/casts, deployed smoke 13/13 with clean teardown. Review round 1: satisfied, zero findings.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a05a39bc-2e10-4c2d-95e8-588a46a9b54c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/auth-s2-email-flows

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/auth-s2-email-flows

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@165

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@165

commit: d594b19

[wmadden-electric]

Superseded by #173, which folds S2's email flows into the ADR-0042 migration (base #161). Same email-module wiring, outbox readback, and magic-link flow, re-applied on the new input model and proven by #173's 13/13 deployed smoke. Closing; review moves to #173.