@pacspace-io/sdk 0.1.0

package/dist/webhooks/verify.d.ts

@@ -0,0 +1,104 @@
+import type { WebhookEvent, WebhookHeaders } from './types';
+/**
+ * Options for webhook verification.
+ */
+export interface VerifyOptions {
+    /**
+     * Maximum age (seconds) of the timestamp before rejecting.
+     * Protects against replay attacks.
+     * @default 300 (5 minutes)
+     */
+    tolerance?: number;
+}
+/**
+ * PacSpace Webhook verification and middleware.
+ *
+ * Provides HMAC-SHA256 signature verification for webhook payloads
+ * using the algorithm documented at:
+ * https://docs.pacspace.io/webhooks/signature-verification
+ */
+export declare class Webhooks {
+    private readonly secret;
+    /**
+     * @param secret - Your webhook signing secret (from the PacSpace dashboard).
+     */
+    constructor(secret: string);
+    /**
+     * Verify a webhook payload and return the typed event.
+     *
+     * @param signature - The `X-PacSpace-Signature` header value.
+     * @param timestamp - The `X-PacSpace-Timestamp` header value.
+     * @param rawBody - The raw request body as a string (before JSON parsing).
+     * @param options - Verification options (timestamp tolerance).
+     * @returns The parsed and verified webhook event.
+     * @throws WebhookVerificationError if verification fails.
+     *
+     * @example
+     * ```typescript
+     * const event = pac.webhooks.verify(
+     *   req.headers['x-pacspace-signature'],
+     *   req.headers['x-pacspace-timestamp'],
+     *   req.rawBody,
+     * );
+     *
+     * if (event.event === 'delta.verified') {
+     *   console.log(event.data.receiptId);
+     * }
+     * ```
+     */
+    verify(signature: string, timestamp: string, rawBody: string, options?: VerifyOptions): WebhookEvent;
+    /**
+     * Verify using a headers object (convenience method).
+     *
+     * Extracts `x-pacspace-signature` and `x-pacspace-timestamp` from headers.
+     *
+     * @param headers - Headers object (Express req.headers or similar).
+     * @param rawBody - The raw request body as a string.
+     * @param options - Verification options.
+     * @returns The parsed and verified webhook event.
+     *
+     * @example
+     * ```typescript
+     * const event = pac.webhooks.verifyFromHeaders(req.headers, req.rawBody);
+     * ```
+     */
+    verifyFromHeaders(headers: WebhookHeaders | Record<string, string | string[] | undefined>, rawBody: string, options?: VerifyOptions): WebhookEvent;
+    /**
+     * Create an Express/Connect-compatible middleware for webhook verification.
+     *
+     * The middleware:
+     * 1. Verifies the HMAC signature
+     * 2. Validates the timestamp
+     * 3. Attaches the parsed event to `req.pacspaceEvent`
+     * 4. Calls `next()` on success, or responds with 401 on failure
+     *
+     * **Important:** Ensure raw body parsing is enabled before this middleware.
+     *
+     * @param options - Verification options.
+     * @returns Express middleware function.
+     *
+     * @example
+     * ```typescript
+     * // Capture raw body (required for signature verification)
+     * app.use('/webhooks', express.json({
+     *   verify: (req, _res, buf) => { req.rawBody = buf.toString(); }
+     * }));
+     *
+     * app.post('/webhooks/pacspace', pac.webhooks.middleware(), (req, res) => {
+     *   const event = req.pacspaceEvent;
+     *   console.log(`Received ${event.event}:`, event.data);
+     *   res.status(200).json({ received: true });
+     * });
+     * ```
+     */
+    middleware(options?: VerifyOptions): (req: any, res: any, next: any) => void;
+    /**
+     * Validate that the timestamp is within the tolerance window.
+     */
+    private validateTimestamp;
+    /**
+     * Extract a header value from a headers object (handles arrays).
+     */
+    private getHeader;
+}
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/webhooks/verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;OAEG;gBACS,MAAM,EAAE,MAAM;IAS1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY;IAyCf;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CACf,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACvE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY;IAkBf;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,aAAa,IACxB,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG;IAgBvC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,OAAO,CAAC,SAAS;CAOlB"}

package/dist/webhooks/verify.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = void 0;
+const crypto_1 = require("crypto");
+const errors_1 = require("../errors");
+/**
+ * PacSpace Webhook verification and middleware.
+ *
+ * Provides HMAC-SHA256 signature verification for webhook payloads
+ * using the algorithm documented at:
+ * https://docs.pacspace.io/webhooks/signature-verification
+ */
+class Webhooks {
+    /**
+     * @param secret - Your webhook signing secret (from the PacSpace dashboard).
+     */
+    constructor(secret) {
+        if (!secret) {
+            throw new errors_1.WebhookVerificationError('Webhook secret is required. Get it from your PacSpace dashboard.');
+        }
+        this.secret = secret;
+    }
+    /**
+     * Verify a webhook payload and return the typed event.
+     *
+     * @param signature - The `X-PacSpace-Signature` header value.
+     * @param timestamp - The `X-PacSpace-Timestamp` header value.
+     * @param rawBody - The raw request body as a string (before JSON parsing).
+     * @param options - Verification options (timestamp tolerance).
+     * @returns The parsed and verified webhook event.
+     * @throws WebhookVerificationError if verification fails.
+     *
+     * @example
+     * ```typescript
+     * const event = pac.webhooks.verify(
+     *   req.headers['x-pacspace-signature'],
+     *   req.headers['x-pacspace-timestamp'],
+     *   req.rawBody,
+     * );
+     *
+     * if (event.event === 'delta.verified') {
+     *   console.log(event.data.receiptId);
+     * }
+     * ```
+     */
+    verify(signature, timestamp, rawBody, options) {
+        if (!signature || !timestamp || !rawBody) {
+            throw new errors_1.WebhookVerificationError('Missing required parameters: signature, timestamp, and rawBody are all required.');
+        }
+        // Validate timestamp to prevent replay attacks
+        this.validateTimestamp(timestamp, options?.tolerance ?? 300);
+        // Reconstruct the signed content: "{timestamp}.{rawBody}"
+        const signedContent = `${timestamp}.${rawBody}`;
+        // Compute HMAC-SHA256
+        const expectedSignature = 'v1=' +
+            (0, crypto_1.createHmac)('sha256', this.secret).update(signedContent).digest('hex');
+        // Constant-time comparison
+        const expected = Buffer.from(expectedSignature);
+        const received = Buffer.from(signature);
+        if (expected.length !== received.length ||
+            !(0, crypto_1.timingSafeEqual)(expected, received)) {
+            throw new errors_1.WebhookVerificationError('Signature mismatch. Ensure you are using the correct webhook secret and the raw (unparsed) request body.');
+        }
+        // Parse and return the event
+        try {
+            return JSON.parse(rawBody);
+        }
+        catch {
+            throw new errors_1.WebhookVerificationError('Failed to parse webhook payload as JSON.');
+        }
+    }
+    /**
+     * Verify using a headers object (convenience method).
+     *
+     * Extracts `x-pacspace-signature` and `x-pacspace-timestamp` from headers.
+     *
+     * @param headers - Headers object (Express req.headers or similar).
+     * @param rawBody - The raw request body as a string.
+     * @param options - Verification options.
+     * @returns The parsed and verified webhook event.
+     *
+     * @example
+     * ```typescript
+     * const event = pac.webhooks.verifyFromHeaders(req.headers, req.rawBody);
+     * ```
+     */
+    verifyFromHeaders(headers, rawBody, options) {
+        const signature = this.getHeader(headers, 'x-pacspace-signature');
+        const timestamp = this.getHeader(headers, 'x-pacspace-timestamp');
+        if (!signature) {
+            throw new errors_1.WebhookVerificationError('Missing X-PacSpace-Signature header.');
+        }
+        if (!timestamp) {
+            throw new errors_1.WebhookVerificationError('Missing X-PacSpace-Timestamp header.');
+        }
+        return this.verify(signature, timestamp, rawBody, options);
+    }
+    /**
+     * Create an Express/Connect-compatible middleware for webhook verification.
+     *
+     * The middleware:
+     * 1. Verifies the HMAC signature
+     * 2. Validates the timestamp
+     * 3. Attaches the parsed event to `req.pacspaceEvent`
+     * 4. Calls `next()` on success, or responds with 401 on failure
+     *
+     * **Important:** Ensure raw body parsing is enabled before this middleware.
+     *
+     * @param options - Verification options.
+     * @returns Express middleware function.
+     *
+     * @example
+     * ```typescript
+     * // Capture raw body (required for signature verification)
+     * app.use('/webhooks', express.json({
+     *   verify: (req, _res, buf) => { req.rawBody = buf.toString(); }
+     * }));
+     *
+     * app.post('/webhooks/pacspace', pac.webhooks.middleware(), (req, res) => {
+     *   const event = req.pacspaceEvent;
+     *   console.log(`Received ${event.event}:`, event.data);
+     *   res.status(200).json({ received: true });
+     * });
+     * ```
+     */
+    middleware(options) {
+        return (req, res, next) => {
+            try {
+                const rawBody = req.rawBody || JSON.stringify(req.body);
+                const event = this.verifyFromHeaders(req.headers, rawBody, options);
+                req.pacspaceEvent = event;
+                next();
+            }
+            catch (err) {
+                if (err instanceof errors_1.WebhookVerificationError) {
+                    res.status(401).json({ error: err.message });
+                }
+                else {
+                    next(err);
+                }
+            }
+        };
+    }
+    /**
+     * Validate that the timestamp is within the tolerance window.
+     */
+    validateTimestamp(timestamp, toleranceSeconds) {
+        const webhookTime = parseInt(timestamp, 10);
+        if (isNaN(webhookTime)) {
+            throw new errors_1.WebhookVerificationError(`Invalid timestamp: "${timestamp}". Expected a Unix timestamp in seconds.`);
+        }
+        const currentTime = Math.floor(Date.now() / 1000);
+        const age = Math.abs(currentTime - webhookTime);
+        if (age > toleranceSeconds) {
+            throw new errors_1.WebhookVerificationError(`Timestamp too old (${age}s > ${toleranceSeconds}s tolerance). This may be a replay attack, or your server clock is skewed.`);
+        }
+    }
+    /**
+     * Extract a header value from a headers object (handles arrays).
+     */
+    getHeader(headers, key) {
+        const value = headers[key] ?? headers[key.toLowerCase()];
+        return Array.isArray(value) ? value[0] : value;
+    }
+}
+exports.Webhooks = Webhooks;
+//# sourceMappingURL=verify.js.map

package/dist/webhooks/verify.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pacspace-io/sdk",
+  "version": "0.1.0",
+  "description": "Official PacSpace Balance API SDK — zero-dependency TypeScript client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "default": "./dist/webhooks/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "pacspace",
+    "balance-api",
+    "blockchain",
+    "settlement",
+    "sdk"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}