|
|
|
@@ -1,6 +1,6 @@
|
|
|
|
|
# EWS Email Transport for the Notification Outbox — Design
|
|
|
|
|
|
|
|
|
|
**Date:** 2026-08-10 · **Status:** Designed, not implemented · **Owner decisions captured below.**
|
|
|
|
|
**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
|
|
|
|
|
|
|
|
|
@@ -71,10 +71,11 @@ call (~200 lines including classification).
|
|
|
|
|
- `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 (persisted server-side, projected away from all read paths by
|
|
|
|
|
`ManagementActor`'s credential-free projection; `CredentialRedactor.Scrub` on every error
|
|
|
|
|
message). The pre-existing asymmetry with `SmsConfiguration`'s Data-Protection-encrypted
|
|
|
|
|
`AuthToken` is noted but out of scope here.
|
|
|
|
|
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
|
|
|
|
@@ -103,15 +104,21 @@ call (~200 lines including classification).
|
|
|
|
|
|
|
|
|
|
### 4.3 Error classification (mirrors `SmtpErrorClassifier` / ESG conventions)
|
|
|
|
|
- **Transient** (retry → park after `MaxRetries`): connect/DNS/socket/timeout failures; HTTP
|
|
|
|
|
5xx/408/429; SOAP fault codes that are load/availability-shaped (`ErrorServerBusy`,
|
|
|
|
|
`ErrorInternalServerTransientError`, `ErrorTimeoutExpired`, `ErrorMailboxStoreUnavailable`).
|
|
|
|
|
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 (wrong URL), 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.
|
|
|
|
|
- New pure `EwsErrorClassifier` alongside `SmtpErrorClassifier`; every surfaced message runs
|
|
|
|
|
through `CredentialRedactor.Scrub`.
|
|
|
|
|
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`,
|
|
|
|
@@ -123,12 +130,17 @@ call (~200 lines including classification).
|
|
|
|
|
- **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.
|
|
|
|
|
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 `EwsErrorClassifier`;
|
|
|
|
|
`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
|
|
|
|
@@ -153,7 +165,22 @@ call (~200 lines including classification).
|
|
|
|
|
- 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).
|
|
|
|
|
- Encrypting `SmtpConfiguration.Credentials` at rest (pre-existing posture, tracked separately
|
|
|
|
|
if desired).
|
|
|
|
|
- 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.
|
|
|
|
|
Joseph Doherty