@dregs/sdk 0.1.0

package/dist/webhooks.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+var chunkK63AUEQR_cjs = require('./chunk-K63AUEQR.cjs');
+
+
+
+Object.defineProperty(exports, "DEFAULT_TOLERANCE_SECONDS", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DEFAULT_TOLERANCE_SECONDS; }
+});
+Object.defineProperty(exports, "EVENT_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.EVENT_HEADER; }
+});
+Object.defineProperty(exports, "SIGNATURE_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.SIGNATURE_HEADER; }
+});
+Object.defineProperty(exports, "TIMESTAMP_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.TIMESTAMP_HEADER; }
+});
+Object.defineProperty(exports, "computeWebhookSignature", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.computeWebhookSignature; }
+});
+Object.defineProperty(exports, "verifyWebhook", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.verifyWebhook; }
+});
+Object.defineProperty(exports, "verifyWebhookSignature", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.verifyWebhookSignature; }
+});
+//# sourceMappingURL=webhooks.cjs.map
+//# sourceMappingURL=webhooks.cjs.map

package/dist/webhooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"webhooks.cjs"}

package/dist/webhooks.d.cts

@@ -0,0 +1,83 @@
+/**
+ * Verifying webhooks Dregs sends you.
+ *
+ * Dregs signs every webhook with the channel's signing secret: `X-Dregs-Signature` is the
+ * hex-encoded HMAC-SHA256 of the raw request body. Verify it before you act on the payload, and
+ * verify it against the bytes you received rather than a re-serialized object, because
+ * re-serializing changes key order and whitespace and will not match.
+ *
+ * ```ts
+ * import { verifyWebhook } from '@dregs/sdk/webhooks';
+ *
+ * app.post('/webhooks/dregs', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const event = verifyWebhook({
+ *     payload: req.body, // the Buffer, not req.body parsed as JSON
+ *     signature: req.header('X-Dregs-Signature') ?? '',
+ *     secret: process.env.DREGS_WEBHOOK_SECRET!,
+ *   });
+ *
+ *   handle(event);
+ * });
+ * ```
+ *
+ * The signing secret is shown once, when you create the webhook channel. It is not your API
+ * secret key: one authenticates you to Dregs, the other proves a payload came from Dregs.
+ *
+ * @module
+ */
+/** The header carrying the hex-encoded HMAC-SHA256 of the raw body. */
+declare const SIGNATURE_HEADER = "X-Dregs-Signature";
+/** The header carrying the delivery's timestamp. */
+declare const TIMESTAMP_HEADER = "X-Dregs-Timestamp";
+/** The header naming the event type. */
+declare const EVENT_HEADER = "X-Dregs-Event";
+/** How far out of date a webhook's timestamp may be before {@link verifyWebhook} rejects it. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * A raw webhook body.
+ *
+ * A `Buffer` or `Uint8Array` is what you want: the bytes exactly as received. A string is
+ * accepted for frameworks that hand you the raw text, and is hashed as UTF-8.
+ */
+type WebhookPayload = string | Uint8Array;
+/** A verified webhook body: `event`, `timestamp`, and the payload for that event. */
+type WebhookEvent = Record<string, unknown>;
+/** The arguments to {@link verifyWebhook}. */
+interface VerifyWebhookOptions {
+    /** The raw request body, exactly as received. Not a parsed object. */
+    payload: WebhookPayload;
+    /** The `X-Dregs-Signature` header. */
+    signature: string;
+    /** The channel's signing secret. */
+    secret: string;
+    /**
+     * How many seconds out of date the payload's own `timestamp` may be before it is treated as a
+     * replay. Defaults to 300. Pass `null` to skip the check, which you should only do if you are
+     * deduplicating on the event id yourself.
+     *
+     * The timestamp is inside the signed body, so an attacker cannot alter it without breaking
+     * the signature.
+     */
+    tolerance?: number | null;
+    /** The current time. For tests. */
+    now?: Date;
+}
+/** Returns the hex-encoded HMAC-SHA256 of `payload` under `secret`. */
+declare function computeWebhookSignature(payload: WebhookPayload, secret: string): string;
+/**
+ * Returns whether `signature` matches `payload`.
+ *
+ * The comparison is constant-time. Prefer {@link verifyWebhook}, which also rejects replays and
+ * hands back the parsed event; reach for this one only when you need the boolean.
+ */
+declare function verifyWebhookSignature(payload: WebhookPayload, signature: string, secret: string): boolean;
+/**
+ * Verifies a webhook and returns its parsed body.
+ *
+ * @returns The parsed webhook body: `event`, `timestamp`, and the payload for that event.
+ * @throws {WebhookVerificationError} The signature did not match, the body was not a JSON
+ *   object, or the payload is older than the tolerance. Answer 400 and do not act on it.
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): WebhookEvent;
+
+export { DEFAULT_TOLERANCE_SECONDS, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, type VerifyWebhookOptions, type WebhookEvent, type WebhookPayload, computeWebhookSignature, verifyWebhook, verifyWebhookSignature };

package/dist/webhooks.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Verifying webhooks Dregs sends you.
+ *
+ * Dregs signs every webhook with the channel's signing secret: `X-Dregs-Signature` is the
+ * hex-encoded HMAC-SHA256 of the raw request body. Verify it before you act on the payload, and
+ * verify it against the bytes you received rather than a re-serialized object, because
+ * re-serializing changes key order and whitespace and will not match.
+ *
+ * ```ts
+ * import { verifyWebhook } from '@dregs/sdk/webhooks';
+ *
+ * app.post('/webhooks/dregs', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const event = verifyWebhook({
+ *     payload: req.body, // the Buffer, not req.body parsed as JSON
+ *     signature: req.header('X-Dregs-Signature') ?? '',
+ *     secret: process.env.DREGS_WEBHOOK_SECRET!,
+ *   });
+ *
+ *   handle(event);
+ * });
+ * ```
+ *
+ * The signing secret is shown once, when you create the webhook channel. It is not your API
+ * secret key: one authenticates you to Dregs, the other proves a payload came from Dregs.
+ *
+ * @module
+ */
+/** The header carrying the hex-encoded HMAC-SHA256 of the raw body. */
+declare const SIGNATURE_HEADER = "X-Dregs-Signature";
+/** The header carrying the delivery's timestamp. */
+declare const TIMESTAMP_HEADER = "X-Dregs-Timestamp";
+/** The header naming the event type. */
+declare const EVENT_HEADER = "X-Dregs-Event";
+/** How far out of date a webhook's timestamp may be before {@link verifyWebhook} rejects it. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * A raw webhook body.
+ *
+ * A `Buffer` or `Uint8Array` is what you want: the bytes exactly as received. A string is
+ * accepted for frameworks that hand you the raw text, and is hashed as UTF-8.
+ */
+type WebhookPayload = string | Uint8Array;
+/** A verified webhook body: `event`, `timestamp`, and the payload for that event. */
+type WebhookEvent = Record<string, unknown>;
+/** The arguments to {@link verifyWebhook}. */
+interface VerifyWebhookOptions {
+    /** The raw request body, exactly as received. Not a parsed object. */
+    payload: WebhookPayload;
+    /** The `X-Dregs-Signature` header. */
+    signature: string;
+    /** The channel's signing secret. */
+    secret: string;
+    /**
+     * How many seconds out of date the payload's own `timestamp` may be before it is treated as a
+     * replay. Defaults to 300. Pass `null` to skip the check, which you should only do if you are
+     * deduplicating on the event id yourself.
+     *
+     * The timestamp is inside the signed body, so an attacker cannot alter it without breaking
+     * the signature.
+     */
+    tolerance?: number | null;
+    /** The current time. For tests. */
+    now?: Date;
+}
+/** Returns the hex-encoded HMAC-SHA256 of `payload` under `secret`. */
+declare function computeWebhookSignature(payload: WebhookPayload, secret: string): string;
+/**
+ * Returns whether `signature` matches `payload`.
+ *
+ * The comparison is constant-time. Prefer {@link verifyWebhook}, which also rejects replays and
+ * hands back the parsed event; reach for this one only when you need the boolean.
+ */
+declare function verifyWebhookSignature(payload: WebhookPayload, signature: string, secret: string): boolean;
+/**
+ * Verifies a webhook and returns its parsed body.
+ *
+ * @returns The parsed webhook body: `event`, `timestamp`, and the payload for that event.
+ * @throws {WebhookVerificationError} The signature did not match, the body was not a JSON
+ *   object, or the payload is older than the tolerance. Answer 400 and do not act on it.
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): WebhookEvent;
+
+export { DEFAULT_TOLERANCE_SECONDS, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, type VerifyWebhookOptions, type WebhookEvent, type WebhookPayload, computeWebhookSignature, verifyWebhook, verifyWebhookSignature };

package/dist/webhooks.js

@@ -0,0 +1,3 @@
+export { DEFAULT_TOLERANCE_SECONDS, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, computeWebhookSignature, verifyWebhook, verifyWebhookSignature } from './chunk-AIUWT3Z7.js';
+//# sourceMappingURL=webhooks.js.map
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"webhooks.js"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@dregs/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Dregs, the fraud and abuse scoring service.",
+  "keywords": [
+    "dregs",
+    "fraud",
+    "abuse",
+    "fraud-detection",
+    "bot-detection",
+    "risk-scoring"
+  ],
+  "homepage": "https://dregs.com",
+  "bugs": "https://github.com/dregs-sdk/dregs-sdk-typescript/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dregs-sdk/dregs-sdk-typescript.git"
+  },
+  "license": "MIT",
+  "author": "Dregs <support@dregs.com>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/webhooks.d.ts",
+        "default": "./dist/webhooks.js"
+      },
+      "require": {
+        "types": "./dist/webhooks.d.cts",
+        "default": "./dist/webhooks.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify:dist": "node scripts/smoke-dist.mjs",
+    "verify:package": "publint && attw --pack . --profile node16"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^9.36.0",
+    "@types/node": "^22.20.4",
+    "eslint": "^9.36.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.6.2",
+    "publint": "^0.3.14",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.44.1",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}