@secureprocessing/node 0.0.0-stage → 0.2.0

package/dist/types.js

@@ -0,0 +1,3 @@
+// @ts-self-types="./types.d.ts"
+/** The objects the API returns. Amounts are integers in the currency's minor unit. */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sent in every request's User-Agent, so a support request can say which SDK made the call.
+ *
+ * A constant rather than a read of package.json, because the SDK runs where there is no
+ * filesystem. `test/sdk.test.ts` fails if the two disagree — 0.1.0's User-Agent was a literal in two
+ * places, and a bump would have left both claiming the old version.
+ */
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1,9 @@
+// @ts-self-types="./version.d.ts"
+/**
+ * Sent in every request's User-Agent, so a support request can say which SDK made the call.
+ *
+ * A constant rather than a read of package.json, because the SDK runs where there is no
+ * filesystem. `test/sdk.test.ts` fails if the two disagree — 0.1.0's User-Agent was a literal in two
+ * places, and a bump would have left both claiming the old version.
+ */
+export const VERSION = "0.2.0";

package/dist/webhooks.d.ts

@@ -0,0 +1,22 @@
+import type { SecureProcessingEvent } from "./types.js";
+export declare const SIGNATURE_HEADER = "Secure-Processing-Signature";
+/**
+ * Verify a webhook and return the event.
+ *
+ * 🔴 Pass the RAW request body, as a string, exactly as it arrived. A body that has been parsed and
+ * re-serialised will not match the signature — key order and whitespace both change — and this is
+ * the single most common reason a first webhook integration fails.
+ *
+ * The timestamp is part of what was signed, so an old request cannot be replayed at you: anything
+ * outside the tolerance window is rejected even if its signature is genuine.
+ *
+ * Works anywhere Web Crypto does: Node 20+, Deno, Bun, Cloudflare Workers.
+ */
+export declare function constructEvent<T = Record<string, unknown>>(payload: string, signatureHeader: string, secret: string, options?: {
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}): Promise<SecureProcessingEvent<T>>;
+export declare function parseSignatureHeader(header: string): {
+    timestamp: number | null;
+    signatures: string[];
+};

package/dist/webhooks.js

@@ -0,0 +1,79 @@
+// @ts-self-types="./webhooks.d.ts"
+import { SecureProcessingError } from "./errors.js";
+export const SIGNATURE_HEADER = "Secure-Processing-Signature";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify a webhook and return the event.
+ *
+ * 🔴 Pass the RAW request body, as a string, exactly as it arrived. A body that has been parsed and
+ * re-serialised will not match the signature — key order and whitespace both change — and this is
+ * the single most common reason a first webhook integration fails.
+ *
+ * The timestamp is part of what was signed, so an old request cannot be replayed at you: anything
+ * outside the tolerance window is rejected even if its signature is genuine.
+ *
+ * Works anywhere Web Crypto does: Node 20+, Deno, Bun, Cloudflare Workers.
+ */
+export async function constructEvent(payload, signatureHeader, secret, options = {}) {
+    const { timestamp, signatures } = parseSignatureHeader(signatureHeader);
+    if (timestamp === null)
+        throw signatureError("The signature header carries no timestamp");
+    if (signatures.length === 0)
+        throw signatureError("The signature header carries no signatures");
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > tolerance) {
+        throw signatureError(`This webhook is ${Math.abs(now - timestamp)}s old, outside the ${tolerance}s tolerance. ` +
+            "If that is unexpected, check your server's clock.");
+    }
+    const expected = await hmacSha256Hex(secret, `${timestamp}.${payload}`);
+    // Every candidate is checked, in constant time: returning early on a match would leak which of a
+    // rotating pair of secrets is the current one.
+    let matched = false;
+    for (const candidate of signatures) {
+        if (timingSafeEqual(expected, candidate))
+            matched = true;
+    }
+    if (!matched) {
+        throw signatureError("No signature matched. Check that you passed the raw request body, and that the signing " +
+            "secret belongs to this endpoint.");
+    }
+    return JSON.parse(payload);
+}
+export function parseSignatureHeader(header) {
+    let timestamp = null;
+    const signatures = [];
+    for (const part of header.split(",")) {
+        const [key, value] = part.trim().split("=", 2);
+        if (!key || value === undefined)
+            continue;
+        if (key === "t") {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                timestamp = parsed;
+        }
+        else if (key === "v1") {
+            signatures.push(value);
+        }
+    }
+    return { timestamp, signatures };
+}
+function signatureError(message) {
+    return new SecureProcessingError(400, {
+        error: { type: "invalid_request_error", code: "signature_verification_failed", message },
+    });
+}
+async function hmacSha256Hex(secret, message) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+    return [...new Uint8Array(signature)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@secureprocessing/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Secure Processing API client. Card payments for Belize.",
+  "homepage": "https://docs.secureprocessing.app/sdk",
+  "bugs": {
+    "url": "https://secureprocessing.app/contact"
+  },
+  "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"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "payments",
+    "belize",
+    "secure-processing",
+    "api"
+  ]
+}