hook-sign 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# hook-sign
+
+A lightweight webhook signature verification utility for Node.js — with ready-to-use Express middleware.  
+Supports Shopify webhook verification (HMAC SHA256) and can be extended for other providers.
+
+---
+
+## Features
+
+- ✅ Verify webhook signature using raw request body (Buffer)
+- ✅ Shopify webhook verification (`X-Shopify-Hmac-Sha256`)
+- ✅ Express middleware included
+- ✅ Timing-safe signature comparison (`crypto.timingSafeEqual`)
+- ✅ TypeScript support
+
+---
+
+## Installation
+
+```bash
+npm install hook-sign
+```
+
+Or with Yarn:
+
+```bash
+yarn add hook-sign
+```
+
+### ⚠️ Important Note (Must Read)
+
+Webhook providers sign the raw request body bytes, not the parsed JSON object. You must capture the raw request body in Express using:
+
+```javascript
+express.json({ verify: rawBodySaver })
+```
+
+If you skip this, signature verification will fail.
+
+---
+
+## Quick Start (Shopify + Express)
+
+### 1. Setup Express raw body capture
+
+```javascript
+import express from "express";
+import { rawBodySaver, shopifyWebhookMiddleware } from "hook-sign";
+
+const app = express();
+
+// Capture raw body (IMPORTANT)
+app.use(
+  express.json({
+    verify: rawBodySaver,
+  })
+);
+```
+
+### 2. Add Shopify webhook route
+
+```javascript
+app.post(
+  "/webhooks/shopify",
+  shopifyWebhookMiddleware({
+    secret: process.env.SHOPIFY_SECRET, // Your Shopify App API Secret Key
+  }),
+  (req, res) => {
+    // ✅ Signature verified successfully
+
+    // Your webhook payload
+    console.log("Shopify Webhook Payload:", req.body);
+
+    res.status(200).send("OK");
+  }
+);
+
+app.listen(5000, () => console.log("Server running on http://localhost:5000"));
+```
+
+### 3. Environment Variable
+
+Your secret should be stored in `.env`:
+
+```env
+SHOPIFY_SECRET=your_shopify_app_api_secret_key
+```
+
+> ✅ **Shopify secret** = Shopify App API Secret Key (not access token)
+
+---
+
+## Manual Verification (Without Express Middleware)
+
+If you don't want middleware, you can manually verify the signature:
+
+```javascript
+import { verifyShopifyWebhook } from "hook-sign";
+
+const isValid = verifyShopifyWebhook({
+  rawBody: req.rawBody,                        // Buffer
+  secret: process.env.SHOPIFY_SECRET,
+  hmacHeader: req.headers["x-shopify-hmac-sha256"],
+});
+
+if (!isValid) return res.status(401).send("Invalid signature");
+```
+
+---
+
+## API Reference
+
+### `verifyShopifyWebhook({ rawBody, secret, hmacHeader })`
+
+Returns `true` if Shopify HMAC signature is valid.
+
+**Example:**
+
+```javascript
+verifyShopifyWebhook({
+  rawBody: Buffer.from("..."),
+  secret: "my_secret",
+  hmacHeader: "base64_signature",
+});
+```
+
+### `shopifyWebhookMiddleware({ secret, headerName?, onError? })`
+
+Express middleware that automatically validates Shopify signature.
+
+**Options:**
+
+- `secret` (required): Shopify App Secret Key
+- `headerName` (optional): Custom header name (default: `x-shopify-hmac-sha256`)
+- `onError` (optional): Custom error handler
+
+### `rawBodySaver(req, res, buf)`
+
+Express verify function used in `express.json()` to store raw body buffer:
+
+```javascript
+app.use(express.json({ verify: rawBodySaver }));
+```
+
+---
+
+## Example: Custom Error Response
+
+```javascript
+app.post(
+  "/webhooks/shopify",
+  shopifyWebhookMiddleware({
+    secret: process.env.SHOPIFY_SECRET,
+    onError: (req, res) =>
+      res.status(401).json({ ok: false, message: "Invalid Shopify signature" }),
+  }),
+  (req, res) => res.status(200).send("OK")
+);
+```
+
+---
+
+## Troubleshooting
+
+### ❌ Error: `RAW_BODY_MISSING`
+
+**✅ Fix:** Ensure you added raw body capture before your routes:
+
+```javascript
+app.use(express.json({ verify: rawBodySaver }));
+```
+
+### ❌ Signature mismatch even with correct secret
+
+**Most common causes:**
+
+- Using parsed JSON instead of raw body
+- Running a second body parser that modifies the payload
+- Using wrong Shopify secret (must be App API Secret Key)
+
+---
+
+## Security Tips
+
+- Never store Shopify secret in database
+- Keep secret only in `.env` / server environment variables
+- Always respond quickly to webhooks (Shopify expects 200 OK)
+
+---
+
+## License
+
+MIT

package/dist/core/hmac.d.ts

@@ -0,0 +1,3 @@
+export type HmacEncoding = "hex" | "base64";
+export declare function computeHmac(rawBody: Buffer, secret: string, algorithm?: string, encoding?: HmacEncoding): string;
+export declare function timingSafeEqual(a: string, b: string): boolean;

package/dist/core/hmac.js

@@ -0,0 +1,48 @@
+"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.computeHmac = computeHmac;
+exports.timingSafeEqual = timingSafeEqual;
+const crypto = __importStar(require("crypto"));
+function computeHmac(rawBody, secret, algorithm = "sha256", encoding = "base64") {
+    return crypto.createHmac(algorithm, secret).update(rawBody).digest(encoding);
+}
+function timingSafeEqual(a, b) {
+    const aBuf = Buffer.from(a);
+    const bBuf = Buffer.from(b);
+    if (aBuf.length !== bBuf.length)
+        return false;
+    return crypto.timingSafeEqual(aBuf, bBuf);
+}

package/dist/express/rawBody.d.ts

@@ -0,0 +1,2 @@
+import type { Request } from "express";
+export declare function rawBodySaver(req: Request, _res: any, buf: Buffer): void;

package/dist/express/rawBody.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawBodySaver = rawBodySaver;
+function rawBodySaver(req, _res, buf) {
+    // attach raw buffer to req for later verification
+    req.rawBody = buf;
+}

package/dist/express/shopifyMiddleware.d.ts

@@ -0,0 +1,7 @@
+import type { Request, Response, NextFunction } from "express";
+export type ShopifyMiddlewareOptions = {
+    secret: string;
+    headerName?: string;
+    onError?: (req: Request, res: Response) => void;
+};
+export declare function shopifyWebhookMiddleware(options: ShopifyMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;

package/dist/express/shopifyMiddleware.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shopifyWebhookMiddleware = shopifyWebhookMiddleware;
+const shopify_1 = require("../providers/shopify");
+function shopifyWebhookMiddleware(options) {
+    const headerName = options.headerName ?? "x-shopify-hmac-sha256";
+    return (req, res, next) => {
+        const rawBody = req.rawBody;
+        if (!rawBody) {
+            // If raw body missing, dev configured body parser wrong
+            return res.status(400).json({
+                ok: false,
+                error: "RAW_BODY_MISSING",
+                message: "Raw body is missing. Configure express.json({ verify }) using rawBodySaver.",
+            });
+        }
+        const hmacHeader = req.headers[headerName];
+        const ok = (0, shopify_1.verifyShopifyWebhook)({
+            rawBody,
+            secret: options.secret,
+            hmacHeader,
+        });
+        if (!ok) {
+            if (options.onError)
+                return options.onError(req, res);
+            return res.status(401).json({ ok: false, error: "INVALID_SIGNATURE" });
+        }
+        return next();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { computeHmac, timingSafeEqual } from "./core/hmac";
+export { verifyShopifyWebhook } from "./providers/shopify";
+export { rawBodySaver } from "./express/rawBody";
+export { shopifyWebhookMiddleware } from "./express/shopifyMiddleware";

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shopifyWebhookMiddleware = exports.rawBodySaver = exports.verifyShopifyWebhook = exports.timingSafeEqual = exports.computeHmac = void 0;
+var hmac_1 = require("./core/hmac");
+Object.defineProperty(exports, "computeHmac", { enumerable: true, get: function () { return hmac_1.computeHmac; } });
+Object.defineProperty(exports, "timingSafeEqual", { enumerable: true, get: function () { return hmac_1.timingSafeEqual; } });
+var shopify_1 = require("./providers/shopify");
+Object.defineProperty(exports, "verifyShopifyWebhook", { enumerable: true, get: function () { return shopify_1.verifyShopifyWebhook; } });
+var rawBody_1 = require("./express/rawBody");
+Object.defineProperty(exports, "rawBodySaver", { enumerable: true, get: function () { return rawBody_1.rawBodySaver; } });
+var shopifyMiddleware_1 = require("./express/shopifyMiddleware");
+Object.defineProperty(exports, "shopifyWebhookMiddleware", { enumerable: true, get: function () { return shopifyMiddleware_1.shopifyWebhookMiddleware; } });

package/dist/providers/shopify.d.ts

@@ -0,0 +1,6 @@
+export type ShopifyVerifyParams = {
+    rawBody: Buffer;
+    secret: string;
+    hmacHeader: string | undefined;
+};
+export declare function verifyShopifyWebhook({ rawBody, secret, hmacHeader, }: ShopifyVerifyParams): boolean;

package/dist/providers/shopify.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyShopifyWebhook = verifyShopifyWebhook;
+const hmac_1 = require("../core/hmac");
+function verifyShopifyWebhook({ rawBody, secret, hmacHeader, }) {
+    if (!hmacHeader)
+        return false;
+    const expected = (0, hmac_1.computeHmac)(rawBody, secret, "sha256", "base64");
+    return (0, hmac_1.timingSafeEqual)(expected, hmacHeader.trim());
+}

package/dist/src/core/hmac.d.ts

@@ -0,0 +1,3 @@
+export type HmacEncoding = "hex" | "base64";
+export declare function computeHmac(rawBody: Buffer, secret: string, algorithm?: string, encoding?: HmacEncoding): string;
+export declare function timingSafeEqual(a: string, b: string): boolean;

package/dist/src/core/hmac.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHmac = computeHmac;
+exports.timingSafeEqual = timingSafeEqual;
+const crypto = require("crypto");
+function computeHmac(rawBody, secret, algorithm = "sha256", encoding = "base64") {
+    return crypto.createHmac(algorithm, secret).update(rawBody).digest(encoding);
+}
+function timingSafeEqual(a, b) {
+    const aBuf = Buffer.from(a);
+    const bBuf = Buffer.from(b);
+    if (aBuf.length !== bBuf.length)
+        return false;
+    return crypto.timingSafeEqual(aBuf, bBuf);
+}

package/dist/src/express/rawBody.d.ts

@@ -0,0 +1,2 @@
+import type { Request } from "express";
+export declare function rawBodySaver(req: Request, _res: any, buf: Buffer): void;

package/dist/src/express/rawBody.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawBodySaver = rawBodySaver;
+function rawBodySaver(req, _res, buf) {
+    // attach raw buffer to req for later verification
+    req.rawBody = buf;
+}

package/dist/src/express/shopifyMiddleware.d.ts

@@ -0,0 +1,7 @@
+import type { Request, Response, NextFunction } from "express";
+export type ShopifyMiddlewareOptions = {
+    secret: string;
+    headerName?: string;
+    onError?: (req: Request, res: Response) => void;
+};
+export declare function shopifyWebhookMiddleware(options: ShopifyMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;

package/dist/src/express/shopifyMiddleware.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shopifyWebhookMiddleware = shopifyWebhookMiddleware;
+const shopify_1 = require("../providers/shopify");
+function shopifyWebhookMiddleware(options) {
+    const headerName = options.headerName ?? "x-shopify-hmac-sha256";
+    return (req, res, next) => {
+        const rawBody = req.rawBody;
+        if (!rawBody) {
+            // If raw body missing, dev configured body parser wrong
+            return res.status(400).json({
+                ok: false,
+                error: "RAW_BODY_MISSING",
+                message: "Raw body is missing. Configure express.json({ verify }) using rawBodySaver.",
+            });
+        }
+        const hmacHeader = req.headers[headerName];
+        const ok = (0, shopify_1.verifyShopifyWebhook)({
+            rawBody,
+            secret: options.secret,
+            hmacHeader,
+        });
+        if (!ok) {
+            if (options.onError)
+                return options.onError(req, res);
+            return res.status(401).json({ ok: false, error: "INVALID_SIGNATURE" });
+        }
+        return next();
+    };
+}

package/dist/src/providers/shopify.d.ts

@@ -0,0 +1,6 @@
+export type ShopifyVerifyParams = {
+    rawBody: Buffer;
+    secret: string;
+    hmacHeader: string | undefined;
+};
+export declare function verifyShopifyWebhook({ rawBody, secret, hmacHeader, }: ShopifyVerifyParams): boolean;

package/dist/src/providers/shopify.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyShopifyWebhook = verifyShopifyWebhook;
+const hmac_1 = require("../core/hmac");
+function verifyShopifyWebhook({ rawBody, secret, hmacHeader, }) {
+    if (!hmacHeader)
+        return false;
+    const expected = (0, hmac_1.computeHmac)(rawBody, secret, "sha256", "base64");
+    return (0, hmac_1.timingSafeEqual)(expected, hmacHeader.trim());
+}

package/dist/test/shopify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/shopify.test.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const supertest_1 = require("supertest");
+const express_1 = require("express");
+const crypto_1 = require("crypto");
+const rawBody_1 = require("../src/express/rawBody");
+const shopifyMiddleware_1 = require("../src/express/shopifyMiddleware");
+(0, vitest_1.describe)("Shopify Express middleware", () => {
+    (0, vitest_1.it)("should allow request with valid signature", async () => {
+        const secret = "my_secret";
+        const app = (0, express_1.default)();
+        app.use(express_1.default.json({ verify: rawBody_1.rawBodySaver }));
+        app.post("/webhooks/shopify", (0, shopifyMiddleware_1.shopifyWebhookMiddleware)({ secret }), (req, res) => res.status(200).send("ok"));
+        const payload = { order_id: 999 };
+        // IMPORTANT: sign the exact JSON string
+        const raw = Buffer.from(JSON.stringify(payload), "utf8");
+        const hmac = crypto_1.default
+            .createHmac("sha256", secret)
+            .update(raw)
+            .digest("base64");
+        const res = await (0, supertest_1.default)(app)
+            .post("/webhooks/shopify")
+            .set("X-Shopify-Hmac-Sha256", hmac)
+            .send(payload);
+        (0, vitest_1.expect)(res.statusCode).toBe(200);
+        (0, vitest_1.expect)(res.text).toBe("ok");
+    });
+    (0, vitest_1.it)("should reject request with invalid signature", async () => {
+        const secret = "my_secret";
+        const app = (0, express_1.default)();
+        app.use(express_1.default.json({ verify: rawBody_1.rawBodySaver }));
+        app.post("/webhooks/shopify", (0, shopifyMiddleware_1.shopifyWebhookMiddleware)({ secret }), (req, res) => res.status(200).send("ok"));
+        const res = await (0, supertest_1.default)(app)
+            .post("/webhooks/shopify")
+            .set("X-Shopify-Hmac-Sha256", "INVALID")
+            .send({ order_id: 999 });
+        (0, vitest_1.expect)(res.statusCode).toBe(401);
+    });
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "hook-sign",
+  "version": "1.0.0",
+  "description": "Webhook signature verification utilities + Express middleware",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest"
+  },
+  "keywords": [
+    "webhook",
+    "shopify",
+    "hmac",
+    "signature",
+    "express"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rakib-dev1/webhook-sign"
+  },
+  "peerDependencies": {
+    "express": ">=4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/node": "^20.19.30",
+    "@types/supertest": "^2.0.0",
+    "express": "^4.22.1",
+    "supertest": "^6.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^1.0.0"
+  }
+}