@nestarc/webhook 0.12.0 → 0.13.0

package/dist/webhook.signer.d.ts

@@ -4,10 +4,15 @@ export interface SignatureHeaders {
     'webhook-timestamp': string;
     'webhook-signature': string;
 }
+export interface WebhookVerificationOptions {
+    toleranceSeconds: number;
+    now?: Date;
+}
 export declare class WebhookSigner {
     signAll(eventId: string, timestamp: number, body: string, secrets: string[]): SignatureHeaders;
     sign(eventId: string, timestamp: number, body: string, secret: string): SignatureHeaders;
     verify(eventId: string, timestamp: number, body: string, secret: string, signature: string): boolean;
+    verifyWithTolerance(eventId: string, timestamp: number, body: string, secret: string, signature: string, options: WebhookVerificationOptions): boolean;
     generateSecret(): string;
     private signSingle;
 }

package/dist/webhook.signer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.signer.d.ts","sourceRoot":"","sources":["../src/webhook.signer.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,qBACa,aAAa;IACxB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,GAChB,gBAAgB;IAgBnB,IAAI,CACF,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,gBAAgB;IAInB,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO;IAcV,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,UAAU;CAcnB"}
+{"version":3,"file":"webhook.signer.d.ts","sourceRoot":"","sources":["../src/webhook.signer.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,qBACa,aAAa;IACxB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,GAChB,gBAAgB;IAgBnB,IAAI,CACF,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,gBAAgB;IAInB,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO;IAcV,mBAAmB,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,0BAA0B,GAClC,OAAO;IAoBV,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,UAAU;CAcnB"}

package/dist/webhook.signer.js

@@ -70,6 +70,20 @@ let WebhookSigner = class WebhookSigner {
             return crypto.timingSafeEqual(a, b);
         });
     }
+    verifyWithTolerance(eventId, timestamp, body, secret, signature, options) {
+        if (!Number.isFinite(options.toleranceSeconds) ||
+            options.toleranceSeconds < 0) {
+            throw new Error('toleranceSeconds must be a finite non-negative number');
+        }
+        if (!Number.isFinite(timestamp)) {
+            return false;
+        }
+        const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
+        if (Math.abs(nowSeconds - timestamp) > options.toleranceSeconds) {
+            return false;
+        }
+        return this.verify(eventId, timestamp, body, secret, signature);
+    }
     generateSecret() {
         return crypto.randomBytes(32).toString('base64');
     }

package/dist/webhook.signer.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.signer.js","sourceRoot":"","sources":["../src/webhook.signer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAiC;AACjC,2CAA4C;AAUrC,IAAM,aAAa,GAAnB,MAAM,aAAa;IACxB,OAAO,CACL,OAAe,EACf,SAAiB,EACjB,IAAY,EACZ,OAAiB;QAEjB,MAAM,UAAU,GAAG,OAAO;aACvB,MAAM,CAAC,CAAC,MAAM,EAAoB,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;aACrD,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAEtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO;YACL,YAAY,EAAE,OAAO;YACrB,mBAAmB,EAAE,MAAM,CAAC,SAAS,CAAC;YACtC,mBAAmB,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;SAC1C,CAAC;IACJ,CAAC;IAED,IAAI,CACF,OAAe,EACf,SAAiB,EACjB,IAAY,EACZ,MAAc;QAEd,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CACJ,OAAe,EACf,SAAiB,EACjB,IAAY,EACZ,MAAc,EACd,SAAiB;QAEjB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACnE,MAAM,kBAAkB,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEzE,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;YAC3C,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAEjC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;YAExC,OAAO,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,cAAc;QACZ,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IAEO,UAAU,CAChB,OAAe,EACf,SAAiB,EACjB,IAAY,EACZ,MAAc;QAEd,MAAM,MAAM,GAAG,GAAG,OAAO,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM;aAChB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;aACnD,MAAM,CAAC,MAAM,CAAC;aACd,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEpB,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;CACF,CAAA;AArEY,sCAAa;wBAAb,aAAa;IADzB,IAAA,mBAAU,GAAE;GACA,aAAa,CAqEzB"}
+{"version":3,"file":"webhook.signer.js","sourceRoot":"","sources":["../src/webhook.signer.ts"],"names":[],"mappings":"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"}

package/dist/webhook.url-validator.d.ts

@@ -7,5 +7,5 @@ export declare class WebhookUrlValidationError extends Error {
     constructor(message: string, reason: WebhookUrlValidationReason, url?: string, resolvedIp?: string);
 }
 export declare function validateWebhookUrl(url: string): Promise<void>;
-export declare function resolveAndValidateHost(hostname: string, url?: string): Promise<void>;
+export declare function resolveAndValidateHost(hostname: string, url?: string): Promise<string[]>;
 //# sourceMappingURL=webhook.url-validator.d.ts.map

package/dist/webhook.url-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.url-validator.d.ts","sourceRoot":"","sources":["../src/webhook.url-validator.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,0BAA0B,GAClC,OAAO,GACP,QAAQ,GACR,kBAAkB,GAClB,UAAU,GACV,SAAS,GACT,YAAY,GACZ,gBAAgB,CAAC;AAErB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,0BAA0B,EAClC,GAAG,CAAC,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM;CAQtB;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCnE;AA+GD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"webhook.url-validator.d.ts","sourceRoot":"","sources":["../src/webhook.url-validator.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,0BAA0B,GAClC,OAAO,GACP,QAAQ,GACR,kBAAkB,GAClB,UAAU,GACV,SAAS,GACT,YAAY,GACZ,gBAAgB,CAAC;AAkCrB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,0BAA0B,EAClC,GAAG,CAAC,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM;CAQtB;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCnE;AAgDD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,EAAE,CAAC,CAsDnB"}

package/dist/webhook.url-validator.js

@@ -44,6 +44,36 @@ const BLOCKED_HOSTNAMES = new Set([
     'ip6-localhost',
     'ip6-loopback',
 ]);
+const BLOCKED_IPV4_RANGES = [
+    ipv4Range('0.0.0.0', 8, 'invalid_target', 'not a valid public target'),
+    ipv4Range('10.0.0.0', 8, 'private', 'a private address'),
+    ipv4Range('100.64.0.0', 10, 'private', 'a shared/private address'),
+    ipv4Range('127.0.0.0', 8, 'loopback', 'a loopback address'),
+    ipv4Range('169.254.0.0', 16, 'link_local', 'a link-local/metadata address'),
+    ipv4Range('172.16.0.0', 12, 'private', 'a private address'),
+    ipv4Range('192.0.0.0', 24, 'invalid_target', 'a special-use address'),
+    ipv4Range('192.0.2.0', 24, 'invalid_target', 'a documentation address'),
+    ipv4Range('192.88.99.0', 24, 'invalid_target', 'a special-use address'),
+    ipv4Range('192.168.0.0', 16, 'private', 'a private address'),
+    ipv4Range('198.18.0.0', 15, 'invalid_target', 'a benchmarking address'),
+    ipv4Range('198.51.100.0', 24, 'invalid_target', 'a documentation address'),
+    ipv4Range('203.0.113.0', 24, 'invalid_target', 'a documentation address'),
+    ipv4Range('224.0.0.0', 4, 'invalid_target', 'a multicast address'),
+    ipv4Range('240.0.0.0', 4, 'invalid_target', 'a reserved address'),
+];
+const BLOCKED_IPV6_RANGES = [
+    ipv6Range('::', 128, 'invalid_target', 'not a valid public target'),
+    ipv6Range('::1', 128, 'loopback', 'a loopback address'),
+    ipv6Range('::', 96, 'invalid_target', 'a special-use address'),
+    ipv6Range('100::', 64, 'invalid_target', 'a discard-only address'),
+    ipv6Range('2001::', 23, 'invalid_target', 'a special-use address'),
+    ipv6Range('2001:db8::', 32, 'invalid_target', 'a documentation address'),
+    ipv6Range('2002::', 16, 'invalid_target', 'a special-use address'),
+    ipv6Range('3fff::', 20, 'invalid_target', 'a documentation address'),
+    ipv6Range('fc00::', 7, 'private', 'a private address'),
+    ipv6Range('fe80::', 10, 'link_local', 'a link-local address'),
+    ipv6Range('ff00::', 8, 'invalid_target', 'a multicast address'),
+];
 class WebhookUrlValidationError extends Error {
     name = 'WebhookUrlValidationError';
     reason;
@@ -86,79 +116,58 @@ async function validateWebhookUrl(url) {
     }
 }
 function validateIPv4(ip, url) {
-    const parts = ip.split('.').map(Number);
-    if (parts[0] === 127) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a loopback address`, 'loopback', url, ip);
-    }
-    if (parts[0] === 10) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a private address`, 'private', url, ip);
-    }
-    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a private address`, 'private', url, ip);
-    }
-    if (parts[0] === 192 && parts[1] === 168) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a private address`, 'private', url, ip);
-    }
-    if (parts[0] === 169 && parts[1] === 254) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a link-local/metadata address`, 'link_local', url, ip);
-    }
-    if (parts[0] === 0) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is not a valid target`, 'invalid_target', url, ip);
+    const value = ipv4ToNumber(ip);
+    const blocked = BLOCKED_IPV4_RANGES.find((range) => ipv4InRange(value, range));
+    if (blocked) {
+        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is ${blocked.description}`, blocked.reason, url, ip);
     }
 }
 function validateIPv6(ip, url) {
-    if (ip === '::1') {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a loopback address`, 'loopback', url, ip);
-    }
     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, url);
-        return;
+    const parsed = parseIPv6ToBigInt(lowerIp);
+    if (parsed === null) {
+        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is not a valid target`, 'invalid_target', url, ip);
     }
-    const firstSegment = ip.split(':')[0].toLowerCase();
-    if (firstSegment.startsWith('fc') || firstSegment.startsWith('fd')) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a private address`, 'private', url, ip);
+    if (isIPv4MappedIPv6(parsed)) {
+        validateIPv4(numberToIPv4(Number(parsed & 0xffffffffn)), url);
+        return;
     }
-    if (firstSegment.startsWith('fe8') || firstSegment.startsWith('fe9') ||
-        firstSegment.startsWith('fea') || firstSegment.startsWith('feb')) {
-        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is a link-local address`, 'link_local', url, ip);
+    const blocked = BLOCKED_IPV6_RANGES.find((range) => ipv6InRange(parsed, range));
+    if (blocked) {
+        throw new WebhookUrlValidationError(`Invalid webhook URL: "${ip}" is ${blocked.description}`, blocked.reason, url, ip);
     }
 }
 async function resolveAndValidateHost(hostname, url) {
+    const cleanHostname = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (BLOCKED_HOSTNAMES.has(cleanHostname)) {
+        throw new WebhookUrlValidationError(`Invalid webhook URL: "${cleanHostname}" is not allowed (loopback address)`, 'blocked_hostname', url);
+    }
+    if (net.isIPv4(cleanHostname)) {
+        validateIPv4(cleanHostname, url);
+        return [cleanHostname];
+    }
+    if (net.isIPv6(cleanHostname)) {
+        validateIPv6(cleanHostname, url);
+        return [cleanHostname];
+    }
     let addresses = [];
     try {
-        const ipv4 = await dns.promises.resolve4(hostname);
+        const ipv4 = await dns.promises.resolve4(cleanHostname);
         addresses = addresses.concat(ipv4);
     }
     catch {
         // No A record — not an error yet
     }
     try {
-        const ipv6 = await dns.promises.resolve6(hostname);
+        const ipv6 = await dns.promises.resolve6(cleanHostname);
         addresses = addresses.concat(ipv6);
     }
     catch {
         // No AAAA record — not an error yet
     }
+    if (addresses.length === 0) {
+        throw new WebhookUrlValidationError(`Invalid webhook URL: hostname "${cleanHostname}" did not resolve to any address`, 'invalid_target', url);
+    }
     for (const ip of addresses) {
         if (net.isIPv4(ip)) {
             validateIPv4(ip, url); // throws if private
@@ -167,5 +176,90 @@ async function resolveAndValidateHost(hostname, url) {
             validateIPv6(ip, url); // throws if private
         }
     }
+    return addresses;
+}
+function ipv4Range(base, prefix, reason, description) {
+    return { base: ipv4ToNumber(base), prefix, reason, description };
+}
+function ipv6Range(base, prefix, reason, description) {
+    const parsed = parseIPv6ToBigInt(base);
+    if (parsed === null) {
+        throw new Error(`Invalid IPv6 range base: ${base}`);
+    }
+    return { base: parsed, prefix, reason, description };
+}
+function ipv4ToNumber(ip) {
+    return ip
+        .split('.')
+        .map(Number)
+        .reduce((value, part) => ((value << 8) + part) >>> 0, 0);
+}
+function numberToIPv4(value) {
+    return [
+        (value >>> 24) & 0xff,
+        (value >>> 16) & 0xff,
+        (value >>> 8) & 0xff,
+        value & 0xff,
+    ].join('.');
+}
+function ipv4InRange(value, range) {
+    const mask = range.prefix === 0
+        ? 0
+        : (0xffffffff << (32 - range.prefix)) >>> 0;
+    return (value & mask) >>> 0 === (range.base & mask) >>> 0;
+}
+function ipv6InRange(value, range) {
+    const shift = BigInt(128 - range.prefix);
+    return (value >> shift) === (range.base >> shift);
+}
+function parseIPv6ToBigInt(ip) {
+    let normalized = ip.replace(/^\[|\]$/g, '').toLowerCase();
+    const zoneIndex = normalized.indexOf('%');
+    if (zoneIndex !== -1) {
+        normalized = normalized.slice(0, zoneIndex);
+    }
+    if (normalized.includes('.')) {
+        const lastColon = normalized.lastIndexOf(':');
+        const ipv4 = normalized.slice(lastColon + 1);
+        if (!net.isIPv4(ipv4)) {
+            return null;
+        }
+        const value = ipv4ToNumber(ipv4);
+        const high = ((value >>> 16) & 0xffff).toString(16);
+        const low = (value & 0xffff).toString(16);
+        normalized = `${normalized.slice(0, lastColon)}:${high}:${low}`;
+    }
+    const compressed = normalized.includes('::');
+    const compressionParts = normalized.split('::');
+    if (compressionParts.length > 2) {
+        return null;
+    }
+    const left = compressionParts[0]
+        ? compressionParts[0].split(':').filter((part) => part.length > 0)
+        : [];
+    const right = compressionParts[1]
+        ? compressionParts[1].split(':').filter((part) => part.length > 0)
+        : [];
+    const missing = compressed ? 8 - left.length - right.length : 0;
+    if (missing < 0) {
+        return null;
+    }
+    const parts = compressed
+        ? [...left, ...Array(missing).fill('0'), ...right]
+        : left;
+    if (parts.length !== 8) {
+        return null;
+    }
+    let value = 0n;
+    for (const part of parts) {
+        if (!/^[0-9a-f]{1,4}$/.test(part)) {
+            return null;
+        }
+        value = (value << 16n) + BigInt(parseInt(part, 16));
+    }
+    return value;
+}
+function isIPv4MappedIPv6(value) {
+    return (value >> 32n) === 0xffffn;
 }
 //# sourceMappingURL=webhook.url-validator.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestarc/webhook",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Outbound webhook delivery for NestJS — HMAC signing, exponential retry, circuit breaker, delivery logs, fan-out, Standard Webhooks compatible",
   "author": "nestarc",
   "license": "MIT",
@@ -35,13 +35,19 @@
     "@prisma/client": "^6.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.6.0",
-    "jest": "^30.3.0",
+    "jest": "^30.4.2",
     "prisma": "^6.19.3",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
-    "ts-jest": "^29.2.0",
+    "ts-jest": "^29.4.11",
     "typescript": "^5.4.0"
   },
+  "overrides": {
+    "@babel/core": "^7.29.7",
+    "js-yaml": "^4.2.0",
+    "multer": "^2.2.0",
+    "qs": "^6.15.2"
+  },
   "engines": {
     "node": ">=20.0.0"
   },

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

@@ -33,15 +33,21 @@ CREATE INDEX IF NOT EXISTS idx_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()
+  id                 UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  event_type         VARCHAR(255) NOT NULL,
+  payload            JSONB        NOT NULL,
+  tenant_id          VARCHAR(255),
+  idempotency_key    VARCHAR(255),
+  correlation_id     VARCHAR(255),
+  payload_purged_at  TIMESTAMPTZ,
+  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 UNIQUE INDEX IF NOT EXISTS webhook_events_idempotency_key_idx
+  ON webhook_events (COALESCE(tenant_id, ''), event_type, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
 
 ---
 

package/src/sql/migrations/v0.13.0.sql

@@ -0,0 +1,11 @@
+-- @nestarc/webhook v0.13.0 - idempotent publish and retention metadata
+-- Adds producer idempotency fields, correlation diagnostics, and payload purge metadata.
+
+ALTER TABLE webhook_events
+  ADD COLUMN IF NOT EXISTS idempotency_key VARCHAR(255),
+  ADD COLUMN IF NOT EXISTS correlation_id VARCHAR(255),
+  ADD COLUMN IF NOT EXISTS payload_purged_at TIMESTAMPTZ;
+
+CREATE UNIQUE INDEX IF NOT EXISTS webhook_events_idempotency_key_idx
+  ON webhook_events (COALESCE(tenant_id, ''), event_type, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;