@nestarc/webhook 0.2.0

package/dist/webhook.url-validator.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWebhookUrl = validateWebhookUrl;
+exports.resolveAndValidateHost = resolveAndValidateHost;
+const net = __importStar(require("net"));
+const dns = __importStar(require("dns"));
+const BLOCKED_HOSTNAMES = new Set([
+    'localhost',
+    'localhost.localdomain',
+    'ip6-localhost',
+    'ip6-loopback',
+]);
+async function validateWebhookUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid webhook URL: unable to parse "${url}"`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Invalid webhook URL: scheme must be http or https, got "${parsed.protocol}"`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (BLOCKED_HOSTNAMES.has(hostname)) {
+        throw new Error(`Invalid webhook URL: "${hostname}" is not allowed (loopback address)`);
+    }
+    if (net.isIPv4(hostname)) {
+        validateIPv4(hostname);
+    }
+    else if (net.isIPv6(hostname) || hostname.startsWith('[')) {
+        const cleanIp = hostname.replace(/^\[|\]$/g, '');
+        validateIPv6(cleanIp);
+    }
+    else {
+        // Hostname — resolve DNS and validate all resolved IPs
+        await resolveAndValidateHost(hostname);
+    }
+}
+function validateIPv4(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts[0] === 127) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a loopback address`);
+    }
+    if (parts[0] === 10) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a private address`);
+    }
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a private address`);
+    }
+    if (parts[0] === 192 && parts[1] === 168) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a private address`);
+    }
+    if (parts[0] === 169 && parts[1] === 254) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a link-local/metadata address`);
+    }
+    if (parts[0] === 0) {
+        throw new Error(`Invalid webhook URL: "${ip}" is not a valid target`);
+    }
+}
+function validateIPv6(ip) {
+    if (ip === '::1') {
+        throw new Error(`Invalid webhook URL: "${ip}" is a loopback address`);
+    }
+    const lowerIp = ip.toLowerCase();
+    // IPv4-mapped IPv6 — ::ffff:x.x.x.x or ::ffff:HHHH:HHHH (hex form)
+    if (lowerIp.startsWith('::ffff:') || lowerIp.startsWith('0:0:0:0:0:ffff:')) {
+        const suffix = lowerIp.replace(/^(::ffff:|0:0:0:0:0:ffff:)/, '');
+        let ipv4;
+        if (net.isIPv4(suffix)) {
+            // ::ffff:10.0.0.1 form
+            ipv4 = suffix;
+        }
+        else {
+            // ::ffff:a00:1 form (hex) — convert to IPv4
+            const hexParts = suffix.split(':');
+            if (hexParts.length === 2) {
+                const hi = parseInt(hexParts[0], 16);
+                const lo = parseInt(hexParts[1], 16);
+                ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+            }
+            else {
+                return; // Unknown format, let it through (conservative)
+            }
+        }
+        validateIPv4(ipv4);
+        return;
+    }
+    const firstSegment = ip.split(':')[0].toLowerCase();
+    if (firstSegment.startsWith('fc') || firstSegment.startsWith('fd')) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a private address`);
+    }
+    if (firstSegment.startsWith('fe8') || firstSegment.startsWith('fe9') ||
+        firstSegment.startsWith('fea') || firstSegment.startsWith('feb')) {
+        throw new Error(`Invalid webhook URL: "${ip}" is a link-local address`);
+    }
+}
+async function resolveAndValidateHost(hostname) {
+    let addresses = [];
+    try {
+        const ipv4 = await dns.promises.resolve4(hostname);
+        addresses = addresses.concat(ipv4);
+    }
+    catch {
+        // No A record — not an error yet
+    }
+    try {
+        const ipv6 = await dns.promises.resolve6(hostname);
+        addresses = addresses.concat(ipv6);
+    }
+    catch {
+        // No AAAA record — not an error yet
+    }
+    for (const ip of addresses) {
+        if (net.isIPv4(ip)) {
+            validateIPv4(ip); // throws if private
+        }
+        else if (net.isIPv6(ip)) {
+            validateIPv6(ip); // throws if private
+        }
+    }
+}
+//# sourceMappingURL=webhook.url-validator.js.map

package/dist/webhook.url-validator.js.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nestarc/webhook",
+  "version": "0.2.0",
+  "description": "Outbound webhook delivery for NestJS — HMAC signing, exponential retry, circuit breaker, delivery logs, fan-out, Standard Webhooks compatible",
+  "author": "nestarc",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/sql"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "test:e2e": "jest --config jest.e2e.config.js --runInBand",
+    "test:cov": "jest --coverage --runInBand",
+    "lint": "tsc --noEmit",
+    "prisma:generate": "prisma generate --schema=test/e2e/schema.prisma",
+    "prepublishOnly": "npm run clean && npm run lint && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/schedule": "^4.0.0 || ^5.0.0",
+    "@prisma/client": "^5.0.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/schedule": "^5.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@prisma/client": "^6.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "prisma": "^6.19.3",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestarc/webhook.git"
+  },
+  "keywords": [
+    "nestjs",
+    "webhook",
+    "outbound",
+    "hmac",
+    "retry",
+    "circuit-breaker",
+    "standard-webhooks"
+  ]
+}

package/src/sql/create-webhook-tables.sql

@@ -0,0 +1,72 @@
+-- @nestarc/webhook — PostgreSQL migration
+-- Creates the three core tables for outbound webhook delivery.
+-- Run this migration against your PostgreSQL database before using the module.
+
+-- Required for gen_random_uuid() on PostgreSQL < 13
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS webhook_endpoints (
+  id                   UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  url                  VARCHAR(2048) NOT NULL,
+  secret               VARCHAR(255)  NOT NULL,
+  events               VARCHAR(255)[] NOT NULL DEFAULT '{}',
+  active               BOOLEAN       NOT NULL DEFAULT TRUE,
+  description          VARCHAR(500),
+  metadata             JSONB,
+  tenant_id            VARCHAR(255),
+
+  consecutive_failures INT           NOT NULL DEFAULT 0,
+  disabled_at          TIMESTAMPTZ,
+  disabled_reason      VARCHAR(255),
+
+  created_at           TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
+  updated_at           TIMESTAMPTZ   NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_endpoints_tenant_active
+  ON webhook_endpoints (tenant_id, active);
+CREATE INDEX IF NOT EXISTS idx_webhook_endpoints_active_events
+  ON webhook_endpoints (active, events);
+
+---
+
+CREATE TABLE IF NOT EXISTS webhook_events (
+  id          UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  event_type  VARCHAR(255) NOT NULL,
+  payload     JSONB        NOT NULL,
+  tenant_id   VARCHAR(255),
+  created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_events_type_created
+  ON webhook_events (event_type, created_at);
+
+---
+
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+  id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  event_id        UUID         NOT NULL REFERENCES webhook_events(id),
+  endpoint_id     UUID         NOT NULL REFERENCES webhook_endpoints(id),
+  status          VARCHAR(20)  NOT NULL DEFAULT 'PENDING',
+  attempts        INT          NOT NULL DEFAULT 0,
+  max_attempts    INT          NOT NULL DEFAULT 5,
+  next_attempt_at TIMESTAMPTZ,
+  claimed_at      TIMESTAMPTZ,
+  last_attempt_at TIMESTAMPTZ,
+  completed_at    TIMESTAMPTZ,
+
+  response_status INT,
+  response_body   TEXT,
+  latency_ms      INT,
+  last_error      TEXT,
+
+  CONSTRAINT fk_delivery_event    FOREIGN KEY (event_id)    REFERENCES webhook_events(id),
+  CONSTRAINT fk_delivery_endpoint FOREIGN KEY (endpoint_id) REFERENCES webhook_endpoints(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_status_next
+  ON webhook_deliveries (status, next_attempt_at);
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_endpoint_status
+  ON webhook_deliveries (endpoint_id, status);
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_event
+  ON webhook_deliveries (event_id);