@sweepconsole/node 0.0.0-stage → 0.1.0

package/dist/webhooks.js

@@ -0,0 +1,110 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { WebhookSignatureError } from "./errors.js";
+/**
+ * Webhook verification, which is where this integration goes wrong most often.
+ *
+ * Three traps, all of them silent, all of them producing the same "bad
+ * signature" symptom:
+ *
+ *   1. The HMAC is over the RAW bytes. If `express.json()` has already parsed
+ *      the body, re-serializing it gives different bytes — key order, spacing,
+ *      unicode escapes — and nothing you do downstream can recover them.
+ *   2. The header is `sha256=<hex>`, not bare hex. Comparing the two fails
+ *      forever, and the failure looks exactly like a wrong secret.
+ *   3. The comparison must be constant-time, or it leaks the expected value a
+ *      byte at a time to anyone willing to send enough requests.
+ *
+ * `verify` handles all three. Give it the raw body as a Buffer or string.
+ */
+export function verify(rawBody, signature, secret) {
+    if (!signature) {
+        throw new WebhookSignatureError("No X-Sweep-Signature header on the request.");
+    }
+    const body = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;
+    const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+    const a = Buffer.from(signature);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        throw new WebhookSignatureError("Signature did not verify. Check that you are hashing the RAW request body " +
+            "(express.raw, not express.json) and using this endpoint's signing secret.");
+    }
+}
+/** Verify, then parse. Returns the event with Dates and camelCase fields. */
+export function construct(rawBody, signature, secret, opts = {}) {
+    verify(rawBody, signature, secret);
+    const raw = JSON.parse(typeof rawBody === "string" ? rawBody : rawBody.toString("utf8"));
+    checkAge(raw.created_at, opts.toleranceSeconds);
+    return {
+        eventId: raw.event_id,
+        eventType: raw.event_type,
+        createdAt: new Date(raw.created_at),
+        merchantId: raw.merchant_id,
+        externalRef: raw.external_ref,
+        data: raw.data,
+    };
+}
+function checkAge(createdAt, toleranceSeconds) {
+    if (toleranceSeconds === undefined)
+        return;
+    const t = Date.parse(createdAt);
+    if (Number.isNaN(t)) {
+        throw new WebhookSignatureError(`Event created_at is not a date: ${JSON.stringify(createdAt)}`);
+    }
+    const ageSeconds = Math.abs(Date.now() - t) / 1000;
+    if (ageSeconds > toleranceSeconds) {
+        throw new WebhookSignatureError(`Event is ${Math.round(ageSeconds)}s old, outside the ${toleranceSeconds}s tolerance. ` +
+            `Note that deliveries retry for up to 11 hours, so a short tolerance rejects genuine retries.`);
+    }
+}
+/**
+ * An Express handler that verifies, routes, and acknowledges.
+ *
+ * Mount it with `express.raw` — the whole point is that the raw bytes survive:
+ *
+ *   app.post("/webhooks/sweep",
+ *     express.raw({ type: "application/json" }),
+ *     sweep.webhooks.express(process.env.SWEEP_WEBHOOK_SECRET!, {
+ *       "charge.succeeded": (e) => db.users.extend(e.externalRef),
+ *     }));
+ *
+ * It answers 2xx before running your handler, because Sweep gives you 10
+ * seconds and retries otherwise. A handler that throws is logged, not
+ * re-raised: the event was accepted, and failing the response would earn a
+ * retry of something you have already recorded.
+ */
+export function expressHandler(secret, handlers) {
+    return (req, res) => {
+        let event;
+        try {
+            event = construct(req.body, header(req, "x-sweep-signature"), secret, {
+                toleranceSeconds: handlers.toleranceSeconds,
+            });
+        }
+        catch (e) {
+            handlers.onError?.(e);
+            res.status(400).send("bad signature");
+            return;
+        }
+        res.status(200).send("ok");
+        // The one place the runtime key and the static types meet. Looking a
+        // handler up by event.eventType is correct at runtime, but the union of
+        // every Handler<K> has an intersection for its parameter, so TypeScript
+        // reduces it to never. Erase it here rather than in the signature, where
+        // it is what gives each handler its own payload type.
+        const handler = handlers[event.eventType];
+        if (!handler)
+            return;
+        void (async () => {
+            try {
+                await handler(event);
+            }
+            catch (e) {
+                handlers.onError?.(e);
+            }
+        })();
+    };
+}
+function header(req, name) {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@sweepconsole/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Node/TypeScript client for the Sweep Console payment rail \u2014 charge a USDC wallet from your own app",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "test": "node test/security.test.mjs"
+  },
+  "keywords": [
+    "usdc",
+    "stablecoin",
+    "subscriptions",
+    "payments",
+    "sweep-console"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/u4believe/sweep-console.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/u4believe/sweep-console#readme",
+  "bugs": {
+    "url": "https://github.com/u4believe/sweep-console/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}