zkp-sdk-node 0.1.0

package/dist/replay.js

@@ -0,0 +1,103 @@
+/**
+ * At-least-once delivery protection and payment matching (P0).
+ *
+ * `isDuplicate()` is a PURE lookup: it never mutates the store. An event is
+ * marked processed only via `markProcessed()` AFTER the local order update
+ * succeeded - marking earlier would turn any crash in between into a
+ * permanently unpaid order (the retry would be skipped as a duplicate).
+ *
+ * Concurrent deliveries of the same event can both pass `isDuplicate()`;
+ * apps needing strict single-processing should implement an atomic claim
+ * (INSERT ... ON CONFLICT / unique constraint) in their EventStore and use
+ * it as the source of truth.
+ *
+ * Monetary validation is fail-closed: an unparseable amount never compares
+ * as "enough" - `matchesOrder()` returns false and `compareDecimals()`
+ * throws instead of silently comparing garbage.
+ */
+/** Plain non-negative decimal only: no sign, exponent, spaces, extra dots or
+ *  NaN/Infinity spellings. Zero is a syntactically valid amount. */
+const DECIMAL_RE = /^[0-9]+(?:\.[0-9]+)?$/;
+/** True only for plain non-negative decimal strings (no float arithmetic). */
+export function isValidDecimal(value) {
+    return typeof value === "string" && DECIMAL_RE.test(value);
+}
+/**
+ * Compare two plain non-negative decimal strings WITHOUT floats.
+ * Throws TypeError on anything that is not a plain decimal - garbage must
+ * never compare silently (validate first; matchesOrder does).
+ */
+export function compareDecimals(a, b) {
+    for (const value of [a, b]) {
+        if (!DECIMAL_RE.test(value)) {
+            throw new TypeError(`not a plain non-negative decimal string: ${JSON.stringify(value)}`);
+        }
+    }
+    const [ai = "0", af = ""] = a.split(".");
+    const [bi = "0", bf = ""] = b.split(".");
+    // normalize BEFORE comparing: leading zeros must not affect length/value
+    // ("0002" is 2, not a 4-digit number greater than "10")
+    const norm = (s) => s.replace(/^0+(?=\d)/, "");
+    const nAi = norm(ai);
+    const nBi = norm(bi);
+    const intCmp = nAi.length !== nBi.length ? nAi.length - nBi.length : nAi.localeCompare(nBi);
+    const fracCmp = af.padEnd(bf.length, "0").localeCompare(bf.padEnd(af.length, "0"));
+    return intCmp || fracCmp; // never -0 (0 stays 0 via ||)
+}
+export class ReplayGuard {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Pure check: true when the event was already processed. No side effects. */
+    async isDuplicate(eventId) {
+        return await this.store.has(eventId);
+    }
+    /** Call only after the local order update has succeeded. */
+    async markProcessed(eventId) {
+        await this.store.markProcessed(eventId);
+    }
+    /**
+     * Signature validity alone is NOT enough to credit an order: match the
+     * invoice id, the paid crypto amount (>= minAmount) and the asset.
+     * Fail-closed: invalid amount data means "not enough", never "paid".
+     */
+    matchesOrder(event, expectedInvoiceId, options = {}) {
+        if (event.invoiceId !== expectedInvoiceId) {
+            return false;
+        }
+        if (options.asset !== undefined && !assetMatches(event, options.asset)) {
+            return false;
+        }
+        if (options.minAmount !== undefined) {
+            const paid = event.paidAmount;
+            if (paid === null || !isValidDecimal(paid) || !isValidDecimal(options.minAmount)) {
+                return false;
+            }
+            if (compareDecimals(paid, options.minAmount) < 0) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+function assetMatches(event, expected) {
+    const paidRaw = (event.paidAsset ?? "").toLowerCase();
+    if (!paidRaw) {
+        return false;
+    }
+    const [expTicker, expNetwork] = expected.toLowerCase().split("_");
+    const [paidTicker] = paidRaw.split("_");
+    if (paidTicker !== expTicker) {
+        return false;
+    }
+    if (expNetwork !== undefined && expNetwork !== "") {
+        // asset id expected: the webhook MUST carry the network explicitly;
+        // missing or different network is a mismatch (fail-closed)
+        const paidNetwork = (event.paidNetwork ?? "").toLowerCase();
+        if (paidNetwork !== expNetwork) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/status.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Normalized invoice status + raw-API status mapping.
+ *
+ * Raw statuses (created/pending/detecting/confirmed/underpaid/expired/canceled)
+ * never leak into billing logic: platforms consume InvoiceStatus
+ * (mirrors the PHP/Python SDKs).
+ */
+export type InvoiceStatus = "PENDING" | "CONFIRMING" | "PAID" | "UNDERPAID" | "EXPIRED" | "CANCELLED" | "OVERPAID" | "FAILED";
+export declare class StatusMapper {
+    static normalize(raw: string): InvoiceStatus | null;
+    static normalizeOrFail(raw: string): InvoiceStatus;
+    static isTerminal(raw: string): boolean;
+    static isPaid(raw: string): boolean;
+}
+export declare function isTerminalStatus(status: InvoiceStatus): boolean;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,YAAY,GACZ,MAAM,GACN,WAAW,GACX,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,CAAC;AAiBb,qBAAa,YAAY;IACvB,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAInD,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAQlD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIvC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAGpC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE/D"}

package/dist/status.js

@@ -0,0 +1,41 @@
+/**
+ * Normalized invoice status + raw-API status mapping.
+ *
+ * Raw statuses (created/pending/detecting/confirmed/underpaid/expired/canceled)
+ * never leak into billing logic: platforms consume InvoiceStatus
+ * (mirrors the PHP/Python SDKs).
+ */
+const MAP = {
+    created: "PENDING",
+    pending: "PENDING",
+    detecting: "CONFIRMING",
+    confirmed: "PAID",
+    underpaid: "UNDERPAID",
+    expired: "EXPIRED",
+    canceled: "CANCELLED",
+    // overpayment is credited and confirmed server-side; kept for forward
+    // compatibility and local bookkeeping
+    overpaid: "OVERPAID",
+};
+const RAW_TERMINAL = new Set(["confirmed", "underpaid", "expired", "canceled"]);
+export class StatusMapper {
+    static normalize(raw) {
+        return MAP[raw] ?? null;
+    }
+    static normalizeOrFail(raw) {
+        const status = MAP[raw];
+        if (!status) {
+            throw new Error(`unknown invoice status '${raw}'`);
+        }
+        return status;
+    }
+    static isTerminal(raw) {
+        return RAW_TERMINAL.has(raw);
+    }
+    static isPaid(raw) {
+        return raw === "confirmed";
+    }
+}
+export function isTerminalStatus(status) {
+    return status !== "PENDING" && status !== "CONFIRMING";
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Single source of truth for the SDK version. */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Single source of truth for the SDK version. */
+export const VERSION = "0.1.0";

package/dist/webhooks/verifier.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Webhook signature verification - security critical (P0).
+ *
+ * Every delivery carries one header:
+ *
+ *     X-ZKP-Signature: t=<unix seconds>,v1=<64-char lowercase hex>
+ *
+ * v1 = HMAC-SHA256(webhookSecret, "{t}.{rawBody}") where rawBody is the exact
+ * request body as received - never re-serialized JSON. Verification is strict
+ * (header format, ±tolerance window) and constant-time (timingSafeEqual).
+ */
+import { WebhookEvent, type VerificationResult } from "../models/webhook.js";
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export interface VerifyOptions {
+    /** Override `now` (unix seconds) for tests. */
+    now?: number;
+    /** Signature secret override (config webhookSecret used when omitted). */
+    secret?: string;
+    /** Tolerance window in seconds, default 300. */
+    toleranceSeconds?: number;
+}
+export declare class WebhookVerifier {
+    private readonly secret;
+    readonly toleranceSeconds: number;
+    constructor(webhookSecret: string, toleranceSeconds?: number);
+    /** Verify and decode; throws WebhookVerificationError on any failure. */
+    verify(rawBody: string | Uint8Array, signatureHeader: string, options?: {
+        now?: number;
+    }): WebhookEvent;
+    /** Non-throwing variant returning a VerificationResult. */
+    check(rawBody: string | Uint8Array, signatureHeader: string, options?: {
+        now?: number;
+    }): VerificationResult;
+    /** Build a signature header for a body (tests and local replay tooling). */
+    sign(rawBody: string | Uint8Array, timestamp?: number): string;
+    private signPayload;
+}
+//# sourceMappingURL=verifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/webhooks/verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI7E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAY7C,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;gBAEtB,aAAa,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAkC;IAWvF,yEAAyE;IACzE,MAAM,CACJ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7B,YAAY;IAQf,2DAA2D;IAC3D,KAAK,CACH,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7B,kBAAkB;IA6CrB,4EAA4E;IAC5E,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAK9D,OAAO,CAAC,WAAW;CAIpB"}

package/dist/webhooks/verifier.js

@@ -0,0 +1,96 @@
+/**
+ * Webhook signature verification - security critical (P0).
+ *
+ * Every delivery carries one header:
+ *
+ *     X-ZKP-Signature: t=<unix seconds>,v1=<64-char lowercase hex>
+ *
+ * v1 = HMAC-SHA256(webhookSecret, "{t}.{rawBody}") where rawBody is the exact
+ * request body as received - never re-serialized JSON. Verification is strict
+ * (header format, ±tolerance window) and constant-time (timingSafeEqual).
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { WebhookVerificationError as WVE } from "../errors.js";
+import { WebhookEvent } from "../models/webhook.js";
+const HEADER_RE = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/;
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+const MESSAGES = {
+    [WVE.MISSING_HEADER]: "X-ZKP-Signature header is missing",
+    [WVE.MALFORMED_HEADER]: "signature header is malformed (expected t=<int>,v1=<64 lowercase hex>)",
+    [WVE.STALE_TIMESTAMP]: "signature timestamp is outside the tolerance window (stale)",
+    [WVE.FUTURE_TIMESTAMP]: "signature timestamp is outside the tolerance window (future)",
+    [WVE.SIGNATURE_MISMATCH]: "signature does not match the raw body",
+    [WVE.MALFORMED_PAYLOAD]: "verified body is not a JSON object",
+};
+export class WebhookVerifier {
+    secret;
+    toleranceSeconds;
+    constructor(webhookSecret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS) {
+        if (!webhookSecret) {
+            throw new Error("webhook secret must not be empty");
+        }
+        if (!Number.isInteger(toleranceSeconds) || toleranceSeconds < 1) {
+            throw new Error("tolerance must be at least 1 second");
+        }
+        this.secret = webhookSecret;
+        this.toleranceSeconds = toleranceSeconds;
+    }
+    /** Verify and decode; throws WebhookVerificationError on any failure. */
+    verify(rawBody, signatureHeader, options = {}) {
+        const result = this.check(rawBody, signatureHeader, options);
+        if (!result.event) {
+            throw new WVE(MESSAGES[result.reason ?? ""] ?? "verification failed", result.reason ?? "invalid");
+        }
+        return result.event;
+    }
+    /** Non-throwing variant returning a VerificationResult. */
+    check(rawBody, signatureHeader, options = {}) {
+        if (!signatureHeader) {
+            return { valid: false, reason: WVE.MISSING_HEADER, event: null };
+        }
+        const match = HEADER_RE.exec(signatureHeader);
+        if (!match) {
+            return { valid: false, reason: WVE.MALFORMED_HEADER, event: null };
+        }
+        const [, timestamp, signature] = match;
+        const now = options.now ?? Math.floor(Date.now() / 1000);
+        const skew = now - Number(timestamp);
+        if (skew > this.toleranceSeconds) {
+            return { valid: false, reason: WVE.STALE_TIMESTAMP, event: null };
+        }
+        if (-skew > this.toleranceSeconds) {
+            return { valid: false, reason: WVE.FUTURE_TIMESTAMP, event: null };
+        }
+        const expected = this.signPayload(timestamp, rawBody);
+        if (expected.length !== signature.length ||
+            !timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(signature, "utf8"))) {
+            return { valid: false, reason: WVE.SIGNATURE_MISMATCH, event: null };
+        }
+        let payload;
+        try {
+            const text = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+            payload = JSON.parse(text);
+        }
+        catch {
+            return { valid: false, reason: WVE.MALFORMED_PAYLOAD, event: null };
+        }
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            return { valid: false, reason: WVE.MALFORMED_PAYLOAD, event: null };
+        }
+        try {
+            return { valid: true, reason: null, event: WebhookEvent.fromJson(payload) };
+        }
+        catch {
+            return { valid: false, reason: WVE.MALFORMED_PAYLOAD, event: null };
+        }
+    }
+    /** Build a signature header for a body (tests and local replay tooling). */
+    sign(rawBody, timestamp) {
+        const t = timestamp ?? Math.floor(Date.now() / 1000);
+        return `t=${t},v1=${this.signPayload(String(t), rawBody)}`;
+    }
+    signPayload(timestamp, rawBody) {
+        const body = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : Buffer.from(rawBody);
+        return createHmac("sha256", this.secret).update(timestamp + ".").update(body).digest("hex");
+    }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "zkp-sdk-node",
+  "version": "0.1.0",
+  "description": "Official Node.js/TypeScript SDK for the ZeroKYC Pay crypto payment gateway (no-KYC checkout for digital services).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "zerokyc",
+    "crypto",
+    "payments",
+    "gateway",
+    "usdt",
+    "bitcoin",
+    "monero",
+    "ton",
+    "webhooks",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "lint": "eslint src tests examples",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.include='src/webhooks/**' --coverage.include='src/replay.ts' --coverage.thresholds.lines=90 --coverage.thresholds.functions=90 --coverage.thresholds.branches=85",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerokyc-payments/zkp-sdk-node.git"
+  },
+  "homepage": "https://zerokyc-payments.com/",
+  "bugs": {
+    "url": "https://github.com/zerokyc-payments/zkp-sdk-node/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.10.0",
+    "express": "^5.2.1",
+    "next": "^16.3.4",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.6.0",
+    "vitest": "^4.1.11"
+  }
+}