Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 each
sub-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 registry
entry — **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 the
diff --git a/src/core/plugins/plugin-manifest.spec.ts b/src/core/plugins/plugin-manifest.spec.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.