@tanqory/plugin-sdk 0.2.0

package/dist/webhooks.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const node_crypto_1 = require("node:crypto");
+/**
+ * How long a signed payload stays acceptable.
+ *
+ * Without this, a signature is valid forever: anyone who captures one delivery
+ * can replay it at any point in the future and it still verifies. Five minutes
+ * is enough slack for clock drift and a slow queue, and short enough that a
+ * captured request is not a permanent liability.
+ */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify that a webhook really came from Tanqory and has not been replayed.
+ *
+ * Pass the **raw** request body — the exact bytes received. Re-serialising a
+ * parsed object changes key order and whitespace, and the signature will not
+ * match. In frameworks that parse JSON for you, read the raw body first.
+ *
+ * ```ts
+ * const raw = await request.text()
+ * if (!verifyWebhookSignature(raw, request.headers.get('x-tanqory-signature'), secret)) {
+ *   return new Response('bad signature', { status: 401 })
+ * }
+ * ```
+ */
+function verifyWebhookSignature(rawBody, signatureHeader, secret, options = {}) {
+    if (!signatureHeader || !secret)
+        return false;
+    const parsed = parseSignatureHeader(signatureHeader);
+    if (!parsed)
+        return false;
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = Math.floor((options.now?.() ?? Date.now()) / 1000);
+    // Rejected in both directions. A timestamp far in the future is not a clock
+    // problem to be generous about — it is someone choosing the timestamp.
+    if (Math.abs(now - parsed.timestamp) > tolerance)
+        return false;
+    const expected = (0, node_crypto_1.createHmac)('sha256', secret)
+        .update(`${parsed.timestamp}.${rawBody}`)
+        .digest('hex');
+    return safeEqual(expected, parsed.signature);
+}
+/** `t=1699999999,v1=abc…` */
+function parseSignatureHeader(header) {
+    let timestamp = null;
+    let signature = null;
+    for (const part of header.split(',')) {
+        const [key, value] = part.trim().split('=');
+        if (key === 't') {
+            const parsedTimestamp = Number.parseInt(value, 10);
+            if (Number.isFinite(parsedTimestamp))
+                timestamp = parsedTimestamp;
+        }
+        else if (key === 'v1') {
+            signature = value;
+        }
+    }
+    return timestamp !== null && signature ? { timestamp, signature } : null;
+}
+/**
+ * `===` on a signature leaks, through timing, how many leading characters an
+ * attacker guessed right — which is enough to reconstruct it one character at
+ * a time.
+ */
+function safeEqual(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(left, right);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":";;AAiCA,wDAsBC;AAvDD,6CAAyD;AAEzD;;;;;;;GAOG;AACH,MAAM,yBAAyB,GAAG,GAAG,CAAA;AASrC;;;;;;;;;;;;;GAaG;AACH,SAAgB,sBAAsB,CACpC,OAAe,EACf,eAA0C,EAC1C,MAAc,EACd,UAAyB,EAAE;IAE3B,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAE7C,MAAM,MAAM,GAAG,oBAAoB,CAAC,eAAe,CAAC,CAAA;IACpD,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAEzB,MAAM,SAAS,GAAG,OAAO,CAAC,gBAAgB,IAAI,yBAAyB,CAAA;IACvE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;IAC9D,4EAA4E;IAC5E,uEAAuE;IACvE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,SAAS;QAAE,OAAO,KAAK,CAAA;IAE9D,MAAM,QAAQ,GAAG,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC;SAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,IAAI,OAAO,EAAE,CAAC;SACxC,MAAM,CAAC,KAAK,CAAC,CAAA;IAEhB,OAAO,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAAA;AAC9C,CAAC;AAED,6BAA6B;AAC7B,SAAS,oBAAoB,CAAC,MAAc;IAC1C,IAAI,SAAS,GAAkB,IAAI,CAAA;IACnC,IAAI,SAAS,GAAkB,IAAI,CAAA;IAEnC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC3C,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;YAChB,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;YAClD,IAAI,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC;gBAAE,SAAS,GAAG,eAAe,CAAA;QACnE,CAAC;aAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACxB,SAAS,GAAG,KAAK,CAAA;QACnB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1E,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACnC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC9C,OAAO,IAAA,6BAAe,EAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AACrC,CAAC"}

package/dist/webhooks.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhooks.spec.d.ts.map

package/dist/webhooks.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.spec.d.ts","sourceRoot":"","sources":["../src/webhooks.spec.ts"],"names":[],"mappings":""}

package/dist/webhooks.spec.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const vitest_1 = require("vitest");
+const webhooks_1 = require("./webhooks");
+/**
+ * This function is the only thing standing between an app's webhook handler and
+ * anyone on the internet who knows its URL. Every case below is a way that
+ * boundary gets crossed by an implementation that "looks right".
+ */
+const SECRET = 'whsec_test';
+const BODY = '{"event":"orders/create","data":{"id":"ord_1"}}';
+function sign(body, timestamp, secret = SECRET) {
+    const signature = (0, node_crypto_1.createHmac)('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+    return `t=${timestamp},v1=${signature}`;
+}
+const NOW = 1_700_000_000_000;
+const now = () => NOW;
+const nowSeconds = Math.floor(NOW / 1000);
+(0, vitest_1.describe)('verifyWebhookSignature', () => {
+    (0, vitest_1.it)('accepts a correctly signed, fresh payload', () => {
+        (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, sign(BODY, nowSeconds), SECRET, { now })).toBe(true);
+    });
+    (0, vitest_1.it)('rejects a body that changed after signing', () => {
+        const header = sign(BODY, nowSeconds);
+        const tampered = BODY.replace('ord_1', 'ord_999');
+        (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(tampered, header, SECRET, { now })).toBe(false);
+    });
+    (0, vitest_1.it)('rejects a signature made with a different secret', () => {
+        const header = sign(BODY, nowSeconds, 'whsec_someone_elses');
+        (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, header, SECRET, { now })).toBe(false);
+    });
+    (0, vitest_1.describe)('replay', () => {
+        (0, vitest_1.it)('rejects a payload older than the tolerance', () => {
+            // Without this, a captured delivery verifies forever.
+            const header = sign(BODY, nowSeconds - 301);
+            (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, header, SECRET, { now })).toBe(false);
+        });
+        (0, vitest_1.it)('accepts one just inside the tolerance', () => {
+            const header = sign(BODY, nowSeconds - 299);
+            (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, header, SECRET, { now })).toBe(true);
+        });
+        (0, vitest_1.it)('rejects a timestamp in the future', () => {
+            // Not a clock problem to be generous about — a future timestamp means
+            // someone chose it.
+            const header = sign(BODY, nowSeconds + 301);
+            (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, header, SECRET, { now })).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('malformed input is rejected, never thrown on', () => {
+        // A handler that 500s on a malformed header tells an attacker their probe
+        // reached real code. Every one of these must simply be false.
+        const bad = [
+            ['missing header', null],
+            ['empty header', ''],
+            ['no timestamp', 'v1=abc'],
+            ['no signature', `t=${nowSeconds}`],
+            ['non-numeric timestamp', 't=not-a-number,v1=abc'],
+            ['garbage', 'nonsense'],
+        ];
+        vitest_1.it.each(bad)('rejects %s', (_label, header) => {
+            (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, header, SECRET, { now })).toBe(false);
+        });
+        (0, vitest_1.it)('rejects when no secret is configured', () => {
+            (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, sign(BODY, nowSeconds), '', { now })).toBe(false);
+        });
+    });
+    (0, vitest_1.it)('rejects a signature of the right shape but the wrong length', () => {
+        // Guards the constant-time compare: a length mismatch must return false,
+        // not throw, or the throw itself becomes the timing signal.
+        (0, vitest_1.expect)((0, webhooks_1.verifyWebhookSignature)(BODY, `t=${nowSeconds},v1=abc`, SECRET, { now })).toBe(false);
+    });
+});
+//# sourceMappingURL=webhooks.spec.js.map

package/dist/webhooks.spec.js.map

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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tanqory/plugin-sdk",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tanqory/tanqory-platform-packages.git",
+    "directory": "packages/tools/plugin-sdk"
+  },
+  "description": "Build a Tanqory marketplace app. Server-side token exchange and REST client, webhook signature verification, a manifest schema, and a React hook that boots an embedded app inside the Tanqory dashboard.",
+  "keywords": [
+    "tanqory",
+    "ecommerce",
+    "app",
+    "plugin",
+    "sdk"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "license": "MIT",
+  "author": "Tanqory",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tanqory/app-bridge": "^0.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false
+}