@vobs/payment 0.3.0 → 1.2.0

package/dist/state-machine.d.ts

@@ -1,41 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/payment
- */
-/**
- * Order state machine (pure functions, no I/O).
- *
- * Transitions (no refund path):
- *   created ──normal callback──▶ paid            (idempotent: a paid order ignores repeated callbacks)
- *   created ──close───▶ closed ──callback again──▶ frozen (payment after close = money-losing anomaly, manual review)
- *   created ──amount mismatch──▶ frozen           (conflict freeze: never auto-book)
- *   created ──paid ≥ auditThreshold──▶ pending (large amount, manual review)──confirm──▶ paid
- *   zero-amount orders are paid immediately (no channel)
- */
-import type { OrderState } from './types.js';
-export type CallbackTransition = {
-    readonly state: OrderState;
-    readonly reason?: string;
-} | {
-    readonly state: 'paid';
-    readonly idempotent: boolean;
-    readonly reason?: string;
-};
-/**
- * Apply a payment callback to an order.
- * @param orderState current state
- * @param orderAmount order amount (fen)
- * @param paidAmount  channel-paid amount (fen)
- * @param auditThreshold large-amount audit threshold (fen); absent/0 = no audit
- */
-export declare function applyPaidCallback(orderState: OrderState, orderAmount: number, paidAmount: number, auditThreshold?: number): CallbackTransition;
-/** Approve a large amount: only pending (audit) → paid. */
-export declare function applyConfirm(orderState: OrderState): {
-    state: OrderState;
-    ok: boolean;
-};
-/** Close on timeout/cancel: only created → closed. */
-export declare function applyClose(orderState: OrderState): {
-    state: OrderState;
-    ok: boolean;
-};

package/dist/state-machine.js

@@ -1,60 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/payment
- */
-/**
- * Order state machine (pure functions, no I/O).
- *
- * Transitions (no refund path):
- *   created ──normal callback──▶ paid            (idempotent: a paid order ignores repeated callbacks)
- *   created ──close───▶ closed ──callback again──▶ frozen (payment after close = money-losing anomaly, manual review)
- *   created ──amount mismatch──▶ frozen           (conflict freeze: never auto-book)
- *   created ──paid ≥ auditThreshold──▶ pending (large amount, manual review)──confirm──▶ paid
- *   zero-amount orders are paid immediately (no channel)
- */
-/**
- * Apply a payment callback to an order.
- * @param orderState current state
- * @param orderAmount order amount (fen)
- * @param paidAmount  channel-paid amount (fen)
- * @param auditThreshold large-amount audit threshold (fen); absent/0 = no audit
- */
-export function applyPaidCallback(orderState, orderAmount, paidAmount, auditThreshold) {
-    // freeze on conflict: paid ≠ order amount (security red line, never auto-book; discount net amounts are judged by the channel, differences go through amountTolerance evaluated by the business)
-    if (paidAmount !== orderAmount) {
-        return { state: 'frozen', reason: 'amount_mismatch' };
-    }
-    switch (orderState) {
-        case 'paid':
-            // idempotent: don't book twice (callback retry/redelivery)
-            return { state: 'paid', idempotent: true };
-        case 'closed':
-            // payment after close → anomaly, manual review
-            return { state: 'frozen', reason: 'paid_after_close' };
-        case 'frozen':
-            return { state: 'frozen' };
-        case 'pending':
-            return { state: 'pending' };
-        default: {
-            // created: large amount awaits manual audit (pending = 'unconfirmed': channel delay or audit)
-            if (auditThreshold && auditThreshold > 0 && paidAmount >= auditThreshold) {
-                return { state: 'pending', reason: 'audit' };
-            }
-            return { state: 'paid' };
-        }
-    }
-}
-/** Approve a large amount: only pending (audit) → paid. */
-export function applyConfirm(orderState) {
-    if (orderState === 'pending') {
-        return { state: 'paid', ok: true };
-    }
-    return { state: orderState, ok: false };
-}
-/** Close on timeout/cancel: only created → closed. */
-export function applyClose(orderState) {
-    if (orderState === 'created') {
-        return { state: 'closed', ok: true };
-    }
-    return { state: orderState, ok: false };
-}

package/dist/store.d.ts

@@ -1,33 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/payment
- */
-/**
- * Order storage abstraction (P0 in-memory; for a production DB see the design doc's production checklist:
- * unique constraints back idempotency, row locks/CAS prevent concurrent double-writes, idempotency records and nonces with TTL).
- */
-import type { AuditEntry, OrderRecord } from './types.js';
-export interface PaymentStore {
-    getOrder(orderId: string): OrderRecord | undefined;
-    /** Atomically reserves an order id before a channel call. Returns false when it is already reserved or persisted. */
-    reserveOrder(orderId: string): boolean;
-    /** Releases an unpersisted reservation after a failed create attempt. */
-    releaseOrderReservation(orderId: string): void;
-    saveOrder(order: OrderRecord): void;
-    /** Iterate all orders (for expiry scans; production implementations should paginate/index). */
-    allOrders(): readonly OrderRecord[];
-    /** nonce dedup (anti-replay): returns true on first use. */
-    addNonce(nonce: string): boolean;
-    getOrderByIdempotencyKey(key: string): string | undefined;
-    setIdempotencyKey(key: string, orderId: string): void;
-    appendAudit(entry: AuditEntry): void;
-    auditLog(): readonly AuditEntry[];
-}
-export interface MemoryStoreOptions {
-    /** Retention for callback nonces and idempotency keys. Defaults to 24 hours. */
-    readonly retentionMs?: number;
-    /** Maximum retained audit entries. Defaults to 10,000. */
-    readonly maxAuditEntries?: number;
-}
-/** In-memory implementation. Production stores must back reserveOrder with a unique constraint or transaction. */
-export declare function createMemoryStore(options?: MemoryStoreOptions): PaymentStore;

package/dist/store.js

@@ -1,76 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/payment
- */
-/**
- * Order storage abstraction (P0 in-memory; for a production DB see the design doc's production checklist:
- * unique constraints back idempotency, row locks/CAS prevent concurrent double-writes, idempotency records and nonces with TTL).
- */
-/** In-memory implementation. Production stores must back reserveOrder with a unique constraint or transaction. */
-export function createMemoryStore(options = {}) {
-    const retentionMs = options.retentionMs ?? 24 * 60 * 60 * 1000;
-    const maxAuditEntries = options.maxAuditEntries ?? 10_000;
-    const orders = new Map();
-    const reservations = new Set();
-    const nonces = new Map();
-    const idempotency = new Map();
-    const audit = [];
-    const pruneExpired = (now) => {
-        for (const [nonce, expiresAt] of nonces) {
-            if (expiresAt <= now)
-                nonces.delete(nonce);
-        }
-        for (const [key, entry] of idempotency) {
-            if (entry.expiresAt <= now)
-                idempotency.delete(key);
-        }
-    };
-    return {
-        getOrder(orderId) {
-            return orders.get(orderId);
-        },
-        reserveOrder(orderId) {
-            if (orders.has(orderId) || reservations.has(orderId))
-                return false;
-            reservations.add(orderId);
-            return true;
-        },
-        releaseOrderReservation(orderId) {
-            reservations.delete(orderId);
-        },
-        saveOrder(order) {
-            orders.set(order.orderId, order);
-            reservations.delete(order.orderId);
-        },
-        allOrders() {
-            return Array.from(orders.values());
-        },
-        addNonce(nonce) {
-            const now = Date.now();
-            pruneExpired(now);
-            if (nonces.has(nonce))
-                return false;
-            nonces.set(nonce, now + retentionMs);
-            return true;
-        },
-        getOrderByIdempotencyKey(key) {
-            const now = Date.now();
-            pruneExpired(now);
-            return idempotency.get(key)?.orderId;
-        },
-        setIdempotencyKey(key, orderId) {
-            const now = Date.now();
-            pruneExpired(now);
-            idempotency.set(key, { orderId, expiresAt: now + retentionMs });
-        },
-        appendAudit(entry) {
-            audit.push(entry);
-            if (audit.length > maxAuditEntries) {
-                audit.splice(0, audit.length - maxAuditEntries);
-            }
-        },
-        auditLog() {
-            return audit;
-        },
-    };
-}

package/dist/types.d.ts

@@ -1,168 +0,0 @@
-/** @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;
-};
-/** Callback authentication owner. Unspecified drivers use the manager HMAC protocol. */
-export type PaymentCallbackVerification = 'manager-hmac' | 'driver';
-/** Unified payment driver contract (three capabilities: createOrder / verifyCallback / queryOrder). */
-export interface PaymentDriver {
-    readonly name: string;
-    readonly scenes: readonly PaymentScene[];
-    /**
-     * Declares who authenticates callbacks. Real channel drivers use `driver`; custom drivers
-     * default to the manager HMAC protocol and therefore require the X-* callback headers.
-     */
-    readonly callbackVerification?: PaymentCallbackVerification;
-    /** 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;
-    /** Business delivery state after a paid transition. Failed delivery remains pending for retry. */
-    deliveryState?: 'pending' | 'delivered';
-    deliveryError?: 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 duplicateStrategy?: 'reuse' | 'replace' | 'reject' | 'ask';
-    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/delivery all logged). */
-export interface AuditEntry {
-    readonly operation: 'create' | 'callback' | 'close' | 'confirm' | 'freeze' | 'delivery';
-    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

@@ -1,11 +0,0 @@
-/** @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

@@ -1,34 +0,0 @@
-/** @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

@@ -1,55 +0,0 @@
-/** @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

@@ -1,40 +0,0 @@
-/** @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;