mymx 0.3.5 → 0.3.7

package/dist/signing-Bqe14lp0.cjs

@@ -1,218 +0,0 @@
-"use strict";
-const require_errors = require('./errors-DOkb_I6u.cjs');
-const node_crypto = require_errors.__toESM(require("node:crypto"));
-
-//#region src/encoding.ts
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-/**
-* Convert a Buffer to string with strict UTF-8 validation.
-* Throws if the buffer contains invalid UTF-8 sequences.
-*
-* Uses TextDecoder with `fatal: true` for robust validation that catches
-* all invalid UTF-8 sequences, not just those that produce replacement characters.
-*
-* @param buffer - The buffer to convert
-* @param label - Label for error messages (e.g., "request body")
-* @returns The UTF-8 decoded string
-* @throws WebhookPayloadError if the buffer contains invalid UTF-8
-*/
-function bufferToString(buffer, label) {
-	try {
-		return utf8Decoder.decode(buffer);
-	} catch (err) {
-		throw new require_errors.WebhookPayloadError("INVALID_ENCODING", `${label} contains invalid UTF-8 bytes`, `Ensure the ${label} is valid UTF-8 encoded text. If the data is binary, it should be base64 encoded first.`, err instanceof Error ? err : void 0);
-	}
-}
-
-//#endregion
-//#region src/signing.ts
-/**
-* WeakMap cache for computed signatures.
-* Only works for Buffer bodies (strings cannot be WeakMap keys).
-* Automatically garbage collected when Buffer is no longer referenced.
-*/
-const signatureCache = new WeakMap();
-/**
-* Hash a secret for cache key comparison.
-* @internal
-*/
-function hashSecret(secret) {
-	return (0, node_crypto.createHash)("sha256").update(secret).digest("hex");
-}
-/** Header name for incoming webhook signature */
-const MYMX_SIGNATURE_HEADER = "MyMX-Signature";
-/** Header name to confirm webhook was processed (prevents retries) */
-const MYMX_CONFIRMED_HEADER = "X-MyMX-Confirmed";
-/** Default max age for webhook requests (5 minutes) */
-const DEFAULT_TOLERANCE_SECONDS = 5 * 60;
-/** Future clock skew tolerance (1 minute) */
-const FUTURE_TOLERANCE_SECONDS = 60;
-/** Valid hex pattern for signature verification */
-const HEX_PATTERN = /^[0-9a-f]+$/i;
-/**
-* Sign a webhook payload using HMAC-SHA256.
-*
-* Useful for:
-* - Internal testing and dogfooding
-* - Generating test vectors
-* - Integration tests
-*
-* @param rawBody - The raw JSON body string to sign
-* @param secret - The webhook secret key
-* @param timestamp - Unix timestamp in seconds (defaults to current time)
-*/
-function signWebhookPayload(rawBody, secret, timestamp) {
-	const ts = timestamp ?? Math.floor(Date.now() / 1e3);
-	const body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "rawBody");
-	const signedPayloadString = `${ts}.${body}`;
-	const hmac = (0, node_crypto.createHmac)("sha256", secret);
-	hmac.update(signedPayloadString);
-	const v1 = hmac.digest("hex");
-	return {
-		header: `t=${ts},v1=${v1}`,
-		timestamp: ts,
-		v1
-	};
-}
-/**
-* Parse the MyMX-Signature header into its components.
-* Tolerant of whitespace around keys/values.
-*
-* @internal
-*/
-function parseSignatureHeader(signatureHeader) {
-	if (!signatureHeader || typeof signatureHeader !== "string") return null;
-	const parts = signatureHeader.split(",");
-	let timestamp = null;
-	const signatures = [];
-	for (const part of parts) {
-		const idx = part.indexOf("=");
-		if (idx === -1) continue;
-		const key = part.slice(0, idx).trim();
-		const value = part.slice(idx + 1).trim();
-		if (!key || !value) continue;
-		if (key === "t") {
-			const parsed = Number.parseInt(value, 10);
-			if (!Number.isNaN(parsed)) timestamp = parsed;
-		} else if (key === "v1") signatures.push(value);
-	}
-	if (timestamp === null || signatures.length === 0) return null;
-	return {
-		timestamp,
-		signatures
-	};
-}
-/**
-* Check if a string is valid lowercase hex of expected length
-*/
-function isValidHex(str, expectedLength) {
-	return str.length === expectedLength && HEX_PATTERN.test(str);
-}
-/**
-* Verify a webhook signature.
-*
-* Throws `WebhookVerificationError` on failure with a specific error code.
-*
-* @example
-* ```typescript
-* import { verifyWebhookSignature, WebhookVerificationError } from 'mymx';
-*
-* try {
-*   verifyWebhookSignature({
-*     rawBody: req.body, // raw string, NOT parsed JSON
-*     signatureHeader: req.headers['mymx-signature'],
-*     secret: process.env.MYMX_WEBHOOK_SECRET,
-*   });
-*   // Signature is valid, process the webhook
-* } catch (err) {
-*   if (err instanceof WebhookVerificationError) {
-*     console.error('Invalid webhook:', err.code, err.message);
-*   }
-*   return res.status(400).send('Invalid signature');
-* }
-* ```
-*/
-function verifyWebhookSignature(opts) {
-	const { rawBody, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, nowSeconds } = opts;
-	if (!secret || typeof secret === "string" && secret.length === 0) throw new require_errors.WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
-	const parsed = parseSignatureHeader(signatureHeader);
-	if (!parsed) throw new require_errors.WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Invalid MyMX-Signature header format. Expected: t={timestamp},v1={signature}");
-	const { timestamp, signatures } = parsed;
-	const now = nowSeconds ?? Math.floor(Date.now() / 1e3);
-	const age = now - timestamp;
-	if (age > toleranceSeconds) throw new require_errors.WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", `Webhook timestamp too old (${age}s). Max age is ${toleranceSeconds}s.`);
-	if (age < -FUTURE_TOLERANCE_SECONDS) throw new require_errors.WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is too far in the future. Check server clock sync.");
-	const body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "request body");
-	let expectedHex;
-	if (Buffer.isBuffer(rawBody)) {
-		const cached = signatureCache.get(rawBody);
-		const currentSecretHash = hashSecret(secret);
-		if (cached && cached.timestamp === timestamp && cached.secretHash === currentSecretHash) expectedHex = cached.computed;
-		else {
-			const signedPayloadString = `${timestamp}.${body}`;
-			const hmac = (0, node_crypto.createHmac)("sha256", secret);
-			hmac.update(signedPayloadString);
-			expectedHex = hmac.digest("hex");
-			signatureCache.set(rawBody, {
-				secretHash: currentSecretHash,
-				timestamp,
-				computed: expectedHex
-			});
-		}
-	} else {
-		const signedPayloadString = `${timestamp}.${body}`;
-		const hmac = (0, node_crypto.createHmac)("sha256", secret);
-		hmac.update(signedPayloadString);
-		expectedHex = hmac.digest("hex");
-	}
-	for (const receivedHex of signatures) {
-		if (!isValidHex(receivedHex, 64)) continue;
-		const receivedBytes = Buffer.from(receivedHex, "hex");
-		const expectedBytes = Buffer.from(expectedHex, "hex");
-		if ((0, node_crypto.timingSafeEqual)(receivedBytes, expectedBytes)) return true;
-	}
-	const reserializationHint = detectReserializedBody(body);
-	const message = reserializationHint ? `No valid signature found. ${reserializationHint}` : "No valid signature found. Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).";
-	throw new require_errors.WebhookVerificationError("SIGNATURE_MISMATCH", message);
-}
-/**
-* Detect if a body looks like it was re-serialized by a framework.
-* Returns a helpful message if detected, null otherwise.
-* @internal
-*/
-function detectReserializedBody(body) {
-	if (/^\s*\{[\s\S]*\n\s{2,}/.test(body)) return "Request body appears re-serialized (pretty-printed). Use the raw request body before any JSON.parse() or JSON.stringify() calls.";
-	return null;
-}
-
-//#endregion
-Object.defineProperty(exports, 'MYMX_CONFIRMED_HEADER', {
-  enumerable: true,
-  get: function () {
-    return MYMX_CONFIRMED_HEADER;
-  }
-});
-Object.defineProperty(exports, 'MYMX_SIGNATURE_HEADER', {
-  enumerable: true,
-  get: function () {
-    return MYMX_SIGNATURE_HEADER;
-  }
-});
-Object.defineProperty(exports, 'bufferToString', {
-  enumerable: true,
-  get: function () {
-    return bufferToString;
-  }
-});
-Object.defineProperty(exports, 'signWebhookPayload', {
-  enumerable: true,
-  get: function () {
-    return signWebhookPayload;
-  }
-});
-Object.defineProperty(exports, 'verifyWebhookSignature', {
-  enumerable: true,
-  get: function () {
-    return verifyWebhookSignature;
-  }
-});

package/dist/signing-ChbxCBRQ.d.cts

@@ -1,84 +0,0 @@
-//#region src/signing.d.ts
-/**
- * Webhook HMAC Signing (Stripe-style format)
- *
- * Implements HMAC-SHA256 signature for webhook security with timestamp validation.
- * Prevents replay attacks by including timestamp in signature.
- *
- * Header format:
- *   MyMX-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
- *
- * Signed payload format: "{timestamp}.{raw_body}"
- *
- * This format matches Stripe's webhook signature scheme, which is widely understood
- * and easy to implement in any language with ~15 lines of code.
- */
-/** Header name for incoming webhook signature */
-declare const MYMX_SIGNATURE_HEADER = "MyMX-Signature";
-/** Header name to confirm webhook was processed (prevents retries) */
-declare const MYMX_CONFIRMED_HEADER = "X-MyMX-Confirmed";
-/**
- * Result from signing a webhook payload
- */
-interface SignResult {
-  /** Full header value ready to set on MyMX-Signature */
-  header: string;
-  /** Unix timestamp used for signing */
-  timestamp: number;
-  /** Raw hex signature (useful for debugging/tests) */
-  v1: string;
-}
-/**
- * Options for verifying a webhook signature
- */
-interface VerifyOptions {
-  /** The raw HTTP request body (must be the exact bytes, not re-serialized JSON) */
-  rawBody: string | Buffer;
-  /** The full MyMX-Signature header value */
-  signatureHeader: string;
-  /** Your webhook secret */
-  secret: string | Buffer;
-  /** Max age in seconds (default: 300) */
-  toleranceSeconds?: number;
-  /** Override current time for testing (unix seconds) */
-  nowSeconds?: number;
-}
-/**
- * Sign a webhook payload using HMAC-SHA256.
- *
- * Useful for:
- * - Internal testing and dogfooding
- * - Generating test vectors
- * - Integration tests
- *
- * @param rawBody - The raw JSON body string to sign
- * @param secret - The webhook secret key
- * @param timestamp - Unix timestamp in seconds (defaults to current time)
- */
-declare function signWebhookPayload(rawBody: string | Buffer, secret: string | Buffer, timestamp?: number): SignResult;
-/**
- * Verify a webhook signature.
- *
- * Throws `WebhookVerificationError` on failure with a specific error code.
- *
- * @example
- * ```typescript
- * import { verifyWebhookSignature, WebhookVerificationError } from 'mymx';
- *
- * try {
- *   verifyWebhookSignature({
- *     rawBody: req.body, // raw string, NOT parsed JSON
- *     signatureHeader: req.headers['mymx-signature'],
- *     secret: process.env.MYMX_WEBHOOK_SECRET,
- *   });
- *   // Signature is valid, process the webhook
- * } catch (err) {
- *   if (err instanceof WebhookVerificationError) {
- *     console.error('Invalid webhook:', err.code, err.message);
- *   }
- *   return res.status(400).send('Invalid signature');
- * }
- * ```
- */
-declare function verifyWebhookSignature(opts: VerifyOptions): true; //#endregion
-export { MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, SignResult, VerifyOptions, signWebhookPayload, verifyWebhookSignature };