rcf-lite 0.12.0 → 0.14.0

package/blueprints/email-smtp-resend/assets/from-address-rotation-pattern.md

@@ -0,0 +1,44 @@
+# From-address rotation pattern (generic)
+
+The adapter's from-address is one configuration reference (`RESEND_FROM_ADDRESS`). A project that ships one product from one verified domain sets one value and moves on. A project that ships several product surfaces from several verified domains uses this pattern to keep the reference-per-surface story clean without hardcoding domain literals into the adapter or the auth wiring.
+
+## Shape
+
+```yaml
+mailFromByProduct:
+  productAlpha:
+    reference: FROM_ADDRESS_PRODUCT_ALPHA
+    subjectPrefix: "Product Alpha"
+  productBeta:
+    reference: FROM_ADDRESS_PRODUCT_BETA
+    subjectPrefix: "Product Beta"
+  transactional:
+    reference: FROM_ADDRESS_TRANSACTIONAL
+    subjectPrefix: null
+```
+
+- One reference name per surface. Values live in the vendor the project's secret resolver reads from; the map above carries only the reference names.
+- The `subjectPrefix` is an optional string a surface may want prepended to the outbound subject; leave `null` for surfaces that pass a fully-composed subject.
+- Any real domain, product name, or sender local-part stays out of this file; the map is a routing table over reference names, not a directory of live addresses.
+
+## How the adapter reads the map
+
+The project's composition wires a `mailFromSelector({ productKey })` in front of the adapter. The selector reads the map, resolves the reference name against the project's secret resolver, and passes the resolved from-address into the adapter's `send` call. The adapter itself continues to consume one from-address per call; the routing lives one level up.
+
+## What the pattern is not
+
+- Not a mail-templating engine. The `subjectPrefix` is a routing detail, not a template layer.
+- Not a domain-verification workflow. The pattern assumes every reference in the map resolves to a value the provider has already verified; see `resend-verification-pointer.md` for where to point the operator for verification.
+- Not a rate-limiting policy. Sending volume decisions live in a project-level ADR, not in this file.
+
+## Example generic values (placeholders only)
+
+The reference names above are illustrative. Real values look like generic placeholders and never appear in this file:
+
+```
+FROM_ADDRESS_PRODUCT_ALPHA -> notifications@example.test
+FROM_ADDRESS_PRODUCT_BETA -> notifications@example.test
+FROM_ADDRESS_TRANSACTIONAL -> notifications@example.test
+```
+
+`example.test` is the IETF reserved test domain; a real project resolves each reference to its own verified sender address inside the vendor the secret resolver reads from.

package/blueprints/email-smtp-resend/assets/resend-verification-pointer.md

@@ -0,0 +1,25 @@
+# Resend sender-domain verification pointer
+
+Sender-domain verification is a provider-owned operation the project performs against Resend before any outbound message is accepted. This file is a pointer to Resend's own public documentation, not a copy of Resend's verification checklist. Copies drift; the pointer does not.
+
+## Where the operator goes
+
+Resend maintains public documentation covering sender-domain setup and the DNS records required (SPF, DKIM, DMARC alignment). The operator applies the blueprint, then walks Resend's own step list against the domain they intend to send from. The blueprint does not restate those steps because Resend owns the source and updates it on its own cadence.
+
+- Resend's public docs are hosted under the provider's own docs site; the operator finds the sender-domains section through the provider's own top-level navigation.
+- The DNS records the provider requires are published on the provider's own docs page; they change from time to time and the provider's page is the current source.
+- The verification-passing UI signal is published on the provider's own dashboard; the operator confirms verification there before running the blueprint's runtime-verify AC that requires a real send.
+
+## What the blueprint gates on locally
+
+Independent of Resend's verification workflow, this blueprint's `AC-4102-1` gates the runtime-verify of the unverified-sender refusal class: a fresh project applying the blueprint before verifying the from-address with the provider will observe `RESEND_SENDER_UNVERIFIED` returned from the adapter. The refusal is the AC's binding, not a bug; the AC passes because the class is surfaced correctly. The operator then completes the provider-side verification and observes the happy-path AC (AC-4101-2) pass on the same running project.
+
+## What this file is not
+
+- Not a substitute for the provider's docs. If a step here contradicts the provider's own page, the provider's page is authoritative.
+- Not a domain-selection guide. Which domain the project sends from is a project-side decision this blueprint does not touch.
+- Not a compliance checklist. Regulatory requirements (double-opt-in, unsubscribe surfaces, retention of consent records) live outside this blueprint's scope; a project subject to them handles them separately.
+
+## Placeholder-only examples
+
+The example addresses that appear elsewhere in this blueprint's assets use IETF reserved test domains (`example.test`, `example.com` where the RFC permits) and are never real deliverable addresses. A real project resolves its own verified addresses through the configured secret resolver and never commits them to the repo.

package/blueprints/email-smtp-resend/assets/stub-adapter.md

@@ -0,0 +1,65 @@
+# Stub Resend send adapter (record-only test double)
+
+TAC-401 names a stub-adapter implementation the project wires into its test harness in place of the real Resend transport. The stub records every outgoing call in memory, resolves a fixed successful outcome by default, and lets a test override the outcome on a per-call basis. The stub satisfies exactly the same `send({ to, subject, textBody, htmlBody })` interface the real adapter does, so a project can swap it in without touching the auth wiring.
+
+## Interface satisfied
+
+```
+send({ to, subject, textBody, htmlBody })
+  -> Promise<{ ok, providerStatus, providerMessageId, error }>
+```
+
+The stub is shape-compatible with the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` and with the real Resend send adapter (`TAC-401-email-smtp-resend-send-adapter`); either can be swapped for the other at composition time.
+
+## Fixed outcome (default successful case)
+
+```json
+{
+  "ok": true,
+  "providerStatus": 202,
+  "providerMessageId": "stub-<n>",
+  "error": null
+}
+```
+
+`<n>` is the 1-based ordinal of the call in the recording session, so a test asserting on `providerMessageId` has a stable value to bind to.
+
+## Fixed outcome (constructed failure case)
+
+Constructed by the test with an override on the stub:
+
+```json
+{
+  "ok": false,
+  "providerStatus": 429,
+  "providerMessageId": null,
+  "error": "RESEND_RATE_LIMITED: stub configured to fail on attempt 1"
+}
+```
+
+Every failure the stub returns starts with one of the four class codes named by REQ-003 (`RESEND_RATE_LIMITED`, `RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`, `RESEND_TRANSPORT_ERROR`); tests binding to the class code are portable between the stub and the real adapter.
+
+## In-memory call log shape
+
+The stub exposes `sends`, an array of every call in the order received:
+
+```json
+[
+  {
+    "to": "operator@example.test",
+    "subject": "Sign in",
+    "textBody": "Someone asked to sign in ...",
+    "htmlBody": "<!doctype html>..."
+  }
+]
+```
+
+Tests assert on `sends[0].to`, `sends[0].textBody.includes(signInUrl)`, and `sends.length === 1` per AC-4101-3.
+
+## Retry harness
+
+For AC-4103-1 and AC-4103-2, the stub exposes a `program` on which the test scripts a sequence of return values consumed one per attempt: `[{ ok: false, error: 'RESEND_RATE_LIMITED: ...' }, { ok: true, providerStatus: 202, ... }]` returns rate-limited on the first attempt and accepts on the second. The stub increments a `submissionCounter` on every call the retry loop makes, which is the counter AC-4103-1 through AC-4103-3 bind to.
+
+## Do not use in production
+
+The stub is a test surface. Loading the stub in a production build silently defeats the send flow: mint succeeds, no message ever leaves the process, and only the presence of the stub in the deployment's dependency graph would tell an operator what happened. A project's deployment configuration refuses the stub adapter's module name in production; the mechanism for that refusal is a project-side configuration decision, not shipped in this blueprint.

package/blueprints/email-smtp-resend/blueprint.json

@@ -0,0 +1,23 @@
+{
+  "slug": "email-smtp-resend",
+  "version": "1.0.0",
+  "category": "email",
+  "contributions": [
+    { "id": "email-smtp-resend-REQ-001", "kind": "req", "path": "requirements/email-smtp-resend-req-001.json" },
+    { "id": "email-smtp-resend-REQ-002", "kind": "req", "path": "requirements/email-smtp-resend-req-002.json" },
+    { "id": "email-smtp-resend-REQ-003", "kind": "req", "path": "requirements/email-smtp-resend-req-003.json" },
+    { "id": "email-smtp-resend-REQ-004", "kind": "req", "path": "requirements/email-smtp-resend-req-004.json" },
+    { "id": "email-smtp-resend-REQ-005", "kind": "req", "path": "requirements/email-smtp-resend-req-005.json" },
+    { "id": "email-smtp-resend-REQ-006", "kind": "req", "path": "requirements/email-smtp-resend-req-006.json" },
+    { "id": "email-smtp-resend-US-4101", "kind": "us", "path": "user-stories/email-smtp-resend-us-4101.json" },
+    { "id": "email-smtp-resend-US-4102", "kind": "us", "path": "user-stories/email-smtp-resend-us-4102.json" },
+    { "id": "email-smtp-resend-US-4103", "kind": "us", "path": "user-stories/email-smtp-resend-us-4103.json" },
+    { "id": "email-smtp-resend-US-4104", "kind": "us", "path": "user-stories/email-smtp-resend-us-4104.json" },
+    { "id": "email-smtp-resend-US-4105", "kind": "us", "path": "user-stories/email-smtp-resend-us-4105.json" },
+    { "id": "email-smtp-resend-US-4106", "kind": "us", "path": "user-stories/email-smtp-resend-us-4106.json" },
+    { "id": "TAC-401-email-smtp-resend-send-adapter", "kind": "tac", "path": "tacs/tac-401-email-smtp-resend-send-adapter.json" },
+    { "id": "TAC-402-email-smtp-resend-webhook-verifier", "kind": "tac", "path": "tacs/tac-402-email-smtp-resend-webhook-verifier.json" },
+    { "id": "ADR-401-email-smtp-resend-transport-choice", "kind": "adr", "path": "adrs/adr-401-email-smtp-resend-transport-choice.json" },
+    { "id": "ADR-402-email-smtp-resend-retry-and-backoff-posture", "kind": "adr", "path": "adrs/adr-402-email-smtp-resend-retry-and-backoff-posture.json" }
+  ]
+}

package/blueprints/email-smtp-resend/contributions/adrs/adr-401-email-smtp-resend-transport-choice.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-401-email-smtp-resend-transport-choice",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The default Resend transport is the SMTP submission endpoint, not the Resend HTTP API",
+  "context": "Resend supports both an HTTP API and an SMTP submission endpoint. The blueprint's job is to fill the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` slot with a shipped default. A shipped default has to make a transport choice; both surfaces satisfy the mail-adapter contract. The choice is scope-local: a project that prefers the API path supersedes this decision with a project-level ADR and swaps the adapter's internal client without changing the interface the auth routes call.",
+  "decision": "The default transport is the Resend SMTP submission endpoint. The adapter uses a plain SMTP client library the project already carries or picks up, dialled at the endpoint host and port declared as configuration references. This keeps the adapter's shape close to a generic SMTP surface: a follow-up `email-smtp-<othervendor>` blueprint (a Postmark-SMTP, an SES-SMTP, a Mailgun-SMTP) can sibling with a minimal delta on the classification table and the endpoint references, sharing the retry loop, the credential resolution, and the boundary discipline. The SMTP path also keeps the adapter's runtime dependency footprint to one SMTP client library and Node built-ins, which is the rcf-lite tier's shape.",
+  "consequences": "The adapter is close to reusable across SMTP-speaking providers; a sibling blueprint is a delta, not a rewrite. The trade against the Resend HTTP API is that the API surfaces richer per-provider metadata (tag propagation, native idempotency keys, structured provider errors) the SMTP path does not carry; a project that needs that metadata supersedes this ADR and swaps in an API-based adapter that still satisfies the shared send contract. The SMTP path also inherits SMTP's operational quirks (SMTP-specific rate-limit signalling, provider-specific reply-code prose the classification table has to know about, connection reuse patterns the SMTP client library governs); the classification table lives in one place in the adapter for exactly this reason.",
+  "alternativesConsidered": [
+    {
+      "name": "Resend HTTP API as the default transport",
+      "summary": "Adapter posts to Resend's REST endpoint using an API key; retries and classification key off HTTP status codes and the provider's JSON error shape.",
+      "reasonNotChosen": "Reserved as the primary supersede path for projects that want the provider's richer per-send metadata (tags, custom headers, idempotency keys). The trade against SMTP is a heavier runtime binding (an HTTP client and a provider-specific JSON contract) and adapter shape that does not port cleanly to a non-Resend follow-up blueprint. A project-level ADR supersede plus an adapter swap is the intended path."
+    },
+    {
+      "name": "Provider-agnostic SMTP with no vendor commitment at v1",
+      "summary": "Ship a generic SMTP adapter and let the project point it at any SMTP-speaking provider.",
+      "reasonNotChosen": "The round-2 reference commits this blueprint to a vendor default; a shipped default lets the project apply and run rather than compose and configure. A generic SMTP shape re-appears as the shared substrate a sibling blueprint reuses, without abandoning the default here."
+    },
+    {
+      "name": "Provider-native SDK",
+      "summary": "Adapter uses Resend's own SDK.",
+      "reasonNotChosen": "Pulls a vendor SDK into the runtime footprint and pins the adapter to that SDK's release cadence. The SMTP client library shape is a smaller, more stable surface the project can pick from an existing dependency it likely already has."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/adrs/adr-402-email-smtp-resend-retry-and-backoff-posture.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-402-email-smtp-resend-retry-and-backoff-posture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Retry is bounded to two attempts on transient classes with exponential full-jitter backoff; terminal classes never retry",
+  "context": "Every mail-adapter default has to pick a retry posture. Unbounded retry against a rate-limited transport is a self-reinforcing failure: every caller retries in lockstep, the transport's throttle escalates, and the outage lengthens. Zero retry surfaces transient network glitches as apparent hard failures the caller has to defend against on its own. The classes the classification table produces split naturally into transient (`RESEND_RATE_LIMITED`, `RESEND_TRANSPORT_ERROR`) and terminal (`RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`); the retry posture is different for each split.",
+  "decision": "On the transient classes the adapter retries up to a bounded budget (default 2 retries, project-configurable via a numeric configuration reference; total attempts including the first are therefore at most 3) using exponential backoff with full jitter, base 250ms and cap 8000ms. On the terminal classes the adapter does not retry: it returns one result immediately with the terminal-class code. The budget and the backoff parameters live behind configuration references; a project running under a tighter latency SLA lowers the cap, a project running behind a proxy layer that already retries lowers the budget to zero, without touching the adapter source.",
+  "consequences": "A transient rate-limit refusal converts to a bounded delay (worst-case around 20 seconds across the default budget) rather than a retry storm the caller has to defend against. A terminally-invalid input (an unverified domain, a malformed recipient) surfaces immediately as one adapter return rather than looping into a rate-limit escalation. The budget and cap are ADR-scoped defaults, not blueprint-immutable numbers; a project with a firmer SLA or a heavier proxy retry layer tunes them without an ADR supersede. The full-jitter algorithm chosen is the AWS-reference exponential-backoff-with-full-jitter shape: `sleep = random_between(0, min(cap, base * 2 ** attempt))`. A project that wants a different jitter shape (equal jitter, decorrelated jitter) supersedes this ADR at the project level and swaps the jitter function; the interface the retry loop consults (`retryClock`) is factored out to support the swap.",
+  "alternativesConsidered": [
+    {
+      "name": "No retry at any layer inside the adapter",
+      "summary": "The adapter returns the first result verbatim; every caller decides its own retry policy.",
+      "reasonNotChosen": "Pushes a decision the caller almost never varies onto every caller, and lets each caller diverge on a class the transport itself treats as retryable. The class distinction is a property of the provider, not a property of the caller; centralising it in the adapter is the correct scope."
+    },
+    {
+      "name": "Unbounded retry until first success",
+      "summary": "Loop until the provider accepts.",
+      "reasonNotChosen": "Turns rate-limit refusal into a self-reinforcing outage. The bounded budget with jitter is the standard defence and is what every well-behaved SMTP-consumer library ships."
+    },
+    {
+      "name": "Retry on the terminal classes as well",
+      "summary": "Retry every non-success return regardless of class.",
+      "reasonNotChosen": "Wastes budget on an outcome the provider has already classified as invalid, and risks an unverified-sender loop tripping the provider's rate limiter. The class distinction is the point of the classification table."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The adapter satisfies the mail-adapter interface named by the shipped magic-link blueprint's TAC-504",
+  "description": "The Resend send adapter exposes exactly the `send({ to, subject, textBody, htmlBody })` method the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` names, and resolves the fixed outcome shape `{ ok, providerStatus, providerMessageId, error }` on every call. No other method is added to the auth-facing surface; provider status codes and provider message ids are normalised into the four declared fields inside the adapter. A project composing this blueprint alongside the magic-link blueprint wires the adapter reference into the auth routes at composition time and calls `adapter.send` directly.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "The mail-adapter contract is the mandate the auth flow gates on; this blueprint's only reason to exist is to fill that mandate with a shipped default a project can apply and rely on. A shape that differs from TAC-504 leaves the auth routes unable to call the adapter without a project-authored shim, which defeats the shipped-default posture. Normalising provider-specific vocabulary inside the adapter keeps the auth code provider-neutral.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:01-mail-adapter-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Transport is Resend's SMTP endpoint, credentialed from placeholder-referenced secrets and a placeholder-referenced verified sender address",
+  "description": "The adapter dials Resend's SMTP submission endpoint (host and port declared as configuration references, not literal in-code strings) and authenticates with an SMTP username and an SMTP password sourced from a Secrets Manager slice. The from-address on every outgoing message is a project-configured verified sender address, also sourced from configuration rather than a literal. Three configuration references are named by the adapter: `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS`. The names are references only; the values live in the vendor the project's Secrets Manager resolves against. No SMTP credential, no signing secret, and no real sender domain is ever committed to the repo or embedded in the adapter's code paths.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "SMTP over the Resend endpoint keeps the adapter close to a generic SMTP shape a follow-up `email-smtp-<othervendor>` blueprint can sibling cleanly. Sourcing credentials and the sender address through placeholder references defers vendor-side secrets custody to the project's secrets-management posture (composable with the shipped `security-secrets-management` blueprint or with a project-authored equivalent) and keeps this blueprint's on-disk footprint free of secret material.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:02-transport-and-credentials"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Provider-side failure modes are enumerated and each maps to a stable-coded error the adapter returns without leaking recipient identity",
+  "description": "The adapter enumerates four provider-side failure classes and maps each to a stable error code on the `error` field of the send-contract return shape, with `ok: false` and the provider's own status code on `providerStatus` when the provider surfaced one. The classes are: rate-limit refusal (`RESEND_RATE_LIMITED`), unverified sender domain or address (`RESEND_SENDER_UNVERIFIED`), invalid or malformed recipient input the provider rejected before dispatch (`RESEND_RECIPIENT_REJECTED`), and generic transport error covering network faults and the provider's 5xx range (`RESEND_TRANSPORT_ERROR`). The error string carries the class code and a short structured reason; the recipient address, the message subject, and the message body never appear on the returned error string, on any log line the adapter writes, or on any exception the adapter throws.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "A single fuzzy `error` string forces every consumer to reverse-engineer the provider's vocabulary. Enumerated codes let the auth flow, the retry policy (REQ-004), and any project-side observability layer branch on class without matching provider prose that may change. Suppressing recipient identity on the error surface keeps the anti-enumeration posture the auth blueprint gates on intact: an operator reading the adapter's log stream cannot use it to confirm a recipient exists.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:03-failure-modes"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Retry-and-backoff posture is bounded, jittered, and refuses to loop on a rejection the provider has already classified as terminal",
+  "description": "On a `RESEND_TRANSPORT_ERROR` or a `RESEND_RATE_LIMITED` return, the adapter retries up to a bounded budget (default 2 retries, project-configurable via a numeric configuration reference; total attempts including the first are therefore at most 3) with exponential backoff and full jitter (base 250ms, cap 8000ms). On `RESEND_SENDER_UNVERIFIED` and `RESEND_RECIPIENT_REJECTED` the adapter does not retry: the provider classified the request as terminally invalid and looping wastes budget and risks a rate-limit escalation. After exhausting the retry budget the adapter returns `{ ok: false, ... }` with the last-observed provider status and the class code that caused the exhaustion; the caller sees one adapter return, not a retry storm.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "Unbounded or unjittered retry against a rate-limited transport is a self-reinforcing failure: every caller retries in lockstep and the transport's own throttle escalates. A jittered, bounded budget converts a transient class into a bounded delay and a terminal class into an immediate return. Skipping retry on the terminally-invalid classes stops the adapter from turning a configuration mistake (unverified domain, malformed recipient) into a retry loop the operator has to hunt.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:04-retry-and-backoff"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Delivery events posted by Resend's webhook are signature-verified and refused when verification fails",
+  "description": "The project exposes one HTTP route the Resend webhook posts delivery events to. The webhook verifier reads the incoming request's signature header (name declared as a configuration reference), reads the timestamp header (name declared as a configuration reference), and computes the expected signature using the webhook signing secret sourced from configuration (`RESEND_WEBHOOK_SIGNING_SECRET` placeholder reference). The verifier compares the computed signature against the header using a constant-time comparison. On mismatch the verifier returns HTTP 401 with an empty body and emits a structured `webhookVerificationFailed` audit event; the delivery event is not delivered to any downstream handler. The signing secret never appears on any log line, error string, or exception message. The header names, the signing algorithm identifier, and the timestamp-tolerance window are configuration references, not literals baked into the verifier.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "The webhook is an inbound trust boundary. Without signature verification any process on the network can post fabricated delivery events into the project's event stream and corrupt any downstream state that keys on them. Constant-time comparison closes the timing-side-channel that variable-time comparison opens. Sourcing the signing algorithm and header names from configuration rather than literals lets a project rotate the algorithm or track a provider header-name change without editing the adapter.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:05-webhook-signature"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-006",
+  "prdId": "PRD-001",
+  "title": "The webhook verifier refuses replayed events by rejecting stale timestamps and refusing already-seen delivery ids inside a bounded window",
+  "description": "The verifier reads the webhook timestamp header and refuses any request whose timestamp is older than the configured tolerance window (default 300 seconds, project-configurable via a numeric configuration reference); a refused request returns HTTP 401 with an empty body and emits a `webhookReplayStale` audit event. On a verification-passing request, the verifier extracts the provider's delivery event id from the payload and consults a bounded event-id store (a stateful component the project realises: an in-memory LRU sized to the tolerance window's expected event volume, or a persisted store with a matching TTL); an event id that already appears in the store is refused with HTTP 200 (idempotent replay acknowledged, no downstream side effect), and emits a `webhookReplayDuplicate` audit event. New event ids are recorded in the store with an expiry equal to the tolerance window.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "Signature verification alone does not defend against replay: a captured signed request can be replayed inside its signature's validity window. A timestamp-tolerance check bounds the window to what fresh delivery requires; a delivery-id memory refuses a replay inside that window. The 200-on-duplicate posture matches provider expectations that a webhook consumer be idempotent under retry; the audit event tells the operator the duplicate arrived and was handled.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:06-replay-defence"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/tacs/tac-401-email-smtp-resend-send-adapter.json

@@ -0,0 +1,53 @@
+{
+  "tacId": "TAC-401-email-smtp-resend-send-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Resend SMTP send adapter",
+  "purpose": "The one module in the project that submits outbound mail to Resend's SMTP endpoint. Satisfies the `send({ to, subject, textBody, htmlBody }) -> Promise<{ ok, providerStatus, providerMessageId, error }>` interface named by the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter`. Normalises provider-specific status codes and error prose into the four declared fields, applies the bounded jittered retry posture named by ADR-402, and sources every credential and the from-address through configured references rather than embedded literals. Every module that hands mail to the provider imports this adapter; nothing else imports the SMTP client library or reaches around the interface.",
+  "responsibilities": [
+    "Expose `send({ to, subject, textBody, htmlBody })` as the sole auth-facing method and no other public method matching that shape (AC-4101-1).",
+    "Return `{ ok, providerStatus, providerMessageId, error }` on every call; on success `ok === true`, `providerStatus` the provider's accepted-status integer, `providerMessageId` the provider's returned identifier, `error === null` (AC-4101-2).",
+    "Dispatch exactly one SMTP submission per adapter call on the successful path (AC-4101-3).",
+    "Classify every non-success provider response into `RESEND_RATE_LIMITED`, `RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`, or `RESEND_TRANSPORT_ERROR` and place the code at the start of the `error` string; carry the provider's own status code on `providerStatus` when the provider surfaced one (AC-4102-1, AC-4103-2).",
+    "Suppress recipient address, subject, and body from the `error` string, every log line the adapter writes for the call, and every exception the adapter throws for the call (AC-4102-2).",
+    "Retry on `RESEND_TRANSPORT_ERROR` and `RESEND_RATE_LIMITED` up to the configured budget (default 2) with exponential backoff and full jitter (base 250ms, cap 8000ms); stop on first success or on budget exhaustion (AC-4103-1, AC-4103-2).",
+    "Do not retry on `RESEND_SENDER_UNVERIFIED` or `RESEND_RECIPIENT_REJECTED`; return one result with the terminal-class code (AC-4103-3).",
+    "Be the sole importer of the SMTP client library across the deployed application's import graph (AC-4106-1).",
+    "Resolve `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS` at boot through the project's configured secret-reference resolver; carry no literal for any of the three values in adapter source (AC-4106-2)."
+  ],
+  "internalStructure": "One stateless class per process, constructed at boot with an injected SMTP client library reference, an injected secret-reference resolver (a Secrets Manager client instance, a project-authored resolver, or an environment shim satisfying the same read interface), and an injected clock and jitter source the retry loop consults. The retry loop is a private method inside the class; the public surface is one method. Provider-response classification is a private function that maps SMTP reply codes and known provider prose to the four class codes; the classification table lives in the adapter's own module and is unit-testable in isolation.",
+  "interfaces": [
+    {
+      "name": "send",
+      "kind": "async-method",
+      "description": "send({ to, subject, textBody, htmlBody }) -> Promise<{ ok, providerStatus, providerMessageId, error }>; the sole auth-facing surface, shape-compatible with TAC-504-security-auth-magic-link-email-delivery-adapter."
+    },
+    {
+      "name": "smtpClient",
+      "kind": "read-write-api",
+      "description": "Project-supplied SMTP client library binding the adapter dials the Resend SMTP endpoint through; injected at boot, imported by no other module of the application."
+    },
+    {
+      "name": "secretResolver",
+      "kind": "read-api",
+      "description": "Project-supplied resolver returning the value for a configured reference name; the adapter calls it at boot for `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS`."
+    },
+    {
+      "name": "retryClock",
+      "kind": "callback",
+      "description": "Project-supplied clock and jitter source the retry loop consults; a real clock in production, a test double in unit tests. Injected at boot; deterministic under test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Configured secret-reference resolver",
+      "kind": "external",
+      "description": "The project's secret-reference resolver. May be a Secrets Manager client from the shipped `security-secrets-management` blueprint, a project-authored resolver, or an environment-variable shim. The adapter reads through it and does not care which."
+    }
+  ],
+  "tradeoffs": "The adapter holds the resolved SMTP credential and the resolved from-address in memory for the lifetime of the process; a heap dump of a compromised process exposes both. That trade means the credential is materialised once at boot and the hot path is a memory read plus an SMTP submission, which is what keeps the successful path affordable. A project that wants per-send credential rotation supplies a resolver whose read on every call is not free and accepts the vendor round trip on every send. The jitter cap of 8000ms bounds worst-case adapter latency at roughly 20 seconds across the default 2-retry budget; a project running under a tighter latency SLA lowers the cap through configuration rather than bypassing the retry loop.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/tacs/tac-402-email-smtp-resend-webhook-verifier.json

@@ -0,0 +1,56 @@
+{
+  "tacId": "TAC-402-email-smtp-resend-webhook-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Resend delivery-webhook verifier",
+  "purpose": "The inbound trust boundary for Resend delivery events. Gates the downstream handler on a constant-time signature check against the configured signing secret, refuses stale timestamps against a bounded tolerance window, and refuses replayed delivery ids against a bounded event-id store. Every request the downstream handler sees has passed all three checks; nothing else in the project accepts delivery events.",
+  "responsibilities": [
+    "Read the signature header, the timestamp header, and the request body; compute the expected signature from the body, the timestamp, and the signing secret using the configured algorithm; compare in constant time (AC-4104-1, AC-4104-2).",
+    "On mismatch, respond HTTP 401 with an empty body, skip the downstream handler, and emit one `webhookVerificationFailed` audit event (AC-4104-2).",
+    "Suppress the signing secret from the response body, from every log line the verifier writes for the call, and from every exception the verifier throws for the call (AC-4104-3).",
+    "Refuse a webhook whose timestamp header is older than the configured tolerance window (default 300 seconds) with HTTP 401, empty body, no handler invocation, and one `webhookReplayStale` audit event (AC-4105-1).",
+    "On a signature-passing request, read the provider's delivery event id from the payload and consult the bounded event-id store; refuse a duplicate with HTTP 200, no handler invocation, and one `webhookReplayDuplicate` audit event; record a new id with an expiry equal to the tolerance window (AC-4105-2).",
+    "Resolve `RESEND_WEBHOOK_SIGNING_SECRET`, the signature header name, the timestamp header name, the signing algorithm identifier, and the tolerance window at boot through the project's configured resolver; carry no literal for the signing secret in verifier source (AC-4106-2)."
+  ],
+  "internalStructure": "One stateless verifier per process, constructed at boot with an injected signature-computation function (a project-selected HMAC implementation matching the configured algorithm identifier), an injected event-id store (an in-memory LRU sized to the tolerance window or a project-authored persistent store with a matching TTL, satisfying the same put-if-absent-with-expiry interface), an injected audit sink, and an injected clock the tolerance check consults. The route handler is a thin adapter over the verifier: the verifier is the thing under test, the route wiring is not.",
+  "interfaces": [
+    {
+      "name": "verify",
+      "kind": "async-method",
+      "description": "verify({ headers, rawBody }) -> Promise<{ ok, status, event, refusal }>; returns `ok: true` with the parsed event on a passing request, `ok: false` with the HTTP status and a refusal class on any refused request."
+    },
+    {
+      "name": "eventIdStore",
+      "kind": "read-write-api",
+      "description": "Project-supplied bounded store implementing `putIfAbsentWithExpiry(id, ttlSeconds) -> Promise<{ inserted }>`; returns `inserted: false` for a duplicate id inside the window and `inserted: true` for a fresh id."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ event, at, principal }` for `webhookVerificationFailed`, `webhookReplayStale`, and `webhookReplayDuplicate`; never invoked with the signing secret."
+    },
+    {
+      "name": "verifierClock",
+      "kind": "read-api",
+      "description": "Project-supplied clock the tolerance check consults; a real clock in production, a test double in unit tests. Injected at boot; deterministic under test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Configured secret-reference resolver",
+      "kind": "external",
+      "description": "The project's secret-reference resolver. May be a Secrets Manager client from the shipped `security-secrets-management` blueprint, a project-authored resolver, or an environment-variable shim. The verifier reads the signing secret and header-name references through it at boot."
+    },
+    {
+      "name": "Resend SMTP send adapter",
+      "kind": "tac",
+      "tacId": "TAC-401-email-smtp-resend-send-adapter",
+      "description": "Sibling adapter that dispatches outbound mail; the verifier and the adapter share the configured secret-reference resolver and belong to the same shelf-level blueprint."
+    }
+  ],
+  "tradeoffs": "The event-id store is a stateful component the project realises; an in-memory LRU sized to the tolerance window is cheap and defends the replay class the tolerance window bounds, but does not defend cross-process replay in a horizontally-scaled deployment. Projects running multiple webhook-consuming processes supply a shared store (a small Redis, a small database table) implementing the same put-if-absent-with-expiry interface. The constant-time comparison assumes a comparison function that itself runs in constant time over the byte length of the expected signature; a project that provides a naive comparison re-opens the timing side channel the verifier is closing.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4101.json

@@ -0,0 +1,45 @@
+{
+  "usId": "email-smtp-resend-US-4101",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The magic-link route hands a composed sign-in URL to the adapter and the adapter dispatches one message",
+  "asA": "operator using a project that composed this blueprint alongside the magic-link blueprint",
+  "iWant": "the auth flow's mint step to call the adapter's send method and see a real message go out",
+  "soThat": "sign-in works on the deployed application without a project-authored provider shim",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4101-1",
+      "description": "The adapter exposes exactly the `send({ to, subject, textBody, htmlBody })` method the magic-link blueprint's TAC-504 names and no other auth-facing method.",
+      "given": "the adapter module imported into a running process",
+      "when": "the process enumerates the adapter's exported surface",
+      "then": "the enumeration returns `send` as the sole async method and no other public method matches the auth-facing shape",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-2",
+      "description": "A successful send resolves the fixed outcome shape `{ ok, providerStatus, providerMessageId, error }` with `ok: true`, `providerStatus` equal to the provider's own accepted-status code, `providerMessageId` equal to the provider's returned identifier, and `error` equal to null.",
+      "given": "a running project with valid configuration and a recipient the provider accepts",
+      "when": "the magic-link route calls `adapter.send({ to, subject, textBody, htmlBody })`",
+      "then": "the returned object matches the shape with `ok === true`, `providerStatus` a positive integer, `providerMessageId` a non-empty string, and `error === null`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-3",
+      "description": "Exactly one SMTP submission is dispatched per adapter call on the successful path; the adapter does not fan out to duplicates.",
+      "given": "a running project instrumented to count SMTP submissions",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter increments by exactly one and no additional submission is observed within the retry window",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4102.json

@@ -0,0 +1,36 @@
+{
+  "usId": "email-smtp-resend-US-4102",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The provider's unverified-sender refusal maps to a stable error code and does not leak the recipient",
+  "asA": "operator running a deployed project where the sender domain has not yet been verified with the provider",
+  "iWant": "the adapter to surface the refusal as a stable error class rather than a raw provider string",
+  "soThat": "downstream code and log readers can act on the class without parsing provider prose",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4102-1",
+      "description": "When the provider refuses the submission because the sender domain or address is unverified, the adapter returns `{ ok: false, providerStatus, providerMessageId: null, error }` with `error` beginning with the code `RESEND_SENDER_UNVERIFIED` and `providerStatus` equal to the provider's own refusal status.",
+      "given": "a running project whose configured from-address is not verified with the provider",
+      "when": "the magic-link route calls `adapter.send({ to, subject, textBody, htmlBody })`",
+      "then": "the returned object matches the shape with `ok === false`, `providerMessageId === null`, `providerStatus` a positive integer, and `error` starting with `RESEND_SENDER_UNVERIFIED`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4102-2",
+      "description": "On any adapter refusal, the recipient address, subject, and body do not appear on the returned `error` string, on the adapter's log stream during the call, or on any exception the adapter throws for the call.",
+      "given": "a running project whose configured from-address is not verified with the provider and a distinctive recipient address the test can byte-scan for",
+      "when": "the magic-link route calls `adapter.send({ to: distinctiveRecipient, subject: distinctiveSubject, textBody: distinctiveBody, htmlBody })` and the call resolves",
+      "then": "the returned `error` string, every line the adapter emitted during the call, and every exception message caught contain none of the distinctive recipient, subject, or body substrings",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4103.json

@@ -0,0 +1,45 @@
+{
+  "usId": "email-smtp-resend-US-4103",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A rate-limited provider triggers bounded jittered retry and returns one adapter result on budget exhaustion",
+  "asA": "operator whose project is receiving rate-limit refusals from the provider",
+  "iWant": "the adapter to retry inside a bounded budget with jittered backoff and then surface one clean failure",
+  "soThat": "a transient rate-limit refusal converts to a bounded delay rather than a retry storm the caller has to defend against",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4103-1",
+      "description": "On a `RESEND_RATE_LIMITED` provider return the adapter retries with exponential backoff and full jitter and stops on either a successful attempt or the configured retry budget, whichever comes first; the number of SMTP submissions equals `1 + observed_retries` and observed_retries is at most the configured budget (default 2).",
+      "given": "a running project instrumented to count SMTP submissions and a provider seam that returns rate-limited on the first attempt and accepts on a later attempt within the budget",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter after the adapter returns equals `1 + observed_retries`, `observed_retries` is at least one and at most the configured budget, and the returned object has `ok === true`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4103-2",
+      "description": "When every attempt in the budget window returns rate-limited, the adapter returns exactly one result with `ok: false`, `error` starting with `RESEND_RATE_LIMITED`, and the submission counter equals `1 + configured_budget`.",
+      "given": "a running project with a provider seam that returns rate-limited on every attempt and configured retry budget of 2",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the adapter returns once, `ok === false`, `error` starts with `RESEND_RATE_LIMITED`, and the SMTP submission counter equals 3",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4103-3",
+      "description": "On a `RESEND_SENDER_UNVERIFIED` or `RESEND_RECIPIENT_REJECTED` provider return the adapter does not retry; the submission counter after the adapter returns equals 1.",
+      "given": "a running project with a provider seam that returns the terminal-invalid class on the first attempt",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter equals 1 and the returned object has `ok === false` with `error` starting with the terminal class code",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}