Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): describe how config layers inherit secrets

Yudhi Armyndharis5ce07776d3b7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e937f6d6e..d0cd488eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -365,6 +365,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `GET /api/sessions/{sessionId}/contacts/profile-pictures` leaves out an id it skipped after another lookup timed out, where an id without a picture or with a failed lookup stays `null`; a client that indexes the answer by every requested id must handle a missing key.
- A plugin catalog with an entry whose `id`, `name`, `version` or text field is not text is refused with `400`, naming the entry; the default catalog is unaffected, and a private `PLUGIN_CATALOG_URL` catalog must correct the entry.
- `POST /api/integration/instances/{pluginId}/{instanceId}/redrive` replays and counts only the dead letters written under the instance's current session binding; rows of an earlier binding stay in the dead-letter table.
+- A per-session plugin config or an integration instance that sets a `net.allowConfigHosts` key (for example `baseUrl`) to another origin than the layer beneath no longer inherits that layer's `secret` fields, and a list holding one is not inherited either; put the secret in that config or instance, or the plugin reaches the new host without it. A deployment that shared one token across per-session hosts must copy the token to each.
### Security
@@ -380,6 +381,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Disconnect a WebSocket whose API key's stored expiry stops parsing, as REST already refuses it.
- The message list no longer returns a row that was replaced between page selection and read and no longer matches the requested chat, time window, direction or type; for a chat-restricted key it could be another chat's message.
- `scripts/restore.sh` also refuses an archive configuration that puts the admin key file, `.env.generated` or `database.sql` on a directory the restore refills, where a link planted in the archive made the copy write outside the data directory.
+- A per-session plugin config or an integration instance that points a `net.allowConfigHosts` key at another origin than the layer beneath no longer receives that layer's secrets, where a session-restricted admin key could send the operator's stored tokens to a host of its choosing.
## [0.25.0] - 2026-10-15
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index dbd5366bd..267d4a7ce 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -204,7 +204,9 @@ A `configSchema` field may set `secret: true` (e.g. an API key): the value is ma
preserved on an unchanged write. A write keeps the stored value for the mask and for an empty string, and
removes it for an explicit `null`. A per-session override and an integration instance's own config are
overlaid on the base config, secret fields included, so a stored secret reaches every override that does
-not replace it, including one that sets its own host.
+not replace it. The exception is an override or instance that points a `net.allowConfigHosts` key at
+another origin than the layer beneath: it does not inherit that layer's secret fields (a list that holds
+one is dropped whole) and must bring its own.
### Plugin Entry Point
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index a0859f58d..33fc0dbe3 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -128,10 +128,11 @@ Alongside this async pipeline, a route may additionally declare a `response` con
inherits keys a sibling projected, and hook dispatch resolves config without per-instance
scoping. Run one enabled wildcard instance per plugin, or scope instances concretely, until the
projection is re-keyed per instance. The base configuration is also the layer under every instance
- and per-session override, secret fields included: a secret saved as a shared default, or projected by a
- wildcard instance, reaches an instance or override that sets its own host. Keep a secret on the instance
- that uses it, and treat a key allowed to create or edit instances as able to send the shared secrets to
- a host it chooses. Capability calls are not confined to the dispatching instance's
+ and per-session override. An instance or override that points a `net.allowConfigHosts` key at another
+ origin than the layer beneath does not inherit that layer's `secret` fields and must bring its own; one
+ that keeps the same origin, or sets no host key, inherits them. A plugin that reaches its destination
+ through a key outside `net.allowConfigHosts` (for example under `net.allow: ['*']`) is not covered, so
+ keep such a secret on the instance that uses it. Capability calls are not confined to the dispatching instance's
scope either: separating tenants across instances of one plugin relies on the handler using the
delivery's `sessionId`.
- **`conversation.send` capability** — a normalized outbound send authored by the plugin and translated