fix(deployment-manager): resolve DeploymentManager-013 — document SMTP-credential artifact handling as a conscious accepted design decision

This commit is contained in:
Joseph Doherty
2026-05-16 23:49:25 -04:00
parent a2f6c1b9b2
commit c583598888
2 changed files with 37 additions and 5 deletions

View File

@@ -111,6 +111,26 @@ A deployment to a site includes the flattened instance configuration plus any sy
System-wide artifact deployment is a **separate action** from instance deployment, triggered explicitly by a user with the Deployment role. Artifacts can be deployed to all sites at once or to an individual site (per-site deployment via the Sites admin page).
### Secret handling in artifacts
The SMTP configuration artifact carries the SMTP credential (password or OAuth2
client secret). This is a **conscious, accepted design decision**: SMTP
configuration is a deployable artifact, so the credential is distributed to
sites that need it. The credential is protected by the following controls:
- **In transit** — artifact-deployment commands travel over the inter-cluster
transport, which is TLS-protected (see Cluster Infrastructure / Communication).
- **Not logged** — the Deployment Manager never writes credential values to
logs; deployment log statements reference only site IDs/names, the deployment
ID, and exception messages.
- **At rest on the site** — the credential is stored in the site's local SQLite
artifact store. At-rest encryption of that field is **not** currently applied;
it is treated as acceptable given the TLS-protected transport, the absence of
any logging leak, and the trust boundary of the site host. Encrypting the
credential field within the artifact payload would require a key-management
scheme (key location and distribution to sites) and is recorded here as a
possible future hardening item, not a current requirement.
## Site-Side Apply Atomicity
Applying a deployment at the site is **all-or-nothing per instance**: