Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(plugins): state that production requires a pin on https URLs
Yudhi Armyndharis277229f79dcf
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 5311f789f..3f7b8cdbb 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5953,17 +5953,17 @@ all kept. A directory the gateway did not install is still refused.#### POST /api/plugins/install-url-Install a plugin by downloading its `.zip` from a URL (SSRF-guarded fetch: host validated, redirects followed with every hop re-validated through the guard and the chain capped at 5 hops, size-capped at `plugins.downloadMaxBytes`, default 5 MB). `https://` is accepted as-is; plain `http://` is only accepted when the URL carries a content pin (below) — the package is executable code and must be integrity-protected in transit; private-network targets remain subject to the SSRF guard. A redirect hop that downgrades back to plain `http://` mid-chain is likewise refused (set `PLUGIN_DOWNLOAD_ALLOW_INSECURE_REDIRECTS=true` only if your vendor genuinely redirects that way); a chain over the cap fails with an explicit "too many redirects" error.+Install a plugin by downloading its `.zip` from a URL (SSRF-guarded fetch: host validated, redirects followed with every hop re-validated through the guard and the chain capped at 5 hops, size-capped at `plugins.downloadMaxBytes`, default 5 MB). `https://` is accepted (production also requires the content pin, below); plain `http://` is only accepted when the URL carries a content pin (below) — the package is executable code and must be integrity-protected in transit; private-network targets remain subject to the SSRF guard. A redirect hop that downgrades back to plain `http://` mid-chain is likewise refused (set `PLUGIN_DOWNLOAD_ALLOW_INSECURE_REDIRECTS=true` only if your vendor genuinely redirects that way); a chain over the cap fails with an explicit "too many redirects" error.-Content pinning: append `#sha256=<64 hex>` (URL fragment — never sent to the server) to require the downloaded bytes to match that digest; the fragment is the only honored marker — query params are deliberately ignored. A mismatch or a malformed marker fails the install closed. The pin is optional over HTTPS (TLS + the SSRF guard are the baseline) and REQUIRED over plain HTTP, which is rejected without one.+Content pinning: append `#sha256=<64 hex>` (URL fragment — never sent to the server) to require the downloaded bytes to match that digest; the fragment is the only honored marker — query params are deliberately ignored. A mismatch or a malformed marker fails the install closed. The pin is always REQUIRED over plain HTTP, which is rejected without one. Over HTTPS it is also REQUIRED when `NODE_ENV=production` (the Docker image, compose and Helm default) unless `PLUGIN_INSTALL_REQUIRE_PIN=false`; elsewhere it is optional over HTTPS (TLS + the SSRF guard are the baseline) unless `PLUGIN_INSTALL_REQUIRE_PIN=true`. An unpinned URL the deployment requires a pin for fails with `400`.**Auth:** API key (ADMIN)**Request body** — `InstallFromUrlDto` (class-validated; extra fields → `400`)-| Field | Type | Required | Constraints | Description |-| ----- | ------ | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------- |-| `url` | string | Yes | `@IsUrl({ protocols:['http','https'], require_protocol:true })` | Absolute URL of the package; https as-is, plain http only with a `#sha256=` digest pin |+| Field | Type | Required | Constraints | Description |+| ----- | ------ | -------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |+| `url` | string | Yes | `@IsUrl({ protocols:['http','https'], require_protocol:true })` | Absolute URL of the package; plain http only with a `#sha256=` digest pin, which production also requires on https |```json{ "url": "https://github.com/openwa-plugins/chat-flow/releases/download/v1.0.0/chat-flow.zip" }@@ -6123,7 +6123,7 @@ Set which sessions a session-scoped plugin is activated for. This is a **full re#### POST /api/plugins/:id/update-Update an installed plugin in place from a URL, preserving config + enabled state. The new package is written to a staging sibling and validated BEFORE the running plugin is stopped, then swapped in with two renames (live → backup, staging → live); a failure before or during the swap restores the previous version, and a process crash mid-swap is reconciled at boot (the backup is restored when the live directory is missing), so an interrupted update can never make the plugin silently vanish. The URL follows the same transport rule as `install-url`: https as-is, plain http only with a `#sha256=` digest pin (fail-closed on mismatch).+Update an installed plugin in place from a URL, preserving config + enabled state. The new package is written to a staging sibling and validated BEFORE the running plugin is stopped, then swapped in with two renames (live → backup, staging → live); a failure before or during the swap restores the previous version, and a process crash mid-swap is reconciled at boot (the backup is restored when the live directory is missing), so an interrupted update can never make the plugin silently vanish. The URL follows the same transport and pin rules as `install-url`: plain http only with a `#sha256=` digest pin, and https needs the pin too under `NODE_ENV=production` unless `PLUGIN_INSTALL_REQUIRE_PIN=false` (fail-closed on mismatch).**Auth:** API key (ADMIN)@@ -6135,9 +6135,9 @@ Update an installed plugin in place from a URL, preserving config + enabled stat**Request body** — `InstallFromUrlDto` (class-validated)-| Field | Type | Required | Constraints | Description |-| ----- | ------ | -------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |-| `url` | string | Yes | `@IsUrl({ protocols:['http','https'], require_protocol:true })` | Absolute URL of the new `.zip` (SSRF-guarded download); https as-is, http only with a `#sha256=` pin |+| Field | Type | Required | Constraints | Description |+| ----- | ------ | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |+| `url` | string | Yes | `@IsUrl({ protocols:['http','https'], require_protocol:true })` | Absolute URL of the new `.zip` (SSRF-guarded download); http only with a `#sha256=` pin, which production also requires on https |```json{ "url": "https://example.com/plugins/chat-flow-1.1.0.zip" }diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.mdindex 6b6d546dd..2de38f1ff 100644--- a/docs/19-plugin-architecture.md+++ b/docs/19-plugin-architecture.md@@ -641,7 +641,7 @@ URL / catalog), not an npm/github source descriptor.| `GET /plugins/catalog` | List the remote plugin catalog, annotated with install state || `GET /plugins/:id` | Get a single plugin || `POST /plugins/install` | Install from an uploaded `.zip` (`multipart/form-data`, field `file`, ≤ 5 MB) |-| `POST /plugins/install-url` | Install by downloading a `.zip` from an https URL (SSRF-guarded; optional `#sha256=` digest pin) |+| `POST /plugins/install-url` | Install by downloading a `.zip` from an https URL (SSRF-guarded; `#sha256=` pin required in production) || `POST /plugins/:id/update` | Update an installed plugin in place from a URL (staged swap, crash-safe; preserves config + enabled state) || `POST /plugins/:id/enable` | Enable a plugin || `POST /plugins/:id/disable` | Disable a plugin |