Implement transactional invitation mail service

workplans/EMAIL-WP-0004-transactional-mail-delivery-service.md

@@ -0,0 +1,101 @@
+---
+id: EMAIL-WP-0004
+type: workplan
+title: "Provide transactional invitation mail delivery"
+domain: infotech
+repo: email-connect
+status: active
+owner: codex
+topic_slug: netkingdom
+created: "2026-08-08"
+updated: "2026-08-08"
+depends_on:
+  - NK-WP-0024
+state_hub_workstream_id: "a37e5e4d-090a-4a75-88d2-aacd0c0fd235"
+---
+
+# EMAIL-WP-0004 - transactional invitation mail delivery
+
+Extend email-connect beyond mailbox evidence scanning with a narrow,
+provider-neutral transactional-send service for user-engine invitations and
+verification messages. Email evidence remains non-authoritative.
+
+## T01 - Define the send and evidence contract
+
+```task
+id: EMAIL-WP-0004-T01
+status: done
+priority: high
+state_hub_task_id: "ef07126a-3c1b-4a8b-9ec1-252c8844ec49"
+```
+
+Define an authenticated HTTP send request derived from the user-engine outbox
+envelope, approved templates, recipient/address validation, tenant/template
+allow-lists, Idempotency-Key, correlation, redaction, and response/error
+semantics. Provider acceptance must not be described as inbox delivery,
+awareness, identity, or authorization.
+
+Done when the contract supports invitation-created and invitation-resent
+events without accepting arbitrary sender, template, or message content.
+
+Done 2026-08-09: authenticated `/v1/send` accepts only the two invitation
+event types, validates recipient/event/idempotency fields, and renders a fixed
+portal invitation template. Provider acceptance remains explicitly distinct
+from delivery or identity evidence.
+
+## T02 - Implement provider-neutral transactional sending
+
+```task
+id: EMAIL-WP-0004-T02
+status: done
+priority: high
+state_hub_task_id: "6a6ae927-4393-480f-a83e-93c9dabe18fe"
+```
+
+Implement the HTTP receiver, template rendering, idempotency store, suppression
+checks, bounded provider calls, and provider adapter. Start with the approved
+IONOS SMTP/STARTTLS lane while keeping provider credentials outside requests,
+logs, Git, and database evidence.
+
+Done when repeated event IDs send at most one message and failures return
+stable retryable/permanent classifications without leaking SMTP details.
+
+Done 2026-08-09: SQLite idempotency, provider-neutral injection, bounded
+STARTTLS SMTP calls, duplicate suppression, and redacted provider-unavailable
+responses are implemented. All 22 repository tests pass.
+
+## T03 - Establish custody and deploy the service
+
+```task
+id: EMAIL-WP-0004-T03
+status: progress
+priority: high
+state_hub_task_id: "13428364-29b1-4e0d-aaf5-c0b254c829b9"
+```
+
+Route SMTP and caller credentials through the credential catalog before
+requesting them, store provider material in OpenBao, and deliver only scoped
+runtime secrets. Deploy an immutable image on railiance01 with probes,
+resource/security controls, default-deny NetworkPolicy, restricted
+user-engine ingress, SMTP-only egress, and rollback.
+
+Done when user-engine can call the cluster-local receiver without possessing
+SMTP credentials and unrelated workloads cannot send through it.
+
+## T04 - Prove invitation delivery failure behavior
+
+```task
+id: EMAIL-WP-0004-T04
+status: todo
+priority: high
+state_hub_task_id: "34127b3e-f7c6-4ebe-a86c-743ba1b27640"
+```
+
+Test template allow-list denial, invalid recipient, provider timeout, temporary
+deferral, permanent rejection, duplicate request, suppression, resend, and
+redacted diagnostics. Verify mailbox ownership and provider acceptance never
+alter user-engine authorization. Hand non-secret message/event references and
+failure evidence back to NK-WP-0024.
+
+Done when deployed invitation and verification flows are observable,
+idempotent, retry-safe, and conservative about delivery evidence.