From f17587914e0f74cdb407483174968349ea265645 Mon Sep 17 00:00:00 2001 From: Rajeh Taher Date: Tue, 17 Nov 2026 20:44:01 +0200 Subject: [PATCH] Verify webhook body signatures in n8n, Zapier and Pipedream triggers --- CHANGELOG.md | 7 ++ MAINTAINING.md | 4 +- make/README.md | 8 ++ make/functions/polymorfaAdvanced.js | 2 +- make/functions/polymorfaBody.js | 2 +- make/functions/polymorfaEnvelope.js | 2 +- make/functions/polymorfaHook.js | 2 +- make/functions/polymorfaRequest.js | 2 +- make/functions/polymorfaResult.js | 2 +- make/functions/polymorfaSegment.js | 2 +- n8n/README.md | 14 +++ n8n/nodes/Polymorfa/PolymorfaTrigger.node.ts | 19 ++-- n8n/shared/core.js | 2 +- n8n/shared/hooks.js | 48 ++++++++-- pipedream/README.md | 18 ++++ pipedream/common/core.cjs | 2 +- pipedream/common/hooks.cjs | 48 ++++++++-- pipedream/polymorfa.app.mjs | 1 + pipedream/sources/callEnded/callEnded.mjs | 6 +- .../messageReceived/messageReceived.mjs | 6 +- .../sources/messageState/messageState.mjs | 6 +- pipedream/sources/numberState/numberState.mjs | 6 +- scripts/generate.mjs | 2 +- shared/core.cjs | 2 +- shared/hooks.cjs | 48 ++++++++-- tests/fake-webhooks.cjs | 26 +++++- tests/hooks.test.cjs | 40 ++++----- tests/native.test.cjs | 76 ++++++++++++---- tests/pipedream.test.mjs | 23 +++-- tests/signature.test.cjs | 89 +++++++++++++++++++ zapier/README.md | 18 ++++ zapier/index.js | 15 ++-- zapier/shared/core.cjs | 2 +- zapier/shared/hooks.cjs | 48 ++++++++-- 34 files changed, 488 insertions(+), 110 deletions(-) create mode 100644 tests/signature.test.cjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a63920..d0091f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ ## Unreleased +- n8n, Zapier and Pipedream triggers verify `X-Webhook-Signature` (HMAC-SHA256 of + the raw body) in addition to the marker header. Activation stores the signing + secret privately, rotating it when the webhook already exists. Subscriptions + saved before this change have no secret and reject deliveries; deactivate and + reactivate them. Rotating an endpoint's secret in the Console also requires + reactivation. Make cannot read the raw body and keeps marker authentication. + - Separate webhook receiver secrets from public marker/idempotency metadata. - Remove the Webhook Creation Key field from all triggers. Each activation uses its own adapter-generated nonce, so off/on, n8n test listening and Pipedream diff --git a/MAINTAINING.md b/MAINTAINING.md index d619e99..967435b 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -75,7 +75,9 @@ an authenticated per-subscription header supported by the public subscription contract. A stable unique subscription key determines its private verifier. Reactivation reuses its owned hook; another callback cannot reuse the key while that hook exists. Changing a verifier or connection requires explicit lifecycle -and rotation testing. The adapters never emit signing secrets or add a relay. +and rotation testing. The adapters never emit signing secrets or add a relay. n8n, Zapier and Pipedream also verify `X-Webhook-Signature` over the raw body +with the endpoint's signing secret, which `hooks.activate` returns separately and +the adapter stores privately; Make cannot read the raw body and keeps the marker. All delivery channels can repeat events. Use the event ID in downstream dedupe storage and a stable business key for effects. Zapier and Pipedream also use that diff --git a/make/README.md b/make/README.md index 201c1f6..4fe4b26 100644 --- a/make/README.md +++ b/make/README.md @@ -56,6 +56,14 @@ template lookup `templates:read`, and hooks `webhooks:read` plus `webhooks:manag The universal **Make an API call** module permits only the public allowlist on the fixed Polymorfa origin; it cannot call arbitrary hosts or change principals. +Make webhooks do not verify `X-Webhook-Signature`. A dedicated webhook's +`communication.json` receives only the parsed `headers` and `body`; no raw request +body is available to IML, and the signature covers the exact raw bytes. Recomputing +it from re-serialized JSON would give false rejections or false acceptance, so the +Make trigger stays on its derived marker header only. Treat that marker as shared +receiver authentication, not as body integrity. The webhook's signing secret is not +requested or stored. Revisit this if Make exposes the raw body. + Writes require a stable business idempotency key and saved ISO start time. Map native files to base64 and MIME type within the 4 MiB decoded connector limit. Use string IDs. Deduplicate project-wide events by their stable event ID before diff --git a/make/functions/polymorfaAdvanced.js b/make/functions/polymorfaAdvanced.js index 8f6b9fd..fd269fe 100644 --- a/make/functions/polymorfaAdvanced.js +++ b/make/functions/polymorfaAdvanced.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaBody.js b/make/functions/polymorfaBody.js index 93bd3ca..9a68935 100644 --- a/make/functions/polymorfaBody.js +++ b/make/functions/polymorfaBody.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaEnvelope.js b/make/functions/polymorfaEnvelope.js index ca1526e..1caa1db 100644 --- a/make/functions/polymorfaEnvelope.js +++ b/make/functions/polymorfaEnvelope.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaHook.js b/make/functions/polymorfaHook.js index eb2c2bb..f232bcc 100644 --- a/make/functions/polymorfaHook.js +++ b/make/functions/polymorfaHook.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaRequest.js b/make/functions/polymorfaRequest.js index e2db7b8..aa456d3 100644 --- a/make/functions/polymorfaRequest.js +++ b/make/functions/polymorfaRequest.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaResult.js b/make/functions/polymorfaResult.js index 884229b..fd08d6a 100644 --- a/make/functions/polymorfaResult.js +++ b/make/functions/polymorfaResult.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/make/functions/polymorfaSegment.js b/make/functions/polymorfaSegment.js index 2e0e35c..423be0f 100644 --- a/make/functions/polymorfaSegment.js +++ b/make/functions/polymorfaSegment.js @@ -4,7 +4,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/n8n/README.md b/n8n/README.md index 5386459..d8fbaaf 100644 --- a/n8n/README.md +++ b/n8n/README.md @@ -44,6 +44,20 @@ Webhook subscriptions are project-wide. Filtering a workflow after receipt does not prevent disclosure to n8n. Dedupe by event `id` before downstream effects; repeated delivery is possible. Delete/disable the owned webhook before revoking its credential. +Each delivery must carry a valid `X-Webhook-Signature` header, an HMAC-SHA256 of +the exact raw request body made with the endpoint's signing secret. The trigger +checks it against the raw bytes before parsing the body, and also checks its +marker header. A missing, duplicate or invalid signature, a missing raw body or +a missing stored secret rejects the delivery. The node's signing secret is +kept in workflow static data and never emitted. Activation returns the secret from the create response, or rotates it +(zero overlap) when the webhook already exists, so activating a trigger replaces +any earlier secret for that webhook. + +Triggers saved before signature verification have no stored secret and reject +every delivery. Deactivate and reactivate the workflow to rotate and store a fresh secret. +Rotating the endpoint's signing secret in the Polymorfa Console also invalidates +the stored secret and rejects deliveries until the trigger is reactivated. + n8n executes your workflow under its own hosting and retention settings. Choosing a Polymorfa EU or Brazil region does not place n8n's processing in that region. Test with synthetic data and check the platform's logs before release. diff --git a/n8n/nodes/Polymorfa/PolymorfaTrigger.node.ts b/n8n/nodes/Polymorfa/PolymorfaTrigger.node.ts index 215e4de..d90d647 100644 --- a/n8n/nodes/Polymorfa/PolymorfaTrigger.node.ts +++ b/n8n/nodes/Polymorfa/PolymorfaTrigger.node.ts @@ -1,7 +1,7 @@ import { NodeConnectionTypes, NodeOperationError } from 'n8n-workflow'; import type { IHookFunctions, IWebhookFunctions, INodeType, INodeTypeDescription, IWebhookResponseData } from 'n8n-workflow'; import { events } from '../../shared/catalog'; -import { activate, unsubscribe, authenticate, envelope, find, identity } from '../../shared/hooks'; +import { activate, unsubscribe, authenticate, verify, envelope, find, identity } from '../../shared/hooks'; import { transport } from './transport'; export class PolymorfaTrigger implements INodeType { @@ -22,16 +22,19 @@ export class PolymorfaTrigger implements INodeType { const auth = await this.getCredentials('polymorfaApi'); const url = this.getNodeWebhookUrl('default')!, group = this.getNodeParameter('eventGroup') as string, subscriptionKey = this.getNodeParameter('subscriptionKey') as string; const found = await find(auth, url, group, subscriptionKey, transport(this), 'n8n'); - if (found) this.getWorkflowStaticData('node').subscription = { id: found.id, url, group, subscriptionKey, markerName: identity(auth, group, subscriptionKey).name }; - return !!found; + const data = this.getWorkflowStaticData('node'); + // A hook without a stored signing secret (saved before verification existed, or whose activation + // failed) is reported missing so n8n calls create, which rotates and stores a fresh secret. + if (found && typeof data.signingSecret === 'string') data.subscription = { id: found.id, url, group, subscriptionKey, markerName: identity(auth, group, subscriptionKey).name }; + return !!found && typeof data.signingSecret === 'string'; }, async create(this: IHookFunctions) { const auth = await this.getCredentials('polymorfaApi'); const data = this.getWorkflowStaticData('node'); // Node static data keeps this activation's creation nonce private to n8n. const store = { get: () => data.pendingCreation, set: (value: unknown) => { if (value) data.pendingCreation = value; else delete data.pendingCreation; } }; - const hook = await activate(auth, this.getNodeWebhookUrl('default')!, this.getNodeParameter('eventGroup') as string, this.getNodeParameter('subscriptionKey') as string, transport(this), 'n8n', store); - data.subscription = hook; return true; + const { owned: hook, secret } = await activate(auth, this.getNodeWebhookUrl('default')!, this.getNodeParameter('eventGroup') as string, this.getNodeParameter('subscriptionKey') as string, transport(this), 'n8n', store); + data.subscription = hook; data.signingSecret = secret; return true; }, async delete(this: IHookFunctions) { const data = this.getWorkflowStaticData('node'); @@ -40,6 +43,7 @@ export class PolymorfaTrigger implements INodeType { await unsubscribe(await this.getCredentials('polymorfaApi'), owned.id, owned.url, owned.group, owned.subscriptionKey, transport(this), 'n8n', owned.markerName); delete data.subscription; } + delete data.signingSecret; delete data.pendingCreation; return true; }, @@ -47,7 +51,10 @@ export class PolymorfaTrigger implements INodeType { async webhook(this: IWebhookFunctions): Promise { const group = this.getNodeParameter('eventGroup') as string; const auth = await this.getCredentials('polymorfaApi'); - if (!authenticate(auth, group, this.getNodeParameter('subscriptionKey') as string, this.getHeaderData())) { + // Verify the exact raw bytes n8n received, before any JSON parsing. No secret or no raw body fails closed. + const secret = this.getWorkflowStaticData('node').signingSecret; + const headers = this.getHeaderData(); + if (!authenticate(auth, group, this.getNodeParameter('subscriptionKey') as string, headers) || !verify(secret, this.getRequestObject().rawBody, headers)) { this.getResponseObject().status(401).end(); return { noWebhookResponse: true }; } try { diff --git a/n8n/shared/core.js b/n8n/shared/core.js index 3d7596b..59e7e2c 100644 --- a/n8n/shared/core.js +++ b/n8n/shared/core.js @@ -10,7 +10,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/n8n/shared/hooks.js b/n8n/shared/hooks.js index 9b68200..89e46c2 100644 --- a/n8n/shared/hooks.js +++ b/n8n/shared/hooks.js @@ -59,14 +59,31 @@ async function find(auth, url, group, subscriptionKey, transport, provider) { } throw new IntegrationError('subscription_inventory_requires_reconciliation'); } +// The API returns a webhook's signing secret once, at create or rotation. It is the only +// credential for body verification, so it is returned in its own field, never inside `owned`. +const SECRET = /^[\x21-\x7e]{16,512}$/; +function validSecret(value) { return typeof value === 'string' && SECRET.test(value); } +async function rotateSecret(auth, id, transport, provider) { + const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}/secret-rotations`; + let r; + try { + // A fresh key per attempt. An uncertain outcome is never retried here: the next activation rotates again. + r = await call(auth, transport, provider, 'POST', path, { overlapSeconds: 0 }, `integration-rotate-${randomUUID()}`); + } catch (error) { + if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw new IntegrationError('signing_secret_unavailable', error.status); + throw new IntegrationError('signing_secret_rotation_requires_reconciliation'); + } + if (!validSecret(r.data?.secret)) throw new IntegrationError('signing_secret_unavailable'); + return r.data.secret; +} async function subscribe(auth, url, group, subscriptionKey, transport, provider, nonce) { url = callback(url); const marker = identity(auth, group, subscriptionKey); const createKey = creationKey(marker.key, nonce); const record = hook => ({ id: hook.id, url, group, subscriptionKey, markerName: marker.name }); + // Returns { owned, secret }. `secret` goes to provider-private state only. const existing = await find(auth, url, group, subscriptionKey, transport, provider); - if (existing) return record(existing); - // Only the owned ID leaves this helper. The API's one-time signing secret is never emitted. + if (existing) return { owned: record(existing), secret: await rotateSecret(auth, existing.id, transport, provider) }; let r; try { // The adapter keeps this activation's nonce in private state, so an uncertain retry reuses the key. @@ -75,13 +92,18 @@ async function subscribe(auth, url, group, subscriptionKey, transport, provider, if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw error; // A lost response may follow a successful create. Reconcile; never blindly create again. const recovered = await find(auth, url, group, subscriptionKey, transport, provider); - if (recovered) return record(recovered); + // The secret was in the lost response, so rotate to obtain one. + if (recovered) return { owned: record(recovered), secret: await rotateSecret(auth, recovered.id, transport, provider) }; throw new IntegrationError('subscription_requires_reconciliation'); } if (!owns(r.data?.webhook, auth, url, group, subscriptionKey)) throw new IntegrationError('invalid_subscription_receipt'); // An idempotency receipt may outlive its deleted webhook. Verify live ownership. const live = await find(auth, url, group, subscriptionKey, transport, provider); - if (live && live.id === r.data.webhook.id) return record(live); + if (live && live.id === r.data.webhook.id) { + // A replayed receipt carries no secret; rotate instead. + const secret = validSecret(r.data.secret) ? r.data.secret : await rotateSecret(auth, live.id, transport, provider); + return { owned: record(live), secret }; + } if (!live) { try { await call(auth, transport, provider, 'GET', `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(r.data.webhook.id, 'webhook_id')}`); } catch (error) { if (error.status === 404) throw new IntegrationError('subscription_receipt_deleted'); } @@ -92,6 +114,7 @@ function creation(url, group, subscriptionKey) { return { nonce: randomUUID(), url: callback(url), group, subscriptionKey }; } // Store: provider-private { get(), set(value) } for this trigger's pending creation. +// Returns { owned, secret }; the caller stores `secret` in provider-private state. async function activate(auth, url, group, subscriptionKey, transport, provider, store) { const target = callback(url); let pending = await store.get(); @@ -100,15 +123,15 @@ async function activate(auth, url, group, subscriptionKey, transport, provider, } // Save before the create so an uncertain retry of this activation sends the same key. await store.set(pending); - let owned; - try { owned = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } + let result; + try { result = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } catch (error) { // The receipt names a confirmed-deleted webhook. The next activation needs a new nonce. if (error.code === 'subscription_receipt_deleted') await store.set(null); throw error; } await store.set(null); - return owned; + return result; } async function unsubscribe(auth, id, url, group, subscriptionKey, transport, provider, recordedMarker) { const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}`; @@ -126,9 +149,18 @@ function authenticate(auth, group, subscriptionKey, incomingHeaders, prefixes = if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected.value)); } +// Verifies X-Webhook-Signature: lowercase hex HMAC-SHA256 of the exact raw body bytes. Fails closed. +function verify(secret, rawBody, incomingHeaders, prefixes = ['']) { + if (!validSecret(secret) || !(Buffer.isBuffer(rawBody) || typeof rawBody === 'string')) return false; + const names = prefixes.map(p => (p + 'x-webhook-signature').toLowerCase()); + const entries = Object.entries(incomingHeaders || {}).filter(([k]) => names.includes(k.toLowerCase())); + if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; + const expected = createHmac('sha256', secret).update(rawBody).digest('hex'); + return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected)); +} function envelope(body, group) { if (!events[group] || !body || typeof body !== 'object' || Array.isArray(body) || typeof body.id !== 'string' || !body.id || typeof body.session !== 'string' || !body.session || typeof body.timestamp !== 'string' || !Number.isFinite(Date.parse(body.timestamp)) || !events[group].types.includes(body.event) || !body.payload || typeof body.payload !== 'object' || Array.isArray(body.payload)) throw new IntegrationError('invalid_event'); // Copy the defined envelope only. Never export arbitrary top-level transport fields. return { id: body.id, session: body.session, ...(typeof body.externalId === 'string' ? { externalId: body.externalId } : {}), timestamp: body.timestamp, event: body.event, payload: body.payload }; } -module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, envelope }; +module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, verify, validSecret, envelope }; diff --git a/pipedream/README.md b/pipedream/README.md index f655617..f84f0b2 100644 --- a/pipedream/README.md +++ b/pipedream/README.md @@ -16,6 +16,24 @@ verifier and emits the public event envelope with `id` as its native dedupe key. Confirm lifecycle, log redaction, Connect actions/events and MCP tools on the real assigned app record before acceptance. +Each delivery must carry a valid `X-Webhook-Signature` header, an HMAC-SHA256 of +the exact raw request body made with the endpoint's signing secret. The trigger +checks it against the raw bytes before parsing the body, and also checks its +marker header. A missing, duplicate or invalid signature, a missing raw body or +a missing stored secret rejects the delivery. The source's signing secret is +kept in `$.service.db` and never emitted. Activation returns the secret from the create response, or rotates it +(zero overlap) when the webhook already exists, so activating a trigger replaces +any earlier secret for that webhook. + +Triggers saved before signature verification have no stored secret and reject +every delivery. Deactivate and redeploy (activate again) the source to rotate and store a fresh secret. +Rotating the endpoint's signing secret in the Polymorfa Console also invalidates +the stored secret and rejects deliveries until the trigger is reactivated. + +The signature is checked against `event.bodyRaw`. A delivery without it is +rejected. This field name comes from Pipedream's HTTP source documentation and is +not in the installed `@pipedream/platform` types; confirm it on a real source. + After the provider creates the app directory, prepare the contribution under its registry conventions, retain MIT attribution and submit the components for review. An unmerged contribution is not marketplace or Connect availability. No purchase diff --git a/pipedream/common/core.cjs b/pipedream/common/core.cjs index 3d7596b..59e7e2c 100644 --- a/pipedream/common/core.cjs +++ b/pipedream/common/core.cjs @@ -10,7 +10,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/pipedream/common/hooks.cjs b/pipedream/common/hooks.cjs index 8b518a7..5930d8e 100644 --- a/pipedream/common/hooks.cjs +++ b/pipedream/common/hooks.cjs @@ -59,14 +59,31 @@ async function find(auth, url, group, subscriptionKey, transport, provider) { } throw new IntegrationError('subscription_inventory_requires_reconciliation'); } +// The API returns a webhook's signing secret once, at create or rotation. It is the only +// credential for body verification, so it is returned in its own field, never inside `owned`. +const SECRET = /^[\x21-\x7e]{16,512}$/; +function validSecret(value) { return typeof value === 'string' && SECRET.test(value); } +async function rotateSecret(auth, id, transport, provider) { + const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}/secret-rotations`; + let r; + try { + // A fresh key per attempt. An uncertain outcome is never retried here: the next activation rotates again. + r = await call(auth, transport, provider, 'POST', path, { overlapSeconds: 0 }, `integration-rotate-${randomUUID()}`); + } catch (error) { + if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw new IntegrationError('signing_secret_unavailable', error.status); + throw new IntegrationError('signing_secret_rotation_requires_reconciliation'); + } + if (!validSecret(r.data?.secret)) throw new IntegrationError('signing_secret_unavailable'); + return r.data.secret; +} async function subscribe(auth, url, group, subscriptionKey, transport, provider, nonce) { url = callback(url); const marker = identity(auth, group, subscriptionKey); const createKey = creationKey(marker.key, nonce); const record = hook => ({ id: hook.id, url, group, subscriptionKey, markerName: marker.name }); + // Returns { owned, secret }. `secret` goes to provider-private state only. const existing = await find(auth, url, group, subscriptionKey, transport, provider); - if (existing) return record(existing); - // Only the owned ID leaves this helper. The API's one-time signing secret is never emitted. + if (existing) return { owned: record(existing), secret: await rotateSecret(auth, existing.id, transport, provider) }; let r; try { // The adapter keeps this activation's nonce in private state, so an uncertain retry reuses the key. @@ -75,13 +92,18 @@ async function subscribe(auth, url, group, subscriptionKey, transport, provider, if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw error; // A lost response may follow a successful create. Reconcile; never blindly create again. const recovered = await find(auth, url, group, subscriptionKey, transport, provider); - if (recovered) return record(recovered); + // The secret was in the lost response, so rotate to obtain one. + if (recovered) return { owned: record(recovered), secret: await rotateSecret(auth, recovered.id, transport, provider) }; throw new IntegrationError('subscription_requires_reconciliation'); } if (!owns(r.data?.webhook, auth, url, group, subscriptionKey)) throw new IntegrationError('invalid_subscription_receipt'); // An idempotency receipt may outlive its deleted webhook. Verify live ownership. const live = await find(auth, url, group, subscriptionKey, transport, provider); - if (live && live.id === r.data.webhook.id) return record(live); + if (live && live.id === r.data.webhook.id) { + // A replayed receipt carries no secret; rotate instead. + const secret = validSecret(r.data.secret) ? r.data.secret : await rotateSecret(auth, live.id, transport, provider); + return { owned: record(live), secret }; + } if (!live) { try { await call(auth, transport, provider, 'GET', `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(r.data.webhook.id, 'webhook_id')}`); } catch (error) { if (error.status === 404) throw new IntegrationError('subscription_receipt_deleted'); } @@ -92,6 +114,7 @@ function creation(url, group, subscriptionKey) { return { nonce: randomUUID(), url: callback(url), group, subscriptionKey }; } // Store: provider-private { get(), set(value) } for this trigger's pending creation. +// Returns { owned, secret }; the caller stores `secret` in provider-private state. async function activate(auth, url, group, subscriptionKey, transport, provider, store) { const target = callback(url); let pending = await store.get(); @@ -100,15 +123,15 @@ async function activate(auth, url, group, subscriptionKey, transport, provider, } // Save before the create so an uncertain retry of this activation sends the same key. await store.set(pending); - let owned; - try { owned = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } + let result; + try { result = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } catch (error) { // The receipt names a confirmed-deleted webhook. The next activation needs a new nonce. if (error.code === 'subscription_receipt_deleted') await store.set(null); throw error; } await store.set(null); - return owned; + return result; } async function unsubscribe(auth, id, url, group, subscriptionKey, transport, provider, recordedMarker) { const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}`; @@ -126,9 +149,18 @@ function authenticate(auth, group, subscriptionKey, incomingHeaders, prefixes = if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected.value)); } +// Verifies X-Webhook-Signature: lowercase hex HMAC-SHA256 of the exact raw body bytes. Fails closed. +function verify(secret, rawBody, incomingHeaders, prefixes = ['']) { + if (!validSecret(secret) || !(Buffer.isBuffer(rawBody) || typeof rawBody === 'string')) return false; + const names = prefixes.map(p => (p + 'x-webhook-signature').toLowerCase()); + const entries = Object.entries(incomingHeaders || {}).filter(([k]) => names.includes(k.toLowerCase())); + if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; + const expected = createHmac('sha256', secret).update(rawBody).digest('hex'); + return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected)); +} function envelope(body, group) { if (!events[group] || !body || typeof body !== 'object' || Array.isArray(body) || typeof body.id !== 'string' || !body.id || typeof body.session !== 'string' || !body.session || typeof body.timestamp !== 'string' || !Number.isFinite(Date.parse(body.timestamp)) || !events[group].types.includes(body.event) || !body.payload || typeof body.payload !== 'object' || Array.isArray(body.payload)) throw new IntegrationError('invalid_event'); // Copy the defined envelope only. Never export arbitrary top-level transport fields. return { id: body.id, session: body.session, ...(typeof body.externalId === 'string' ? { externalId: body.externalId } : {}), timestamp: body.timestamp, event: body.event, payload: body.payload }; } -module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, envelope }; +module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, verify, validSecret, envelope }; diff --git a/pipedream/polymorfa.app.mjs b/pipedream/polymorfa.app.mjs index 29f56b8..1d6a334 100644 --- a/pipedream/polymorfa.app.mjs +++ b/pipedream/polymorfa.app.mjs @@ -20,6 +20,7 @@ export default { activate($, url, group, key, store) { return hooks.activate(this.auth(), url, group, key, this.transport($), 'pipedream', store); }, unsubscribe($, owned) { return hooks.unsubscribe(this.auth(), owned.id, owned.url, owned.group, owned.subscriptionKey, this.transport($), 'pipedream', owned.markerName); }, authenticate(group, key, headers) { return hooks.authenticate(this.auth(), group, key, headers); }, + verify(secret, rawBody, headers) { return hooks.verify(secret, rawBody, headers); }, envelope(body, group) { return hooks.envelope(body, group); }, }, }; diff --git a/pipedream/sources/callEnded/callEnded.mjs b/pipedream/sources/callEnded/callEnded.mjs index dfe12a7..cd16ae2 100644 --- a/pipedream/sources/callEnded/callEnded.mjs +++ b/pipedream/sources/callEnded/callEnded.mjs @@ -8,17 +8,19 @@ export default { hooks: { async activate() { const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) }; - const owned = await this.polymorfa.activate(undefined, this.http.endpoint, "callEnded", this.subscriptionKey, store); + const { owned, secret } = await this.polymorfa.activate(undefined, this.http.endpoint, "callEnded", this.subscriptionKey, store); this.db.set('ownedSubscription', owned); + this.db.set('signingSecret', secret); }, async deactivate() { const owned = this.db.get('ownedSubscription'); if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); } + this.db.set('signingSecret', null); this.db.set('pendingCreation', null); }, }, async run(event) { - if (!this.polymorfa.authenticate("callEnded", this.subscriptionKey, event.headers)) { this.http.respond({ status: 401 }); return; } + if (!this.polymorfa.authenticate("callEnded", this.subscriptionKey, event.headers) || !this.polymorfa.verify(this.db.get('signingSecret'), event.bodyRaw, event.headers)) { this.http.respond({ status: 401 }); return; } let data; try { data = this.polymorfa.envelope(event.body, "callEnded"); } catch { this.http.respond({ status: 400 }); return; } this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) }); diff --git a/pipedream/sources/messageReceived/messageReceived.mjs b/pipedream/sources/messageReceived/messageReceived.mjs index 963c23d..c805fe3 100644 --- a/pipedream/sources/messageReceived/messageReceived.mjs +++ b/pipedream/sources/messageReceived/messageReceived.mjs @@ -8,17 +8,19 @@ export default { hooks: { async activate() { const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) }; - const owned = await this.polymorfa.activate(undefined, this.http.endpoint, "messageReceived", this.subscriptionKey, store); + const { owned, secret } = await this.polymorfa.activate(undefined, this.http.endpoint, "messageReceived", this.subscriptionKey, store); this.db.set('ownedSubscription', owned); + this.db.set('signingSecret', secret); }, async deactivate() { const owned = this.db.get('ownedSubscription'); if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); } + this.db.set('signingSecret', null); this.db.set('pendingCreation', null); }, }, async run(event) { - if (!this.polymorfa.authenticate("messageReceived", this.subscriptionKey, event.headers)) { this.http.respond({ status: 401 }); return; } + if (!this.polymorfa.authenticate("messageReceived", this.subscriptionKey, event.headers) || !this.polymorfa.verify(this.db.get('signingSecret'), event.bodyRaw, event.headers)) { this.http.respond({ status: 401 }); return; } let data; try { data = this.polymorfa.envelope(event.body, "messageReceived"); } catch { this.http.respond({ status: 400 }); return; } this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) }); diff --git a/pipedream/sources/messageState/messageState.mjs b/pipedream/sources/messageState/messageState.mjs index 8aba13e..f7b0ab2 100644 --- a/pipedream/sources/messageState/messageState.mjs +++ b/pipedream/sources/messageState/messageState.mjs @@ -8,17 +8,19 @@ export default { hooks: { async activate() { const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) }; - const owned = await this.polymorfa.activate(undefined, this.http.endpoint, "messageState", this.subscriptionKey, store); + const { owned, secret } = await this.polymorfa.activate(undefined, this.http.endpoint, "messageState", this.subscriptionKey, store); this.db.set('ownedSubscription', owned); + this.db.set('signingSecret', secret); }, async deactivate() { const owned = this.db.get('ownedSubscription'); if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); } + this.db.set('signingSecret', null); this.db.set('pendingCreation', null); }, }, async run(event) { - if (!this.polymorfa.authenticate("messageState", this.subscriptionKey, event.headers)) { this.http.respond({ status: 401 }); return; } + if (!this.polymorfa.authenticate("messageState", this.subscriptionKey, event.headers) || !this.polymorfa.verify(this.db.get('signingSecret'), event.bodyRaw, event.headers)) { this.http.respond({ status: 401 }); return; } let data; try { data = this.polymorfa.envelope(event.body, "messageState"); } catch { this.http.respond({ status: 400 }); return; } this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) }); diff --git a/pipedream/sources/numberState/numberState.mjs b/pipedream/sources/numberState/numberState.mjs index cff0dfd..80ae989 100644 --- a/pipedream/sources/numberState/numberState.mjs +++ b/pipedream/sources/numberState/numberState.mjs @@ -8,17 +8,19 @@ export default { hooks: { async activate() { const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) }; - const owned = await this.polymorfa.activate(undefined, this.http.endpoint, "numberState", this.subscriptionKey, store); + const { owned, secret } = await this.polymorfa.activate(undefined, this.http.endpoint, "numberState", this.subscriptionKey, store); this.db.set('ownedSubscription', owned); + this.db.set('signingSecret', secret); }, async deactivate() { const owned = this.db.get('ownedSubscription'); if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); } + this.db.set('signingSecret', null); this.db.set('pendingCreation', null); }, }, async run(event) { - if (!this.polymorfa.authenticate("numberState", this.subscriptionKey, event.headers)) { this.http.respond({ status: 401 }); return; } + if (!this.polymorfa.authenticate("numberState", this.subscriptionKey, event.headers) || !this.polymorfa.verify(this.db.get('signingSecret'), event.bodyRaw, event.headers)) { this.http.respond({ status: 401 }); return; } let data; try { data = this.polymorfa.envelope(event.body, "numberState"); } catch { this.http.respond({ status: 400 }); return; } this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) }); diff --git a/scripts/generate.mjs b/scripts/generate.mjs index 08e70b6..87a5e82 100644 --- a/scripts/generate.mjs +++ b/scripts/generate.mjs @@ -47,7 +47,7 @@ for (const [key, action] of Object.entries(actions)) { } emit(`pipedream/actions/${key}/${key}.mjs`, `// Generated from shared/catalog.cjs.\nimport polymorfa from '../../polymorfa.app.mjs';\nexport default {\n key: ${JSON.stringify('polymorfa-' + key)}, name: ${JSON.stringify(action.label)}, description: ${JSON.stringify(action.description)},\n version: '0.1.0', type: 'action',\n props: { polymorfa, ...${JSON.stringify(props, null, 2)} },\n async run({ $ }) {\n const input = Object.fromEntries(${JSON.stringify(action.fields)}.map(key => [key, this[key]]));\n return this.polymorfa.execute($, ${JSON.stringify(key)}, input);\n },\n};\n`); } -for (const [key, event] of Object.entries(events)) emit(`pipedream/sources/${key}/${key}.mjs`, `// Generated from shared/catalog.cjs.\nimport polymorfa from '../../polymorfa.app.mjs';\nexport default {\n key: ${JSON.stringify('polymorfa-' + key)}, name: ${JSON.stringify(event.label)}, description: ${JSON.stringify(event.description)},\n version: '0.1.0', type: 'source', dedupe: 'unique',\n props: { polymorfa, db: '$.service.db', http: { type: '$.interface.http', customResponse: true },\n subscriptionKey: { type: 'string', label: 'Subscription Key', description: 'Unique stable label for this source. Events are project-wide.' } },\n hooks: {\n async activate() {\n const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) };\n const owned = await this.polymorfa.activate(undefined, this.http.endpoint, ${JSON.stringify(key)}, this.subscriptionKey, store);\n this.db.set('ownedSubscription', owned);\n },\n async deactivate() {\n const owned = this.db.get('ownedSubscription');\n if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); }\n this.db.set('pendingCreation', null);\n },\n },\n async run(event) {\n if (!this.polymorfa.authenticate(${JSON.stringify(key)}, this.subscriptionKey, event.headers)) { this.http.respond({ status: 401 }); return; }\n let data;\n try { data = this.polymorfa.envelope(event.body, ${JSON.stringify(key)}); } catch { this.http.respond({ status: 400 }); return; }\n this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) });\n this.http.respond({ status: 200 });\n },\n};\n`); +for (const [key, event] of Object.entries(events)) emit(`pipedream/sources/${key}/${key}.mjs`, `// Generated from shared/catalog.cjs.\nimport polymorfa from '../../polymorfa.app.mjs';\nexport default {\n key: ${JSON.stringify('polymorfa-' + key)}, name: ${JSON.stringify(event.label)}, description: ${JSON.stringify(event.description)},\n version: '0.1.0', type: 'source', dedupe: 'unique',\n props: { polymorfa, db: '$.service.db', http: { type: '$.interface.http', customResponse: true },\n subscriptionKey: { type: 'string', label: 'Subscription Key', description: 'Unique stable label for this source. Events are project-wide.' } },\n hooks: {\n async activate() {\n const store = { get: () => this.db.get('pendingCreation'), set: value => this.db.set('pendingCreation', value || null) };\n const { owned, secret } = await this.polymorfa.activate(undefined, this.http.endpoint, ${JSON.stringify(key)}, this.subscriptionKey, store);\n this.db.set('ownedSubscription', owned);\n this.db.set('signingSecret', secret);\n },\n async deactivate() {\n const owned = this.db.get('ownedSubscription');\n if (owned) { await this.polymorfa.unsubscribe(undefined, owned); this.db.set('ownedSubscription', null); }\n this.db.set('signingSecret', null);\n this.db.set('pendingCreation', null);\n },\n },\n async run(event) {\n if (!this.polymorfa.authenticate(${JSON.stringify(key)}, this.subscriptionKey, event.headers) || !this.polymorfa.verify(this.db.get('signingSecret'), event.bodyRaw, event.headers)) { this.http.respond({ status: 401 }); return; }\n let data;\n try { data = this.polymorfa.envelope(event.body, ${JSON.stringify(key)}); } catch { this.http.respond({ status: 400 }); return; }\n this.$emit(data, { id: data.id, summary: data.event, ts: Date.parse(data.timestamp) });\n this.http.respond({ status: 200 });\n },\n};\n`); // Make custom IML functions reuse the exact shared request/response behavior. // Every function fits Make's 5,000-character limit. They require provider enablement. diff --git a/shared/core.cjs b/shared/core.cjs index 5288dff..63dfe4f 100644 --- a/shared/core.cjs +++ b/shared/core.cjs @@ -9,7 +9,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/shared/hooks.cjs b/shared/hooks.cjs index 68538a6..9f1f682 100644 --- a/shared/hooks.cjs +++ b/shared/hooks.cjs @@ -58,14 +58,31 @@ async function find(auth, url, group, subscriptionKey, transport, provider) { } throw new IntegrationError('subscription_inventory_requires_reconciliation'); } +// The API returns a webhook's signing secret once, at create or rotation. It is the only +// credential for body verification, so it is returned in its own field, never inside `owned`. +const SECRET = /^[\x21-\x7e]{16,512}$/; +function validSecret(value) { return typeof value === 'string' && SECRET.test(value); } +async function rotateSecret(auth, id, transport, provider) { + const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}/secret-rotations`; + let r; + try { + // A fresh key per attempt. An uncertain outcome is never retried here: the next activation rotates again. + r = await call(auth, transport, provider, 'POST', path, { overlapSeconds: 0 }, `integration-rotate-${randomUUID()}`); + } catch (error) { + if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw new IntegrationError('signing_secret_unavailable', error.status); + throw new IntegrationError('signing_secret_rotation_requires_reconciliation'); + } + if (!validSecret(r.data?.secret)) throw new IntegrationError('signing_secret_unavailable'); + return r.data.secret; +} async function subscribe(auth, url, group, subscriptionKey, transport, provider, nonce) { url = callback(url); const marker = identity(auth, group, subscriptionKey); const createKey = creationKey(marker.key, nonce); const record = hook => ({ id: hook.id, url, group, subscriptionKey, markerName: marker.name }); + // Returns { owned, secret }. `secret` goes to provider-private state only. const existing = await find(auth, url, group, subscriptionKey, transport, provider); - if (existing) return record(existing); - // Only the owned ID leaves this helper. The API's one-time signing secret is never emitted. + if (existing) return { owned: record(existing), secret: await rotateSecret(auth, existing.id, transport, provider) }; let r; try { // The adapter keeps this activation's nonce in private state, so an uncertain retry reuses the key. @@ -74,13 +91,18 @@ async function subscribe(auth, url, group, subscriptionKey, transport, provider, if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw error; // A lost response may follow a successful create. Reconcile; never blindly create again. const recovered = await find(auth, url, group, subscriptionKey, transport, provider); - if (recovered) return record(recovered); + // The secret was in the lost response, so rotate to obtain one. + if (recovered) return { owned: record(recovered), secret: await rotateSecret(auth, recovered.id, transport, provider) }; throw new IntegrationError('subscription_requires_reconciliation'); } if (!owns(r.data?.webhook, auth, url, group, subscriptionKey)) throw new IntegrationError('invalid_subscription_receipt'); // An idempotency receipt may outlive its deleted webhook. Verify live ownership. const live = await find(auth, url, group, subscriptionKey, transport, provider); - if (live && live.id === r.data.webhook.id) return record(live); + if (live && live.id === r.data.webhook.id) { + // A replayed receipt carries no secret; rotate instead. + const secret = validSecret(r.data.secret) ? r.data.secret : await rotateSecret(auth, live.id, transport, provider); + return { owned: record(live), secret }; + } if (!live) { try { await call(auth, transport, provider, 'GET', `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(r.data.webhook.id, 'webhook_id')}`); } catch (error) { if (error.status === 404) throw new IntegrationError('subscription_receipt_deleted'); } @@ -91,6 +113,7 @@ function creation(url, group, subscriptionKey) { return { nonce: randomUUID(), url: callback(url), group, subscriptionKey }; } // Store: provider-private { get(), set(value) } for this trigger's pending creation. +// Returns { owned, secret }; the caller stores `secret` in provider-private state. async function activate(auth, url, group, subscriptionKey, transport, provider, store) { const target = callback(url); let pending = await store.get(); @@ -99,15 +122,15 @@ async function activate(auth, url, group, subscriptionKey, transport, provider, } // Save before the create so an uncertain retry of this activation sends the same key. await store.set(pending); - let owned; - try { owned = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } + let result; + try { result = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } catch (error) { // The receipt names a confirmed-deleted webhook. The next activation needs a new nonce. if (error.code === 'subscription_receipt_deleted') await store.set(null); throw error; } await store.set(null); - return owned; + return result; } async function unsubscribe(auth, id, url, group, subscriptionKey, transport, provider, recordedMarker) { const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}`; @@ -125,9 +148,18 @@ function authenticate(auth, group, subscriptionKey, incomingHeaders, prefixes = if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected.value)); } +// Verifies X-Webhook-Signature: lowercase hex HMAC-SHA256 of the exact raw body bytes. Fails closed. +function verify(secret, rawBody, incomingHeaders, prefixes = ['']) { + if (!validSecret(secret) || !(Buffer.isBuffer(rawBody) || typeof rawBody === 'string')) return false; + const names = prefixes.map(p => (p + 'x-webhook-signature').toLowerCase()); + const entries = Object.entries(incomingHeaders || {}).filter(([k]) => names.includes(k.toLowerCase())); + if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; + const expected = createHmac('sha256', secret).update(rawBody).digest('hex'); + return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected)); +} function envelope(body, group) { if (!events[group] || !body || typeof body !== 'object' || Array.isArray(body) || typeof body.id !== 'string' || !body.id || typeof body.session !== 'string' || !body.session || typeof body.timestamp !== 'string' || !Number.isFinite(Date.parse(body.timestamp)) || !events[group].types.includes(body.event) || !body.payload || typeof body.payload !== 'object' || Array.isArray(body.payload)) throw new IntegrationError('invalid_event'); // Copy the defined envelope only. Never export arbitrary top-level transport fields. return { id: body.id, session: body.session, ...(typeof body.externalId === 'string' ? { externalId: body.externalId } : {}), timestamp: body.timestamp, event: body.event, payload: body.payload }; } -module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, envelope }; +module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, verify, validSecret, envelope }; diff --git a/tests/fake-webhooks.cjs b/tests/fake-webhooks.cjs index 3b00476..4e75342 100644 --- a/tests/fake-webhooks.cjs +++ b/tests/fake-webhooks.cjs @@ -5,14 +5,19 @@ const assert = require('node:assert/strict'); const auth = { apiKey: 'synthetic-project-token-not-a-credential', projectId: '11111111-1111-4111-8111-111111111111' }; function server(credentials = auth) { const rows = []; const calls = []; const receipts = new Map(); - let lose = 0; let hide = 0; let created = 0; + let lose = 0; let hide = 0; let created = 0; let rotations = 0; let rotateMode = 'ok'; + const secrets = new Map(); const api = { rows, calls, receipts, // The next create is accepted but its response is lost. loseNextCreate() { lose++; }, // The next n inventory reads omit the newest row, as an eventually consistent list may. hideNewest(n) { hide = n; }, - posts() { return calls.filter(r => r.method === 'POST'); }, + secrets, + // 'ok' | 'reject' (4xx) | 'lose' (accepted, response lost) | 'nosecret' (2xx without a secret) + rotateMode(m) { rotateMode = m; }, + rotations() { return calls.filter(r => r.method === 'POST' && /secret-rotations$/.test(r.url)); }, + posts() { return calls.filter(r => r.method === 'POST' && !/secret-rotations$/.test(r.url)); }, async request(r) { calls.push(r); assert.equal(new URL(r.url).origin, 'https://api.polymorfa.com'); @@ -22,16 +27,29 @@ function server(credentials = auth) { if (hide > 0) { hide--; data = data.slice(0, -1); } return { status: 200, headers: {}, body: { data, page: { hasMore: false, nextCursor: null } } }; } + if (r.method === 'POST' && /\/webhooks\/[^/]+\/secret-rotations$/.test(new URL(r.url).pathname)) { + assert.ok(r.headers['Idempotency-Key'], 'rotation requires an idempotency key'); + assert.deepEqual(r.body, { overlapSeconds: 0 }); + const id = new URL(r.url).pathname.split('/').at(-2); + if (!rows.some(row => row.id === id)) return { status: 404, headers: {}, body: { error: { code: 'not_found' } } }; + if (rotateMode === 'reject') return { status: 403, headers: {}, body: { error: { code: 'forbidden' } } }; + const secret = `SYNTHETIC-ROTATED-SIGNING-SECRET-${++rotations}`; + secrets.set(id, secret); + if (rotateMode === 'lose') throw new Error('Response lost after accepted rotation'); + if (rotateMode === 'nosecret') return { status: 200, headers: {}, body: { data: { secretMetadata: {} } } }; + return { status: 200, headers: {}, body: { data: { secret, secretMetadata: {} } } }; + } if (r.method === 'POST') { const key = r.headers['Idempotency-Key']; assert.ok(key, 'create requires an idempotency key'); if (receipts.has(key)) { const receipt = receipts.get(key); assert.deepEqual(r.body, receipt.request, 'replayed create must send the same request'); - return { ...receipt.response, body: { data: { ...receipt.response.body.data, idempotency: { key, replayed: true } } } }; + const { secret: _omitted, ...replay } = receipt.response.body.data; + return { ...receipt.response, body: { data: { ...replay, idempotency: { key, replayed: true } } } }; } const row = { ...r.body, owner: 'project', projectId: credentials.projectId, id: `synthetic-hook-${++created}`, headers: r.body.headers.map(h => ({ name: h.name })) }; - rows.push(row); + rows.push(row); secrets.set(row.id, 'SYNTHETIC-ONE-TIME-SIGNING-SECRET'); const response = { status: 201, headers: {}, body: { data: { webhook: { ...row }, secret: 'SYNTHETIC-ONE-TIME-SIGNING-SECRET' } } }; receipts.set(key, { request: r.body, response }); if (lose > 0) { lose--; throw new Error('Response lost after accepted create'); } diff --git a/tests/hooks.test.cjs b/tests/hooks.test.cjs index 686c36f..0627e25 100644 --- a/tests/hooks.test.cjs +++ b/tests/hooks.test.cjs @@ -11,11 +11,11 @@ const NONCE = '11111111-1111-4111-8111-111111111111'; function memory() { let value; return { get: () => value, set: v => { value = v || undefined; }, peek: () => value }; } for (const group of Object.keys(events)) test(`${group}: activation, reactivation, authentication and owned cleanup`, async () => { const s = server(); const transport = s.request.bind(s); - const first = await hooks.subscribe(auth, url, group, key, transport, 'test', NONCE); + const first = (await hooks.subscribe(auth, url, group, key, transport, 'test', NONCE)).owned; assert.deepEqual(Object.keys(first).sort(), ['group', 'id', 'markerName', 'subscriptionKey', 'url']); assert.ok(!JSON.stringify(first).includes('SYNTHETIC-ONE-TIME-SIGNING-SECRET')); - assert.deepEqual(await hooks.subscribe(auth, url, group, key, transport, 'test', NONCE), first); - assert.equal(s.calls.filter(r => r.method === 'POST').length, 1); + assert.deepEqual((await hooks.subscribe(auth, url, group, key, transport, 'test', NONCE)).owned, first); + assert.equal(s.posts().length, 1); const marker = hooks.identity(auth, group, key); assert.ok(hooks.authenticate(auth, group, key, { [marker.name.toLowerCase()]: marker.value })); assert.ok(!hooks.authenticate(auth, group, 'another-trigger', { [marker.name]: marker.value })); @@ -26,20 +26,20 @@ for (const group of Object.keys(events)) test(`${group}: activation, reactivatio }); test('an ambiguous accepted create is recovered without another create', async () => { const s = server(); s.loseNextCreate(); - const result = await hooks.subscribe(auth, url, 'messageReceived', key, s.request.bind(s), 'test', NONCE); - assert.ok(result.id); assert.equal(s.calls.filter(r => r.method === 'POST').length, 1); + const result = (await hooks.subscribe(auth, url, 'messageReceived', key, s.request.bind(s), 'test', NONCE)).owned; + assert.ok(result.id); assert.equal(s.posts().length, 1); }); test('an operator-disabled hook is preserved instead of silently enabling or duplicating it', async () => { const s = server(); const t = s.request.bind(s); - await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE); s.rows[0].enabled = false; + (await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE)).owned; s.rows[0].enabled = false; await assert.rejects(hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE), e => e.code === 'subscription_changed_requires_reconciliation'); - assert.equal(s.calls.filter(r => r.method === 'POST').length, 1); + assert.equal(s.posts().length, 1); }); test('a different callback cannot reuse the same active subscription identity', async () => { const s = server(); const t = s.request.bind(s); - await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE); + (await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE)).owned; await assert.rejects(hooks.subscribe(auth, 'https://other.example/hook', 'messageReceived', key, t, 'test', NONCE), e => e.code === 'subscription_key_already_in_use'); - assert.equal(s.calls.filter(r => r.method === 'POST').length, 1); + assert.equal(s.posts().length, 1); }); test('owned lookup follows cursor pages and refuses looping cursors', async () => { const marker = hooks.identity(auth, 'messageReceived', key); const calls = []; @@ -51,7 +51,7 @@ test('owned lookup follows cursor pages and refuses looping cursors', async () = await assert.rejects(hooks.find(auth, url, 'messageReceived', key, async () => ({ status: 200, body: { data: [], page: { hasMore: true, nextCursor: 'loop' } } }), 'test'), e => e.code === 'invalid_subscription_pagination'); }); test('cleanup refuses another subscription and never falls back to broader credentials', async () => { - const s = server(); const t = s.request.bind(s); const owned = await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE); + const s = server(); const t = s.request.bind(s); const owned = (await hooks.subscribe(auth, url, 'messageReceived', key, t, 'test', NONCE)).owned; await assert.rejects(hooks.unsubscribe(auth, owned.id, 'https://another.example/hook', 'messageReceived', key, t, 'test'), e => e.code === 'subscription_ownership_mismatch'); assert.equal(s.calls.filter(r => r.method === 'DELETE').length, 0); }); @@ -82,10 +82,10 @@ test('public marker and create keys do not reveal receiver verifier material', ( test('deactivate then reactivate registers a new webhook with a new creation key', async () => { const s = server(); const store = memory(); - const first = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + const first = (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; assert.equal(store.peek(), undefined, 'a confirmed activation clears its pending nonce'); await hooks.unsubscribe(auth, first.id, url, 'messageReceived', key, s.transport, 'test'); - const second = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + const second = (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; assert.equal(s.rows.length, 1); assert.equal(s.rows[0].id, second.id); assert.notEqual(second.id, first.id); const posts = s.posts(); assert.equal(posts.length, 2); assert.notEqual(posts[0].headers['Idempotency-Key'], posts[1].headers['Idempotency-Key']); @@ -94,9 +94,9 @@ test('deactivate then reactivate registers a new webhook with a new creation key test('a test callback followed by the production callback activates both in turn', async () => { const s = server(); const store = memory(); - const test = await hooks.activate(auth, 'https://n8n.example/webhook-test/abc/webhook', 'messageReceived', key, s.transport, 'test', store); + const test = (await hooks.activate(auth, 'https://n8n.example/webhook-test/abc/webhook', 'messageReceived', key, s.transport, 'test', store)).owned; await hooks.unsubscribe(auth, test.id, test.url, 'messageReceived', key, s.transport, 'test'); - const live = await hooks.activate(auth, 'https://n8n.example/webhook/abc/webhook', 'messageReceived', key, s.transport, 'test', store); + const live = (await hooks.activate(auth, 'https://n8n.example/webhook/abc/webhook', 'messageReceived', key, s.transport, 'test', store)).owned; assert.equal(s.rows.length, 1); assert.equal(s.rows[0].url, live.url); }); @@ -108,7 +108,7 @@ test('a lost create response followed by a retry of the same activation yields o const pending = store.peek(); assert.ok(pending && pending.nonce, 'the uncertain activation keeps its nonce'); // The retry runs before the inventory catches up, so it sends the create again with the same key. s.hideNewest(1); - const owned = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + const owned = (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; const posts = s.posts(); assert.equal(posts.length, 2); assert.equal(posts[0].headers['Idempotency-Key'], posts[1].headers['Idempotency-Key']); assert.equal(s.rows.length, 1); assert.equal(owned.id, s.rows[0].id); assert.equal(store.peek(), undefined); @@ -116,7 +116,7 @@ test('a lost create response followed by a retry of the same activation yields o test('a lost create response is reconciled from the inventory without a second create', async () => { const s = server(); const store = memory(); s.loseNextCreate(); - const owned = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + const owned = (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; assert.equal(s.posts().length, 1); assert.equal(s.rows.length, 1); assert.equal(owned.id, s.rows[0].id); }); @@ -130,7 +130,7 @@ test('a replayed receipt for a deleted webhook is refused, then the next activat assert.equal(s.rows.length, 0, 'the dead webhook is not reported as live and nothing new was created'); assert.equal(s.posts()[1].headers['Idempotency-Key'], s.posts()[0].headers['Idempotency-Key']); assert.equal(store.peek(), undefined, 'the spent nonce is discarded'); - const owned = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + const owned = (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; assert.equal(s.rows.length, 1); assert.equal(owned.id, s.rows[0].id); assert.notEqual(s.posts()[2].headers['Idempotency-Key'], s.posts()[0].headers['Idempotency-Key']); assert.ok(nonce); @@ -148,7 +148,7 @@ test('creation keys require an adapter nonce and a pending nonce is bound to its await assert.rejects(hooks.subscribe(auth, url, 'messageReceived', key, async () => ({ status: 200, body: { data: [], page: {} } }), 'test'), e => e.code === 'invalid_creation_nonce'); const s = server(); const store = memory(); store.set({ nonce: NONCE, url: 'https://other.example/hook', group: 'messageReceived', subscriptionKey: key }); - await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + (await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store)).owned; assert.notEqual(s.posts()[0].headers['Idempotency-Key'], hooks.creationKey(hooks.identity(auth, 'messageReceived', key).key, NONCE)); }); @@ -166,9 +166,9 @@ test('public QuickLink reference survives the event projection without arbitrary test('callback normalization preserves ownership across activation and cleanup', async () => { const s = server(); const transport = s.request.bind(s); - const first = await hooks.subscribe(auth, 'https://EXAMPLE.COM:443', 'messageReceived', key, transport, 'test', NONCE); + const first = (await hooks.subscribe(auth, 'https://EXAMPLE.COM:443', 'messageReceived', key, transport, 'test', NONCE)).owned; assert.equal(s.rows[0].url, 'https://example.com/'); - assert.deepEqual(await hooks.subscribe(auth, 'https://example.com/', 'messageReceived', key, transport, 'test', NONCE), first); + assert.deepEqual((await hooks.subscribe(auth, 'https://example.com/', 'messageReceived', key, transport, 'test', NONCE)).owned, first); await hooks.unsubscribe(auth, first.id, 'https://EXAMPLE.COM:443', 'messageReceived', key, transport, 'test'); assert.equal(s.rows.length, 0); assert.equal(hooks.sameCallback(url + '?key=A', url + '?key=a'), false); diff --git a/tests/native.test.cjs b/tests/native.test.cjs index 2585b03..f022630 100644 --- a/tests/native.test.cjs +++ b/tests/native.test.cjs @@ -2,6 +2,7 @@ const { test } = require('node:test'); const assert = require('node:assert/strict'); const { Polymorfa } = require('../n8n/dist/nodes/Polymorfa/Polymorfa.node.js'); const { PolymorfaTrigger } = require('../n8n/dist/nodes/Polymorfa/PolymorfaTrigger.node.js'); +const { createHmac } = require('node:crypto'); const zapier = require('../zapier'); const hooks = require('../shared/hooks.cjs'); const fake = require('./fake-webhooks.cjs'); @@ -26,13 +27,23 @@ test('compiled n8n native binary input maps bytes through the existing base64 re }); test('compiled n8n trigger rejects unauthenticated input and keeps event identity on valid input', async () => { const marker = hooks.identity(auth, 'messageReceived', 'synthetic-trigger'); - const sample = require('../fixtures/events.json').messageReceived; - let incoming = {}; let status; - const context = { getCredentials: async () => auth, getNodeParameter: k => k === 'eventGroup' ? 'messageReceived' : 'synthetic-trigger', getHeaderData: () => incoming, getBodyData: () => sample, getResponseObject: () => ({ status(v) { status = v; return this; }, end() {} }), helpers: { returnJsonArray: value => [{ json: value }] } }; + const sample = require('../fixtures/events.json').messageReceived; const secret = 'synthetic-signing-secret-for-tests'; + const raw = Buffer.from(JSON.stringify(sample)); const sig = createHmac('sha256', secret).update(raw).digest('hex'); + let incoming = {}; let status; let rawBody = raw; let stored = secret; + const context = { getCredentials: async () => auth, getNodeParameter: k => k === 'eventGroup' ? 'messageReceived' : 'synthetic-trigger', getHeaderData: () => incoming, getBodyData: () => sample, getRequestObject: () => ({ rawBody }), getWorkflowStaticData: () => ({ signingSecret: stored }), getResponseObject: () => ({ status(v) { status = v; return this; }, end() {} }), helpers: { returnJsonArray: value => [{ json: value }] } }; const trigger = new PolymorfaTrigger(); - assert.deepEqual(await trigger.webhook.call(context), { noWebhookResponse: true }); assert.equal(status, 401); - incoming = { [marker.name]: marker.value }; + const rejected = async () => { status = undefined; assert.deepEqual(await trigger.webhook.call(context), { noWebhookResponse: true }); assert.equal(status, 401); }; + await rejected(); + incoming = { [marker.name]: marker.value }; await rejected(); // marker alone is not enough + incoming = { [marker.name]: marker.value, 'x-webhook-signature': sig }; const valid = await trigger.webhook.call(context); assert.equal(valid.workflowData[0][0].json.id, sample.id); + assert.ok(!JSON.stringify(valid).includes(secret)); + rawBody = Buffer.from(JSON.stringify(sample) + ' '); await rejected(); // tampered body + rawBody = undefined; await rejected(); // no raw body + rawBody = raw; stored = undefined; await rejected(); // subscription saved before verification existed + stored = 'another-synthetic-signing-secret'; await rejected(); // wrong secret + stored = secret; incoming = { [marker.name]: marker.value, 'x-webhook-signature': sig.toUpperCase() }; await rejected(); + incoming = { 'x-webhook-signature': sig }; await rejected(); // signature alone is not enough }); test('Zapier native action returns the real API envelope and never follows redirects', async () => { let request; @@ -44,10 +55,14 @@ test('Zapier native hook uses stable event IDs and synthetic setup samples witho const marker = hooks.identity(auth, 'messageReceived', 'synthetic-trigger'); const sample = require('../fixtures/events.json').messageReceived; const operation = zapier.triggers.messageReceived.operation; let requests = 0; const z = { request: () => { requests++; }, errors: { Error } }; - const bundle = { authData: auth, inputData: { subscriptionKey: 'synthetic-trigger' }, cleanedRequest: { headers: { [marker.name]: marker.value }, content: sample } }; + const secret = 'synthetic-signing-secret-for-tests'; const content = JSON.stringify(sample); + const headers = { [marker.name]: marker.value, 'x-webhook-signature': createHmac('sha256', secret).update(content).digest('hex') }; + const bundle = { authData: auth, inputData: { subscriptionKey: 'synthetic-trigger' }, subscribeData: { signingSecret: secret }, rawRequest: { headers, content } }; assert.deepEqual(await operation.perform(z, bundle), [sample]); + // The parsed request alone cannot be verified, so it is refused. + await assert.rejects(operation.perform(z, { ...bundle, rawRequest: undefined, cleanedRequest: { headers, content: sample } })); assert.equal((await operation.performList(z, bundle))[0].id, sample.id); assert.equal(requests, 0); - await assert.rejects(operation.perform(z, { ...bundle, cleanedRequest: { headers: {}, content: sample } })); + await assert.rejects(operation.perform(z, { ...bundle, rawRequest: { ...bundle.rawRequest, headers: {} } })); }); test('n8n continue-on-fail retains successful write results and continues later items', async () => { @@ -118,7 +133,9 @@ test('compiled n8n trigger survives test listen, activation, deactivation and re const context = n8nHookContext(s, staticData, params); if (!(await methods.checkExists.call(context))) await methods.create.call(context); assert.equal(staticData.pendingCreation, undefined); assert.equal(s.rows.length, 1); assert.equal(staticData.subscription.id, s.rows[0].id); - await methods.delete.call(context); assert.equal(s.rows.length, 0); assert.equal(staticData.subscription, undefined); + assert.equal(typeof staticData.signingSecret, 'string'); assert.ok(!JSON.stringify(staticData.subscription).includes(staticData.signingSecret)); + assert.equal(await methods.checkExists.call(context), true); + await methods.delete.call(context); assert.equal(s.rows.length, 0); assert.equal(staticData.subscription, undefined); assert.equal(staticData.signingSecret, undefined); }; await run(); await run(); params.url = 'https://n8n.example/webhook/abc/webhook'; @@ -126,6 +143,19 @@ test('compiled n8n trigger survives test listen, activation, deactivation and re assert.equal(s.posts().length, 4); assert.equal(new Set(s.posts().map(r => r.headers['Idempotency-Key'])).size, 4); assert.deepEqual(new PolymorfaTrigger().description.properties.map(p => p.name), ['eventGroup', 'subscriptionKey', 'scopeNotice']); }); +test('compiled n8n trigger treats an existing hook with no stored secret as missing and rotates on create', async () => { + const s = fake.server(); const methods = new PolymorfaTrigger().webhookMethods.default; const first = {}; + const params = { eventGroup: 'messageReceived', subscriptionKey: 'synthetic-trigger', url: 'https://n8n.example/webhook/abc/webhook' }; + await methods.create.call(n8nHookContext(s, first, params)); + const lost = {}; // The saved workflow state predates signature verification. + const context = n8nHookContext(s, lost, params); + assert.equal(await methods.checkExists.call(context), false); + await methods.create.call(context); + assert.equal(s.rows.length, 1); assert.equal(s.rotations().length, 1); assert.equal(lost.signingSecret, s.secrets.get(s.rows[0].id)); + s.rotateMode('reject'); const failed = {}; + await assert.rejects(methods.create.call(n8nHookContext(s, failed, params)), e => e.code === 'signing_secret_unavailable'); + assert.equal(failed.signingSecret, undefined); assert.equal(failed.subscription, undefined); +}); test('compiled n8n trigger keeps an uncertain activation nonce in node static data for its retry', async () => { const s = fake.server(); const staticData = {}; const methods = new PolymorfaTrigger().webhookMethods.default; const context = n8nHookContext(s, staticData, { eventGroup: 'messageReceived', subscriptionKey: 'synthetic-trigger', url: 'https://n8n.example/webhook/abc/webhook' }); @@ -146,21 +176,35 @@ test('Zapier REST hook turns off and on again with a fresh activation each time' for (let i = 0; i < 3; i++) { const subscribeData = await operation.performSubscribe(z, bundle()); assert.equal(s.rows.length, 1); assert.equal(subscribeData.id, s.rows[0].id); - assert.ok(!JSON.stringify(subscribeData).includes('SYNTHETIC-ONE-TIME-SIGNING-SECRET')); + assert.equal(subscribeData.signingSecret, s.secrets.get(s.rows[0].id)); await operation.performUnsubscribe(z, { ...bundle(), subscribeData }); assert.equal(s.rows.length, 0); } assert.equal(new Set(s.posts().map(r => r.headers['Idempotency-Key'])).size, 3); }); -test('Zapier accepts the documented rawRequest shape with Http- prefixed Camel-Case headers', async () => { +test('Zapier accepts the documented rawRequest shape with Http- prefixed Camel-Case headers and verifies the raw body', async () => { const marker = hooks.identity(auth, 'messageReceived', 'synthetic-trigger'); const sample = require('../fixtures/events.json').messageReceived; const operation = zapier.triggers.messageReceived.operation; const z = { errors: { Error } }; + const secret = 'synthetic-signing-secret-for-tests'; const content = JSON.stringify(sample); + const sig = createHmac('sha256', secret).update(content).digest('hex'); // Zapier docs (Bundle object, bundle.rawRequest): headers other than Content-Length and Content-Type // are prefixed with Http- and written in Camel-Case, for example X-Time-GMT becomes Http-X-Time-Gmt. - const camel = ('Http-' + marker.name).split('-').map(w => w[0].toUpperCase() + w.slice(1).toLowerCase()).join('-'); - const rawRequest = { method: 'POST', querystring: '', headers: { 'Content-Type': 'application/json', [camel]: marker.value, 'Http-User-Agent': 'polymorfa-webhooks' }, content: JSON.stringify(sample) }; - const bundle = { authData: auth, inputData: { subscriptionKey: 'synthetic-trigger' }, rawRequest, cleanedRequest: sample }; + const camel = name => ('Http-' + name).split('-').map(w => w[0].toUpperCase() + w.slice(1).toLowerCase()).join('-'); + const headers = { 'Content-Type': 'application/json', [camel(marker.name)]: marker.value, [camel('x-webhook-signature')]: sig, 'Http-User-Agent': 'polymorfa-webhooks' }; + const rawRequest = { method: 'POST', querystring: '', headers, content }; + const bundle = { authData: auth, inputData: { subscriptionKey: 'synthetic-trigger' }, rawRequest, cleanedRequest: sample, subscribeData: { signingSecret: secret } }; assert.deepEqual(await operation.perform(z, bundle), [sample]); - await assert.rejects(operation.perform(z, { ...bundle, rawRequest: { ...rawRequest, headers: { 'Content-Type': 'application/json' } } })); - await assert.rejects(operation.perform(z, { ...bundle, rawRequest: { ...rawRequest, headers: { [camel]: marker.value, [marker.name]: marker.value } } }), 'one marker header only'); - await assert.rejects(operation.perform(z, { ...bundle, rawRequest: { ...rawRequest, headers: { [camel]: '0'.repeat(64) } } })); + const { 'Http-X-Webhook-Signature': _drop, ...unsigned } = headers; + for (const [name, change] of Object.entries({ + 'no marker': { rawRequest: { ...rawRequest, headers: { 'Content-Type': 'application/json' } } }, + 'duplicate marker': { rawRequest: { ...rawRequest, headers: { ...headers, [marker.name]: marker.value } } }, + 'wrong marker': { rawRequest: { ...rawRequest, headers: { ...headers, [camel(marker.name)]: '0'.repeat(64) } } }, + 'marker without signature': { rawRequest: { ...rawRequest, headers: unsigned } }, + 'tampered body': { rawRequest: { ...rawRequest, content: content + ' ' } }, + 'missing raw body': { rawRequest: { ...rawRequest, content: undefined } }, + 'no stored secret': { subscribeData: {} }, + 'no subscribe data': { subscribeData: undefined }, + 'wrong secret': { subscribeData: { signingSecret: 'another-synthetic-signing-secret' } }, + })) { + await assert.rejects(operation.perform(z, { ...bundle, ...change }), e => !JSON.stringify(e.message).includes(secret), name); + } }); diff --git a/tests/pipedream.test.mjs b/tests/pipedream.test.mjs index aa2a033..bd5d6ec 100644 --- a/tests/pipedream.test.mjs +++ b/tests/pipedream.test.mjs @@ -3,6 +3,7 @@ import action from '../pipedream/actions/sendText/sendText.mjs'; import source from '../pipedream/sources/messageReceived/messageReceived.mjs'; import hooks from '../shared/hooks.cjs'; import { readFileSync } from 'node:fs'; +import { createHmac } from 'node:crypto'; test('Pipedream action passes exact fields to the app request boundary', async () => { const input = { session: '739182640518203', recipientType: 'id', recipient: '9007199254740993123', text: 'Synthetic', quotedMessageId: undefined, idempotencyKey: 'write-1', writeCreatedAt: '2026-11-01T12:00:00Z' }; let call; @@ -12,11 +13,22 @@ test('Pipedream action passes exact fields to the app request boundary', async ( test('Pipedream source rejects forgery and emits only the defined envelope with dedupe identity', async () => { const auth = { apiKey: 'synthetic-token', projectId: '11111111-1111-4111-8111-111111111111' }; const key = 'source-1'; const marker = hooks.identity(auth, 'messageReceived', key); const sample = JSON.parse(readFileSync('fixtures/events.json')).messageReceived; - const emitted = []; const responses = []; - const context = { subscriptionKey: key, polymorfa: { authenticate: (g, k, h) => hooks.authenticate(auth, g, k, h), envelope: hooks.envelope }, http: { respond: value => responses.push(value) }, $emit: (data, metadata) => emitted.push({ data, metadata }) }; - await source.run.call(context, { headers: {}, body: sample }); assert.equal(responses.at(-1).status, 401); assert.equal(emitted.length, 0); - await source.run.call(context, { headers: { [marker.name]: marker.value }, body: sample }); + const secret = 'synthetic-signing-secret-for-tests'; const bodyRaw = JSON.stringify(sample); + const sig = createHmac('sha256', secret).update(bodyRaw).digest('hex'); + const emitted = []; const responses = []; let stored = secret; + const context = { subscriptionKey: key, db: { get: k => k === 'signingSecret' ? stored : undefined }, polymorfa: { authenticate: (g, k, h) => hooks.authenticate(auth, g, k, h), verify: hooks.verify, envelope: hooks.envelope }, http: { respond: value => responses.push(value) }, $emit: (data, metadata) => emitted.push({ data, metadata }) }; + const signed = { [marker.name]: marker.value, 'x-webhook-signature': sig }; + const rejected = async event => { const before = emitted.length; await source.run.call(context, event); assert.equal(responses.at(-1).status, 401); assert.equal(emitted.length, before); }; + await rejected({ headers: {}, body: sample, bodyRaw }); + await rejected({ headers: { [marker.name]: marker.value }, body: sample, bodyRaw }); // marker alone + await rejected({ headers: { 'x-webhook-signature': sig }, body: sample, bodyRaw }); // signature alone + await rejected({ headers: signed, body: sample }); // no raw body + await rejected({ headers: signed, body: sample, bodyRaw: bodyRaw + ' ' }); // tampered + stored = undefined; await rejected({ headers: signed, body: sample, bodyRaw }); // subscribed before verification existed + stored = secret; + await source.run.call(context, { headers: signed, body: sample, bodyRaw }); assert.deepEqual(emitted[0].data, sample); assert.equal(emitted[0].metadata.id, sample.id); assert.equal(source.dedupe, 'unique'); + assert.ok(!JSON.stringify(emitted).includes(secret) && !JSON.stringify(responses).includes(secret)); }); import app from '../pipedream/polymorfa.app.mjs'; @@ -32,8 +44,9 @@ test('Pipedream source deactivates and reactivates with a fresh creation nonce i for (let i = 0; i < 3; i++) { await source.hooks.activate.call(context); assert.equal(s.rows.length, 1); assert.equal(db.get('ownedSubscription').id, s.rows[0].id); assert.equal(db.get('pendingCreation'), null); + assert.equal(db.get('signingSecret'), s.secrets.get(s.rows[0].id)); assert.ok(!JSON.stringify(db.get('ownedSubscription')).includes(db.get('signingSecret'))); await source.hooks.deactivate.call(context); - assert.equal(s.rows.length, 0); assert.equal(db.get('ownedSubscription'), null); + assert.equal(s.rows.length, 0); assert.equal(db.get('ownedSubscription'), null); assert.equal(db.get('signingSecret'), null); } assert.equal(new Set(s.posts().map(r => r.headers['Idempotency-Key'])).size, 3); }); diff --git a/tests/signature.test.cjs b/tests/signature.test.cjs new file mode 100644 index 0000000..099d9eb --- /dev/null +++ b/tests/signature.test.cjs @@ -0,0 +1,89 @@ +'use strict'; +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { createHmac } = require('node:crypto'); +const hooks = require('../shared/hooks.cjs'); +const { auth, server } = require('./fake-webhooks.cjs'); +const url = 'https://example.com/synthetic-callback'; +const key = 'synthetic-trigger-1'; +const NONCE = '11111111-1111-4111-8111-111111111111'; +const SECRET = 'synthetic-signing-secret-for-tests'; +const sign = (secret, body) => createHmac('sha256', secret).update(body).digest('hex'); +const body = '{"id":"evt-1","note":" spacing and \\u00e9 kept "}'; +const H = 'x-webhook-signature'; + +test('verify accepts a valid signature over the exact raw body, string or Buffer', () => { + assert.ok(hooks.verify(SECRET, body, { [H]: sign(SECRET, body) })); + assert.ok(hooks.verify(SECRET, Buffer.from(body), { 'X-Webhook-Signature': sign(SECRET, body) })); + assert.ok(hooks.verify(SECRET, body, { 'Http-X-Webhook-Signature': sign(SECRET, body) }, ['', 'http-'])); +}); +test('verify fails closed on every malformed or mismatched input', () => { + const good = sign(SECRET, body); + const cases = { + 'wrong secret': [SECRET + 'x', body, { [H]: good }], + 'tampered body': [SECRET, body + ' ', { [H]: good }], + 're-serialized body': [SECRET, JSON.stringify(JSON.parse(body)), { [H]: good }], + 'missing header': [SECRET, body, {}], + 'duplicate header': [SECRET, body, { [H]: good, 'X-Webhook-Signature': good }], + 'uppercase hex': [SECRET, body, { [H]: good.toUpperCase() }], + 'short hex': [SECRET, body, { [H]: good.slice(0, 62) }], + 'array value': [SECRET, body, { [H]: [good] }], + 'prefix not allowed': [SECRET, body, { 'Http-X-Webhook-Signature': good }], + 'missing raw body': [SECRET, undefined, { [H]: good }], + 'parsed object body': [SECRET, JSON.parse(body), { [H]: good }], + 'missing secret': [undefined, body, { [H]: good }], + 'empty secret': ['', body, { [H]: sign('', body) }], + 'short secret': ['short', body, { [H]: sign('short', body) }], + }; + for (const [name, args] of Object.entries(cases)) assert.equal(hooks.verify(...args), false, name); +}); +test('the secret from the create response is returned separately and used without rotation', async () => { + const s = server(); + const { owned, secret } = await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + assert.equal(secret, 'SYNTHETIC-ONE-TIME-SIGNING-SECRET'); + assert.equal(s.rotations().length, 0); + assert.ok(!JSON.stringify(owned).includes(secret)); +}); +test('an existing hook gets a fresh secret by rotation with overlap 0 and a fresh key', async () => { + const s = server(); + await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + const again = await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + assert.equal(again.secret, 'SYNTHETIC-ROTATED-SIGNING-SECRET-1'); + const [rotation] = s.rotations(); assert.deepEqual(rotation.body, { overlapSeconds: 0 }); + assert.ok(rotation.headers['Idempotency-Key'].startsWith('integration-rotate-')); + await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + const keys = s.rotations().map(r => r.headers['Idempotency-Key']); assert.equal(new Set(keys).size, 2); +}); +test('a hook recovered after a lost create response gets its secret by rotation', async () => { + const s = server(); s.loseNextCreate(); + const { owned, secret } = await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + assert.equal(s.posts().length, 1); assert.equal(s.rotations().length, 1); + assert.equal(secret, s.secrets.get(owned.id)); +}); +test('a replayed create receipt without a secret falls back to rotation', async () => { + const s = server(); const store = { v: undefined, get() { return this.v; }, set(x) { this.v = x || undefined; } }; + s.loseNextCreate(); s.hideNewest(2); + await assert.rejects(hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store), e => e.code === 'subscription_requires_reconciliation'); + s.hideNewest(1); // The retry's first inventory read misses it, so it replays the create receipt. + const { owned, secret } = await hooks.activate(auth, url, 'messageReceived', key, s.transport, 'test', store); + assert.equal(s.posts().length, 2); assert.equal(s.rotations().length, 1); + assert.equal(secret, s.secrets.get(owned.id)); +}); +test('rotation failure or a missing secret gives signing_secret_unavailable and no owned hook', async () => { + for (const mode of ['reject', 'nosecret']) { + const s = server(); await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + s.rotateMode(mode); + await assert.rejects(hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE), e => e.code === 'signing_secret_unavailable' && !/SYNTHETIC/.test(e.message), mode); + } +}); +test('an uncertain rotation is not retried and asks for reconciliation', async () => { + const s = server(); await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + s.rotateMode('lose'); + await assert.rejects(hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE), e => e.code === 'signing_secret_rotation_requires_reconciliation' && /rotate again/.test(e.message)); + assert.equal(s.rotations().length, 1); +}); +test('a malformed rotated secret is refused', async () => { + const s = server(); await hooks.subscribe(auth, url, 'messageReceived', key, s.transport, 'test', NONCE); + const transport = r => /secret-rotations$/.test(r.url) ? Promise.resolve({ status: 200, headers: {}, body: { data: { secret: 'has space and is long enough' } } }) : s.request(r); + await assert.rejects(hooks.subscribe(auth, url, 'messageReceived', key, transport, 'test', NONCE), e => e.code === 'signing_secret_unavailable'); +}); diff --git a/zapier/README.md b/zapier/README.md index ea6b925..faacca4 100644 --- a/zapier/README.md +++ b/zapier/README.md @@ -24,6 +24,24 @@ says those headers, other than Content-Type and Content-Length, arrive with an `Http-` prefix in Camel-Case. The receiver accepts that form or the plain name, exactly once. Confirm it on a real REST Hook delivery before review. +Each delivery must carry a valid `X-Webhook-Signature` header, an HMAC-SHA256 of +the exact raw request body made with the endpoint's signing secret. The trigger +checks it against the raw bytes before parsing the body, and also checks its +marker header. A missing, duplicate or invalid signature, a missing raw body or +a missing stored secret rejects the delivery. The REST Hook's signing secret is +kept in `bundle.subscribeData` and never emitted. Activation returns the secret from the create response, or rotates it +(zero overlap) when the webhook already exists, so activating a trigger replaces +any earlier secret for that webhook. + +Triggers saved before signature verification have no stored secret and reject +every delivery. Turn the Zap off and on again to rotate and store a fresh secret. +Rotating the endpoint's signing secret in the Polymorfa Console also invalidates +the stored secret and rejects deliveries until the trigger is reactivated. + +The signature is checked against `bundle.rawRequest.content`. If Zapier does not +provide the raw body, or does not pass `subscribeData` to `perform`, every delivery +is rejected. Confirm both on a real REST Hook delivery before review. + Validate without contacting Zapier's style service: ```sh diff --git a/zapier/index.js b/zapier/index.js index 10c9ce0..d7ab213 100644 --- a/zapier/index.js +++ b/zapier/index.js @@ -45,8 +45,9 @@ const triggers = Object.fromEntries(Object.entries(events).map(([key, event]) => // with its own creation nonce. Its result is stored by Zapier as subscribeData. let pending; const store = { get: () => pending, set: value => { pending = value || undefined; } }; - const owned = await withThrottling(z, () => hooks.activate(bundle.authData, bundle.targetUrl, key, bundle.inputData.subscriptionKey, transport(z), 'zapier', store)); - return { ...owned, url: bundle.targetUrl }; + const { owned, secret } = await withThrottling(z, () => hooks.activate(bundle.authData, bundle.targetUrl, key, bundle.inputData.subscriptionKey, transport(z), 'zapier', store)); + // subscribeData is private to Zapier; the signing secret is never emitted by a trigger. + return { ...owned, url: bundle.targetUrl, signingSecret: secret }; }, async performUnsubscribe(z, bundle) { const owned = bundle.subscribeData; @@ -57,10 +58,12 @@ const triggers = Object.fromEntries(Object.entries(events).map(([key, event]) => // (except Content-Type and Content-Length). Accept that form and the plain name, once. const incoming = bundle.rawRequest?.headers || bundle.cleanedRequest?.headers; if (!hooks.authenticate(bundle.authData, key, bundle.inputData.subscriptionKey, incoming, ['', 'http-'])) throw new z.errors.Error('Webhook authentication failed.', 'WebhookAuthentication', 401); - let body = bundle.cleanedRequest?.content; - if (typeof bundle.rawRequest?.content === 'string') { - try { body = JSON.parse(bundle.rawRequest.content); } catch { throw new z.errors.Error('Invalid webhook body.', 'InvalidEvent', 400); } - } + // Verify the exact raw bytes before parsing. A missing secret (subscribed before verification + // existed) or a missing raw body fails closed; turn the Zap off and on again to rotate the secret. + const raw = bundle.rawRequest?.content; + if (typeof raw !== 'string' || !hooks.verify(bundle.subscribeData?.signingSecret, raw, incoming, ['', 'http-'])) throw new z.errors.Error('Webhook authentication failed.', 'WebhookAuthentication', 401); + let body; + try { body = JSON.parse(raw); } catch { throw new z.errors.Error('Invalid webhook body.', 'InvalidEvent', 400); } return [hooks.envelope(body, key)]; }, async performList() { return [require('./shared/samples.json')[key]]; }, diff --git a/zapier/shared/core.cjs b/zapier/shared/core.cjs index 3d7596b..59e7e2c 100644 --- a/zapier/shared/core.cjs +++ b/zapier/shared/core.cjs @@ -10,7 +10,7 @@ class IntegrationError extends Error { // A write that ended in a server error or is still running has an uncertain outcome, whatever its code. const uncertain = /unknown|reconciliation/.test(code) || code === 'idempotency_in_progress' || (write && status >= 500); const wait = retryAfter !== undefined ? ` Wait at least ${retryAfter} seconds; preserve the same key and start time.` : ''; - const recovery = code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; + const recovery = code === 'signing_secret_unavailable' ? ' Polymorfa did not provide a signing secret. Check that the API key has webhooks:manage, then deactivate and reactivate the trigger.' : code === 'signing_secret_rotation_requires_reconciliation' ? ' The secret rotation outcome is unknown. Deactivate and reactivate the trigger to rotate again.' : code === 'idempotency_completed' ? ' The original write completed. Recover its original result; do not send again with a new key.' : code === 'subscription_receipt_deleted' ? ' The webhook created by this activation was deleted. Activate the trigger again to register a new one.' : uncertain ? ' Reconcile the original write before retrying. Keep its key and start time.' + wait : wait; super(`Polymorfa ${code}${status ? ` (HTTP ${status})` : ''}${requestId ? `. Request: ${requestId}` : ''}.${recovery}`); this.name = 'IntegrationError'; this.code = code; this.status = status; this.requestId = requestId; this.retryAfter = retryAfter; diff --git a/zapier/shared/hooks.cjs b/zapier/shared/hooks.cjs index 8b518a7..5930d8e 100644 --- a/zapier/shared/hooks.cjs +++ b/zapier/shared/hooks.cjs @@ -59,14 +59,31 @@ async function find(auth, url, group, subscriptionKey, transport, provider) { } throw new IntegrationError('subscription_inventory_requires_reconciliation'); } +// The API returns a webhook's signing secret once, at create or rotation. It is the only +// credential for body verification, so it is returned in its own field, never inside `owned`. +const SECRET = /^[\x21-\x7e]{16,512}$/; +function validSecret(value) { return typeof value === 'string' && SECRET.test(value); } +async function rotateSecret(auth, id, transport, provider) { + const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}/secret-rotations`; + let r; + try { + // A fresh key per attempt. An uncertain outcome is never retried here: the next activation rotates again. + r = await call(auth, transport, provider, 'POST', path, { overlapSeconds: 0 }, `integration-rotate-${randomUUID()}`); + } catch (error) { + if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw new IntegrationError('signing_secret_unavailable', error.status); + throw new IntegrationError('signing_secret_rotation_requires_reconciliation'); + } + if (!validSecret(r.data?.secret)) throw new IntegrationError('signing_secret_unavailable'); + return r.data.secret; +} async function subscribe(auth, url, group, subscriptionKey, transport, provider, nonce) { url = callback(url); const marker = identity(auth, group, subscriptionKey); const createKey = creationKey(marker.key, nonce); const record = hook => ({ id: hook.id, url, group, subscriptionKey, markerName: marker.name }); + // Returns { owned, secret }. `secret` goes to provider-private state only. const existing = await find(auth, url, group, subscriptionKey, transport, provider); - if (existing) return record(existing); - // Only the owned ID leaves this helper. The API's one-time signing secret is never emitted. + if (existing) return { owned: record(existing), secret: await rotateSecret(auth, existing.id, transport, provider) }; let r; try { // The adapter keeps this activation's nonce in private state, so an uncertain retry reuses the key. @@ -75,13 +92,18 @@ async function subscribe(auth, url, group, subscriptionKey, transport, provider, if (error instanceof IntegrationError && error.status >= 400 && error.status < 500) throw error; // A lost response may follow a successful create. Reconcile; never blindly create again. const recovered = await find(auth, url, group, subscriptionKey, transport, provider); - if (recovered) return record(recovered); + // The secret was in the lost response, so rotate to obtain one. + if (recovered) return { owned: record(recovered), secret: await rotateSecret(auth, recovered.id, transport, provider) }; throw new IntegrationError('subscription_requires_reconciliation'); } if (!owns(r.data?.webhook, auth, url, group, subscriptionKey)) throw new IntegrationError('invalid_subscription_receipt'); // An idempotency receipt may outlive its deleted webhook. Verify live ownership. const live = await find(auth, url, group, subscriptionKey, transport, provider); - if (live && live.id === r.data.webhook.id) return record(live); + if (live && live.id === r.data.webhook.id) { + // A replayed receipt carries no secret; rotate instead. + const secret = validSecret(r.data.secret) ? r.data.secret : await rotateSecret(auth, live.id, transport, provider); + return { owned: record(live), secret }; + } if (!live) { try { await call(auth, transport, provider, 'GET', `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(r.data.webhook.id, 'webhook_id')}`); } catch (error) { if (error.status === 404) throw new IntegrationError('subscription_receipt_deleted'); } @@ -92,6 +114,7 @@ function creation(url, group, subscriptionKey) { return { nonce: randomUUID(), url: callback(url), group, subscriptionKey }; } // Store: provider-private { get(), set(value) } for this trigger's pending creation. +// Returns { owned, secret }; the caller stores `secret` in provider-private state. async function activate(auth, url, group, subscriptionKey, transport, provider, store) { const target = callback(url); let pending = await store.get(); @@ -100,15 +123,15 @@ async function activate(auth, url, group, subscriptionKey, transport, provider, } // Save before the create so an uncertain retry of this activation sends the same key. await store.set(pending); - let owned; - try { owned = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } + let result; + try { result = await subscribe(auth, target, group, subscriptionKey, transport, provider, pending.nonce); } catch (error) { // The receipt names a confirmed-deleted webhook. The next activation needs a new nonce. if (error.code === 'subscription_receipt_deleted') await store.set(null); throw error; } await store.set(null); - return owned; + return result; } async function unsubscribe(auth, id, url, group, subscriptionKey, transport, provider, recordedMarker) { const path = `/platform/projects/${segment(auth.projectId, 'project_id')}/webhooks/${segment(id, 'webhook_id')}`; @@ -126,9 +149,18 @@ function authenticate(auth, group, subscriptionKey, incomingHeaders, prefixes = if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected.value)); } +// Verifies X-Webhook-Signature: lowercase hex HMAC-SHA256 of the exact raw body bytes. Fails closed. +function verify(secret, rawBody, incomingHeaders, prefixes = ['']) { + if (!validSecret(secret) || !(Buffer.isBuffer(rawBody) || typeof rawBody === 'string')) return false; + const names = prefixes.map(p => (p + 'x-webhook-signature').toLowerCase()); + const entries = Object.entries(incomingHeaders || {}).filter(([k]) => names.includes(k.toLowerCase())); + if (entries.length !== 1 || typeof entries[0][1] !== 'string' || !/^[a-f0-9]{64}$/.test(entries[0][1])) return false; + const expected = createHmac('sha256', secret).update(rawBody).digest('hex'); + return timingSafeEqual(Buffer.from(entries[0][1]), Buffer.from(expected)); +} function envelope(body, group) { if (!events[group] || !body || typeof body !== 'object' || Array.isArray(body) || typeof body.id !== 'string' || !body.id || typeof body.session !== 'string' || !body.session || typeof body.timestamp !== 'string' || !Number.isFinite(Date.parse(body.timestamp)) || !events[group].types.includes(body.event) || !body.payload || typeof body.payload !== 'object' || Array.isArray(body.payload)) throw new IntegrationError('invalid_event'); // Copy the defined envelope only. Never export arbitrary top-level transport fields. return { id: body.id, session: body.session, ...(typeof body.externalId === 'string' ? { externalId: body.externalId } : {}), timestamp: body.timestamp, event: body.event, payload: body.payload }; } -module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, envelope }; +module.exports = { identity, callback, sameCallback, creationKey, creation, owns, find, subscribe, activate, unsubscribe, authenticate, verify, validSecret, envelope };