@ritkey/sdk 0.1.0

package/dist/verify/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Webhook verification helper for receivers.
+ *
+ * Use this on YOUR endpoint that receives webhook deliveries from Ritkey:
+ *
+ *   import { verifyWebhook } from '@ritkey/sdk';
+ *
+ *   app.post('/ritkey-hook', async (req, res) => {
+ *     const rawBody = await readRawBody(req);
+ *     const result = verifyWebhook(rawBody, req.headers['ritkey-signature'], MY_SECRET);
+ *     if (!result.ok) return res.status(401).end(result.reason);
+ *     // result.event is now a typed RitkeyEvent
+ *     handleEvent(result.event);
+ *     res.status(200).end();
+ *   });
+ *
+ * IMPORTANT: rawBody must be the EXACT bytes Ritkey sent. If your framework
+ * parses JSON before you see the body, your HMAC will not match. Use a raw
+ * body parser for the webhook route.
+ */
+import type { RitkeyEvent, EventType } from '../types.js';
+export interface VerifyOptions {
+    /**
+     * Reject signatures older than this many seconds. Defaults to 300 (5 min).
+     * Set to 0 to disable timestamp check (NOT recommended).
+     */
+    toleranceSeconds?: number;
+    /** Override "now" for tests. */
+    nowSeconds?: number;
+}
+export type VerifyResult<T = unknown> = {
+    ok: true;
+    event: RitkeyEvent<T>;
+    timestamp: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Verify a Ritkey webhook delivery.
+ *
+ * @param rawBody  The exact request body bytes (string or Buffer).
+ * @param sigHeader The value of the `Ritkey-Signature` header. May be undefined / string[] / string.
+ * @param secret   Your subscription's `whsec_...` secret.
+ * @param opts     Optional tolerance / clock override.
+ */
+export declare function verifyWebhook<T = unknown>(rawBody: string | Uint8Array, sigHeader: string | string[] | undefined, secret: string, opts?: VerifyOptions): VerifyResult<T>;
+/**
+ * Narrow a verified event to a specific type tag.
+ *
+ *   if (isEvent(result.event, 'tx.sent')) {
+ *     // result.event.data is now typed
+ *   }
+ */
+export declare function isEvent<E extends EventType>(event: RitkeyEvent, type: E): event is RitkeyEvent & {
+    type: E;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/verify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIlC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,aAAkB,GACvB,YAAY,CAAC,CAAC,CAAC,CA8DjB;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,SAAS,EACzC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,CAAC,GACN,KAAK,IAAI,WAAW,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAEpC"}

package/dist/verify/index.js

@@ -0,0 +1,104 @@
+/**
+ * Webhook verification helper for receivers.
+ *
+ * Use this on YOUR endpoint that receives webhook deliveries from Ritkey:
+ *
+ *   import { verifyWebhook } from '@ritkey/sdk';
+ *
+ *   app.post('/ritkey-hook', async (req, res) => {
+ *     const rawBody = await readRawBody(req);
+ *     const result = verifyWebhook(rawBody, req.headers['ritkey-signature'], MY_SECRET);
+ *     if (!result.ok) return res.status(401).end(result.reason);
+ *     // result.event is now a typed RitkeyEvent
+ *     handleEvent(result.event);
+ *     res.status(200).end();
+ *   });
+ *
+ * IMPORTANT: rawBody must be the EXACT bytes Ritkey sent. If your framework
+ * parses JSON before you see the body, your HMAC will not match. Use a raw
+ * body parser for the webhook route.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify a Ritkey webhook delivery.
+ *
+ * @param rawBody  The exact request body bytes (string or Buffer).
+ * @param sigHeader The value of the `Ritkey-Signature` header. May be undefined / string[] / string.
+ * @param secret   Your subscription's `whsec_...` secret.
+ * @param opts     Optional tolerance / clock override.
+ */
+export function verifyWebhook(rawBody, sigHeader, secret, opts = {}) {
+    if (!secret)
+        return { ok: false, reason: 'missing secret' };
+    const header = Array.isArray(sigHeader) ? sigHeader[0] : sigHeader;
+    if (!header)
+        return { ok: false, reason: 'missing Ritkey-Signature header' };
+    // Parse `t=<ts>,v1=<hex>` — order-independent.
+    let tStr;
+    let v1Str;
+    for (const part of header.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        const v = part.slice(eq + 1).trim();
+        if (k === 't')
+            tStr = v;
+        else if (k === 'v1')
+            v1Str = v;
+    }
+    if (!tStr || !v1Str)
+        return { ok: false, reason: 'malformed Ritkey-Signature header' };
+    const timestamp = parseInt(tStr, 10);
+    if (!Number.isFinite(timestamp)) {
+        return { ok: false, reason: 'invalid timestamp in signature' };
+    }
+    // Timestamp tolerance check (replay protection).
+    const tolerance = opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (tolerance > 0) {
+        const now = opts.nowSeconds ?? Math.floor(Date.now() / 1000);
+        if (Math.abs(now - timestamp) > tolerance) {
+            return { ok: false, reason: 'signature timestamp outside tolerance window' };
+        }
+    }
+    // Compute expected HMAC over `<t>.<rawBody>`.
+    const bodyStr = typeof rawBody === 'string' ? rawBody : Buffer.from(rawBody).toString('utf8');
+    const signedPayload = `${tStr}.${bodyStr}`;
+    const expected = createHmac('sha256', secret).update(signedPayload).digest('hex');
+    // Timing-safe compare. Lengths must match before timingSafeEqual.
+    const expBuf = Buffer.from(expected, 'hex');
+    let provBuf;
+    try {
+        provBuf = Buffer.from(v1Str, 'hex');
+    }
+    catch {
+        return { ok: false, reason: 'invalid signature encoding' };
+    }
+    if (expBuf.length !== provBuf.length) {
+        return { ok: false, reason: 'signature mismatch' };
+    }
+    if (!timingSafeEqual(expBuf, provBuf)) {
+        return { ok: false, reason: 'signature mismatch' };
+    }
+    // Parse the event payload.
+    let event;
+    try {
+        event = JSON.parse(bodyStr);
+    }
+    catch {
+        return { ok: false, reason: 'body is not valid JSON' };
+    }
+    return { ok: true, event, timestamp };
+}
+/**
+ * Narrow a verified event to a specific type tag.
+ *
+ *   if (isEvent(result.event, 'tx.sent')) {
+ *     // result.event.data is now typed
+ *   }
+ */
+export function isEvent(event, type) {
+    return event.type === type;
+}
+//# sourceMappingURL=index.js.map

package/dist/verify/index.js.map

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

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ritkey/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Ritkey — wallet operations, webhooks, and event subscriptions",
+  "license": "MIT",
+  "author": "Chiefmmorgs <chiefmmorgs@gmail.com>",
+  "homepage": "https://github.com/mmorgsmorgan/ritual-agentic-wallet-#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmorgsmorgan/ritual-agentic-wallet-.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/mmorgsmorgan/ritual-agentic-wallet-/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ritkey",
+    "ritual",
+    "wallet",
+    "sdk",
+    "mpc",
+    "webhooks",
+    "ai-agents",
+    "ethereum"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  }
+}