@0xinsider/mcp 1.3.1 → 2.0.0

package/dist/sdk/webhooks.js

@@ -0,0 +1,122 @@
+/**
+ * Webhook signature verification and typed delivery payloads.
+ *
+ * The backend signs every webhook delivery exactly like this (source of truth:
+ * `backend/src/api_v1/handlers/webhooks/endpoint_security.rs::sign_webhook_payload`):
+ *
+ *   signature = "v1=" + hex( HMAC_SHA256( signing_secret, `${timestamp}.${raw_body}` ) )
+ *
+ * It is sent on two headers:
+ *   - `x-0xinsider-timestamp: <unix-seconds>`
+ *   - `x-0xinsider-signature: v1=<hex>`   (may be a comma-separated list)
+ *
+ * Verification, the receiver side. The backend only signs; the published
+ * recipe is the delivery-signing paragraph on POST /api/v1/webhooks in
+ * `web/public/api/v1/openapi.json`:
+ *   1. Reject if `|now - timestamp| > 300` seconds (replay tolerance).
+ *   2. Recompute the expected `v1=<hex>` over `${timestamp}.${rawBody}`.
+ *   3. Constant-time compare against each candidate in the header.
+ *
+ * `rawBody` MUST be the exact bytes received: verify before JSON parsing, since
+ * re-serializing changes whitespace/key order and breaks the HMAC.
+ *
+ * ENDPOINT ACTIVATION (`verifyWebhook`, `POST /api/v1/webhooks/{id}/verify`):
+ * the one-time `verification.token` is necessary but not sufficient. That call
+ * POSTs a challenge to your webhook url and activates the endpoint only if you
+ * answer 2xx within 10 seconds. The challenge body is
+ * `{ "type": "webhook.verification", "token": "<verification_token>",
+ * "webhook_id": <id> }`, it carries `x-0xinsider-event-type:
+ * webhook.verification`, and it is signed with the endpoint's `signing_secret`
+ * exactly like a delivery -- so `verifySignature` below validates it unchanged.
+ * The challenge follows no redirects and never reads your response body. A
+ * non-2xx answer, no answer inside 10 seconds, or a url that does not resolve to
+ * a publicly routable address returns 422 and leaves the endpoint
+ * `pending_verification`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Default replay tolerance; the published contract is 300 seconds. */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+/** Header carrying the `v1=<hex>` signature. */
+export const SIGNATURE_HEADER = "x-0xinsider-signature";
+/** Header carrying the unix-seconds signing timestamp. */
+export const TIMESTAMP_HEADER = "x-0xinsider-timestamp";
+/**
+ * Recompute the canonical signature for a payload. Returns `v1=<hex>`.
+ * Exposed so callers can sign in tests; matches the backend byte-for-byte.
+ */
+export function computeSignature(secret, timestamp, body) {
+    const hmac = createHmac("sha256", secret);
+    hmac.update(String(timestamp));
+    hmac.update(".");
+    hmac.update(typeof body === "string" ? Buffer.from(body, "utf-8") : body);
+    return `v1=${hmac.digest("hex")}`;
+}
+/**
+ * Verify a webhook signature. Returns `true` only when the timestamp is within
+ * tolerance AND a candidate signature constant-time-matches the recomputed one.
+ * Never throws on a bad signature; throws only on a missing/empty secret.
+ */
+export function verifySignature(input) {
+    if (!input.secret) {
+        throw new Error("verifySignature requires a non-empty signing secret");
+    }
+    const tolerance = input.toleranceSeconds ?? SIGNATURE_TOLERANCE_SECONDS;
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    // Guard a caller-injected non-finite `now` (e.g. NaN): a non-finite reference
+    // time would make `Math.abs(now - ts) > tolerance` false and silently skip the
+    // replay-window check, so reject outright rather than verify on the HMAC alone.
+    if (!Number.isFinite(now)) {
+        return false;
+    }
+    const ts = Number(input.timestamp);
+    if (!Number.isFinite(ts)) {
+        return false;
+    }
+    if (Math.abs(now - ts) > tolerance) {
+        return false;
+    }
+    const expected = computeSignature(input.secret, ts, input.body);
+    const expectedBuf = Buffer.from(expected, "utf-8");
+    // The header may carry multiple comma-separated candidate signatures.
+    return input.signature
+        .split(",")
+        .map((part) => part.trim())
+        .some((candidate) => constantTimeEqual(candidate, expectedBuf));
+}
+function constantTimeEqual(candidate, expected) {
+    const candidateBuf = Buffer.from(candidate, "utf-8");
+    // timingSafeEqual throws on length mismatch; the length check itself is not
+    // secret (signature length is public), so guard first.
+    if (candidateBuf.length !== expected.length) {
+        return false;
+    }
+    return timingSafeEqual(candidateBuf, expected);
+}
+// --- Typed webhook payloads ---
+/**
+ * Webhook event types. Source of truth:
+ * `web/public/api/v1/openapi.json` -> components.schemas.WebhookEventType.enum.
+ * `whale_trades_inserted`, `wallet_grade_changed`, `insider_radar_flag_raised`,
+ * and `smart_money_flow_detected` are Pro-only: they deliver only to API keys
+ * on an active Pro subscription.
+ */
+export const WEBHOOK_EVENT_TYPES = [
+    "whale_trades_inserted",
+    "live_sports_updated",
+    "whale_trader_synced",
+    "large_positions_updated",
+    "wallet_grade_changed",
+    "insider_radar_flag_raised",
+    // Pro-only; present in the OpenAPI WebhookEventType enum + backend
+    // allowlist but previously missing here (drift fix, #6915). The wire
+    // identifier stays `smart_money_flow_detected` (frozen event name).
+    "smart_money_flow_detected",
+];
+/**
+ * Parse a verified raw body into the typed delivery envelope. Call only AFTER
+ * `verifySignature` passes (parsing first would let an unverified payload in).
+ */
+export function parseWebhookEvent(body) {
+    return JSON.parse(body);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/sdk/webhooks.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xinsider/mcp",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "mcpName": "io.github.0xinsider/mcp",
   "description": "Official 0xinsider CLI and MCP server: advanced tools for sports and esports markets, powered by Polymarket",
   "type": "module",
@@ -13,7 +13,7 @@
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
     "prebuild": "node scripts/generate-version.mjs",
-    "build": "tsc",
+    "build": "tsc -p tsconfig.sdk.json && tsc",
     "generate:catalog": "node ../scripts/generate-mcp-catalog.mjs",
     "catalog:parity": "node ../scripts/mcp-catalog-parity.mjs",
     "test": "tsx --test tests/**/*.test.ts",
@@ -47,7 +47,7 @@
   },
   "homepage": "https://0xinsider.com/developers",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -65,5 +65,8 @@
     "semver": "^7.8.5",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2"
+  },
+  "imports": {
+    "#sdk": "./dist/sdk/index.js"
   }
 }