@seasonkoh/webaz 0.1.27 → 0.1.29

package/dist/direct-pay-launch-readiness.js

@@ -0,0 +1,108 @@
+import { readDirectPayControlsConfig, sellerDirectPayBreakerTripped, sellerDirectPayKybPassed, sellerDirectPaySanctionsClear, sellerDirectPayAmlClear, } from './direct-pay-controls.js';
+import { sellerHasProductionBaseBondLocked } from './direct-receive-deposits.js';
+import { sellerBaseBondEntrySatisfied } from './direct-pay-base-bond-entry.js';
+import { getActiveDeferral } from './direct-receive-deferral.js';
+import { bondRailClearanceBlockers, isBondRailClearedForProduction } from './direct-pay-bond-rail-clearance.js';
+import { getActivePaymentInstruction } from './direct-receive-payment-instruction.js';
+/** 候选生产 base-bond 收款轨(与 #112 registry 一致;manual 是非生产确认轨,不算)。 */
+// 候选生产 base-bond 收款轨。operator_attested(#116,已实现的运营核实轨)是 v1 实际要用的那条,必须纳入诊断,
+//   否则它被 registry 放行后 readiness 仍误报"无 legal-cleared rail"。manual=非生产确认轨,不算。
+const PRODUCTION_BOND_RAILS = ['operator_attested', 'usdc_onchain', 'fiat_psp'];
+/**
+ * 只读 readiness 汇总。args.getProtocolParam 读控制面配置;args.sellerId 提供时附加 seller-specific blockers。
+ * ready ⟺ blockers 为空。绝不写库。
+ */
+export function readDirectPayLaunchReadiness(db, args) {
+    const { getProtocolParam, sellerId } = args;
+    const cfg = readDirectPayControlsConfig(getProtocolParam);
+    const blockers = [];
+    // ── global / policy(镜像 evaluateDirectPayLaunchControls 的非订单条件;不短路,收集全部)──
+    if (cfg.enabled !== true)
+        blockers.push('DIRECT_PAY_NOT_ENABLED');
+    if (cfg.railBreakerTripped === true)
+        blockers.push('DIRECT_PAY_RAIL_BREAKER_TRIPPED');
+    const allow = Array.isArray(cfg.regionAllowlist) ? cfg.regionAllowlist : [];
+    if (!allow.length || !cfg.region || !allow.includes(cfg.region))
+        blockers.push('DIRECT_PAY_REGION_NOT_ALLOWED');
+    if (!(Number.isSafeInteger(cfg.perTxCapUnits) && cfg.perTxCapUnits > 0))
+        blockers.push('DIRECT_PAY_PER_TX_CAP_UNSET');
+    // ── production bond-rail clearance(#112;rail-level,jurisdiction-aware)── 【诊断 facts,非 launch blocker】
+    //   关键:真实建单/可用性门(evaluateDirectPayLaunchControls + direct-pay-create/availability)从不校验 rail-clearance。
+    //   rail-clearance 只 gate【有人交真实保证金】这一条路(confirmProductionReceipt 的 Lock B);缓交卖家根本不交 bond,
+    //   也就不需要任何 cleared rail 即可直付。因此把 rail-clearance 当全局 launch blocker 会让 readiness 误报"未开放"——
+    //   与真实门不一致(Codex #117 P1)。这里只【计算并下发为诊断 facts】(anyRailLegalCleared / perRailClearance),
+    //   供运营判断"若要接收真实保证金,bonded-deposit 轨是否就绪",但绝不进 blockers / 不影响 ready / PLATFORM_OPEN。
+    const perRailClearance = {};
+    for (const rid of PRODUCTION_BOND_RAILS)
+        perRailClearance[rid] = bondRailClearanceBlockers(rid, { hasProductionReceipt: true });
+    // jurisdiction-aware:把【当前部署 region】传进去,校验 region ∈ rail 的 legal jurisdictionAllowlist(coarse 判定会误报 cleared)。
+    const anyRailLegalCleared = PRODUCTION_BOND_RAILS.some(rid => isBondRailClearedForProduction(rid, cfg.region));
+    // ── seller-specific(仅当传入 sellerId)──
+    let sellerSuspended = null, productionBaseBondLocked = null;
+    let activeDeferral = null, baseBondSatisfied = null;
+    let kybPassed = null, sanctionsClear = null, amlClear = null;
+    let paymentInstructionPresent = null;
+    if (sellerId) {
+        const nowIso = new Date().toISOString();
+        sellerSuspended = sellerDirectPayBreakerTripped(db, sellerId);
+        productionBaseBondLocked = sellerHasProductionBaseBondLocked(db, sellerId);
+        activeDeferral = getActiveDeferral(db, sellerId, nowIso) != null;
+        // 镜像 create gate(direct-pay-base-bond-entry):保证金门 = 生产 bond OR 有效缓交。
+        baseBondSatisfied = sellerBaseBondEntrySatisfied(db, sellerId, nowIso);
+        kybPassed = sellerDirectPayKybPassed(db, sellerId);
+        sanctionsClear = sellerDirectPaySanctionsClear(db, sellerId);
+        amlClear = sellerDirectPayAmlClear(db, sellerId);
+        // 镜像真实建单硬门(direct-pay-create.ts):无 active 收款说明 → create 返回 NO_PAYMENT_INSTRUCTION,绝不建单。
+        paymentInstructionPresent = getActivePaymentInstruction(db, sellerId) != null;
+        if (sellerSuspended)
+            blockers.push('DIRECT_PAY_SELLER_SUSPENDED');
+        // 与 create gate 一致:有生产 bond 或有效缓交即满足;两者都无才 blocker。
+        if (!baseBondSatisfied)
+            blockers.push('DIRECT_PAY_SELLER_NO_PRODUCTION_BASE_BOND');
+        if (!kybPassed)
+            blockers.push('DIRECT_PAY_SELLER_KYB_NOT_APPROVED');
+        if (!sanctionsClear)
+            blockers.push('DIRECT_PAY_SELLER_SANCTIONS_NOT_CLEARED');
+        if (!amlClear)
+            blockers.push('DIRECT_PAY_SELLER_AML_REVIEW_REQUIRED');
+        if (!paymentInstructionPresent)
+            blockers.push('DIRECT_PAY_SELLER_PAYMENT_INSTRUCTION_MISSING');
+    }
+    return {
+        ready: blockers.length === 0,
+        blockers,
+        facts: {
+            enabled: cfg.enabled, railBreakerTripped: cfg.railBreakerTripped, region: cfg.region,
+            regionAllowlist: cfg.regionAllowlist, perTxCapUnits: cfg.perTxCapUnits,
+            perRailClearance, anyRailLegalCleared,
+            sellerEvaluated: !!sellerId, sellerId: sellerId ?? null,
+            sellerSuspended, productionBaseBondLocked, activeDeferral, baseBondSatisfied, kybPassed, sanctionsClear, amlClear, paymentInstructionPresent,
+        },
+    };
+}
+// PLATFORM_OPEN 只折叠【真实全局建单门】(镜像 evaluateDirectPayLaunchControls 的非订单条件):enabled / rail-breaker /
+//   region / per-tx cap。rail-clearance 不在此列(它不 gate 直付,见上),否则缓交卖家会被误显示"平台未开放"。
+const GLOBAL_LAUNCH_BLOCKERS = new Set([
+    'DIRECT_PAY_NOT_ENABLED', 'DIRECT_PAY_RAIL_BREAKER_TRIPPED', 'DIRECT_PAY_REGION_NOT_ALLOWED', 'DIRECT_PAY_PER_TX_CAP_UNSET',
+]);
+/**
+ * 卖家脱敏 readiness 视图。复用 readDirectPayLaunchReadiness(只读),把内部 blockers/facts 折叠成卖家安全的项目集。
+ * 输出【不含】任何 raw blocker code、KYB/sanctions/AML 分项或法务/rail 细节。纯读。
+ */
+export function sellerDirectPayReadinessView(db, args) {
+    const { getProtocolParam, sellerId } = args;
+    const r = readDirectPayLaunchReadiness(db, { getProtocolParam, sellerId });
+    const f = r.facts;
+    const platformOpen = !r.blockers.some(b => GLOBAL_LAUNCH_BLOCKERS.has(b));
+    const hasPasskey = !!db.prepare('SELECT 1 FROM webauthn_credentials WHERE user_id = ? LIMIT 1').get(sellerId);
+    const complianceCleared = f.kybPassed === true && f.sanctionsClear === true && f.amlClear === true; // 折叠;不分项
+    const items = [
+        { code: 'PLATFORM_OPEN', ok: platformOpen, actionable: false },
+        { code: 'PAYMENT_INSTRUCTION', ok: f.paymentInstructionPresent === true, actionable: true },
+        { code: 'PASSKEY', ok: hasPasskey, actionable: true },
+        { code: 'BASE_BOND', ok: f.baseBondSatisfied === true, actionable: false }, // 生产 bond 或有效缓交即算满足(与 create gate 一致)
+        { code: 'COMPLIANCE_REVIEW', ok: complianceCleared, actionable: false },
+        { code: 'NOT_SUSPENDED', ok: f.sellerSuspended === false, actionable: false },
+    ];
+    return { directPayReady: items.every(i => i.ok), items };
+}

package/dist/direct-pay-launch-summary.js

@@ -0,0 +1,68 @@
+import { readDirectPayLaunchReadiness } from './direct-pay-launch-readiness.js';
+import { readDirectPayControlsConfig } from './direct-pay-controls.js';
+import { checkDeferralQuota, readDeferralQuotaConfig } from './direct-pay-deferral-quota.js';
+import { productStoreVerified } from './product-verification.js';
+import { sellerExemptFromPerProduct } from './store-verification.js';
+import { toUnits } from './money.js';
+/** 候选卖家:在任一 direct-pay 相关表里出现过的卖家(有意接入直付者)。 */
+function candidateSellers(db) {
+    const rows = db.prepare(`
+    SELECT DISTINCT seller_id FROM (
+      SELECT seller_id FROM direct_receive_payment_instructions WHERE status = 'active'
+      UNION SELECT user_id   FROM direct_receive_deferrals
+      UNION SELECT user_id   FROM direct_receive_deposits
+      UNION SELECT seller_id FROM product_verifications
+      UNION SELECT user_id   FROM store_verifications
+    ) WHERE seller_id IS NOT NULL
+  `).all();
+    return rows.map(r => r.seller_id);
+}
+/** 聚合 go/no-go。纯读。getProtocolParam 由调用方按部署注入(CLI 从 protocol_params 构造)。 */
+export function summarizeDirectPayLaunchReadiness(db, getProtocolParam) {
+    const globalRd = readDirectPayLaunchReadiness(db, { getProtocolParam }); // 无 sellerId → 仅全局 blockers
+    const global = { ready: globalRd.blockers.length === 0, blockers: globalRd.blockers, facts: globalRd.facts };
+    const globalSet = new Set(global.blockers);
+    const nowIso = new Date().toISOString();
+    const quotaCfg = readDeferralQuotaConfig(getProtocolParam);
+    const controlsCfg = readDirectPayControlsConfig(getProtocolParam);
+    const sellers = candidateSellers(db).map(sellerId => {
+        const rd = readDirectPayLaunchReadiness(db, { getProtocolParam, sellerId });
+        // 仅 seller-specific blockers(去掉全局 blockers,避免每个卖家都重复挂全局问题)。
+        const sellerBlockers = rd.blockers.filter(b => !globalSet.has(b));
+        const ready = sellerBlockers.length === 0;
+        const storeExempt = sellerExemptFromPerProduct(db, sellerId);
+        const products = db.prepare("SELECT id, price, stock, has_variants FROM products WHERE seller_id = ? AND status = 'active'").all(sellerId);
+        // 可直付商品 = 必须能真正走 direct_p2p 建单(镜像 create gate / evaluateDirectPayLaunchControls + 建单库存门),全部满足:
+        //   ① 简单商品(direct_p2p v1 拒规格商品 has_variants=1);② 逐品 verified 或卖家店铺豁免;
+        //   ③ 单笔上限:amount>0 且 ≤ perTxCapUnits(且 cap 已配 >0)—— 镜像 DIRECT_PAY_CAP_EXCEEDED;
+        //   ④ 有货(stock≥1)—— 镜像 createDirectPayOrder 的 `stock >= qty`(否则 'stock depleted');
+        //   ⑤ 无进行中限时促销(direct_p2p v1 拒 flash_sale=DIRECT_PAY_UNSUPPORTED_OPTION;谓词镜像 getActiveFlashSale@flash-sales.ts 的简单商品分支);
+        //   ⑥ 通过缓交额度(checkDeferralQuota qty=1 该单价;非缓交卖家=no-op)。否则报告会误判 go=true 而真实下单被拒。
+        const flashActive = db.prepare(`SELECT 1 FROM flash_sales WHERE product_id = ? AND is_active = 1
+      AND starts_at <= datetime('now') AND ends_at > datetime('now') AND (max_qty = 0 OR sold_count < max_qty) AND variant_id IS NULL LIMIT 1`);
+        const eligibleProductCount = products.filter(p => {
+            const priceU = toUnits(Number(p.price) || 0);
+            return Number(p.has_variants) !== 1
+                && (storeExempt || productStoreVerified(db, p.id))
+                && controlsCfg.perTxCapUnits > 0 && priceU > 0 && priceU <= controlsCfg.perTxCapUnits
+                && Number(p.stock) >= 1
+                && !flashActive.get(p.id)
+                && checkDeferralQuota(db, sellerId, priceU, nowIso, quotaCfg).ok;
+        }).length;
+        return { sellerId, ready, blockers: sellerBlockers, storeExempt, activeProductCount: products.length, eligibleProductCount, launchable: ready && eligibleProductCount > 0 };
+    });
+    const launchableSellerCount = sellers.filter(s => s.launchable).length;
+    // PRE-FLIP 自检:忽略【且仅忽略】"总开关未开"这一项,回答"除了翻 enabled,还差什么"。其余(region/cap/卖家/商品)照常要求。
+    const preflipReady = global.blockers.filter(b => b !== 'DIRECT_PAY_NOT_ENABLED').length === 0;
+    const pendingEnable = global.facts.enabled !== true;
+    return {
+        go: global.ready && launchableSellerCount > 0, // LIVE(含 enabled)
+        preflipGo: preflipReady && launchableSellerCount > 0, // 只差翻 enabled 即就绪
+        pendingEnable,
+        global, sellers, launchableSellerCount,
+    };
+}
+/** 便捷:从控制面配置取关键运营数值(供 CLI 打印)。 */
+export function directPayControlsSnapshot(getProtocolParam) {
+    return readDirectPayControlsConfig(getProtocolParam);
+}

package/dist/direct-pay-ledger.js

@@ -0,0 +1,94 @@
+import { toUnits, toDecimal, allocate } from './money.js';
+import { applyWalletDelta, walletUnits, creditColumns } from './ledger.js';
+/**
+ * penalty 科目【唯一】写入口(只进,无对应出账函数)。
+ *   - source='fee_stake' → 真入 WAZ balance(fee-stake 本就是 WAZ)。
+ *   - source='base_bond' → 仅记 provenance 计数(外部资产,真实处置 gated;不进 balance)。
+ */
+function creditPenalty(db, opts) {
+    const { kind, source, fromUserId = null, amountU, relatedOrderId = null, reason = null, txnId } = opts;
+    const deltas = source === 'fee_stake'
+        ? { balance: amountU, total_fee_stake_slash: amountU } // WAZ 真入池
+        : { total_base_bond_slash: amountU }; // 外部资产:仅计数,不进 balance
+    creditColumns(db, 'penalty_fund', "id = 'main'", [], deltas);
+    db.prepare("UPDATE penalty_fund SET updated_at = datetime('now') WHERE id = 'main'").run();
+    db.prepare(`INSERT INTO penalty_fund_txns (id, kind, source, from_user_id, amount, related_order_id, reason, created_at) VALUES (?,?,?,?,?,?,?,datetime('now'))`)
+        .run(txnId, kind, source, fromUserId, toDecimal(amountU), relatedOrderId, reason);
+}
+function getStake(db, orderId) {
+    return db.prepare('SELECT id, order_id, seller_id, amount, status FROM direct_pay_fee_stakes WHERE order_id = ?')
+        .get(orderId);
+}
+/** 只读断言:订单是否有【locked】fee-stake(可在完成时取费)。完成路径预检用,缺则拒绝 direct_p2p 进 completed。 */
+export function hasLockedFeeStake(db, orderId) {
+    return getStake(db, orderId)?.status === 'locked';
+}
+/** 锁定逐单费用质押(= 平台费):卖家可用余额 → fee_staked。余额不足返回 {ok:false}(调用方不开单)。 */
+export function lockFeeStake(db, opts) {
+    const { orderId, sellerId, feeUnits, stakeId } = opts;
+    if (feeUnits <= 0)
+        return { ok: false, reason: 'fee must be > 0' };
+    if (getStake(db, orderId))
+        return { ok: false, reason: 'fee-stake already exists for order' };
+    const w = walletUnits(db, sellerId);
+    if (w.balance < feeUnits)
+        return { ok: false, reason: 'insufficient balance for fee-stake' };
+    applyWalletDelta(db, sellerId, { balance: -feeUnits, fee_staked: feeUnits });
+    db.prepare(`INSERT INTO direct_pay_fee_stakes (id, order_id, seller_id, amount, status, created_at) VALUES (?,?,?,?, 'locked', datetime('now'))`)
+        .run(stakeId, orderId, sellerId, toDecimal(feeUnits));
+    return { ok: true };
+}
+/**
+ * 完成时取费:整笔 fee-stake → 协议(reserve 50% + sys_protocol 50%,与 settleOrder 协议费去向一致)。
+ * **FAIL-CLOSED(钱路不变量):** direct_p2p 单完成必须有可取的 locked fee-stake,否则平台费会被静默落空。
+ *   - 无 stake 行 / 状态非 locked 且非 fee_taken → **抛错**(调用方 settleOrder 在 db.transaction 内 → 回滚,
+ *     拒绝"完成但零平台费")。绝不静默 return(那正是审计 P1-2 指出的 fail-open 漏洞)。
+ *   - 已 fee_taken → 幂等:返回 'already_taken',不重复取费(支持重结算)。
+ * fee-stake == 平台费,故无 remainder(若将来 stake>fee 可在此退差额给卖家)。
+ */
+export function takeFeeAtCompletion(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s)
+        throw new Error(`takeFeeAtCompletion: no fee-stake for direct_p2p order ${opts.orderId} — refusing to settle without platform fee (fail-closed)`);
+    if (s.status === 'fee_taken')
+        return { outcome: 'already_taken' }; // 幂等:重结算不重复取费
+    if (s.status !== 'locked')
+        throw new Error(`takeFeeAtCompletion: fee-stake for order ${opts.orderId} is '${s.status}', not 'locked' — refusing to settle (fail-closed)`);
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU });
+    const [toReserveU, toOpsU] = allocate(feeU, [1, 1]);
+    if (toReserveU > 0)
+        creditColumns(db, 'protocol_reserve_pool', 'id = 1', [], { balance: toReserveU });
+    if (toOpsU > 0)
+        applyWalletDelta(db, 'sys_protocol', { balance: toOpsU });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='fee_taken', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+    return { outcome: 'taken' };
+}
+/** 释放(未付/取消/超时):整笔退回卖家可用余额。幂等。 */
+export function releaseFeeStake(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s || s.status !== 'locked')
+        return;
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU, balance: feeU });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='released', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+}
+/** 违约罚没:整笔 fee-stake → penalty 科目(feeRetainedOnFault=false → WebAZ 不收费,整笔入池)。幂等。 */
+export function slashFeeStakeToPenalty(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s || s.status !== 'locked')
+        return;
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU });
+    creditPenalty(db, { kind: 'fee_stake_slash', source: 'fee_stake', fromUserId: s.seller_id, amountU: feeU, relatedOrderId: opts.orderId, reason: opts.reason ?? null, txnId: opts.txnId });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='slashed', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+}
+/**
+ * base bond(外部担保物)罚没:仅记 provenance(total_base_bond_slash + txn),不进 WAZ balance。
+ * 真实外部资产(USDC/法币)处置 GATED(deposit-rail 非生产 / 法务)。由 Phase 4 deposit 生命周期调用。
+ */
+export function recordBaseBondSlash(db, opts) {
+    if (opts.amountUnits <= 0)
+        return;
+    creditPenalty(db, { kind: 'base_bond_slash', source: 'base_bond', fromUserId: opts.userId, amountU: opts.amountUnits, relatedOrderId: null, reason: opts.reason ?? null, txnId: opts.txnId });
+}

package/dist/direct-receive-account-qr.js

@@ -0,0 +1,77 @@
+import { createHash } from 'crypto';
+export const QR_DATA_URI_RE = /^data:image\/(png|webp);base64,[A-Za-z0-9+/=]+$/;
+export const QR_MAX_BYTES = 64 * 1024;
+/** PNG magic 8 bytes / WEBP RIFF....WEBP。仅接受与声明 mime 一致的字节。 */
+function magicMatches(subtype, buf) {
+    if (subtype === 'png')
+        return buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    if (subtype === 'webp')
+        return buf.length >= 12 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP';
+    return false;
+}
+/** PURE: 校验收款码 data-URI。返回 {ok, ...} 或 {ok:false, reason}。绝不解析二维码。 */
+export function validateQrDataUri(dataUri) {
+    const s = typeof dataUri === 'string' ? dataUri.trim() : '';
+    const m = QR_DATA_URI_RE.exec(s);
+    if (!m)
+        return { ok: false, reason: 'QR must be a data:image/(png|webp);base64 image (svg/html/text/jpeg rejected)' };
+    const subtype = m[1];
+    let buf;
+    try {
+        buf = Buffer.from(s.slice(s.indexOf(',') + 1), 'base64');
+    }
+    catch {
+        return { ok: false, reason: 'QR base64 decode failed' };
+    }
+    if (buf.length === 0)
+        return { ok: false, reason: 'QR is empty' };
+    if (buf.length > QR_MAX_BYTES)
+        return { ok: false, reason: `QR must decode to ≤ ${QR_MAX_BYTES} bytes` };
+    if (!magicMatches(subtype, buf))
+        return { ok: false, reason: `QR bytes do not match declared image/${subtype} (magic-byte mismatch)` };
+    const sha256 = createHash('sha256').update(buf).digest('hex');
+    return { ok: true, value: { mime: `image/${subtype}`, buf, sha256 } };
+}
+/** append-only 审计事件。只记 ref,【绝不】写 raw instruction / raw QR。 */
+export function appendAccountEvent(db, args, generateId) {
+    db.prepare('INSERT INTO direct_receive_account_events (id, account_id, seller_id, event_type, qr_ref) VALUES (?,?,?,?,?)')
+        .run(generateId('drae'), args.accountId, args.sellerId, args.eventType, args.qrRef ?? null);
+}
+/**
+ * 存收款码(owner-scoped)。校验 → sha256 → 【一个同步事务】内:INSERT OR IGNORE 不可变行 + 更新 account.qr_image_ref
+ *   + append qr_uploaded 事件。account 必须属于 sellerId(不属于 → {ok:false})。返回 ref。
+ */
+export function storeQrImage(db, args, generateId) {
+    const v = validateQrDataUri(args.dataUri);
+    if (!v.ok)
+        return v;
+    const owns = db.prepare("SELECT 1 FROM direct_receive_accounts WHERE id = ? AND seller_id = ?").get(args.accountId, args.sellerId);
+    if (!owns)
+        return { ok: false, reason: 'account not found or not owned' };
+    const ref = v.value.sha256;
+    db.transaction(() => {
+        db.prepare('INSERT OR IGNORE INTO direct_receive_account_qr_images (ref, account_id, seller_id, mime, data_b64, byte_len, sha256) VALUES (?,?,?,?,?,?,?)')
+            .run(ref, args.accountId, args.sellerId, v.value.mime, v.value.buf.toString('base64'), v.value.buf.length, ref);
+        db.prepare("UPDATE direct_receive_accounts SET qr_image_ref = ?, updated_at = datetime('now') WHERE id = ? AND seller_id = ?").run(ref, args.accountId, args.sellerId);
+        appendAccountEvent(db, { accountId: args.accountId, sellerId: args.sellerId, eventType: 'qr_uploaded', qrRef: ref }, generateId);
+    })();
+    return { ok: true, ref };
+}
+/** owner-scoped 取码字节(供硬化端点转发)。非本人 / 不存在 → null(端点统一 404,不枚举)。 */
+export function getQrImageForOwner(db, ref, sellerId) {
+    const row = db.prepare('SELECT mime, data_b64 FROM direct_receive_account_qr_images WHERE ref = ? AND seller_id = ?').get(ref, sellerId);
+    if (!row)
+        return null;
+    let buf;
+    try {
+        buf = Buffer.from(row.data_b64, 'base64');
+    }
+    catch {
+        return null;
+    }
+    // defense-in-depth: re-validate on read (mime whitelist + magic + size) — never serve unexpected bytes.
+    const re = validateQrDataUri(`data:${row.mime};base64,${row.data_b64}`);
+    if (!re.ok)
+        return null;
+    return { mime: row.mime, buf };
+}

package/dist/direct-receive-accounts.js

@@ -0,0 +1,82 @@
+export const MAX_INSTRUCTION_LEN = 500;
+export const MAX_LABEL_LEN = 40;
+export const MAX_METHOD_LEN = 40;
+export const MAX_QR_REF_LEN = 200;
+// currency:卖家声明的币种码(自由文本,2-8 位大写字母数字)。WebAZ 不限制卖家怎么收钱;买家侧只在 FX 支持时才显换算。
+export const CURRENCY_RE = /^[A-Z0-9]{2,8}$/;
+/** PURE: 校验 + 规范化卖家入参(trim / 长度 / 币种格式 / 大写)。不碰 DB。
+ *  长度超限 = 【显式拒绝】(非静默截断)—— 卖家看到的收款标签 / 方式 / 二维码引用不能被悄悄改短。 */
+export function normalizeAccountInput(input) {
+    const instruction = String(input?.instruction ?? '').trim();
+    if (!instruction)
+        return { ok: false, reason: 'instruction required' };
+    if (instruction.length > MAX_INSTRUCTION_LEN)
+        return { ok: false, reason: `instruction must be ≤ ${MAX_INSTRUCTION_LEN} chars` };
+    // trim + reject-if-over-limit (no silent slice). null/absent → null.
+    const field = (v, max, name) => {
+        if (v == null)
+            return { ok: true, v: null };
+        const s = String(v).trim();
+        if (s.length > max)
+            return { ok: false, reason: `${name} must be ≤ ${max} chars` };
+        return { ok: true, v: s || null };
+    };
+    const L = field(input.label, MAX_LABEL_LEN, 'label');
+    if (!L.ok)
+        return L;
+    const M = field(input.method, MAX_METHOD_LEN, 'method');
+    if (!M.ok)
+        return M;
+    const Q = field(input.qrImageRef, MAX_QR_REF_LEN, 'qr image ref');
+    if (!Q.ok)
+        return Q;
+    let currency = null;
+    if (input.currency != null && String(input.currency).trim()) {
+        currency = String(input.currency).trim().toUpperCase();
+        if (!CURRENCY_RE.test(currency))
+            return { ok: false, reason: 'currency must be a 2-8 char code (e.g. THB, IDR, USDC)' };
+    }
+    return { ok: true, value: { instruction, label: L.v, method: M.v, currency, qr_image_ref: Q.v } };
+}
+const COLS = 'id, seller_id, method, currency, instruction, label, qr_image_ref, status';
+/** 卖家的收款账号(默认仅 active;{ includeInactive:true } 取全部)。多行。 */
+export function listSellerAccounts(db, sellerId, opts = {}) {
+    const where = opts.includeInactive ? '' : " AND status = 'active'";
+    return db.prepare(`SELECT ${COLS} FROM direct_receive_accounts WHERE seller_id = ?${where} ORDER BY created_at ASC, id ASC`).all(sellerId);
+}
+/** 单个账号(任意状态);调用方自行做 owner 校验。 */
+export function getAccount(db, id) {
+    return db.prepare(`SELECT ${COLS} FROM direct_receive_accounts WHERE id = ?`).get(id) ?? null;
+}
+/** 买家侧【可选收款账号】(仅 active)—— 只投影元数据 method/currency/label 供结算前选"怎么付"+FX 换算展示。
+ *  ⚠️【绝不】含 instruction 原文 / qr_image_ref —— 收款目标受披露门保护(D1/D2 ack 后才随订单快照下发)。 */
+export function listSellerAccountOptions(db, sellerId) {
+    return db.prepare("SELECT id AS account_id, method, currency, label FROM direct_receive_accounts WHERE seller_id = ? AND status = 'active' ORDER BY created_at ASC, id ASC").all(sellerId);
+}
+/** 新增一个 active 收款账号。入参经 normalizeAccountInput 校验;只写本表。 */
+export function addAccount(db, sellerId, input, generateId) {
+    const norm = normalizeAccountInput(input);
+    if (!norm.ok)
+        return norm;
+    const id = generateId('dra');
+    const v = norm.value;
+    db.prepare(`INSERT INTO direct_receive_accounts (id, seller_id, method, currency, instruction, label, qr_image_ref, status) VALUES (?,?,?,?,?,?,?, 'active')`)
+        .run(id, sellerId, v.method, v.currency, v.instruction, v.label, v.qr_image_ref);
+    return { ok: true, account: { id, seller_id: sellerId, status: 'active', ...v } };
+}
+/** owner-scoped 文本字段更新(仅该 seller 拥有的行)。返回是否有行被改。
+ *  ⚠️ 【绝不】碰 qr_image_ref —— 收款码生命周期【只】由 storeQrImage(/qr 端点)管理。
+ *  否则卖家改一次收款说明/标签/币种就会把已上传的 QR 解绑(qr_image_ref→null),核心功能掉链子。 */
+export function updateAccount(db, id, sellerId, input) {
+    const norm = normalizeAccountInput(input);
+    if (!norm.ok)
+        return norm;
+    const v = norm.value;
+    const info = db.prepare(`UPDATE direct_receive_accounts SET method = ?, currency = ?, instruction = ?, label = ?, updated_at = datetime('now') WHERE id = ? AND seller_id = ?`).run(v.method, v.currency, v.instruction, v.label, id, sellerId);
+    return { ok: true, changed: info.changes > 0 };
+}
+/** owner-scoped 软停用。返回是否有行被停用。 */
+export function deactivateAccount(db, id, sellerId) {
+    const info = db.prepare("UPDATE direct_receive_accounts SET status = 'inactive', updated_at = datetime('now') WHERE id = ? AND seller_id = ? AND status = 'active'").run(id, sellerId);
+    return info.changes > 0;
+}

package/dist/direct-receive-deferral.js

@@ -0,0 +1,142 @@
+export const DEFAULT_DEFERRAL_CONFIG = {
+    defaultPeriodDays: 30, defaultGraceDays: 7, minReducedQuotaFactor: 0.1, maxReducedQuotaFactor: 0.9,
+    maxPeriodDays: 365, maxGraceDays: 90,
+};
+const isPosInt = (x) => typeof x === 'number' && Number.isInteger(x) && x > 0;
+const getRow = (db, id) => db.prepare('SELECT id, user_id, status, period_days, reduced_quota_factor, expires_at, grace_until FROM direct_receive_deferrals WHERE id = ?').get(id);
+/** 配额系数夹到 [min,max](不零威慑 + 缓交期必压低);非法/缺省 → 配置默认中点。 */
+export function clampReducedQuotaFactor(factor, config = DEFAULT_DEFERRAL_CONFIG) {
+    const lo = config.minReducedQuotaFactor, hi = config.maxReducedQuotaFactor;
+    const f = typeof factor === 'number' && Number.isFinite(factor) ? factor : (lo + hi) / 2;
+    return Math.min(hi, Math.max(lo, f));
+}
+/** 是否有【活跃】缓交(pending,或 granted 且未过 grace_until)。活跃则禁止再申请。 */
+function hasActiveDeferral(db, userId, nowIso) {
+    const rows = db.prepare("SELECT status, grace_until FROM direct_receive_deferrals WHERE user_id = ? AND status IN ('pending','granted')").all(userId);
+    const now = Date.parse(nowIso);
+    return rows.some(r => r.status === 'pending' || !r.grace_until || !Number.isFinite(Date.parse(r.grace_until)) || Date.parse(r.grace_until) > now);
+}
+/** 申请缓交(商户发起)→ pending。绝不自动授予。 */
+export function requestDeferral(db, args) {
+    const { deferralId, userId, reason, nowIso } = args;
+    const config = args.config ?? DEFAULT_DEFERRAL_CONFIG;
+    if (!deferralId || !userId)
+        return { ok: false, reason: 'missing deferralId/userId' };
+    if (!Number.isFinite(Date.parse(nowIso)))
+        return { ok: false, reason: 'unparseable nowIso' };
+    if (getRow(db, deferralId))
+        return { ok: false, reason: 'deferral id already exists' };
+    const periodDays = args.periodDays ?? config.defaultPeriodDays;
+    if (!isPosInt(periodDays))
+        return { ok: false, reason: 'periodDays must be a positive integer' };
+    // 上限校验:超大 periodDays 会在 approve 时令 new Date(now + days*86_400_000) 溢出 → RangeError(approve 500)。
+    //   在【申请入口】就 fail-closed,既挡 500 也挡超长期缓交。
+    if (periodDays > config.maxPeriodDays)
+        return { ok: false, reason: `periodDays exceeds max (${config.maxPeriodDays})` };
+    if (hasActiveDeferral(db, userId, nowIso))
+        return { ok: false, reason: 'user already has an active deferral' };
+    db.prepare(`INSERT INTO direct_receive_deferrals (id, user_id, reason, period_days, status, created_at)
+    VALUES (?,?,?,?, 'pending', datetime('now'))`).run(deferralId, userId, reason ?? null, periodDays);
+    return { ok: true, status: 'pending' };
+}
+/** 审批通过 → granted。设缓交到期 + 宽限截止 + 压低配额。仅要求 caller 传非空 adminId(无自动批);
+ *  ROOT/Passkey/human-presence 由【调用方 route】强制,helper 不验证身份。 */
+export function approveDeferral(db, args) {
+    const { deferralId, adminId, nowIso } = args;
+    const config = args.config ?? DEFAULT_DEFERRAL_CONFIG;
+    if (!adminId)
+        return { ok: false, reason: 'approveDeferral requires a human adminId (no auto-grant)' };
+    const row = getRow(db, deferralId);
+    if (!row)
+        return { ok: false, reason: 'deferral not found' };
+    if (row.status === 'granted')
+        return { ok: true, status: 'granted', already: true };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `cannot approve from status '${row.status}'` };
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return { ok: false, reason: 'unparseable nowIso' };
+    const graceDays = args.graceDays ?? config.defaultGraceDays;
+    if (!isPosInt(row.period_days) || !(Number.isInteger(graceDays) && graceDays >= 0))
+        return { ok: false, reason: 'invalid period/grace days' };
+    // 上限校验(防溢出 / 超长期):period 是申请时存的(理应已被 requestDeferral 卡住,这里防御 legacy/旁路行),
+    //   grace 是 admin 本次输入。任一超大都会让 new Date(now + (period+grace)*86_400_000) 溢出 → RangeError。
+    //   返回【结构化错误】(由 route 转 409),绝不抛 → 杜绝"消耗 Passkey token 后 500"。
+    if (row.period_days > config.maxPeriodDays)
+        return { ok: false, reason: `periodDays exceeds max (${config.maxPeriodDays})` };
+    if (graceDays > config.maxGraceDays)
+        return { ok: false, reason: `graceDays exceeds max (${config.maxGraceDays})` };
+    const expiresAt = new Date(now + row.period_days * 86_400_000).toISOString().slice(0, 19).replace('T', ' ');
+    const graceUntil = new Date(now + (row.period_days + graceDays) * 86_400_000).toISOString().slice(0, 19).replace('T', ' ');
+    const factor = clampReducedQuotaFactor(args.reducedQuotaFactor, config);
+    db.prepare(`UPDATE direct_receive_deferrals SET status = 'granted', approved_by = ?, approved_at = datetime('now'),
+    expires_at = ?, grace_until = ?, reduced_quota_factor = ? WHERE id = ?`)
+        .run(adminId, expiresAt, graceUntil, factor, deferralId);
+    return { ok: true, status: 'granted' };
+}
+/** 真人 admin 拒绝 → rejected。 */
+export function rejectDeferral(db, args) {
+    if (!args.adminId)
+        return { ok: false, reason: 'rejectDeferral requires a human adminId' };
+    const row = getRow(db, args.deferralId);
+    if (!row)
+        return { ok: false, reason: 'deferral not found' };
+    if (row.status === 'rejected')
+        return { ok: true, status: 'rejected', already: true };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `cannot reject from status '${row.status}'` };
+    db.prepare("UPDATE direct_receive_deferrals SET status = 'rejected', approved_by = ?, approved_at = datetime('now') WHERE id = ?").run(args.adminId, args.deferralId);
+    return { ok: true, status: 'rejected' };
+}
+/**
+ * 取某 user 当前【生效中】的缓交(granted 且 now ≤ grace_until)。无 → null。供 PR2 eligibility / 配额读取。
+ * 【FAIL-CLOSED】:grace_until 或 expires_at 为空/不可解析 = 坏 granted 行,**绝不**当作 active(返回 null 跳过)。
+ *   语义与 expireDeferrals 一致(坏行视为可清理/不生效),杜绝"坏 granted 行被误认有效缓交"放进 eligibility。
+ */
+export function getActiveDeferral(db, userId, nowIso) {
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return null;
+    const rows = db.prepare("SELECT id, reduced_quota_factor, expires_at, grace_until FROM direct_receive_deferrals WHERE user_id = ? AND status = 'granted'").all(userId);
+    for (const r of rows) {
+        const grace = r.grace_until ? Date.parse(r.grace_until) : NaN;
+        const exp = r.expires_at ? Date.parse(r.expires_at) : NaN;
+        // fail-closed:两个时钟锚点都必须是合法时间;grace 必须在未来。任一空/坏 → 跳过(不承认为 active)。
+        if (Number.isFinite(grace) && Number.isFinite(exp) && grace > now) {
+            return { id: r.id, reducedQuotaFactor: r.reduced_quota_factor, expiresAt: r.expires_at, graceUntil: r.grace_until, inGrace: now > exp };
+        }
+    }
+    return null;
+}
+/** 取某 user【最新一条】缓交申请(任意状态)。无 → null。纯读。供卖家自助 status 端点展示当前申请状态。 */
+export function getLatestDeferral(db, userId) {
+    // created_at 同秒并列时用 rowid(插入序)兜底,保证"最新"=最后插入,确定性。
+    return db.prepare(`SELECT id, status, period_days, reduced_quota_factor, expires_at, grace_until, created_at
+    FROM direct_receive_deferrals WHERE user_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(userId) ?? null;
+}
+export function listDeferrals(db, opts = {}) {
+    const cols = 'id, user_id, reason, period_days, reduced_quota_factor, status, approved_by, approved_at, expires_at, grace_until, created_at';
+    if (opts.status) {
+        return db.prepare(`SELECT ${cols} FROM direct_receive_deferrals WHERE status = ? ORDER BY created_at DESC, rowid DESC`).all(opts.status);
+    }
+    return db.prepare(`SELECT ${cols} FROM direct_receive_deferrals ORDER BY created_at DESC, rowid DESC`).all();
+}
+/** 到期清理(cron):granted 且【超过 grace_until】→ expired。返回受影响的 user_id(调用方据此停权;本模块不改 privileges)。 */
+export function expireDeferrals(db, nowIso) {
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return { expired: [] };
+    const rows = db.prepare("SELECT id, user_id, grace_until FROM direct_receive_deferrals WHERE status = 'granted'").all();
+    const expired = [];
+    const tx = db.transaction(() => {
+        for (const r of rows) {
+            const grace = r.grace_until ? Date.parse(r.grace_until) : NaN;
+            if (!Number.isFinite(grace) || grace <= now) {
+                db.prepare("UPDATE direct_receive_deferrals SET status = 'expired' WHERE id = ?").run(r.id);
+                expired.push(r.user_id);
+            }
+        }
+    });
+    tx();
+    return { expired };
+}