@traceten/sdk-node 1.0.0

package/dist/webhook.js

@@ -0,0 +1,141 @@
+/**
+ * Verification for Traceten's client-facing OUTBOUND webhooks.
+ *
+ * Traceten signs every webhook delivery so your endpoint can prove the request
+ * really came from us and was not tampered with or replayed. {@link verifyWebhook}
+ * does the three things a hand-rolled verifier most often gets wrong:
+ *
+ *   1. Recomputes `hmac-sha256(secret, `${timestamp}.${rawBody}`)` over the RAW
+ *      body bytes — never a re-serialized object.
+ *   2. Compares in **constant time** (`crypto.timingSafeEqual`), length-guarded
+ *      so a mismatched-length signature can never throw.
+ *   3. Rejects deliveries whose timestamp is outside the replay window.
+ *
+ * On success it returns the parsed, typed {@link WebhookEvent}. On ANY failure
+ * it throws {@link WebhookVerificationError} — and it never parses the body
+ * before the signature checks out.
+ *
+ * The constants below are vendored (not imported from `@traceten/shared`) so
+ * this SDK stays a self-contained, publishable package. They mirror the frozen
+ * signing spec exactly; the known-answer vector in the test suite proves this
+ * implementation is byte-identical to Traceten's signer.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook, WebhookVerificationError } from "@traceten/sdk-node";
+ *
+ * // Express — note `express.raw`, so `req.body` is the exact bytes we signed.
+ * app.post("/traceten-webhooks", express.raw({ type: "application/json" }), (req, res) => {
+ *   try {
+ *     const event = verifyWebhook(
+ *       req.body, // Buffer or string of the RAW body
+ *       req.header("X-Traceten-Signature") ?? "",
+ *       req.header("X-Traceten-Signature-Timestamp") ?? "",
+ *       process.env.TRACETEN_WEBHOOK_SECRET!,
+ *     );
+ *     if (event.type === "ai_session.classified") {
+ *       // event.data is fully typed here
+ *     }
+ *     res.status(200).end(); // ack fast; do heavy work on a queue
+ *   } catch (err) {
+ *     if (err instanceof WebhookVerificationError) res.status(401).end();
+ *     else res.status(400).end();
+ *   }
+ * });
+ * ```
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Header carrying the hex HMAC-SHA256 signature. */
+export const WEBHOOK_SIGNATURE_HEADER = "X-Traceten-Signature";
+/** Header carrying the unix-SECONDS timestamp that was signed over. */
+export const WEBHOOK_TIMESTAMP_HEADER = "X-Traceten-Signature-Timestamp";
+/** Default replay tolerance for verification, in seconds (5 minutes). */
+export const WEBHOOK_REPLAY_TOLERANCE_SECONDS = 300;
+/**
+ * The exhaustive allow-list of outbound webhook event types (frozen contract).
+ * Adding a type is additive-only.
+ */
+export const WEBHOOK_EVENT_TYPES = [
+    "ai_session.classified",
+    "conversion.attributed",
+    "webhook.ping",
+];
+/** Attribution model names carried in `conversion.attributed`. */
+export const ATTRIBUTION_MODELS = ["first_touch", "last_touch", "linear", "time_decay"];
+/**
+ * Thrown by {@link verifyWebhook} when a delivery cannot be trusted: a bad or
+ * missing signature, a stale/invalid timestamp, or a body that is not the JSON
+ * envelope we signed. Never thrown for a valid, fresh delivery.
+ */
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+/**
+ * Verify an outbound Traceten webhook and return its typed envelope.
+ *
+ * @param rawBody          The EXACT raw request body — a `Buffer` (preferred)
+ *                         or the raw UTF-8 string. Never a re-serialized object;
+ *                         re-serializing changes the bytes and the signature
+ *                         will not match.
+ * @param signatureHeader  The `X-Traceten-Signature` header value.
+ * @param timestampHeader  The `X-Traceten-Signature-Timestamp` header value
+ *                         (unix seconds).
+ * @param secret           The endpoint's signing secret (raw UTF-8 string).
+ * @param options          {@link VerifyWebhookOptions}.
+ * @returns The verified, parsed {@link WebhookEvent}.
+ * @throws {WebhookVerificationError} on any verification or parse failure.
+ * @throws {TypeError} if `secret` is empty or blank — a misconfiguration (e.g.
+ *   an unset `TRACETEN_WEBHOOK_SECRET`), surfaced loudly rather than silently
+ *   weakening verification. This is a config bug, not a bad delivery, so it is
+ *   deliberately NOT a {@link WebhookVerificationError}.
+ */
+export function verifyWebhook(rawBody, signatureHeader, timestampHeader, secret, options = {}) {
+    const { toleranceSeconds = WEBHOOK_REPLAY_TOLERANCE_SECONDS, nowSeconds } = options;
+    if (typeof secret !== "string" || secret.trim().length === 0) {
+        throw new TypeError("traceten: a non-empty webhook signing secret is required");
+    }
+    if (typeof signatureHeader !== "string" || signatureHeader.length === 0) {
+        throw new WebhookVerificationError("missing X-Traceten-Signature header");
+    }
+    if (typeof timestampHeader !== "string" || timestampHeader.length === 0) {
+        throw new WebhookVerificationError("missing X-Traceten-Signature-Timestamp header");
+    }
+    // Replay window. A non-numeric timestamp is always a hard reject.
+    const ts = Number(timestampHeader);
+    if (!Number.isFinite(ts)) {
+        throw new WebhookVerificationError("invalid X-Traceten-Signature-Timestamp header");
+    }
+    const now = nowSeconds ?? Date.now() / 1000;
+    if (Math.abs(now - ts) > toleranceSeconds) {
+        throw new WebhookVerificationError("timestamp outside the replay tolerance window");
+    }
+    // Recompute the signature over the RAW body bytes.
+    const body = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;
+    const hmac = createHmac("sha256", secret);
+    hmac.update(`${timestampHeader}.`, "utf8");
+    hmac.update(body);
+    const expected = hmac.digest("hex");
+    // Constant-time compare. timingSafeEqual throws on length mismatch, so guard
+    // first — a length mismatch is a definite reject, not an exception.
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const providedBuf = Buffer.from(signatureHeader, "utf8");
+    if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {
+        throw new WebhookVerificationError("signature mismatch");
+    }
+    // Only now — after the signature is proven — do we parse the body.
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        throw new WebhookVerificationError("verified body is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new WebhookVerificationError("verified body is not a webhook envelope object");
+    }
+    return parsed;
+}
+//# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@traceten/sdk-node",
+  "version": "1.0.0",
+  "description": "Traceten server-side SDK for Node.js — send AI-traffic pageviews and conversions from your backend.",
+  "keywords": [
+    "traceten",
+    "traceten.com",
+    "analytics",
+    "attribution",
+    "ai-traffic",
+    "ai-analytics",
+    "web-analytics",
+    "product-analytics",
+    "revenue-attribution",
+    "conversion-tracking",
+    "funnels",
+    "ai-visibility",
+    "chatgpt",
+    "perplexity",
+    "llm-traffic",
+    "generative-engine-optimization",
+    "aeo",
+    "nodejs",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://docs.traceten.com/sdks/node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/traceten/sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/traceten/sdk-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "lint": "echo 'no linter configured yet'"
+  },
+  "dependencies": {
+    "undici": "^6.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  }
+}