@vobs/payment 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,157 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * @vobs/payment contract types (aligned with docs/development/payment-factory-design.md §3/§5).
+ *
+ * Scope boundary: the payment factory only does **forward collection** (order → verify → book → reconcile).
+ * Refunds are out of scope — business refunds go directly to the channel's refund API.
+ */
+/** Payment scenes (channel support matrix). */
+export type PaymentScene = 'pc' | 'h5' | 'miniapp' | 'app';
+/** Order states (no refund path). */
+export type OrderState = 'created' | 'pending' | 'paid' | 'closed' | 'frozen';
+/**
+ * Channel order input.
+ * `orderId` is globally unique — used as the channel's `out_trade_no` (channel-side unique constraint = natural idempotency, safe to retry after disconnects).
+ */
+export interface CreateOrderInput {
+    readonly orderId: string;
+    /** Fen (amounts are always integers to avoid float errors; currency CNY, extensible for multi-currency). */
+    readonly amount: number;
+    readonly subject: string;
+    readonly scene: PaymentScene;
+    readonly notifyUrl: string;
+    readonly extras?: Readonly<Record<string, unknown>>;
+}
+/** One-time payment params (the frontend initiates payment with these; keys never reach the frontend). */
+export type OrderInit = {
+    readonly kind: 'jsapi';
+    readonly payParams: Readonly<Record<string, string>>;
+} | {
+    readonly kind: 'qr';
+    readonly qrUrl: string;
+    readonly expiresAt?: string;
+} | {
+    readonly kind: 'redirect';
+    readonly payUrl: string;
+};
+/** Unified payment driver contract (three capabilities: createOrder / verifyCallback / queryOrder). */
+export interface PaymentDriver {
+    readonly name: string;
+    readonly scenes: readonly PaymentScene[];
+    /** Place an order: call the payment channel → return one-time payment params. */
+    createOrder(input: CreateOrderInput): Promise<OrderInit>;
+    /** Channel callback verification + normalization: NOTIFY request → verify channel signature → normalize order result. */
+    verifyCallback(payload: unknown, headers: unknown): VerifiedCallback;
+    /** Query order status (reconciliation/compensation). */
+    queryOrder(orderId: string): Promise<OrderStatus>;
+    /**
+     * Channel-agreed callback success text (e.g. WeChat/Jeepay `SUCCESS`, Alipay `success`).
+     * Default = JSON response (mock/self-built backends). After a successful callback the HTTP layer
+     * returns this channel-agreed format so the channel doesn't misjudge failure and retry.
+     */
+    readonly successResponseText?: string;
+}
+/** Normalized channel callback result (amounts always in fen). */
+export interface VerifiedCallback {
+    readonly ok: boolean;
+    readonly reason?: string;
+    readonly orderId?: string;
+    readonly paidAmount?: number;
+    readonly channelTxnId?: string;
+}
+export type OrderStatus = {
+    readonly state: OrderState;
+    readonly paidAt?: string;
+} | {
+    readonly state: 'unknown';
+    readonly raw: unknown;
+};
+/** Order record (payment-factory internal state, stored in PaymentStore). */
+export interface OrderRecord {
+    readonly orderId: string;
+    readonly amount: number;
+    readonly subject: string;
+    readonly scene: PaymentScene;
+    readonly driver: string;
+    state: OrderState;
+    paidAt?: string;
+    createdAt: number;
+    init?: OrderInit;
+    channelTxnId?: string;
+    /** Large-amount audit pending reason (audit). */
+    auditReason?: string;
+}
+/** Global policy config (PaymentManager-level, driver-agnostic). */
+export interface PaymentConfig {
+    /** Strategy when an unpaid order already exists for the same business order. Default 'ask'. */
+    readonly duplicateOrderStrategy?: 'reuse' | 'replace' | 'reject' | 'ask';
+    /** Large-amount audit threshold (fen): callback succeeds but paid ≥ this → stay pending until manually confirmed. */
+    readonly auditThreshold?: number;
+    /** Per-order limit (fen): reject over-limit orders (channel limits are usually lower; configure per driver). */
+    readonly maxAmount?: number;
+    /** Callback time window (sec) for anti-replay. Default 300. */
+    readonly timeWindowSec?: number;
+    /** Retention (ms) for idempotency records / callback nonces. Default 24h. */
+    readonly idempotencyTtlMs?: number;
+}
+/** Create-order HTTP input. `amount` is only a display/consistency check — the server-side price wins (server-pricing red line). */
+export interface CreateOrderRequest {
+    readonly orderId: string;
+    readonly amount: number;
+    readonly subject: string;
+    readonly scene?: PaymentScene;
+    readonly driver?: string;
+    readonly idempotencyKey?: string;
+}
+/** Create-order result. */
+export type CreateOrderResult = {
+    readonly kind: 'ok';
+    readonly driver: string;
+    readonly orderId: string;
+    readonly state: OrderState;
+    readonly init?: OrderInit;
+} | {
+    readonly kind: 'duplicate';
+    readonly existingOrderId: string;
+    readonly existingAmount: number;
+};
+/** Callback handling result (incl. HTTP response protocol: persist before responding). */
+export interface CallbackResult {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly orderId?: string;
+    readonly state?: OrderState;
+    readonly reason?: string;
+    /** Channel-agreed success text (WeChat/Jeepay `SUCCESS`, Alipay `success`) — when present the HTTP layer returns plain text instead of JSON. */
+    readonly text?: string;
+}
+/** Notification after booking (onVerified hook — business deliver/activate; must be idempotent). */
+export interface VerifiedResult {
+    readonly orderId: string;
+    readonly state: OrderState;
+    readonly paidAt?: string;
+    readonly channelTxnId?: string;
+}
+/** Alert (onAlert hook — triggered on frozen/conflict/large-amount/signature failure). */
+export interface PaymentAlert {
+    readonly level: 'warn' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly orderId?: string;
+    readonly driver?: string;
+}
+/** Operation audit entry (create/callback-book/freeze/confirm all logged). */
+export interface AuditEntry {
+    readonly operation: 'create' | 'callback' | 'close' | 'confirm' | 'freeze';
+    readonly orderId?: string;
+    readonly from?: OrderState;
+    readonly to?: OrderState;
+    readonly reason?: string;
+    readonly at: number;
+}
+/** Server-pricing hook (business: orderId → amount; undefined = order not found). */
+export type GetOrderAmount = (orderId: string) => number | undefined | Promise<number | undefined>;

package/dist/types.js

@@ -0,0 +1,11 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * @vobs/payment contract types (aligned with docs/development/payment-factory-design.md §3/§5).
+ *
+ * Scope boundary: the payment factory only does **forward collection** (order → verify → book → reconcile).
+ * Refunds are out of scope — business refunds go directly to the channel's refund API.
+ */
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,34 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Callback verification + anti-replay utilities.
+ *
+ * Protocol: `X-Signature = hex( HMAC-SHA256( apiKey, "{timestamp}.{nonce}.{raw body}" ) )`
+ * Check order:
+ *  ① |now - timestamp| ≤ timeWindowSec        else timestamp_expired (time-window anti-replay)
+ *  ② signature matches                          else bad_signature
+ *  ③ nonce unused (deduped by the caller via store)  else nonce_reused (anti-replay)
+ *
+ * Idempotency prevents double-booking; anti-replay prevents forged replays — both are required.
+ */
+import type { PaymentConfig } from './types.js';
+export type VerifyResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** HMAC-SHA256 hex (Web Crypto, globally available in Node 22+). */
+export declare function hmacSha256Hex(key: string, data: string): Promise<string>;
+/** Callback verification + time-window check (nonce dedup is the caller's job — needs concurrency-safe storage). */
+export declare function verifySignedCallback(opts: {
+    readonly apiKey: string;
+    readonly timestamp: string;
+    readonly nonce: string;
+    readonly signature: string;
+    readonly body: string;
+    readonly timeWindowSec?: number;
+}): Promise<VerifyResult>;
+export declare function timeWindowOf(config: PaymentConfig | undefined): number | undefined;

package/dist/verify.js

@@ -0,0 +1,55 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * Callback verification + anti-replay utilities.
+ *
+ * Protocol: `X-Signature = hex( HMAC-SHA256( apiKey, "{timestamp}.{nonce}.{raw body}" ) )`
+ * Check order:
+ *  ① |now - timestamp| ≤ timeWindowSec        else timestamp_expired (time-window anti-replay)
+ *  ② signature matches                          else bad_signature
+ *  ③ nonce unused (deduped by the caller via store)  else nonce_reused (anti-replay)
+ *
+ * Idempotency prevents double-booking; anti-replay prevents forged replays — both are required.
+ */
+const DEFAULT_TIME_WINDOW_SEC = 300;
+/** HMAC-SHA256 hex (Web Crypto, globally available in Node 22+). */
+export async function hmacSha256Hex(key, data) {
+    const keyBytes = new TextEncoder().encode(key);
+    const dataBytes = new TextEncoder().encode(data);
+    const cryptoKey = await crypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', cryptoKey, dataBytes);
+    return Array.from(new Uint8Array(sig))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** Callback verification + time-window check (nonce dedup is the caller's job — needs concurrency-safe storage). */
+export async function verifySignedCallback(opts) {
+    const windowSec = opts.timeWindowSec ?? DEFAULT_TIME_WINDOW_SEC;
+    const ts = Number(opts.timestamp);
+    if (!Number.isFinite(ts)) {
+        return { ok: false, reason: 'bad_timestamp' };
+    }
+    if (Math.abs(Date.now() / 1000 - ts) > windowSec) {
+        return { ok: false, reason: 'timestamp_expired' };
+    }
+    const expected = await hmacSha256Hex(opts.apiKey, `${opts.timestamp}.${opts.nonce}.${opts.body}`);
+    if (!timingSafeEqual(expected, opts.signature)) {
+        return { ok: false, reason: 'bad_signature' };
+    }
+    return { ok: true };
+}
+/** Constant-time comparison to prevent timing side channels. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+export function timeWindowOf(config) {
+    return config?.timeWindowSec;
+}

package/dist/wechat-official.d.ts

@@ -0,0 +1,40 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * WeChat Pay official driver (API v3) — Native (PC scan) / JSAPI (official account, miniapp webview) / H5.
+ *
+ * Covered scenes (web):
+ *  - `pc`       → Native payment → `{kind:'qr', qrUrl: code_url}`
+ *  - `h5` + openid → JSAPI payment → `{kind:'jsapi', payParams}` (official account / WeChat built-in browser)
+ *  - `h5` (no openid) → H5 payment → `{kind:'redirect', payUrl: h5_url}`
+ *  - `miniapp` + openid → JSAPI payment (miniapp webview)
+ *
+ * Security:
+ *  - Request signing: Authorization `WECHATPAY2-SHA256-RSA2048` (merchant private key SHA256withRSA)
+ *  - Callback: AES-256-GCM decryption (apiV3Key) + optional platform-cert verification (enforced when platformPublicKeyPem is set) + time-window/nonce anti-replay
+ *  - Channel self-verification path: callbacks bypass the framework's generic HMAC protocol; this driver verifies the channel itself
+ *
+ * Dependencies: node:crypto (Node built-in, zero third-party). Sandbox needs sandbox keys/certs from the merchant platform (configure baseUrl per the sandbox docs when integrating).
+ */
+import type { PaymentDriver } from './types.js';
+import type { PaymentStore } from './store.js';
+export interface WechatOfficialOptions {
+    readonly appId: string;
+    readonly mchId: string;
+    /** APIv3 key (32-byte string, used for AES-GCM callback decryption). Inject via KMS/env in production. */
+    readonly apiV3Key: string;
+    /** Merchant API certificate private key (PEM). */
+    readonly privateKeyPem: string;
+    /** Merchant API certificate serial number. */
+    readonly serialNo: string;
+    /** Platform public key (PEM, optional) — when set, callbacks require platform-cert verification; otherwise rely on AES-GCM decryption (apiV3Key confidentiality) + anti-replay. */
+    readonly platformPublicKeyPem?: string;
+    /** Callback time window (sec, anti-replay). Default 300. */
+    readonly timeWindowSec?: number;
+    /** Channel gateway URL (sandbox/prod). Defaults to prod. */
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createWechatOfficialDriver(store: PaymentStore, options: WechatOfficialOptions): PaymentDriver;

package/dist/wechat-official.js

@@ -0,0 +1,207 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/payment
+ */
+/**
+ * WeChat Pay official driver (API v3) — Native (PC scan) / JSAPI (official account, miniapp webview) / H5.
+ *
+ * Covered scenes (web):
+ *  - `pc`       → Native payment → `{kind:'qr', qrUrl: code_url}`
+ *  - `h5` + openid → JSAPI payment → `{kind:'jsapi', payParams}` (official account / WeChat built-in browser)
+ *  - `h5` (no openid) → H5 payment → `{kind:'redirect', payUrl: h5_url}`
+ *  - `miniapp` + openid → JSAPI payment (miniapp webview)
+ *
+ * Security:
+ *  - Request signing: Authorization `WECHATPAY2-SHA256-RSA2048` (merchant private key SHA256withRSA)
+ *  - Callback: AES-256-GCM decryption (apiV3Key) + optional platform-cert verification (enforced when platformPublicKeyPem is set) + time-window/nonce anti-replay
+ *  - Channel self-verification path: callbacks bypass the framework's generic HMAC protocol; this driver verifies the channel itself
+ *
+ * Dependencies: node:crypto (Node built-in, zero third-party). Sandbox needs sandbox keys/certs from the merchant platform (configure baseUrl per the sandbox docs when integrating).
+ */
+import { createDecipheriv, createPrivateKey, createPublicKey, randomBytes, sign, verify, } from 'node:crypto';
+const DEFAULT_BASE = 'https://api.mch.weixin.qq.com';
+function isWxResource(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    return typeof r['ciphertext'] === 'string' && typeof r['nonce'] === 'string';
+}
+export function createWechatOfficialDriver(store, options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE;
+    const timeWindowSec = options.timeWindowSec ?? 300;
+    const fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    const privateKey = createPrivateKey(options.privateKeyPem);
+    const platformKey = options.platformPublicKeyPem
+        ? createPublicKey(options.platformPublicKeyPem)
+        : undefined;
+    /** API v3 request signature header. */
+    function authorizeHeader(method, urlPath, body) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const nonce = randomBytes(16).toString('hex');
+        const message = `${method}\n${urlPath}\n${timestamp}\n${nonce}\n${body}\n`;
+        const signature = sign('RSA-SHA256', Buffer.from(message), privateKey).toString('base64');
+        return `WECHATPAY2-SHA256-RSA2048 mchid="${options.mchId}",nonce_str="${nonce}",signature="${signature}",timestamp="${timestamp}",serial_no="${options.serialNo}"`;
+    }
+    async function request(method, urlPath, body) {
+        const headers = {
+            Authorization: authorizeHeader(method, urlPath, body ?? ''),
+            Accept: 'application/json',
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const res = await fetchImpl(`${baseUrl}${urlPath}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`wechat_api_error:${res.status}:${text}`);
+        }
+        return JSON.parse(text);
+    }
+    /** JSAPI invocation params (for the frontend wx.requestPayment): paySign signed with the merchant private key. */
+    function buildJsapiParams(prepayId) {
+        const timeStamp = String(Math.floor(Date.now() / 1000));
+        const nonceStr = randomBytes(16).toString('hex');
+        const pkg = `prepay_id=${prepayId}`;
+        const message = `${options.appId}\n${timeStamp}\n${nonceStr}\n${pkg}\n`;
+        const paySign = sign('RSA-SHA256', Buffer.from(message), privateKey).toString('base64');
+        return {
+            appId: options.appId,
+            timeStamp,
+            nonceStr,
+            package: pkg,
+            signType: 'RSA',
+            paySign,
+        };
+    }
+    async function createOrder(input) {
+        const base = {
+            appid: options.appId,
+            mchid: options.mchId,
+            description: input.subject,
+            out_trade_no: input.orderId,
+            notify_url: input.notifyUrl,
+            amount: { total: input.amount, currency: 'CNY' },
+        };
+        const openid = input.extras?.['openid'];
+        if (input.scene === 'miniapp' || (input.scene === 'h5' && typeof openid === 'string')) {
+            // JSAPI (official account / miniapp webview; requires openid)
+            const res = await request('POST', '/v3/pay/transactions/jsapi', JSON.stringify({ ...base, payer: { openid } }));
+            return { kind: 'jsapi', payParams: buildJsapiParams(res.prepay_id) };
+        }
+        if (input.scene === 'pc') {
+            // Native scan-to-pay
+            const res = await request('POST', '/v3/pay/transactions/native', JSON.stringify(base));
+            return {
+                kind: 'qr',
+                qrUrl: res.code_url,
+                expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+            };
+        }
+        // H5 (mobile browser)
+        const h5Input = {
+            ...base,
+            scene_info: {
+                payer_client_ip: input.extras?.['clientIp'] ?? '127.0.0.1',
+                h5_info: { type: 'Wap' },
+            },
+        };
+        const res = await request('POST', '/v3/pay/transactions/h5', JSON.stringify(h5Input));
+        return { kind: 'redirect', payUrl: res.h5_url };
+    }
+    function verifyCallback(payload, headers) {
+        const h = (headers ?? {});
+        const ts = h['wechatpay-timestamp'];
+        const nonce = h['wechatpay-nonce'];
+        const signature = h['wechatpay-signature'];
+        if (!ts || !nonce) {
+            return { ok: false, reason: 'missing_wechatpay_headers' };
+        }
+        // time-window check (anti-replay)
+        if (Math.abs(Date.now() / 1000 - Number(ts)) > timeWindowSec) {
+            return { ok: false, reason: 'timestamp_expired' };
+        }
+        // nonce anti-replay (channel self-verify path; the driver dedups via the store)
+        if (!store.addNonce(`wx:${nonce}`)) {
+            return { ok: false, reason: 'nonce_reused' };
+        }
+        // optional: platform-cert verification (signed string = timestamp\nnonce\nbody\n)
+        if (platformKey) {
+            const rawBody = typeof payload === 'string' ? payload : JSON.stringify(payload);
+            const ok = verify('RSA-SHA256', Buffer.from(`${ts}\n${nonce}\n${rawBody}\n`), platformKey, Buffer.from(signature ?? '', 'base64'));
+            if (!ok) {
+                return { ok: false, reason: 'bad_platform_signature' };
+            }
+        }
+        // AES-256-GCM decrypt (apiV3Key confidentiality → successful decryption proves the message came from WeChat)
+        let obj;
+        try {
+            obj =
+                typeof payload === 'string'
+                    ? JSON.parse(payload)
+                    : payload;
+            const resource = obj['resource'];
+            if (!isWxResource(resource)) {
+                return { ok: false, reason: 'bad_resource' };
+            }
+            // WeChat ciphertext format: ciphertext = encrypted || authTag(16B)
+            const buf = Buffer.from(resource.ciphertext, 'base64');
+            const decipher = createDecipheriv('aes-256-gcm', Buffer.from(options.apiV3Key), Buffer.from(resource.nonce));
+            if (resource.associated_data)
+                decipher.setAAD(Buffer.from(resource.associated_data));
+            decipher.setAuthTag(buf.subarray(buf.length - 16));
+            const plain = Buffer.concat([
+                decipher.update(buf.subarray(0, buf.length - 16)),
+                decipher.final(),
+            ]).toString('utf8');
+            const data = JSON.parse(plain);
+            if (data['trade_state'] !== 'SUCCESS') {
+                return { ok: false, reason: `trade_state:${String(data['trade_state'])}` };
+            }
+            const amount = data['amount'];
+            const orderId = data['out_trade_no'];
+            const paidAmount = amount?.['total'];
+            if (typeof orderId !== 'string' || typeof paidAmount !== 'number') {
+                return { ok: false, reason: 'bad_payload' };
+            }
+            return {
+                ok: true,
+                orderId,
+                paidAmount,
+                ...(typeof data['transaction_id'] === 'string'
+                    ? { channelTxnId: data['transaction_id'] }
+                    : {}),
+            };
+        }
+        catch {
+            return { ok: false, reason: 'decrypt_failed' };
+        }
+    }
+    async function queryOrder(orderId) {
+        try {
+            const urlPath = `/v3/pay/transactions/out-trade-no/${encodeURIComponent(orderId)}?mchid=${options.mchId}`;
+            const res = await request('GET', urlPath);
+            const state = res.trade_state;
+            if (state === 'SUCCESS') {
+                return { state: 'paid', ...(res.success_time ? { paidAt: res.success_time } : {}) };
+            }
+            if (state === 'CLOSED' || state === 'PAYERROR') {
+                return { state: 'closed' };
+            }
+            return { state: 'created' };
+        }
+        catch {
+            return { state: 'unknown', raw: { error: 'query_failed' } };
+        }
+    }
+    return {
+        name: 'wechat_official',
+        scenes: ['pc', 'h5', 'miniapp'],
+        createOrder,
+        verifyCallback,
+        queryOrder,
+        successResponseText: 'SUCCESS',
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vobs/payment",
+  "version": "0.1.0",
+  "description": "Payment factory backend SDK for vobs — channel drivers, order state machine, callback verification (signature + replay protection), server-side pricing and amount risk control (Experimental).",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "vobsjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vobsjs/vobs.git",
+    "directory": "packages/integrations/payment"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bugs": {
+    "url": "https://github.com/vobsjs/vobs/issues"
+  },
+  "homepage": "https://github.com/vobsjs/vobs#readme",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false
+}