Merge pull request #198 from hypercerts-org/feat/resend-delivery-webhooks

Add optional Resend delivery event logging

Author: aspiers

.changeset/resend-delivery-webhooks.md

@@ -0,0 +1,9 @@
+---
+'ePDS': minor
+---
+
+Optional email-event logging for operators who choose the third-party Resend service to send email; ePDS continues to support other email providers.
+
+**Affects:** Operators
+
+**Operators:** ePDS remains compatible with any SMTP provider and does not require Resend. Operators who already use Resend can opt in by registering `https://<AUTH_HOSTNAME>/webhooks/resend` for the documented email events and setting `RESEND_WEBHOOK_SECRET`; optional Resend open tracking adds `opened` logs. The route verifies each webhook, logs only events whose sender exactly matches `SMTP_FROM`, and does not persist webhook data.

.env.example

@@ -214,6 +214,12 @@ SMTP_PASS=
 SMTP_FROM=noreply@pds.example
 SMTP_FROM_NAME=ePDS
 
+# Resend users only (optional): email webhook signing secret. ePDS supports
+# any SMTP provider and does not require Resend. To opt into Resend email event
+# logs, configure https://auth.pds.example/webhooks/resend and set:
+# RESEND_WEBHOOK_SECRET=whsec_...
+# Account-wide Resend events are filtered to the exact SMTP_FROM address.
+
 DB_LOCATION=/data/epds.sqlite
 
 # ============================================================================

docs/configuration.md

@@ -198,6 +198,57 @@ buttons appear on the login page.
 | `POSTMARK_SERVER_TOKEN`          | Postmark server token                                                                                                                                                                                                  |
 | `EMAIL_TEMPLATE_ALLOWED_DOMAINS` | Optional comma-separated list of HTTPS hostnames from which `email_template_uri` can be fetched. If unset, any HTTPS URL is allowed. If set, templates hosted on unlisted domains are logged as a warning and ignored. |
 
+#### Optional Resend email event logs
+
+ePDS does **not** require Resend: operators can use any SMTP provider. This
+provider-specific integration is only for operators who already send through
+Resend and choose to log its email webhooks. Without
+`RESEND_WEBHOOK_SECRET`, the webhook route is not mounted.
+
+| Variable                | Description                                                                                                                                           |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RESEND_WEBHOOK_SECRET` | Resend users only. Optional webhook signing secret (`whsec_...`) that enables `POST /webhooks/resend` and structured Resend event logs when provided. |
+
+To opt into email-event logging for email sent through Resend:
+
+1. In the Resend dashboard, register `https://<AUTH_HOSTNAME>/webhooks/resend`.
+2. Subscribe it to `email.sent`, `email.delivered`, `email.delivery_delayed`,
+   `email.opened`, `email.bounced`, and `email.failed`.
+3. To receive `email.opened`, enable Resend open tracking for the sending domain
+   and configure its tracking CNAME. Resend inserts the tracking pixel; ePDS
+   does not alter email HTML. Without tracking, the other events still work.
+4. Set `RESEND_WEBHOOK_SECRET` to that endpoint's signing secret and redeploy
+   the auth service.
+5. Send a test sign-in code through the production SMTP configuration and
+   confirm that `email.sent` and `email.delivered` reach the receiver. If open
+   tracking is enabled, open the message and confirm `email.opened` also arrives.
+   Resend's documentation does not explicitly guarantee that SMTP-submitted
+   email emits webhooks, so verify this before relying on the logs.
+
+Resend webhooks cover the whole Resend account rather than one sending domain.
+The receiver parses each event's `data.from` address and logs it only when it
+exactly matches this ePDS instance's `SMTP_FROM`; events for other senders are
+acknowledged without logging their payload. ePDS instances sharing a Resend
+account must therefore use distinct `SMTP_FROM` addresses. Events cannot be
+separated when multiple instances use the same sender address.
+
+The receiver verifies the Svix signature against the raw request body and emits
+a provider-neutral log schema: `provider`, `eventId`, `eventType`, `occurredAt`,
+`messageId`, `email`, and `subject`. Any sign-in code in `subject` is replaced
+with `[REDACTED]` to prevent it from reaching logs while preserving the rest of
+the subject. Resend event types are normalized to `sent`, `delivered`, `delayed`,
+`opened`, `bounced`, or `failed`. Normal events use `info`; `delayed` uses
+`warn`. An `opened` event means the tracking pixel was fetched, which can be
+caused or suppressed by mail-client privacy features and is not proof that the
+recipient read the message. No webhook data is persisted by ePDS. The
+provider-specific rate limit permits 300 webhook requests per minute per source
+IP.
+
+Resend retries carry the same source event ID, logged as `eventId`, and events
+may arrive out of order. Log analysis should deduplicate by `eventId`, order
+each `messageId` by `occurredAt`, and subtract `sent` from `delivered` to
+calculate delivery latency.
+
 ### Database
 
 | Variable      | Description                                                    |

docs/design/testing-gaps.md

@@ -15,7 +15,7 @@ pds-core callback, full OAuth flow).
 | `auth-service/lib/`           | ~77%     | `auto-provision.ts` at 0% (needs live PDS)                             |
 | `auth-service/middleware/`    | ~91%     | `rate-limit.ts` timer cleanup at 82%                                   |
 | `auth-service/email/`         | ~71%     | Template conditional branches partially covered                        |
-| `auth-service/routes/`        | 0%       | All seven route files — see below                                      |
+| `auth-service/routes/`        | ~32%     | Resend webhook is HTTP-tested; browser/OAuth routes remain gaps        |
 | `auth-service/better-auth.ts` | 0%       | better-auth wiring — see below                                         |
 | `auth-service/context.ts`     | 0%       | Minimal glue class                                                     |
 | `auth-service/index.ts`       | 0%       | Express app assembly + `main()`                                        |
@@ -57,10 +57,13 @@ pds-core callback, full OAuth flow).
   concerns that should be covered by end-to-end tests (see
   `docs/design/e2e-testing.md`).
 
-### 2. `auth-service/src/routes/` (0% — 7 route files, ~2300 lines total)
+### 2. `auth-service/src/routes/` (low coverage)
 
-**Files:** `login-page.ts`, `consent.ts`, `recovery.ts`, `account-login.ts`,
-`account-settings.ts`, `choose-handle.ts`, `complete.ts`
+The signed `resend-webhook.ts` receiver has HTTP-level integration coverage
+for valid signatures, rejected signatures, supported event filtering,
+structured logging, and retry correlation. The browser/OAuth route files remain the
+main gap: `login-page.ts`, `consent.ts`, `recovery.ts`, `account-login.ts`,
+`account-settings.ts`, `choose-handle.ts`, and `complete.ts`.
 
 **Why they're hard:**
 
@@ -78,6 +81,9 @@ pds-core callback, full OAuth flow).
 
 **What can be tested:**
 
+- Provider webhook routes can be tested through an ephemeral Express server
+  with locally signed payloads, as demonstrated by
+  `resend-webhook.test.ts`.
 - The DB-level logic used by these routes is already well-covered via
   `consent.test.ts` (auth_flow operations, client login tracking,
   signCallback round-trip).

packages/auth-service/.env.example

@@ -138,6 +138,13 @@ SMTP_PASS=
 SMTP_FROM=noreply@pds.example
 SMTP_FROM_NAME=ePDS
 
+# Resend users only (optional). ePDS supports any SMTP provider and does not
+# require Resend. To opt into Resend email event logs, register
+# https://<AUTH_HOSTNAME>/webhooks/resend for email.sent, email.delivered,
+# email.delivery_delayed, email.opened, email.bounced, and email.failed, then set:
+# RESEND_WEBHOOK_SECRET=whsec_...
+# Account-wide Resend events are filtered to the exact SMTP_FROM address.
+
 # Database path (separate from PDS account.sqlite)
 DB_LOCATION=/data/epds.sqlite
 

packages/auth-service/package.json

@@ -16,7 +16,8 @@
     "cookie-parser": "^1.4.6",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
-    "nodemailer": "^6.9.8"
+    "nodemailer": "^6.9.8",
+    "svix": "^1.96.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.8",

packages/auth-service/src/__tests__/rate-limit.test.ts

@@ -98,6 +98,29 @@ describe('requestRateLimit', () => {
     expect(next2).toBe(true)
   })
 
+  it('keeps independently configured limiter namespaces separate', () => {
+    const ip = `namespace-${Date.now()}-${randomUUID()}`
+    const globalLimiter = requestRateLimit({
+      windowMs: 60_000,
+      maxRequests: 1,
+    })
+    const webhookLimiter = requestRateLimit({
+      windowMs: 60_000,
+      maxRequests: 1,
+      keyPrefix: 'resend-webhook',
+    })
+
+    for (const limiter of [globalLimiter, webhookLimiter]) {
+      const req = makeReq(ip)
+      const res = makeRes()
+      let nextCalled = false
+      limiter(req as never, res as never, () => {
+        nextCalled = true
+      })
+      expect(nextCalled).toBe(true)
+    }
+  })
+
   it('uses req.ip when available', () => {
     const limiter = requestRateLimit({ windowMs: 60000, maxRequests: 10 })
     const req = {