Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(plugins): refuse a plugin that needs a newer OpenWA
Yudhi Armyndharis51ea12c307b1
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.mdindex a18e7bb17..23e88d020 100644--- a/docs/19-plugin-architecture.md+++ b/docs/19-plugin-architecture.md@@ -109,8 +109,8 @@ plugins/### Manifest File`id`, `name`, `version`, `type`, and `main` are required; the rest are optional. There is **no**-`types` field and **no** version-compatibility (`min`/`maxVersion`) check — the loader does not gate on-a host version, except for the SDK-major check applied to a manifest that declares `ingress` (see the+`types` field and **no** `maxVersion`. The host version is gated by `minOpenWAVersion` only (see its+row), and the SDK major by the check applied to a manifest that declares `ingress` (see the`sdkVersion` row). The config schema is the top-level `configSchema` (note: not nested under `config`).```json@@ -166,6 +166,7 @@ a host version, except for the SDK-major check applied to a manifest that declar| `net.allow` | — | Outbound-HTTP host allowlist for `ctx.net.fetch` (`host`, `host:port`, or `'*'`). Absent = deny all, unless `net.allowConfigHosts` admits a host || `net.allowConfigHosts` | — | Config keys holding an https URL; each URL's host is admitted at fetch time on top of `net.allow`, so an adapter can reach an operator-configured host without `net.allow: ['*']`. Credentialed or non-https values are ignored, and the SSRF guard still applies || `sdkVersion` | — | Integration SDK `major` (or `major.minor`) the plugin was authored against. Absent = `'1'`. Only enforced for a manifest declaring `ingress`: a major other than `1` is refused at load |+| `minOpenWAVersion` | - | Oldest OpenWA release the plugin runs on (`MAJOR.MINOR.PATCH`). Install answers 400 and boot load fails when the running host is older; a malformed value is rejected. Absent or `null` = no floor || `ingress` | — | Inbound webhook routes this plugin claims (requires the `webhook:ingress` permission). Validated at load — route uniqueness, signature scheme, ack contract; see [25 — Integration Fabric](./25-integration-fabric.md) || `configSchema` | — | Declarative config schema the dashboard renders as a form when there is no `configUi`. Still required with one: it defines the fields, their types and which are `secret` || `configUi` | — | Optional self-contained HTML config editor served into a sandboxed iframe. When present it **replaces** the generated form and owns saving — the dashboard renders neither the form nor its Save button |@@ -538,9 +539,11 @@ volume; `PLUGINS_DIR` overrides it). For eachsub-directory with a `manifest.json` it reads the manifest, validates the required fields(`id`/`name`/`version`/`type`/`main`), and records an `INSTALLED` plugin plus a persisted registryentry — **without running any plugin code**. Persisted config and per-session activation/config are-read back so an operator's choices survive a restart. There is **no** host version-compatibility check;-the one version gate is `validateIngressManifest`, which refuses a manifest declaring `ingress` whose-`sdkVersion` major is not the supported Integration SDK major (`1`).+read back so an operator's choices survive a restart. There are two version gates. The manifest+validator refuses a plugin whose `minOpenWAVersion` is newer than the running OpenWA (the plugin goes+to `ERROR` with its config kept, and loads again after a host upgrade), and `validateIngressManifest`+refuses a manifest declaring `ingress` whose `sdkVersion` major is not the supported Integration SDK+major (`1`).> Loading a plugin from disk never runs it: a load always yields `INSTALLED`. Enabling is a separate> step that runs the lifecycle, and happens either on an explicit ADMIN action or — for a plugin thediff --git a/src/core/plugins/plugin-manifest.spec.ts b/src/core/plugins/plugin-manifest.spec.tsindex e42499207..8990e99af 100644--- a/src/core/plugins/plugin-manifest.spec.ts+++ b/src/core/plugins/plugin-manifest.spec.ts@@ -57,4 +57,40 @@ describe('validatePluginManifest', () => {expect(() => validatePluginManifest({ ...valid, main: './index.js' })).not.toThrow();expect(() => validatePluginManifest({ ...valid, main: 'dist/../index.js' })).not.toThrow();});++ describe('minOpenWAVersion', () => {+ const host = '0.23.7';++ it('accepts an absent or null floor', () => {+ expect(() => validatePluginManifest({ ...valid }, host)).not.toThrow();+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: null }, host)).not.toThrow();+ });++ it('accepts a floor at or below the running host', () => {+ for (const min of ['0.23.7', '0.8.16', '0.0.1']) {+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: min }, host)).not.toThrow();+ }+ });++ it('rejects a floor above the running host, naming both versions', () => {+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: '0.24.0' }, host)).toThrow(+ /my-plg requires OpenWA >= 0\.24\.0 \(running 0\.23\.7\)/,+ );+ });++ it('rejects a malformed floor instead of reading it as 0.0.0', () => {+ for (const min of ['v1.0.0', '1.2', 'garbage', 5, '']) {+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: min }, host)).toThrow(/minOpenWAVersion/);+ }+ });++ it('lets a prerelease host satisfy its own release floor', () => {+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: '0.24.0' }, '0.24.0-rc.1')).not.toThrow();+ });++ it('checks against the running package version by default', () => {+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: '0.0.1' })).not.toThrow();+ expect(() => validatePluginManifest({ ...valid, minOpenWAVersion: '999.0.0' })).toThrow(/requires OpenWA/);+ });+ });});diff --git a/src/core/plugins/plugin-manifest.ts b/src/core/plugins/plugin-manifest.tsindex 4c0ced519..ade53a06b 100644--- a/src/core/plugins/plugin-manifest.ts+++ b/src/core/plugins/plugin-manifest.ts@@ -1,5 +1,10 @@import * as path from 'path';import { PluginManifest, PluginType } from './plugin.interfaces';+import { compareSemver } from '../../modules/plugins/catalog';++// The version of the running code (same source as /api/health), the default floor check target.+// eslint-disable-next-line @typescript-eslint/no-require-imports+const { version: HOST_VERSION } = require('../../../package.json') as { version: string };/*** Plugin ids a plugin package / directory must never use. `whatsapp-web.js` / `baileys` are built-in@@ -14,6 +19,8 @@ export const INSTALLABLE_TYPES = new Set<string>([PluginType.EXTENSION]);const SAFE_ID = /^[a-z0-9][a-z0-9._-]*$/i;const REQUIRED_FIELDS = ['id', 'name', 'version', 'type', 'main'] as const;+// compareSemver reads garbage as 0.0.0, so a floor must be well-formed before it is compared.+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;/*** The manifest validation BOTH install-time (parsePluginPackage) and boot-time@@ -23,12 +30,17 @@ const REQUIRED_FIELDS = ['id', 'name', 'version', 'type', 'main'] as const;* logged + the directory skipped).** Checks: plain-object shape; required fields present as non-empty strings; id format + reserved- * ids; installable (extension) type; and that `main` is a relative path that cannot escape the- * plugin directory. The `main` check here is lexical (forward-slash semantics); the loader- * additionally anchors it against the real on-disk directory, which also catches platform-separator- * tricks, and requires the entry file to exist (parity with install's in-archive check).+ * ids; installable (extension) type; that `main` is a relative path that cannot escape the+ * plugin directory; and that an optional `minOpenWAVersion` is a MAJOR.MINOR.PATCH version no newer+ * than `hostVersion` (pre-release suffixes are ignored, so 0.24.0-rc.1 satisfies 0.24.0). The+ * `main` check here is lexical (forward-slash semantics); the loader additionally anchors it+ * against the real on-disk directory, which also catches platform-separator tricks, and requires+ * the entry file to exist (parity with install's in-archive check).*/-export function validatePluginManifest(manifest: unknown): asserts manifest is PluginManifest {+export function validatePluginManifest(+ manifest: unknown,+ hostVersion: string = HOST_VERSION,+): asserts manifest is PluginManifest {// JSON.parse("null") / "[]" / "5" don't throw — but indexing a field on a non-object then throws a// TypeError downstream. Require a plain object up front.if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {@@ -56,6 +68,15 @@ export function validatePluginManifest(manifest: unknown): asserts manifest is P);}assertMainContained(m.main);+ const min: unknown = m.minOpenWAVersion;+ if (min !== undefined && min !== null) {+ if (typeof min !== 'string' || !SEMVER.test(min)) {+ throw new Error('manifest.json minOpenWAVersion must be a MAJOR.MINOR.PATCH version');+ }+ if (compareSemver(hostVersion, min) < 0) {+ throw new Error(`Plugin ${m.id} requires OpenWA >= ${min} (running ${hostVersion})`);+ }+ }}/**diff --git a/src/core/plugins/plugin-package-scanner.ts b/src/core/plugins/plugin-package-scanner.tsindex 7ccd38d55..fbea21727 100644--- a/src/core/plugins/plugin-package-scanner.ts+++ b/src/core/plugins/plugin-package-scanner.ts@@ -304,9 +304,10 @@ export class PluginPackageScanner {// Boot-time validation is the SAME validation install runs (parsePluginPackage): a hand-placed// or crash-leftover directory must satisfy the install contract too — plain-object shape,- // required string fields, id format + reserved ids, extension-only type, and a `main` that- // cannot escape the plugin dir. Otherwise a manifest the installer would have rejected loads- // anyway and only fails (or worse, runs unexpected code) at enable time.+ // required string fields, id format + reserved ids, extension-only type, a `main` that cannot+ // escape the plugin dir, and no minOpenWAVersion floor above the running host. Otherwise a+ // manifest the installer would have rejected loads anyway and only fails (or worse, runs+ // unexpected code) at enable time.validatePluginManifest(manifest);// Anchor `main` inside THIS on-disk directory: the lexical check above is forward-slash only,diff --git a/src/core/plugins/plugin.interfaces.ts b/src/core/plugins/plugin.interfaces.tsindex bce0a6295..7a8e5486a 100644--- a/src/core/plugins/plugin.interfaces.ts+++ b/src/core/plugins/plugin.interfaces.ts@@ -102,6 +102,10 @@ export interface PluginManifest {// is enforced — see SUPPORTED_SDK_MAJOR / validateIngressManifest. Absent = treated as '1'.sdkVersion?: string;+ // Oldest OpenWA release the plugin runs on (MAJOR.MINOR.PATCH). validatePluginManifest refuses the+ // plugin at install and at boot load when the running host is older. Absent or null = no floor.+ minOpenWAVersion?: string | null;+// Inbound webhook routes this plugin claims (requires the `webhook:ingress` permission). Validated// by validateIngressManifest, which the loader calls on every external plugin load (loadPlugin).// (Built-in registration declares no ingress and bypasses that validation.)diff --git a/src/modules/plugins/plugin-installer.spec.ts b/src/modules/plugins/plugin-installer.spec.tsindex 98a939f4c..17f76b594 100644--- a/src/modules/plugins/plugin-installer.spec.ts+++ b/src/modules/plugins/plugin-installer.spec.ts@@ -119,6 +119,13 @@ describe('parsePluginPackage', () => {);});+ it('rejects a package that needs a newer OpenWA with a 400', () => {+ const bad = { ...validManifest, minOpenWAVersion: '999.0.0' };+ const zip = zipOf({ 'manifest.json': JSON.stringify(bad), 'index.js': 'x' });+ expect(() => parsePluginPackage(zip)).toThrow(BadRequestException);+ expect(() => parsePluginPackage(zip)).toThrow(/requires OpenWA >= 999\.0\.0/);+ });+it('rejects a non-string required field (numeric main) with a clean 400, not a TypeError/500', () => {// A non-string `main` is truthy, so a bare falsy check would pass it through and then crash// path.posix.normalize with an uncaught TypeError (HTTP 500). It must be rejected as a 400.