Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): list the bootstrap key file and plugin instance secrets

Yudhi Armyndharis582806fa4db5
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index c0e9e02bd..aa0b9b9a4 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -181,16 +181,18 @@ OpenWA serves plain HTTP on its port; terminate **TLS at your reverse proxy / lo
### At Rest
-> **There is currently no application-level encryption at rest.** API keys are stored **hashed** (one-way), but other sensitive values are stored as plaintext in the database / on disk and are protected by filesystem and database permissions, not by encryption. Encryption at rest for these fields is a roadmap item, not a shipped feature — do not assume it.
-
-| Data | At rest | How it is protected |
-| ----------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API keys | **Hashed** — SHA-256 with an optional `API_KEY_PEPPER` HMAC; never reversible | A database leak alone cannot recover the keys; with a pepper set, hashes can't be precomputed offline. See §4.2. |
-| Session auth state (WhatsApp credentials) | Plaintext on disk (the engine's auth store under the data volume) | Filesystem permissions on the data volume — keep it private. |
-| Webhook secrets | Plaintext — `webhooks.secret` (`varchar`) | Database access control; never returned by the webhook read DTOs (write-only) and omitted from `GET /api/infra/export-data` webhook rows. |
-| Proxy credentials | Plaintext — `sessions.proxyUrl` may embed `user:pass` | Database access control; never returned by the session read DTOs — only masked `proxyHost`, `proxyType` (derived from the URL scheme), and `hasCredentials` on `GET/PATCH /proxy`. The userinfo is also stripped from `GET /api/infra/export-data` session rows; scheme and host survive so a restore cannot silently connect direct. |
-| Generated config (`data/.env.generated`) | Plaintext file, written `0600` | Owner-only file permissions. |
-| Message content | Plaintext in the `messages` table | Database access control. |
+> **There is currently no application-level encryption at rest.** API keys are stored **hashed** (one-way) in the database, but the first-boot key file and other sensitive values are stored as plaintext in the database / on disk and are protected by filesystem and database permissions, not by encryption. Encryption at rest for these fields is a roadmap item, not a shipped feature — do not assume it.
+
+| Data | At rest | How it is protected |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| API keys | **Hashed** — SHA-256 with an optional `API_KEY_PEPPER` HMAC; never reversible | A database leak alone cannot recover the keys; with a pepper set, hashes can't be precomputed offline. See §4.2. |
+| Session auth state (WhatsApp credentials) | Plaintext on disk (the engine's auth store under the data volume) | Filesystem permissions on the data volume — keep it private. |
+| Webhook secrets | Plaintext — `webhooks.secret` (`varchar`) | Database access control; never returned by the webhook read DTOs (write-only) and omitted from `GET /api/infra/export-data` webhook rows. |
+| Proxy credentials | Plaintext — `sessions.proxyUrl` may embed `user:pass` | Database access control; never returned by the session read DTOs — only masked `proxyHost`, `proxyType` (derived from the URL scheme), and `hasCredentials` on `GET/PATCH /proxy`. The userinfo is also stripped from `GET /api/infra/export-data` session rows; scheme and host survive so a restore cannot silently connect direct. |
+| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | Plaintext raw ADMIN key, written `0600` on first boot | Owner-only file permissions; removed when the key it holds is revoked or deleted. Delete it once the key is stored elsewhere. |
+| Plugin instance secrets | Plaintext: `plugin_instances.secret`, `verifyToken`, `config` | Database access control; `secret`, `verifyToken` and the config fields a plugin marks secret are masked on API reads, but `GET /api/infra/export-data` includes all three verbatim, so treat an export file as a secret. |
+| Generated config (`data/.env.generated`) | Plaintext file, written `0600` | Owner-only file permissions. |
+| Message content | Plaintext in the `messages` table | Database access control. |
**Hardening you can apply today:** set `API_KEY_PEPPER`; restrict the data volume and database to the app's user; and encrypt at the infrastructure layer (LUKS / cloud-provider encrypted volumes / an encrypted managed Postgres) rather than relying on application-level field encryption, which is not implemented.
@@ -558,14 +560,16 @@ flowchart TB
### Secrets Inventory
-| Secret | Storage | Rotation guidance |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| Database credentials | Environment variable | 90 days |
-| Redis password | Environment variable | 90 days |
-| API master key (`API_MASTER_KEY`) | Environment variable (first-boot seed only) | Not via the env var; see the note below |
-| API key pepper (`API_KEY_PEPPER`) | Environment variable | Rotating it invalidates all existing key hashes |
-| Webhook secrets | Database — **plaintext**; not in the webhook read DTOs, and omitted from `GET /api/infra/export-data` webhook rows | Per webhook |
-| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
+| Secret | Storage | Rotation guidance |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Database credentials | Environment variable | 90 days |
+| Redis password | Environment variable | 90 days |
+| API master key (`API_MASTER_KEY`) | Environment variable (first-boot seed only) | Not via the env var; see the note below |
+| API key pepper (`API_KEY_PEPPER`) | Environment variable | Rotating it invalidates all existing key hashes |
+| Webhook secrets | Database — **plaintext**; not in the webhook read DTOs, and omitted from `GET /api/infra/export-data` webhook rows | Per webhook |
+| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | File system: raw ADMIN key in **plaintext**, `0600`; removed when that key is revoked or deleted | Delete it once the key is stored elsewhere |
+| Plugin instance secrets (`plugin_instances.secret`, `verifyToken`, `config`) | Database: **plaintext**; `secret`, `verifyToken` and secret-marked config are masked on API reads, but `GET /api/infra/export-data` includes them verbatim | Per instance (regenerate-secret) |
+| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
> `API_MASTER_KEY` only seeds the first ADMIN key, and is read only while the key table is empty. Changing it later has no effect: the new value never authenticates and the seeded key stays valid. Rotate by minting a new ADMIN key with `POST /api/auth/api-keys` and revoking the seeded `Default Admin Key`.