@stormwateriq/api-client 0.0.1

package/dist/webhooks.js

@@ -0,0 +1,65 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Reference webhook-signature verifier for the StormwaterIQ external API
+ * (docs/external-api.md §06). Byte-identical to the server's `verifyWebhook`
+ * (packages/api) and the Python SDK — all three are pinned to the shared vectors in
+ * fixtures/webhook-signature-vectors.json. Tenants call this rather than re-rolling
+ * HMAC code.
+ *
+ * Header form: `t=<unix_ts>,v1=<hmac_sha256_hex>` over the message `"<t>.<rawBody>"`.
+ * The timestamp is inside the signed material, so a tampered timestamp invalidates the
+ * signature — that is what lets us reject replays by age without trusting the clock.
+ */
+/** Deliveries older than this (seconds) are rejected as replays (§06). */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(header) {
+    const parts = new Map();
+    for (const segment of header.split(",")) {
+        const idx = segment.indexOf("=");
+        if (idx === -1)
+            return null;
+        parts.set(segment.slice(0, idx).trim(), segment.slice(idx + 1).trim());
+    }
+    const tRaw = parts.get("t");
+    const v1 = parts.get("v1");
+    if (!tRaw || !v1)
+        return null;
+    if (!/^\d+$/.test(tRaw))
+        return null;
+    if (!/^[0-9a-f]+$/.test(v1))
+        return null;
+    return { t: Number(tRaw), v1 };
+}
+function timingSafeHexEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Verify a webhook delivery. Returns `true` only when the signature matches the
+ * payload under `secret` AND the signed timestamp is within `toleranceSec` of now.
+ * Tampered bodies, wrong secrets, malformed headers, and stale/replayed deliveries
+ * all return `false`.
+ *
+ * @param payload   the raw request body string exactly as received
+ * @param signature the `X-StormwaterIQ-Signature` header value
+ * @param secret    the endpoint's signing secret
+ */
+export function verify(payload, signature, secret, opts) {
+    const parsed = parseSignatureHeader(signature);
+    if (!parsed)
+        return false;
+    const tolerance = opts?.toleranceSec ?? SIGNATURE_TOLERANCE_SECONDS;
+    const now = opts?.nowSec ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - parsed.t) > tolerance)
+        return false;
+    const expected = createHmac("sha256", secret)
+        .update(`${parsed.t}.${payload}`)
+        .digest("hex");
+    return timingSafeHexEqual(expected, parsed.v1);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@stormwateriq/api-client",
+  "version": "0.0.1",
+  "description": "Official TypeScript client for the StormwaterIQ external API: generated typed SDK over the gateway's OpenAPI contract, plus the reference webhook-signature verifier and automatic retries.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "openapi-ts": "openapi-ts",
+    "test": "vitest run --config vitest.config.ts",
+    "release": "release-it"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "0.98.1",
+    "@release-it/conventional-changelog": "^11.0.1",
+    "@stormwateriq/typescript-config": "*",
+    "@types/node": "^25.2.2",
+    "release-it": "^20.2.0",
+    "typescript": "~5.9.2",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hey-api/client-fetch": "0.13.1"
+  }
+}