ScadaBridge/docs/plans/2026-08-10-ews-email-transport-design.md

# EWS Email Transport for the Notification Outbox — Design

**Date:** 2026-08-10 · **Status:** Implemented on `feature/ews-email-transport`; manual live gate pending · **Owner decisions captured below.**

## 1. Context — the pending task this supersedes

The long-deferred "Office 365 / Exchange" email work is **Q12** (`docs/plans/questions.md:13`,
`docs/plans/phase-7-integrations.md:466`): *"What Microsoft 365 tenant/app registration is
available for SMTP OAuth2 testing?"* The OAuth2 Client-Credentials SMTP path
(`OAuth2TokenService`, XOAUTH2 in `MailKitSmtpClientWrapper`) shipped in Phase 7 but was never
verified against a real tenant — Mailpit cannot speak OAuth2 (`docs/test_infra/test_infra_smtp.md:125`),
and `docs/deployment/production-checklist.md:46` still assumes OAuth2-over-587 as the production
posture.

**Q12's premise is now obsolete.** The real mail infrastructure on the network where ScadaBridge
runs is an **on-prem Exchange 2013** server exposing **EWS** (SOAP over HTTPS) at
`https://webmail.zimmer.com/ews/exchange.asmx`, with a service mailbox
(`ww_notify@zimmerbiomet.com`, domain account `nam\ww_notify`). Dev/test credentials live in the
**untracked, git-ignored** `email_details.txt` — they must never enter the repo, this doc, or a
Transport bundle exported for another org.

### Decision on Q12 (owner, 2026-08-10)
**Close Q12 as superseded.** The OAuth2 SMTP code path stays in place, config-selectable and
unit-tested, but "untested against a real M365 tenant" becomes an accepted, documented state
rather than a pending task. If email ever moves to Exchange Online, Q12's question revives.

## 2. Live evidence (probed 2026-08-10 from the dev Mac)

| Probe | Result | Consequence |
|---|---|---|
| Unauthenticated `GET /ews/exchange.asmx` | `401`, `WWW-Authenticate: Negotiate, NTLM, Basic` — IIS 8.5, OWA 15.0.1497 (Exchange 2013) | Basic auth is enabled on the EWS vdir; **NTLM is not required** |
| Authenticated GET with HTTPS Basic (`nam\ww_notify`) | `200` | Basic works for the service account; the client is a plain `HttpClient` — cross-platform, macOS-testable, no GSSAPI/NTLM machinery |
| SMTP ports on the same host | 25 open; **587/465 closed** | Authenticated SMTP submission is not offered. Port 25 relay would be unauthenticated + receive-connector-IP-scoped — brittle, needs Exchange admin action per environment. Rejected as the transport (see Approach C) |

## 3. Approaches considered

### A. Transport mode inside the existing email pipeline — **CHOSEN**
Add a `Transport` discriminator (`Smtp` default / `Ews`) to the existing `SmtpConfiguration`
row. `EmailNotificationDeliveryAdapter` branches after loading the config: the SMTP/MailKit path
is untouched; the EWS path sends one SOAP `CreateItem` via a new seam. Everything around
delivery — outbox lifecycle, retry/park, recipient resolution, KPIs, UI/CLI surface, bundle
SecretsBlock travel — is reused unchanged.
*Trade-offs:* smallest diff; one additive EF column; slight impurity of "SmtpConfiguration"
naming now covering two transports (accepted — it is THE email config row, and renaming the
entity/table would ripple through bundles and repos for cosmetics).

### B. Separate `EwsConfiguration` entity + separate delivery adapter — rejected
A parallel entity/table/UI page/CLI noun and a second Email-type adapter. The outbox dispatcher
keys adapters by `NotificationType`, so two Email adapters need a dispatcher change plus a
which-config-wins rule; Transport bundles need a new artifact kind. Roughly double the surface
for no behavioural gain.

### C. No-code: point the existing SMTP adapter at Exchange — rejected on evidence
Would be zero code, but the probe shows authenticated submission (587/465) is closed. Port-25
relay is anonymous, scoped by source IP on a receive connector, and an Exchange admin change per
environment — an unauthenticated, brittle dependency the moment containers move hosts.

### EWS client style (owner decision)
**Hand-rolled SOAP envelope over `HttpClient` — no SDK**, matching the house pattern set by
`SmsNotificationDeliveryAdapter` (Twilio REST, no SDK). The Microsoft EWS Managed API is
archived; the community fork is a heavyweight dependency for what is one fixed `CreateItem`
call (~200 lines including classification).

## 4. Design

### 4.1 Configuration model
- `SmtpConfiguration` (Commons POCO + `SmtpConfigurations` table) gains one **additive** column:
  `Transport` (`string`, default `"Smtp"`; parsed case-insensitively like `TlsMode`). One EF
  migration; existing rows keep SMTP semantics with no data change.
- Field reuse under `Transport = "Ews"`:
  - `Host` — the **full EWS endpoint URL** (absolute `https://` URI, validated).
  - `AuthType` — must be `basic`; `Credentials` stays `username:password` where username may be
    `domain\user` (split on the **first** `:` only, as today). Same storage treatment as SMTP
    credentials: `SmtpConfiguration.Credentials` is **encrypted at rest** via
    `EncryptedStringConverter` (wired in `ScadaBridgeDbContext.ApplySecretColumnEncryption`,
    `ConfigurationDatabase`), exactly like `SmsConfiguration.AuthToken` — there is no asymmetry
    between them. It is additionally projected away from all read paths by `ManagementActor`'s
    credential-free projection, and `CredentialRedactor.Scrub` runs on every error message.
  - `FromAddress`, `MaxRetries`, `RetryDelay`, `ConnectionTimeoutSeconds` — same meaning
    (timeout becomes the `HttpClient` request timeout).
  - `Port`, `TlsMode`, `OAuth2Authority`, `OAuth2Scope`, `MaxConcurrentConnections` — unused for
    EWS; validation requires them unset/ignored and the UI hides them.
- Validation (in `HandleUpdateSmtpConfig` + options validator, eager per §1.5 conventions):
  unknown `Transport` rejected; `Ews` requires absolute https `Host`, `basic` auth, non-empty
  credentials; `Smtp` validation unchanged.

### 4.2 Delivery path
- New seam in the NotificationService project: `IEwsMailSender` with one method
  `SendAsync(EwsSendRequest, CancellationToken)` (endpoint, credential, from, bcc list, subject,
  plain-text body). Implementation `EwsSoapMailSender`:
  - `IHttpClientFactory` named client; **explicit `Authorization: Basic` header** (deterministic,
    proven live) rather than handler-negotiated auth. If Basic is ever disabled in a hardening
    pass, an `EwsAuthMode` knob (Negotiate/NTLM via `HttpClientHandler.Credentials`) is the
    documented follow-on — not built now (YAGNI), and noted that NTLM-on-Linux containers would
    then need `gss-ntlmssp` in the image.
  - One `CreateItem` SOAP envelope, `RequestServerVersion Exchange2013`,
    `MessageDisposition="SendOnly"` (no Sent-Items copy — the `Notifications` table is the audit
    record of what was sent; a mailbox copy would just grow unboundedly). Recipients go in
    `BccRecipients` only, preserving the SMTP path's BCC semantics (recipients can't see each
    other). All user content XML-escaped; body `BodyType="Text"` (plain text, as today).
- `EmailNotificationDeliveryAdapter.DeliverAsync` branches on the parsed transport after the
  existing list-resolution/config/address-validation steps (all shared): `Smtp` → current
  `SendAsync`; `Ews` → `IEwsMailSender`. Outcome mapping stays three-way `DeliveryOutcome`.

### 4.3 Error classification (mirrors `SmtpErrorClassifier` / ESG conventions)
- **Transient** (retry → park after `MaxRetries`): connect/DNS/socket/timeout failures; HTTP
  5xx/408/429; response/fault codes that are load/availability-shaped (`ErrorServerBusy`,
  `ErrorInternalServerTransientError`, `ErrorTimeoutExpired`, `ErrorMailboxStoreUnavailable`,
  `ErrorInsufficientResources`).
- **Permanent** (park immediately): HTTP 401/403 (credential/authorization — retrying burns
  lockout budget on a domain account), 404/410/405 (wrong URL or endpoint), SOAP schema faults,
  recipient-shaped response codes (`ErrorInvalidRecipients`, `ErrorMessageSizeExceeded`),
  malformed-config findings (bad URL, bad credential form) — same "unclassified defaults to
  permanent" stance the SMTP adapter takes.
- **As built:** there is no standalone `EwsErrorClassifier` type. Classification lives inside
  `EwsSoapMailSender`, which throws typed `EwsTransientException` / `EwsPermanentException` that
  the adapter maps to `DeliveryOutcome`; the pure `EwsResponseParser` stays judgement-free,
  reporting only the response shape and code (and parsing with DTD processing prohibited). A
  parsed response code beats the HTTP status — only an unparseable body falls back to the status
  code. Every surfaced message runs through `CredentialRedactor.Scrub`, plus a mask of the
  base64 Basic-auth value.

### 4.4 Management surfaces
- **CLI:** `notification smtp update` gains `--transport smtp|ews` (existing `--host`,
  `--auth-type`, `--credentials`, retry flags reused). `notification smtp list` shows the
  transport; credential-free projection unchanged.
- **Central UI `/notifications/smtp`:** a Transport selector; EWS mode shows URL + username +
  password inputs and hides Port/TLS/OAuth2 inputs (which remain SMTP-only, OAuth2 inputs
  remaining auth-type-gated as today). Admin-only, as today.
- **Transport bundles:** `SmtpConfiguration` already travels in the encrypted SecretsBlock; the
  new field rides along additively (`schemaVersion` additive rules). The existing round-trip
  guard (arch-review T8 style) is extended to cover `Transport` so export/import can't silently
  drop it. **Discovered during implementation:** `OAuth2Authority` and `OAuth2Scope` (shipped
  2026-07) were **already** being silently dropped by bundle export/import — `SmtpConfigDto`
  never carried them. Fixed in the same slice as `Transport` (DTO, serializer,
  `BundleImporter.ApplySmtpFields`, `ArtifactDiff`), and the round-trip guard reseeded so all
  three fields are now pinned.

### 4.5 Testing (owner decision: fake stub + live gate)
- **Unit:** `EwsSoapMailSender` against an in-process fake EWS endpoint (Kestrel `TestServer`)
  asserting the Basic header, envelope shape (BCC-only, SendOnly, escaping) and driving canned
  `CreateItemResponse` success / SOAP-fault / HTTP-error bodies through the sender's
  classification (see §4.3 — no standalone classifier type);
  adapter-level tests for the transport branch and outcome mapping; validator tests for the new
  config rules. All macOS-runnable — no NTLM, no network.
- **Live gate (manual, one-off):** from the dev Mac, configure `Transport=Ews` with the
  dev/test credentials (from the untracked `email_details.txt`) against
  `webmail.zimmer.com`, send to a single-recipient test list, verify Delivered status +
  received mail + a permanent-classification case (bad password on a throwaway config —
  mindful of domain lockout policy, one attempt only). Recorded as a PASS note in this doc when
  run.
- Mailpit-based SMTP tests are untouched (the SMTP path is untouched).

### 4.6 Documentation updates that travel with the implementation
- `Component-NotificationService.md`: EWS transport section (config model, classification,
  BCC/SendOnly semantics, auth posture).
- `docs/plans/questions.md` Q12 + `phase-7-integrations.md` Q12 row: closed as superseded,
  pointing here.
- `docs/deployment/production-checklist.md`: EWS variant (outbound HTTPS 443 to the Exchange
  CAS; service-account password rotation note) alongside the SMTP items.
- `docs/test_infra/test_infra_smtp.md`: note that the OAuth2 gap is superseded by EWS for
  on-prem deployments.

## 5. Explicitly out of scope
- Removing the SMTP/OAuth2 path (stays config-selectable; Approach "additional transport" was
  the owner's choice).
- NTLM/Negotiate auth mode (documented follow-on trigger: Basic disabled on the EWS vdir).
- HTML bodies, attachments, per-recipient sends, Sent-Items copies.
- Site-side anything — notification delivery remains central-only.

## 6. Follow-ups (from execution reviews)

Raised while implementing; none blocking, none scheduled here.

1. **Catch-chain duplication in `EmailNotificationDeliveryAdapter`.** The SMTP and EWS branches
   each carry a near-identical permanent / caller-cancel / transient / unclassified catch chain
   differing only in exception types and log wording. Extract a shared helper **before** a third
   transport is added.
2. **Bundle-import shape validation parity.** Import applies `SmtpConfigDto` fields as data and
   does not run the EWS shape gate that `ManagementActor` (CLI/API) and the Central UI apply. The
   delivery adapter is authoritative and parks an unusable row with a clear reason, so this is
   accepted for now rather than duplicating the gate a fourth time.
3. **`CredentialRedactor.MinSecretLength` = 12.** A standalone password shorter than that is not
   scrubbed on its own; EWS messages are still covered by the packed `username:password` and
   base64 Basic-auth scrubs, which comfortably exceed the floor. Revisit if a code path ever
   surfaces a bare short password.