Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(plugins): hold stored secrets back from a moved host key

Yudhi Armyndharis30cf15fc3016
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 756c6d074..7db7e974a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -371,7 +371,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.
+- 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. A host key that holds a list, an object or a number counts as another origin, and a write to an override or an instance that moves a host key to another origin no longer gets the stored secret back for `***` or an empty string; send the secret with it.
- A send or message-action body whose `chatId`, `fromChatId` or `toChatId` has no domain (`6281234567890` instead of `[email protected]`), or is a JSON number, answers `400`; it answered `500` before and never sent.
### Security
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index 267d4a7ce..c1e6b06d6 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -206,7 +206,10 @@ removes it for an explicit `null`. A per-session override and an integration ins
overlaid on the base config, secret fields included, so a stored secret reaches every override that does
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.
+one is dropped whole) and must bring its own. A host key that holds no text (a list, an object, a number) counts
+as another origin. The same rule applies on write: a write to an override or an instance that points a host key
+at another origin than the stored layer names gets no stored secret back for the mask or an empty string, so
+the secret has to be sent with it.
### Plugin Entry Point
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index 33fc0dbe3..f9849e686 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -130,7 +130,9 @@ Alongside this async pipeline, a route may additionally declare a `response` con
projection is re-keyed per instance. The base configuration is also the layer under every instance
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
+ that keeps the same origin, or sets no host key, inherits them. A host key that holds no text counts as
+ another origin, and a write that moves a host key to another origin than the stored layer names gets no
+ stored secret back for the mask, so the secret has to be sent with it. 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
diff --git a/src/core/plugins/plugin-activation.spec.ts b/src/core/plugins/plugin-activation.spec.ts
index 05c6fbd78..dedaca390 100644
--- a/src/core/plugins/plugin-activation.spec.ts
+++ b/src/core/plugins/plugin-activation.spec.ts
@@ -4,6 +4,7 @@ import {
isPluginActiveForSession,
resolveInstanceConfig,
resolvePluginConfig,
+ restorableConfig,
sessionScopeKey,
} from './plugin-activation';
@@ -151,12 +152,21 @@ describe('a layer that names another host than the layer beneath', () => {
expect(resolveFor({ inboxId: '9' })).toMatchObject({ apiToken: 'OPERATOR-TOKEN', inboxId: '9' });
});
- it('is no redirect when the host key is set to nothing or to a non-string', () => {
- for (const none of ['', ' ', null, 5]) {
+ it('is no redirect when the host key is set to nothing', () => {
+ for (const none of ['', ' ', null, undefined]) {
expect(resolveFor({ baseUrl: none })).toMatchObject({ apiToken: 'OPERATOR-TOKEN' });
}
});
+ // A plugin may turn a value that is no text into a URL: String(['https://x.example']) is 'https://x.example'. With no
+ // origin to compare, such a value is a redirect, or a one-element list would carry the operator's token to its host.
+ it('is a redirect when the host key holds a list, an object, a number or a boolean', () => {
+ for (const odd of [['https://attacker.example'], { url: 'https://attacker.example' }, 5, true, []]) {
+ expect(resolveFor({ baseUrl: odd })).not.toHaveProperty('apiToken');
+ expect(resolveInstanceConfig(base, { baseUrl: odd }, adapter)).not.toHaveProperty('apiToken');
+ }
+ });
+
it('counts a host named where the base names none', () => {
expect(resolvePluginConfig({ apiToken: 'T' }, { s: { baseUrl: 'https://x.example' } }, 's', true, adapter)).toEqual(
{
@@ -222,6 +232,41 @@ describe('resolveInstanceConfig', () => {
});
});
+describe('restorableConfig: the stored layer a write may restore a masked secret from', () => {
+ const stored = { baseUrl: 'https://tenant.example', apiToken: 'TENANT-TOKEN', inboxId: '3' };
+
+ it('is the stored layer when the write keeps the host or leaves it alone', () => {
+ expect(restorableConfig(stored, { baseUrl: 'HTTPS://Tenant.Example:443/x', apiToken: '***' }, adapter)).toBe(
+ stored,
+ );
+ expect(restorableConfig(stored, { inboxId: '4', apiToken: '***' }, adapter)).toBe(stored);
+ expect(restorableConfig(stored, { baseUrl: '', apiToken: '***' }, adapter)).toBe(stored);
+ });
+
+ it('holds back every stored secret when the write points the host key at another origin', () => {
+ expect(restorableConfig(stored, { baseUrl: 'https://attacker.example', apiToken: '***' }, adapter)).toEqual({
+ baseUrl: 'https://tenant.example',
+ inboxId: '3',
+ });
+ });
+
+ it('treats a host key that is no text as another origin, and a first host as one too', () => {
+ expect(restorableConfig(stored, { baseUrl: ['https://attacker.example'] }, adapter)).not.toHaveProperty('apiToken');
+ expect(restorableConfig({ apiToken: 'T' }, { baseUrl: 'https://x.example' }, adapter)).toEqual({});
+ });
+
+ it('holds back everything when there is no schema to tell a secret from, and has nothing to hold back without a layer', () => {
+ expect(restorableConfig(stored, { baseUrl: 'https://x.example' }, { net: adapter.net })).toEqual({});
+ expect(restorableConfig(undefined, { baseUrl: 'https://x.example' }, adapter)).toBeUndefined();
+ });
+
+ it('is the stored layer when the manifest names no host key', () => {
+ expect(restorableConfig(stored, { baseUrl: 'https://x.example' }, { configSchema: adapter.configSchema })).toBe(
+ stored,
+ );
+ });
+});
+
describe('the all-sessions scope', () => {
it.each([null, undefined, '', '*'])('is one key whichever way it is spelled (%j)', scope => {
expect(sessionScopeKey(scope)).toBe('*');
diff --git a/src/core/plugins/plugin-activation.ts b/src/core/plugins/plugin-activation.ts
index 094bc08e8..1aafe2702 100644
--- a/src/core/plugins/plugin-activation.ts
+++ b/src/core/plugins/plugin-activation.ts
@@ -62,10 +62,17 @@ function hostOf(value: unknown): string | null {
}
}
-/** Whether `layer` points a host key at an origin other than the one `beneath` names. */
+/**
+ * Whether `layer` points a host key at an origin other than the one `beneath` names. A value that is no text
+ * (a list, an object, a number) has no origin to compare, yet a plugin may still turn it into a URL
+ * (`String(['https://x.example'])` is `https://x.example`), so it counts as a redirect: only an unset, null or
+ * blank value names nothing.
+ */
const redirectsHost = (beneath: Record<string, unknown>, layer: Record<string, unknown>, hostKeys: string[]): boolean =>
hostKeys.some(key => {
- const next = hostOf(layer[key]);
+ const value = layer[key];
+ if (typeof value !== 'string') return value !== undefined && value !== null;
+ const next = hostOf(value);
return next !== null && next !== hostOf(beneath[key]);
});
@@ -112,6 +119,24 @@ function mergeLayer(
return deepMerge(properties ? withoutSecrets(beneath, properties) : {}, layer);
}
+/**
+ * The stored layer a write may restore a masked or blank secret from. A write that points a host key at
+ * another origin than the stored layer names gets none of the stored secrets back, for the reason
+ * {@link mergeLayer} gives: they belong to the host they were saved for, and a key allowed to write the layer
+ * (a session-restricted admin) would otherwise send them to a host of its choosing by echoing the mask. A
+ * masked or blank secret in such a write is then dropped, and the sender has to supply it.
+ */
+export function restorableConfig(
+ stored: Record<string, unknown> | undefined,
+ incoming: Record<string, unknown>,
+ manifest: ConfigLayerManifest,
+): Record<string, unknown> | undefined {
+ const hostKeys = manifest.net?.allowConfigHosts;
+ if (!stored || !hostKeys?.length || !redirectsHost(stored, incoming, hostKeys)) return stored;
+ const properties = manifest.configSchema?.properties;
+ return properties ? withoutSecrets(stored, properties) : {};
+}
+
/**
* Layer one integration instance's own config over whatever resolution produced.
*
diff --git a/src/modules/integration/integration-instance.controller.spec.ts b/src/modules/integration/integration-instance.controller.spec.ts
index 737a2a1f0..2912210e0 100644
--- a/src/modules/integration/integration-instance.controller.spec.ts
+++ b/src/modules/integration/integration-instance.controller.spec.ts
@@ -390,6 +390,7 @@ describe('IntegrationInstanceController provisioning bridge', () => {
'acct1',
{ sessionScope: null, config: undefined },
undefined,
+ undefined,
);
expect(view.sessionScope).toBeNull();
expect(setPluginSessionConfig).toHaveBeenCalledWith('chatwoot-adapter', 'sess-1', {}); // old scope torn down
@@ -625,10 +626,10 @@ describe('IntegrationInstanceController session-scope fence', () => {
const scopedKey = { allowedSessions: ['sess-1'] } as ApiKey;
const unrestrictedKey = { allowedSessions: null } as unknown as ApiKey;
- function build(instances: Partial<PluginInstanceService>) {
+ function build(instances: Partial<PluginInstanceService>, net?: { allowConfigHosts: string[] }) {
const loader = {
getPlugin: jest.fn().mockReturnValue({
- manifest: { id: 'chatwoot-adapter', ingress: [{ route: 'chatwoot' }], permissions: ['webhook:ingress'] },
+ manifest: { id: 'chatwoot-adapter', ingress: [{ route: 'chatwoot' }], permissions: ['webhook:ingress'], net },
activeSessions: [],
}),
setPluginSessionConfig: jest.fn(),
@@ -744,6 +745,19 @@ describe('IntegrationInstanceController session-scope fence', () => {
expect(update).not.toHaveBeenCalled();
});
+ // The service holds back a stored secret from a PATCH that moves a host key, but only knows the host keys if
+ // the controller hands over the manifest's net rules.
+ it('hands the manifest net rules to update(), so a moved host key is told from an unchanged one', async () => {
+ const inst = { ...baseInstance, sessionScope: 'sess-1' };
+ const update = jest.fn().mockResolvedValue(inst);
+ const net = { allowConfigHosts: ['baseUrl'] };
+ const { controller } = build({ resolve: jest.fn().mockResolvedValue(inst), update }, net);
+
+ await controller.patch('chatwoot-adapter', 'acct1', { config: { baseUrl: 'https://x.example' } }, scopedKey);
+
+ expect(update.mock.calls[0][4]).toBe(net);
+ });
+
it('lets a scoped key patch an in-scope instance without touching sessionScope', async () => {
const inst = { ...baseInstance, sessionScope: 'sess-1' };
const update = jest.fn().mockResolvedValue({ ...inst, enabled: false });
@@ -756,6 +770,7 @@ describe('IntegrationInstanceController session-scope fence', () => {
'acct1',
{ enabled: false, sessionScope: undefined, config: undefined },
undefined,
+ undefined,
);
});
});
@@ -1005,6 +1020,7 @@ describe('IntegrationInstanceController update audit', () => {
'acct1',
{ enabled: false, sessionScope: 'sess-2', config: { apiToken: 'rotated-token' } },
undefined,
+ undefined,
);
});
diff --git a/src/modules/integration/integration-instance.controller.ts b/src/modules/integration/integration-instance.controller.ts
index f89926ac7..5c446355c 100644
--- a/src/modules/integration/integration-instance.controller.ts
+++ b/src/modules/integration/integration-instance.controller.ts
@@ -161,6 +161,7 @@ export class IntegrationInstanceController {
instanceId,
{ enabled: dto.enabled, sessionScope: dto.sessionScope, config: dto.config },
this.schemaFor(pluginId),
+ this.loader.getPlugin(pluginId)?.manifest.net,
);
// update() answers null when the row was deleted after resolveVisible read it.
if (!inst) throw new NotFoundException('instance not found');
diff --git a/src/modules/integration/plugin-instance.service.spec.ts b/src/modules/integration/plugin-instance.service.spec.ts
index 8623225c3..acfa22886 100644
--- a/src/modules/integration/plugin-instance.service.spec.ts
+++ b/src/modules/integration/plugin-instance.service.spec.ts
@@ -116,6 +116,35 @@ describe('PluginInstanceService', () => {
expect(updated?.config).toEqual({ apiToken: 'real-token', accountId: 2 });
});
+
+ it('update withholds the stored secret from a PATCH that points the host key at another origin', async () => {
+ const schema = {
+ type: 'object',
+ properties: { baseUrl: { type: 'string' }, apiToken: { type: 'string', secret: true } },
+ } as PluginConfigSchema;
+ const net = { allowConfigHosts: ['baseUrl'] };
+ await service.create('chatwoot', 'acct1', {
+ config: { baseUrl: 'https://tenant.example', apiToken: 'real-token' },
+ });
+
+ const same = await service.update(
+ 'chatwoot',
+ 'acct1',
+ { config: { baseUrl: 'https://tenant.example/x', apiToken: '***' } },
+ schema,
+ net,
+ );
+ expect(same?.config).toEqual({ baseUrl: 'https://tenant.example/x', apiToken: 'real-token' });
+
+ const moved = await service.update(
+ 'chatwoot',
+ 'acct1',
+ { config: { baseUrl: 'https://attacker.example', apiToken: '***' } },
+ schema,
+ net,
+ );
+ expect(moved?.config).toEqual({ baseUrl: 'https://attacker.example' });
+ });
});
describe('PluginInstanceService provisioning', () => {
diff --git a/src/modules/integration/plugin-instance.service.ts b/src/modules/integration/plugin-instance.service.ts
index 103ba88e0..7407252d1 100644
--- a/src/modules/integration/plugin-instance.service.ts
+++ b/src/modules/integration/plugin-instance.service.ts
@@ -6,7 +6,8 @@ import { PluginInstance } from './entities/plugin-instance.entity';
import { ConversationMapping } from './entities/conversation-mapping.entity';
import { isUniqueViolation } from '../../common/utils/db-errors';
import { awaitNoOpenTransaction } from '../../common/utils/shared-connection';
-import type { PluginConfigSchema } from '../../core/plugins/plugin.interfaces';
+import type { PluginConfigSchema, PluginManifest } from '../../core/plugins/plugin.interfaces';
+import { restorableConfig } from '../../core/plugins/plugin-activation';
import { redactSecretConfig, restoreSecretConfig, SECRET_SENTINEL } from '../plugins/redact-config';
// Type-only: the module binds this class to PLUGIN_INSTANCE_PORT with a `useExisting` alias, which
// TypeScript does not check, so `implements` is what keeps the two in step.
@@ -123,6 +124,7 @@ export class PluginInstanceService implements PluginInstancePort {
instanceId: string,
patch: { enabled?: boolean; sessionScope?: string | null; config?: Record<string, unknown> },
schema?: PluginConfigSchema,
+ net?: PluginManifest['net'],
): Promise<PluginInstance | null> {
const inst = await this.resolve(pluginId, instanceId);
if (!inst) return null;
@@ -133,7 +135,9 @@ export class PluginInstanceService implements PluginInstancePort {
// The operator view masks secrets as the sentinel, so a round-tripped config carries '***' for
// unchanged secrets. Restore the stored values instead of persisting the mask (which would corrupt
// the credential); genuinely-new values are written as provided.
- changes.config = restoreSecretConfig(patch.config, inst.config ?? undefined, schema);
+ // A PATCH that points a host key at another origin gets no stored secret back, see restorableConfig.
+ const stored = restorableConfig(inst.config ?? undefined, patch.config, { configSchema: schema, net });
+ changes.config = restoreSecretConfig(patch.config, stored, schema);
}
if (Object.keys(changes).length === 0) return inst;
const { affected } = await this.repo.update({ id: inst.id }, changes as QueryDeepPartialEntity<PluginInstance>);
diff --git a/src/modules/plugins/plugins.service.spec.ts b/src/modules/plugins/plugins.service.spec.ts
index da96b5873..3a7e92c31 100644
--- a/src/modules/plugins/plugins.service.spec.ts
+++ b/src/modules/plugins/plugins.service.spec.ts
@@ -698,6 +698,47 @@ describe('PluginsService — per-session config', () => {
expect(loader.getPlugin('sess-cfg')?.sessionConfig?.['sess-A']).toEqual({ apiKey: 'A-secret', lang: 'en' });
});
+ // A session-restricted admin may write a session's override but cannot read its secrets, which come back masked.
+ // Echoing the mask must not retarget a stored secret: it belongs to the host it was saved for.
+ describe('with a host key the plugin may call', () => {
+ const hostManifest = {
+ ...manifest,
+ id: 'sess-host',
+ net: { allowConfigHosts: ['baseUrl'] },
+ configSchema: {
+ type: 'object',
+ properties: { baseUrl: { type: 'string' }, apiKey: { type: 'string', secret: true } },
+ },
+ };
+ const slice = () => loader.getPlugin('sess-host')?.sessionConfig?.['sess-A'];
+
+ beforeEach(() => {
+ const z = new AdmZip();
+ z.addFile('manifest.json', Buffer.from(JSON.stringify(hostManifest)));
+ z.addFile('index.js', Buffer.from('module.exports = class {};'));
+ service.install({ buffer: z.toBuffer() });
+ service.updateSessionConfig('sess-host', 'sess-A', { baseUrl: 'https://tenant.example', apiKey: 'TENANT' });
+ });
+
+ it('keeps restoring the stored secret while the write names the same host', () => {
+ service.updateSessionConfig('sess-host', 'sess-A', { baseUrl: 'https://tenant.example/v2', apiKey: '***' });
+ expect(slice()).toEqual({ baseUrl: 'https://tenant.example/v2', apiKey: 'TENANT' });
+ });
+
+ it('drops a masked or blank secret in a write that points the host at another origin', () => {
+ for (const echoed of ['***', '']) {
+ service.updateSessionConfig('sess-host', 'sess-A', { baseUrl: 'https://tenant.example', apiKey: 'TENANT' });
+ service.updateSessionConfig('sess-host', 'sess-A', { baseUrl: 'https://attacker.example', apiKey: echoed });
+ expect(slice()).toEqual({ baseUrl: 'https://attacker.example' });
+ }
+ });
+
+ it('stores a secret the write brings itself, whatever the host', () => {
+ service.updateSessionConfig('sess-host', 'sess-A', { baseUrl: 'https://other.example', apiKey: 'NEW' });
+ expect(slice()).toEqual({ baseUrl: 'https://other.example', apiKey: 'NEW' });
+ });
+ });
+
// A write is merged over the stored base config, so a removed secret has to travel as null; an empty
// string is not a removal.
it('removes the base secret on an explicit null and keeps it on an empty string', () => {
diff --git a/src/modules/plugins/plugins.service.ts b/src/modules/plugins/plugins.service.ts
index c7e8d01fc..03d5e904e 100644
--- a/src/modules/plugins/plugins.service.ts
+++ b/src/modules/plugins/plugins.service.ts
@@ -14,6 +14,7 @@ import { pluginUpdateBackupDirName, pluginUpdateStagingDirName } from '../../cor
import type { PluginConfigSchema } from '../../core/plugins';
import { PluginDto } from './dto/plugin.dto';
import { redactSecretConfig, restoreSecretConfig } from './redact-config';
+import { restorableConfig } from '../../core/plugins/plugin-activation';
import { parsePluginPackage } from './plugin-installer';
import { assertDownloadSha256, assertPluginInstallUrl, fetchSafeBuffer } from './plugin-download';
import { annotateCatalog, CatalogEntry, CatalogPlugin, isCatalogEntry } from './catalog';
@@ -274,7 +275,11 @@ export class PluginsService {
try {
const existing = plugin.sessionConfig?.[sessionId];
- const merged = restoreSecretConfig(config, existing, plugin.manifest.configSchema);
+ const merged = restoreSecretConfig(
+ config,
+ restorableConfig(existing, config, plugin.manifest),
+ plugin.manifest.configSchema,
+ );
this.pluginLoader.setPluginSessionConfig(id, sessionId, merged);
return { success: true, message: `Plugin ${id} configuration for session ${sessionId} updated` };
} catch (error) {