@wesell/n8n-nodes-confirmx 0.1.0

package/nodes/ConfirmX/ConfirmXWebhook.node.ts

@@ -0,0 +1,163 @@
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow'
+import { confirmxApiRequest } from '../../transports/http'
+import { WEBHOOK_EVENT_TYPES } from '../../types/api'
+
+export class ConfirmXWebhook implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'ConfirmX Webhook',
+    name: 'confirmXWebhook',
+    icon: 'file:confirmx.svg',
+    group: ['transform'],
+    version: 1,
+    subtitle: '={{$parameter["operation"]}}',
+    description:
+      'Manage ConfirmX outbound webhook subscriptions (list, create, update, delete). Use the ConfirmX Trigger node to receive events automatically.',
+    defaults: { name: 'ConfirmX Webhook' },
+    inputs: ['main'],
+    outputs: ['main'],
+    credentials: [{ name: 'confirmXApi', required: true }],
+    // Admin-only — not exposed as an AI tool.
+    properties: [
+      {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        options: [
+          { name: 'List', value: 'list', action: 'List webhook subscriptions' },
+          { name: 'Create', value: 'create', action: 'Create a webhook subscription' },
+          { name: 'Update', value: 'update', action: 'Update a webhook subscription' },
+          { name: 'Delete', value: 'delete', action: 'Delete a webhook subscription' },
+        ],
+        default: 'list',
+      },
+      // --- Common ---
+      {
+        displayName: 'Webhook ID',
+        name: 'webhookId',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['update', 'delete'] } },
+        description: 'The webhook subscription ID',
+      },
+      // --- Create / Update ---
+      {
+        displayName: 'URL',
+        name: 'url',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['create', 'update'] } },
+        placeholder: 'https://example.com/webhook',
+        description: 'Public URL that ConfirmX will POST events to',
+      },
+      {
+        displayName: 'Events',
+        name: 'events',
+        type: 'multiOptions',
+        default: ['message.received'],
+        required: true,
+        displayOptions: { show: { operation: ['create', 'update'] } },
+        options: WEBHOOK_EVENT_TYPES.map((e) => ({ name: e, value: e })),
+        description: 'Event types this subscription should receive',
+      },
+      {
+        displayName: 'Description',
+        name: 'description',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['create', 'update'] } },
+        description: 'Optional human-readable description (max 256 chars)',
+      },
+      {
+        displayName: 'Active',
+        name: 'isActive',
+        type: 'boolean',
+        default: true,
+        displayOptions: { show: { operation: ['update'] } },
+        description: 'Whether the subscription is active',
+      },
+      // --- List ---
+      {
+        displayName: 'Return All',
+        name: 'returnAll',
+        type: 'boolean',
+        default: false,
+        displayOptions: { show: { operation: ['list'] } },
+      },
+      {
+        displayName: 'Limit',
+        name: 'limit',
+        type: 'number',
+        default: 50,
+        typeOptions: { minValue: 1, maxValue: 200 },
+        displayOptions: { show: { operation: ['list'], returnAll: [false] } },
+      },
+    ],
+  }
+
+  async execute(this: any) {
+    const items = this.getInputData()
+    const returnData: any[] = []
+
+    for (let i = 0; i < items.length; i++) {
+      const operation = this.getNodeParameter('operation', i) as string
+
+      if (operation === 'list') {
+        const returnAll = this.getNodeParameter('returnAll', i) as boolean
+        const limit = (this.getNodeParameter('limit', i) as number) || 50
+        const res = await confirmxApiRequest<{ webhooks: any[] }>(this, {
+          method: 'GET',
+          endpoint: '/webhooks',
+        })
+        const sliced = returnAll ? res.webhooks || [] : (res.webhooks || []).slice(0, limit)
+        returnData.push(...sliced.map((w) => ({ json: w })))
+      } else if (operation === 'create') {
+        const body = {
+          url: this.getNodeParameter('url', i) as string,
+          events: this.getNodeParameter('events', i) as string[],
+          description: (this.getNodeParameter('description', i) as string) || undefined,
+        }
+        const res = await confirmxApiRequest<any>(this, {
+          method: 'POST',
+          endpoint: '/webhooks',
+          body,
+        })
+        // Surface the secret prominently — it is returned ONLY at create time.
+        returnData.push({
+          json: {
+            ...res,
+            _warning: res.secretNote || 'Save the secret now — it cannot be retrieved later.',
+          },
+        })
+      } else if (operation === 'update') {
+        const webhookId = this.getNodeParameter('webhookId', i) as string
+        const body: Record<string, any> = {}
+        const url = this.getNodeParameter('url', i) as string
+        const events = this.getNodeParameter('events', i) as string[]
+        const description = this.getNodeParameter('description', i) as string
+        const isActive = this.getNodeParameter('isActive', i, true) as boolean
+        if (url) body.url = url
+        if (events && events.length) body.events = events
+        if (description !== undefined) body.description = description
+        body.isActive = isActive
+        const res = await confirmxApiRequest<{ webhook: any }>(this, {
+          method: 'PATCH',
+          endpoint: `/webhooks/${webhookId}`,
+          body,
+        })
+        returnData.push({ json: res.webhook })
+      } else if (operation === 'delete') {
+        const webhookId = this.getNodeParameter('webhookId', i) as string
+        const res = await confirmxApiRequest<any>(this, {
+          method: 'DELETE',
+          endpoint: `/webhooks/${webhookId}`,
+        })
+        returnData.push({ json: { success: true, webhookId, ...res } })
+      }
+    }
+
+    return [returnData]
+  }
+}

package/nodes/ConfirmX/confirmx.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60" width="60" height="60">
+  <rect width="60" height="60" rx="12" fill="#25D366"/>
+  <path d="M30 12c-9.9 0-18 8.1-18 18 0 3.2.8 6.3 2.4 9l-2.4 9 9.2-2.4c2.6 1.4 5.5 2.2 8.8 2.2 9.9 0 18-8.1 18-18S39.9 12 30 12zm10.7 25.7c-.4 1.2-2.4 2.3-3.3 2.4-.8.1-1.9.2-3-.2-.7-.2-1.6-.5-2.7-1-4.8-2.1-7.9-6.9-8.1-7.2-.2-.3-1.9-2.5-1.9-4.8 0-2.3 1.2-3.4 1.6-3.9.4-.5.9-.6 1.2-.6h.9c.3 0 .7-.1 1 .7.4 1 1.3 3.4 1.4 3.6.1.2.2.5 0 .8-.2.3-.2.5-.5.8-.2.2-.5.6-.7.8-.2.2-.5.5-.2.9.3.5 1.3 2.1 2.7 3.4 1.8 1.6 3.3 2.1 3.8 2.3.5.2.8.2 1.1-.1.3-.3 1.2-1.4 1.5-1.9.3-.5.6-.4 1.1-.3.5.2 3 1.4 3.5 1.7.5.2.9.4 1 .6.1.2.1 1.1-.3 2.2z" fill="#fff"/>
+</svg>

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@wesell/n8n-nodes-confirmx",
+  "version": "0.1.0",
+  "description": "n8n community nodes for the ConfirmX WhatsApp Business Platform Public REST API. Exposes 6 resource nodes + 1 webhook trigger, all eligible as AI Agent tools via n8n's usableAsTool.",
+  "license": "MIT",
+  "author": {
+    "name": "wesell",
+    "url": "https://github.com/ConfirmX/n8n-nodes-confirmx"
+  },
+  "homepage": "https://github.com/ConfirmX/n8n-nodes-confirmx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ConfirmX/n8n-nodes-confirmx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ConfirmX/n8n-nodes-confirmx/issues"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "credentials/ConfirmXApi.credentials.js"
+    ],
+    "nodes": [
+      "nodes/ConfirmX/ConfirmXAccount.node.js",
+      "nodes/ConfirmX/ConfirmXTemplate.node.js",
+      "nodes/ConfirmX/ConfirmXConversation.node.js",
+      "nodes/ConfirmX/ConfirmXMessage.node.js",
+      "nodes/ConfirmX/ConfirmXWebhook.node.js",
+      "nodes/ConfirmX/ConfirmXShippingZone.node.js",
+      "nodes/ConfirmX/ConfirmXTrigger.node.js"
+    ]
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "credentials/**/*",
+    "nodes/**/*",
+    "transports/**/*",
+    "types/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint . --ext .ts",
+    "prepack": "tsc",
+    "release": "npm run build && npm publish --access public"
+  },
+  "keywords": [
+    "n8n-community-node",
+    "n8n",
+    "confirmx",
+    "whatsapp",
+    "ai-agent",
+    "langchain"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "n8n-workflow": "^2.16.0",
+    "typescript": "^5.4.0"
+  }
+}

package/transports/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared HTTP transport for every ConfirmX node in this package.
+ *
+ * Single `confirmxApiRequest()` function used by all 6 action nodes +
+ * the trigger's self-registration logic. Adds the Authorization header,
+ * maps ConfirmX's 402 Payment Required into a rich NodeOperationError,
+ * and retries 429/5xx with exponential backoff.
+ */
+import type { IExecuteFunctions, IHookFunctions, ILoadOptionsFunctions, ITriggerFunctions, IWebhookFunctions } from 'n8n-workflow';
+type Ctx = IExecuteFunctions | IHookFunctions | ILoadOptionsFunctions | ITriggerFunctions | IWebhookFunctions;
+export interface ApiRequestOpts {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    endpoint: string;
+    body?: unknown;
+    qs?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+export interface ConfirmXCredentials {
+    apiKey: string;
+    baseUrl: string;
+}
+/**
+ * Execute a v1 API request against ConfirmX and return the parsed JSON
+ * response. Throws NodeOperationError / NodeApiError on failure.
+ *
+ * - 402 → NodeOperationError with the topup URL and balance figures
+ *   (both in USD).
+ * - 401/403 → NodeApiError — never retried.
+ * - 4xx → NodeApiError with the API error message — never retried.
+ * - 429 + 5xx → exponential backoff (500ms, 1s, 2s); max 3 attempts.
+ */
+export declare function confirmxApiRequest<T = any>(ctx: Ctx, opts: ApiRequestOpts): Promise<T>;
+/**
+ * Load options helper for `accountId` pickers. Calls
+ * GET /api/v1/accounts and maps to {name, value} pairs for n8n's
+ * resourceLocator. Caches for 60s in workflow staticData to avoid N+1
+ * on flows with many nodes.
+ */
+export declare function loadAccountOptions(ctx: ILoadOptionsFunctions | IExecuteFunctions): Promise<Array<{
+    name: string;
+    value: string;
+}>>;
+export {};

package/transports/http.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmxApiRequest = confirmxApiRequest;
+exports.loadAccountOptions = loadAccountOptions;
+const n8n_workflow_1 = require("n8n-workflow");
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 500;
+const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * Execute a v1 API request against ConfirmX and return the parsed JSON
+ * response. Throws NodeOperationError / NodeApiError on failure.
+ *
+ * - 402 → NodeOperationError with the topup URL and balance figures
+ *   (both in USD).
+ * - 401/403 → NodeApiError — never retried.
+ * - 4xx → NodeApiError with the API error message — never retried.
+ * - 429 + 5xx → exponential backoff (500ms, 1s, 2s); max 3 attempts.
+ */
+async function confirmxApiRequest(ctx, opts) {
+    const creds = (await ctx.getCredentials('confirmXApi'));
+    const baseUrl = (creds.baseUrl || '').replace(/\/$/, '');
+    if (!baseUrl) {
+        throw new n8n_workflow_1.NodeOperationError(ctx.getNode(), 'ConfirmX Base URL is empty.');
+    }
+    const url = `${baseUrl}${opts.endpoint}`;
+    const headers = {
+        Authorization: `Bearer ${creds.apiKey}`,
+        Accept: 'application/json',
+        ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...(opts.headers ?? {}),
+    };
+    let lastError = null;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            const response = await ctx.helpers.httpRequest({
+                method: opts.method,
+                url,
+                headers,
+                qs: opts.qs,
+                body: opts.body !== undefined ? opts.body : undefined,
+                json: true,
+                timeout: REQUEST_TIMEOUT_MS,
+            });
+            // Empty body (e.g. 204) → return {}
+            if (response === undefined || response === null)
+                return {};
+            return response;
+        }
+        catch (err) {
+            lastError = err;
+            const status = err?.statusCode ?? err?.response?.statusCode;
+            const body = err?.response?.body ?? err?.error ?? null;
+            // 402 Payment Required — surface rich error, never retry.
+            if (status === 402) {
+                const parsed = typeof body === 'string' ? tryParse(body) : body;
+                const required = Number(parsed?.requiredMicros ?? 0) / 1000000;
+                const current = Number(parsed?.currentBalanceMicros ?? 0) / 1000000;
+                const topupUrl = parsed?.topupUrl || '(no topup URL returned)';
+                throw new n8n_workflow_1.NodeOperationError(ctx.getNode(), `ConfirmX wallet balance too low ($${current.toFixed(6)} available; $${required.toFixed(6)} required). Top up at ${topupUrl}.`, { description: parsed?.message ?? 'Insufficient wallet balance.' });
+            }
+            // 401/403 — bad credentials / scope — never retry.
+            if (status === 401 || status === 403) {
+                throw new n8n_workflow_1.NodeApiError(ctx.getNode(), err, {
+                    message: `ConfirmX auth failed (${status}). Check the API key and required scopes.`,
+                });
+            }
+            // 4xx — don't retry; show API error message.
+            if (status && status >= 400 && status < 500) {
+                const parsed = typeof body === 'string' ? tryParse(body) : body;
+                const apiMessage = parsed?.error ?? parsed?.message ?? err?.message ?? 'Unknown error';
+                throw new n8n_workflow_1.NodeApiError(ctx.getNode(), err, {
+                    message: `ConfirmX ${opts.method} ${opts.endpoint} → ${status}: ${apiMessage}`,
+                });
+            }
+            // 429 or 5xx — backoff and retry.
+            if (attempt < MAX_ATTEMPTS) {
+                const wait = BACKOFF_BASE_MS * 2 ** (attempt - 1);
+                await sleep(wait);
+                continue;
+            }
+        }
+    }
+    throw new n8n_workflow_1.NodeApiError(ctx.getNode(), lastError, {
+        message: `ConfirmX ${opts.method} ${opts.endpoint} failed after ${MAX_ATTEMPTS} attempts.`,
+    });
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function tryParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load options helper for `accountId` pickers. Calls
+ * GET /api/v1/accounts and maps to {name, value} pairs for n8n's
+ * resourceLocator. Caches for 60s in workflow staticData to avoid N+1
+ * on flows with many nodes.
+ */
+async function loadAccountOptions(ctx) {
+    const staticData = ctx.getWorkflowStaticData('global');
+    const cached = staticData.__confirmx_accounts;
+    const now = Date.now();
+    if (cached && now - cached.ts < 60000)
+        return cached.options;
+    const res = await confirmxApiRequest(ctx, { method: 'GET', endpoint: '/accounts' });
+    const options = (res.accounts || [])
+        .filter((a) => a.isActive)
+        .map((a) => ({ name: a.label || a.id, value: a.id }));
+    staticData.__confirmx_accounts = { ts: now, options };
+    return options;
+}
+//# sourceMappingURL=http.js.map

package/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["http.ts"],"names":[],"mappings":"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"}

package/transports/http.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared HTTP transport for every ConfirmX node in this package.
+ *
+ * Single `confirmxApiRequest()` function used by all 6 action nodes +
+ * the trigger's self-registration logic. Adds the Authorization header,
+ * maps ConfirmX's 402 Payment Required into a rich NodeOperationError,
+ * and retries 429/5xx with exponential backoff.
+ */
+import type {
+  IExecuteFunctions,
+  IHookFunctions,
+  ILoadOptionsFunctions,
+  ITriggerFunctions,
+  IWebhookFunctions,
+} from 'n8n-workflow'
+import { NodeApiError, NodeOperationError } from 'n8n-workflow'
+
+type Ctx =
+  | IExecuteFunctions
+  | IHookFunctions
+  | ILoadOptionsFunctions
+  | ITriggerFunctions
+  | IWebhookFunctions
+
+export interface ApiRequestOpts {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  endpoint: string
+  body?: unknown
+  qs?: Record<string, string | number | boolean | undefined>
+  headers?: Record<string, string>
+}
+
+export interface ConfirmXCredentials {
+  apiKey: string
+  baseUrl: string
+}
+
+const MAX_ATTEMPTS = 3
+const BACKOFF_BASE_MS = 500
+const REQUEST_TIMEOUT_MS = 30_000
+
+/**
+ * Execute a v1 API request against ConfirmX and return the parsed JSON
+ * response. Throws NodeOperationError / NodeApiError on failure.
+ *
+ * - 402 → NodeOperationError with the topup URL and balance figures
+ *   (both in USD).
+ * - 401/403 → NodeApiError — never retried.
+ * - 4xx → NodeApiError with the API error message — never retried.
+ * - 429 + 5xx → exponential backoff (500ms, 1s, 2s); max 3 attempts.
+ */
+export async function confirmxApiRequest<T = any>(
+  ctx: Ctx,
+  opts: ApiRequestOpts,
+): Promise<T> {
+  const creds = (await ctx.getCredentials('confirmXApi')) as unknown as ConfirmXCredentials
+  const baseUrl = (creds.baseUrl || '').replace(/\/$/, '')
+  if (!baseUrl) {
+    throw new NodeOperationError(ctx.getNode(), 'ConfirmX Base URL is empty.')
+  }
+  const url = `${baseUrl}${opts.endpoint}`
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${creds.apiKey}`,
+    Accept: 'application/json',
+    ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+    ...(opts.headers ?? {}),
+  }
+
+  let lastError: unknown = null
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const response = await ctx.helpers.httpRequest({
+        method: opts.method,
+        url,
+        headers,
+        qs: opts.qs,
+        body: opts.body !== undefined ? (opts.body as any) : undefined,
+        json: true,
+        timeout: REQUEST_TIMEOUT_MS,
+      })
+      // Empty body (e.g. 204) → return {}
+      if (response === undefined || response === null) return {} as T
+      return response as T
+    } catch (err: any) {
+      lastError = err
+      const status: number | undefined = err?.statusCode ?? err?.response?.statusCode
+      const body: any = err?.response?.body ?? err?.error ?? null
+
+      // 402 Payment Required — surface rich error, never retry.
+      if (status === 402) {
+        const parsed = typeof body === 'string' ? tryParse(body) : body
+        const required = Number(parsed?.requiredMicros ?? 0) / 1_000_000
+        const current = Number(parsed?.currentBalanceMicros ?? 0) / 1_000_000
+        const topupUrl = parsed?.topupUrl || '(no topup URL returned)'
+        throw new NodeOperationError(
+          ctx.getNode(),
+          `ConfirmX wallet balance too low ($${current.toFixed(6)} available; $${required.toFixed(6)} required). Top up at ${topupUrl}.`,
+          { description: parsed?.message ?? 'Insufficient wallet balance.' },
+        )
+      }
+
+      // 401/403 — bad credentials / scope — never retry.
+      if (status === 401 || status === 403) {
+        throw new NodeApiError(ctx.getNode(), err, {
+          message: `ConfirmX auth failed (${status}). Check the API key and required scopes.`,
+        })
+      }
+
+      // 4xx — don't retry; show API error message.
+      if (status && status >= 400 && status < 500) {
+        const parsed = typeof body === 'string' ? tryParse(body) : body
+        const apiMessage = parsed?.error ?? parsed?.message ?? err?.message ?? 'Unknown error'
+        throw new NodeApiError(ctx.getNode(), err, {
+          message: `ConfirmX ${opts.method} ${opts.endpoint} → ${status}: ${apiMessage}`,
+        })
+      }
+
+      // 429 or 5xx — backoff and retry.
+      if (attempt < MAX_ATTEMPTS) {
+        const wait = BACKOFF_BASE_MS * 2 ** (attempt - 1)
+        await sleep(wait)
+        continue
+      }
+    }
+  }
+
+  throw new NodeApiError(ctx.getNode(), lastError as any, {
+    message: `ConfirmX ${opts.method} ${opts.endpoint} failed after ${MAX_ATTEMPTS} attempts.`,
+  })
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
+function tryParse(s: string): any {
+  try {
+    return JSON.parse(s)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load options helper for `accountId` pickers. Calls
+ * GET /api/v1/accounts and maps to {name, value} pairs for n8n's
+ * resourceLocator. Caches for 60s in workflow staticData to avoid N+1
+ * on flows with many nodes.
+ */
+export async function loadAccountOptions(
+  ctx: ILoadOptionsFunctions | IExecuteFunctions,
+): Promise<Array<{ name: string; value: string }>> {
+  const staticData = ctx.getWorkflowStaticData('global') as Record<string, any>
+  const cached = staticData.__confirmx_accounts as
+    | { ts: number; options: Array<{ name: string; value: string }> }
+    | undefined
+  const now = Date.now()
+  if (cached && now - cached.ts < 60_000) return cached.options
+
+  const res = await confirmxApiRequest<{ accounts: Array<{ id: string; label: string; isActive: boolean }> }>(
+    ctx as any,
+    { method: 'GET', endpoint: '/accounts' },
+  )
+  const options = (res.accounts || [])
+    .filter((a) => a.isActive)
+    .map((a) => ({ name: a.label || a.id, value: a.id }))
+  staticData.__confirmx_accounts = { ts: now, options }
+  return options
+}

package/transports/signature.d.ts

@@ -0,0 +1,21 @@
+export interface VerifyOpts {
+    secret: string;
+    body: string;
+    timestamp: string;
+    signatureHeader: string;
+}
+/**
+ * Constant-time verification of the X-ConfirmX-Signature header against
+ * HMAC-SHA256(secret, `${timestamp}.${body}`).
+ *
+ * Returns false on any mismatch, length mismatch, or non-string input.
+ * Never throws.
+ */
+export declare function verifyPayload(opts: VerifyOpts): boolean;
+/**
+ * Returns the absolute skew (in seconds) between the supplied timestamp
+ * and now. Replay window enforced by ConfirmX is 300s.
+ */
+export declare function timestampSkewSeconds(timestamp: string, now?: number): number;
+/** Replay window in seconds — must match the receiver convention. */
+export declare const REPLAY_WINDOW_SECONDS = 300;

package/transports/signature.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_WINDOW_SECONDS = void 0;
+exports.verifyPayload = verifyPayload;
+exports.timestampSkewSeconds = timestampSkewSeconds;
+/**
+ * HMAC-SHA256 signature verification for inbound ConfirmX webhooks.
+ *
+ * Must stay byte-compatible with the verifier in
+ * apps/worker/src/lib/webhooks.ts::verifyPayload (and the corresponding
+ * outbound signer in apps/api/src/lib/webhooks.ts::signPayload). The
+ * signing scheme is `${timestamp}.${body}` keyed by the per-webhook
+ * plaintext secret; the receiver must also enforce a 300s skew window
+ * to defeat replay.
+ */
+const node_crypto_1 = require("node:crypto");
+/**
+ * Constant-time verification of the X-ConfirmX-Signature header against
+ * HMAC-SHA256(secret, `${timestamp}.${body}`).
+ *
+ * Returns false on any mismatch, length mismatch, or non-string input.
+ * Never throws.
+ */
+function verifyPayload(opts) {
+    const { secret, body, timestamp, signatureHeader } = opts;
+    if (typeof secret !== 'string' || typeof body !== 'string')
+        return false;
+    if (typeof timestamp !== 'string' || typeof signatureHeader !== 'string') {
+        return false;
+    }
+    const expected = 'sha256=' + (0, node_crypto_1.createHmac)('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+    const expectedBuf = Buffer.from(expected, 'utf8');
+    const providedBuf = Buffer.from(signatureHeader, 'utf8');
+    if (expectedBuf.length !== providedBuf.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(expectedBuf, providedBuf);
+}
+/**
+ * Returns the absolute skew (in seconds) between the supplied timestamp
+ * and now. Replay window enforced by ConfirmX is 300s.
+ */
+function timestampSkewSeconds(timestamp, now = Date.now()) {
+    const ts = parseInt(timestamp, 10);
+    if (!Number.isFinite(ts))
+        return Number.POSITIVE_INFINITY;
+    return Math.abs(now / 1000 - ts);
+}
+/** Replay window in seconds — must match the receiver convention. */
+exports.REPLAY_WINDOW_SECONDS = 300;
+//# sourceMappingURL=signature.js.map

package/transports/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["signature.ts"],"names":[],"mappings":";;;AA0BA,sCAeC;AAMD,oDAIC;AAnDD;;;;;;;;;GASG;AACH,6CAAyD;AASzD;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,IAAgB;IAC5C,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,IAAI,CAAA;IAEzD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACxE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACzE,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,QAAQ,GACZ,SAAS,GAAG,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAEvF,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAA;IACxD,IAAI,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC3D,OAAO,IAAA,6BAAe,EAAC,WAAW,EAAE,WAAW,CAAC,CAAA;AAClD,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,SAAiB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC9E,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;IAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAA;IACzD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAA;AAClC,CAAC;AAED,qEAAqE;AACxD,QAAA,qBAAqB,GAAG,GAAG,CAAA"}