settings: encrypted secrets and SMTP settings

1 files changed, 27 insertions, 3 deletions

diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index e02d2f7..a4e61ec 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -370,8 +370,8 @@ resolved rows in a dry run.
 
 | Command | Args | Notes |
 |---|---|---|
-| `settings.get` | — | effective org settings (defaults included) |
-| `settings.set` | `key`, `value` | known keys: `default_series`, `attachment_dir`, `bank_account`, `invoice_receivable_account`, `invoice_revenue_account` |
+| `settings.get` | — | effective org settings (defaults included); secret values replaced by `_set` flags |
+| `settings.set` | `key`, `value?` | known keys: `default_series`, `attachment_dir`, `bank_account`, `invoice_receivable_account`, `invoice_revenue_account`, `smtp_host`, `smtp_port`, `smtp_user`, `smtp_from`, `smtp_reply_to`, `smtp_security`, `smtp_password` |
 
 `default_series` (1–8 characters, e.g. `A`, `V-`, `A `) is used when
 `voucher.post` carries no `series` and as the default series for new
@@ -385,6 +385,25 @@ characters. Verification ids are the concatenation of series and number
 (`V-8`), and series are free-form: only an unbroken numbering per series is
 required.
 
+`smtp_host` (up to 255 characters, no control characters), `smtp_user` (up to
+255), `smtp_from` and `smtp_reply_to` (up to 254), `smtp_port` (digits,
+1–65535) and `smtp_security` (`starttls`, `tls` or `plain`, default
+`starttls` when unset) configure the outgoing mail used when invoices are
+sent.
+
+`smtp_password` is a secret setting. `settings.set` encrypts the value with
+AES-256-GCM under the key in the `BOKFD_SECRET_KEY` environment variable (32
+bytes as 64 hex characters or standard base64, padding optional) and stores
+only the `enc:v1:<nonce>:<ciphertext>` form; a plaintext password is never
+written. `settings.get` never returns the value. When the setting exists it
+returns the boolean `smtp_password_set:true` and omits `smtp_password`;
+when it is absent it returns `smtp_password_set:false`. Setting `value` to
+the empty string deletes the setting. A dry run and the success response
+both report `"value":"[redacted]"`, and the audit entry is
+`{"key":"smtp_password","value":"[redacted]"}`. Setting or clearing the
+password when `BOKFD_SECRET_KEY` is missing or does not decode to 32 bytes
+fails with `INTERNAL`.
+
 ### 7.5 Attachments (underlag)
 
 | Command | Args | Notes |
@@ -690,7 +709,12 @@ beyond the session and calls nothing but public commands.
 - Passwords: Argon2id (vendored reference implementation). Tokens: 256-bit
   random, stored hashed, revocable, never logged. Sessions: memory only.
 - Audit and logs redact secrets: `session.open` records username and outcome,
-  never the password or token value.
+  never the password or token value. `settings.set smtp_password` is audited
+  as `[redacted]`.
+- Settings secrets (`smtp_password`) are encrypted at rest with AES-256-GCM
+  under `BOKFD_SECRET_KEY` (32 bytes, hex or base64, read from the
+  environment); the key itself is never stored in the database, returned by
+  any command or written to a log.
 - Socket and database files are `0600`/`0660`; backups inherit the same
   discipline.
 - For data at rest, prefer LUKS on the host. SQLCipher support is a possible