@seasonkoh/webaz 0.1.29 → 0.1.30

package/dist/pwa/routes/seller-quota.js

@@ -45,7 +45,7 @@ export function registerSellerQuotaRoutes(app, deps) {
         const d30 = fmt(new Date(now - 30 * 86400000));
         const d60 = fmt(new Date(now - 60 * 86400000));
         const orders = await dbAll(`
-      SELECT o.id, o.product_id, o.buyer_id, o.status, o.total_amount, o.created_at,
+      SELECT o.id, o.product_id, o.buyer_id, o.status, o.total_amount, o.created_at, o.payment_rail,
              COALESCE(p.title, '已下架商品') as product_title,
              COALESCE(ub.name, '匿名') as buyer_name
       FROM orders o
@@ -60,6 +60,8 @@ export function registerSellerQuotaRoutes(app, deps) {
         const inLast30 = orders.filter(o => o.created_at >= d30);
         const inPrev30 = orders.filter(o => o.created_at < d30);
         const gmv = (arr) => arr.filter(o => completedStatuses.has(o.status)).reduce((s, o) => s + Number(o.total_amount || 0), 0);
+        // GMV 按支付轨拆分:托管=平台真实托管收入,直接收款=场外收款(平台不经手)—— 不再混算(诚实口径)
+        const gmvRail = (arr, rail) => arr.filter(o => completedStatuses.has(o.status) && (rail === 'direct_p2p' ? o.payment_rail === 'direct_p2p' : (o.payment_rail || 'escrow') === 'escrow')).reduce((s, o) => s + Number(o.total_amount || 0), 0);
         const curGmv = gmv(inLast30);
         const prevGmv = gmv(inPrev30);
         const curCount = inLast30.length;
@@ -116,6 +118,8 @@ export function registerSellerQuotaRoutes(app, deps) {
             period_days: 30,
             summary: {
                 gmv: curGmv,
+                gmv_escrow: gmvRail(inLast30, 'escrow'),
+                gmv_direct_pay: gmvRail(inLast30, 'direct_p2p'),
                 order_count: curCount,
                 completed_count: completedOrders30.length,
                 aov,

package/dist/pwa/routes/shipping-templates.js

@@ -0,0 +1,219 @@
+import { parseShippingTemplate, loadTemplateJson, resolveShipping } from '../../shipping-templates.js';
+import { validateSaleRegionsInput, parseSaleRegionsRule, regionAllowedByRule, parsePlatformBlocklist } from '../../sale-regions.js'; // S1 可售区域(店铺+单品写入;gate 在 orders-create;S5 只读披露复用判定 + 与建单门同一 blocklist parser)
+import { validateFreeShippingThreshold } from '../../free-shipping.js'; // 营销域满额免邮(S2 返工:写入口暂列本设置面,规则/判定在 free-shipping.ts)
+import { validateImportDutyTerms, validateTaxLines, effectiveImportDutyTerms, effectiveTaxLines, parseTaxLines, taxLinesForRegion } from '../../trade-tax.js'; // S3 跨境税费/进口责任声明层(seller-declared,平台不算不收)
+import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
+export function registerShippingTemplateRoutes(app, deps) {
+    const { auth, errorRes } = deps;
+    app.post('/api/seller/shipping-template', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'seller')
+            return void errorRes(res, 403, 'SELLER_ONLY', '仅卖家可设置运费模板');
+        const b = req.body || {};
+        const touched = {};
+        if ('store_template' in b) {
+            const p = parseShippingTemplate(b.store_template);
+            if (!p.ok)
+                return void errorRes(res, 400, 'BAD_SHIPPING_TEMPLATE', p.error);
+            await dbRun('UPDATE users SET store_shipping_template = ? WHERE id = ?', [p.entries ? JSON.stringify(p.entries) : null, user.id]);
+            touched.store_template = p.entries;
+        }
+        if ('store_quote_ok' in b) { // PR-3:模板外地区询价 opt-in(店铺默认;直付轨生效)
+            if (b.store_quote_ok !== null && typeof b.store_quote_ok !== 'boolean')
+                return void errorRes(res, 400, 'BAD_QUOTE_OK', 'store_quote_ok 只允许 true|false|null');
+            await dbRun('UPDATE users SET store_shipping_quote_ok = ? WHERE id = ?', [b.store_quote_ok === null ? null : (b.store_quote_ok ? 1 : 0), user.id]);
+            touched.store_quote_ok = b.store_quote_ok;
+        }
+        if ('store_sale_regions' in b) { // S1 可售区域(店铺默认):{mode:'all'|'list', include?, exclude?};null=清除(不限)
+            const v = validateSaleRegionsInput(b.store_sale_regions);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_SALE_REGIONS', v.error);
+            await dbRun('UPDATE users SET store_sale_regions = ? WHERE id = ?', [v.json, user.id]);
+            touched.store_sale_regions = v.json ? JSON.parse(v.json) : null;
+        }
+        if ('product_id' in b && 'sale_regions' in b) { // S1 单品覆盖(优先于店铺;null=回落店铺)
+            const v = validateSaleRegionsInput(b.sale_regions);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_SALE_REGIONS', v.error);
+            const prodS = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prodS)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prodS.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品');
+            await dbRun('UPDATE products SET sale_regions = ? WHERE id = ?', [v.json, b.product_id]);
+            touched.product_sale_regions = v.json ? JSON.parse(v.json) : null;
+        }
+        if ('store_free_shipping_threshold' in b) { // 营销:满额免邮(店铺默认;null=清除)。券后货款≥阈值→运费商家承担
+            const v = validateFreeShippingThreshold(b.store_free_shipping_threshold);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_FREE_SHIPPING_THRESHOLD', v.error);
+            await dbRun('UPDATE users SET store_free_shipping_threshold = ? WHERE id = ?', [v.value, user.id]);
+            touched.store_free_shipping_threshold = v.value;
+        }
+        if ('product_id' in b && 'free_shipping_threshold' in b) { // 营销:单品覆盖(null=回落店铺)
+            const v = validateFreeShippingThreshold(b.free_shipping_threshold);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_FREE_SHIPPING_THRESHOLD', v.error);
+            const prodF = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prodF)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prodF.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品');
+            await dbRun('UPDATE products SET free_shipping_threshold = ? WHERE id = ?', [v.value, b.product_id]);
+            touched.product_free_shipping_threshold = v.value;
+        }
+        if ('store_import_duty_terms' in b) { // S3:DDP/DDU 进口责任声明(店铺默认;null=清除)
+            const v = validateImportDutyTerms(b.store_import_duty_terms);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_IMPORT_DUTY_TERMS', v.error);
+            await dbRun('UPDATE users SET store_import_duty_terms = ? WHERE id = ?', [v.value, user.id]);
+            touched.store_import_duty_terms = v.value;
+        }
+        if ('product_id' in b && 'import_duty_terms' in b) { // S3:单品覆盖(null=回落店铺)
+            const v = validateImportDutyTerms(b.import_duty_terms);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_IMPORT_DUTY_TERMS', v.error);
+            const prodD = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prodD)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prodD.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品');
+            await dbRun('UPDATE products SET import_duty_terms = ? WHERE id = ?', [v.value, b.product_id]);
+            touched.product_import_duty_terms = v.value;
+        }
+        if ('store_tax_lines' in b) { // S3:价内已含税声明(店铺默认;仅 'included';null=清除)
+            const v = validateTaxLines(b.store_tax_lines);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_TAX_LINES', v.error);
+            await dbRun('UPDATE users SET store_tax_lines = ? WHERE id = ?', [v.value, user.id]);
+            touched.store_tax_lines = v.value ? JSON.parse(v.value) : null;
+        }
+        if ('product_id' in b && 'tax_lines' in b) { // S3:单品覆盖(null=回落店铺)
+            const v = validateTaxLines(b.tax_lines);
+            if ('error' in v)
+                return void errorRes(res, 400, 'BAD_TAX_LINES', v.error);
+            const prodT = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prodT)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prodT.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品');
+            await dbRun('UPDATE products SET tax_lines = ? WHERE id = ?', [v.value, b.product_id]);
+            touched.product_tax_lines = v.value ? JSON.parse(v.value) : null;
+        }
+        if ('product_id' in b && 'quote_ok' in b) {
+            if (b.quote_ok !== null && typeof b.quote_ok !== 'boolean')
+                return void errorRes(res, 400, 'BAD_QUOTE_OK', 'quote_ok 只允许 true|false|null');
+            const prodQ = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prodQ)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prodQ.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品');
+            await dbRun('UPDATE products SET shipping_quote_ok = ? WHERE id = ?', [b.quote_ok === null ? null : (b.quote_ok ? 1 : 0), b.product_id]);
+            touched.product_quote_ok = b.quote_ok;
+        }
+        if ('template' in b) { // 单品运费模板:仅在显式带 template 时进入 —— 关闭整类隐患(此前 'product_id' in b 会让 {product_id, store_*} 等组合尾随进来把模板静默清成 NULL;审计 P2)。清除走 {product_id, template:null}('template' in b 成立)
+            if (!b.product_id)
+                return void errorRes(res, 400, 'MISSING_PRODUCT_ID', '设置单品运费模板须带 product_id');
+            const p = parseShippingTemplate(b.template);
+            if (!p.ok)
+                return void errorRes(res, 400, 'BAD_SHIPPING_TEMPLATE', p.error);
+            const prod = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!prod)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (prod.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品的运费模板');
+            await dbRun('UPDATE products SET shipping_template = ? WHERE id = ?', [p.entries ? JSON.stringify(p.entries) : null, b.product_id]);
+            touched.product_template = p.entries;
+        }
+        if (Object.keys(touched).length === 0)
+            return void errorRes(res, 400, 'NOTHING_TO_SET', '未提供任何设置项');
+        return void res.json({ success: true, ...touched });
+    });
+    // 卖家读自己的店铺级设置(设置 UI 回显):接单模式 + 运费模板 + 询价开关。
+    app.get('/api/seller/shipping-settings', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'seller')
+            return void errorRes(res, 403, 'SELLER_ONLY', '仅卖家');
+        const row = await dbOne('SELECT store_accept_mode, store_shipping_template, store_shipping_quote_ok, store_sale_regions, store_free_shipping_threshold, store_import_duty_terms, store_tax_lines FROM users WHERE id = ?', [user.id]);
+        return void res.json({
+            store_accept_mode: row?.store_accept_mode ?? null,
+            store_sale_regions: parseSaleRegionsRule(row?.store_sale_regions ?? null),
+            store_free_shipping_threshold: row?.store_free_shipping_threshold ?? null,
+            store_import_duty_terms: (row?.store_import_duty_terms === 'ddu' || row?.store_import_duty_terms === 'ddp') ? row.store_import_duty_terms : null,
+            store_tax_lines: parseTaxLines(row?.store_tax_lines ?? null),
+            store_template: loadTemplateJson(row?.store_shipping_template),
+            store_quote_ok: row?.store_shipping_quote_ok == null ? null : Number(row.store_shipping_quote_ok) === 1,
+        });
+    });
+    // 公开读:买家下单前查配送范围。生效 = 单品覆盖 ?? 店铺默认;template=null → 不按地区计费(下单不要求选地区)。
+    app.get('/api/products/:id/shipping-options', async (req, res) => {
+        const prod = await dbOne('SELECT id, seller_id, shipping_template, shipping_quote_ok, import_duty_terms, tax_lines, sale_regions, free_shipping_threshold FROM products WHERE id = ?', [req.params.id]);
+        if (!prod)
+            return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+        let entries = loadTemplateJson(prod.shipping_template);
+        let source = entries ? 'product' : null;
+        const seller = await dbOne('SELECT store_shipping_template, store_shipping_quote_ok, store_import_duty_terms, store_tax_lines, store_sale_regions, store_free_shipping_threshold FROM users WHERE id = ?', [prod.seller_id]);
+        if (!entries) {
+            entries = loadTemplateJson(seller?.store_shipping_template);
+            if (entries)
+                source = 'store';
+        }
+        const quoteOk = prod.shipping_quote_ok != null ? Number(prod.shipping_quote_ok) === 1 : Number(seller?.store_shipping_quote_ok) === 1;
+        // S3 税费/进口责任披露(买家下单前可见;卖家 seller-declared,平台不算不收)。
+        //   价内含税【按收货地区过滤】(?ship_to_region):目的区匹配项 + '*' 通用项;无地区参数=仅 '*'(只披露必然适用的,
+        //   不把不属于该目的地的税误示给买家)。DDP/DDU 是整单单一声明,不按区分。
+        const importDuty = effectiveImportDutyTerms(prod.import_duty_terms, seller?.store_import_duty_terms);
+        const shipToRegion = typeof req.query.ship_to_region === 'string' && req.query.ship_to_region.trim() ? req.query.ship_to_region.trim().toUpperCase() : null;
+        const taxLines = taxLinesForRegion(effectiveTaxLines(prod.tax_lines, seller?.store_tax_lines), shipToRegion);
+        // S5 买家下单前聚合(只读,复用 S1-S4 判定;不动订单金额/不收税)。
+        const saleRule = parseSaleRegionsRule(prod.sale_regions) ?? parseSaleRegionsRule(seller?.store_sale_regions ?? null); // 可售规则(商品??店铺)
+        // 平台合规名单:与建单门 gateSaleRegionForCreate 共用 parsePlatformBlocklist,坏配置 fail-closed 一致(建单 503 ⇄ 预检 platform_policy_invalid),
+        //   不再把坏配置当空名单静默放行(否则预检显示"可买"、提交才 503,与 create gate 不一致)。缺省 '[]'/无行=空名单=可售。
+        const pr = await dbOne("SELECT value FROM protocol_params WHERE key = 'trade.platform_region_blocklist'").catch(() => null);
+        const parsedBlock = parsePlatformBlocklist(pr ? pr.value : '[]');
+        const policyInvalid = !parsedBlock.ok;
+        const platformBlock = parsedBlock.ok ? parsedBlock.list : [];
+        const freeThreshold = (prod.free_shipping_threshold != null && Number(prod.free_shipping_threshold) > 0) ? Number(prod.free_shipping_threshold)
+            : (seller?.store_free_shipping_threshold != null && Number(seller.store_free_shipping_threshold) > 0 ? Number(seller.store_free_shipping_threshold) : null);
+        // 可售裁定(镜像建单 gateSaleRegionForCreate 的判定,只读不抛):平台配置异常 > 平台合规 > 商家意愿。
+        const restricted = policyInvalid || !!saleRule || platformBlock.length > 0;
+        let sellable = { ok: true, reason: 'ok' };
+        if (policyInvalid)
+            sellable = { ok: false, reason: 'platform_policy_invalid' }; // 坏配置 fail-closed:显示不可下单,不诱导买家提交后才 503
+        else if (restricted) {
+            if (!shipToRegion)
+                sellable = { ok: false, reason: 'region_required' };
+            else if (platformBlock.includes(shipToRegion))
+                sellable = { ok: false, reason: 'product_restricted' }; // 平台合规,商家不可放宽
+            else if (saleRule && !regionAllowedByRule(saleRule, shipToRegion))
+                sellable = { ok: false, reason: 'region_not_for_sale' }; // 商家不销往
+        }
+        // 目的区运费裁定(有模板时;免邮阈值仅回传数值供 UI 提示"满 X 免邮",实际是否免取决于买家券后货款,建单时定)
+        let resolvedShipping = null;
+        if (entries && shipToRegion) {
+            const r = resolveShipping(entries, shipToRegion);
+            resolvedShipping = { covered: r.covered, fee: r.covered ? r.fee : null, est_days: r.est_days, quote_required: !r.covered && quoteOk };
+        }
+        return void res.json({
+            product_id: prod.id,
+            region_required: !!entries || restricted, // S5:可售/合规限制也需买家指定目的地(与建单 SHIP_REGION_REQUIRED 一致)
+            template: entries,
+            source,
+            sellable, // S5:{ ok, reason: ok|region_required|product_restricted|region_not_for_sale|platform_policy_invalid }
+            sale_regions: saleRule, // S5:生效可售规则(商品??店铺){mode:'list',include:[...]} | {mode:'all',exclude:[...]} | null —— UI 据此在无运费模板时也能生成地区入口
+            resolved_shipping: resolvedShipping, // S5:目的区运费裁定(covered/fee/est_days/quote_required)| null(无模板或未选区)
+            free_shipping_threshold: freeThreshold, // S5:生效满额免邮阈值(UI 提示"满 X 免邮";实际免取决于建单时券后货款)
+            import_duty_terms: importDuty, // 'ddu'(买家到境自付关税/税)| 'ddp'(卖家已含)| null(未声明)
+            tax_included_lines: taxLines, // 价内已含税声明(如 [{region:'SG',label:'GST',rate_pct:9,kind:'included'}])
+            tax_disclosure: 'seller_declared_platform_no_collect', // S5:税费/进口责任均为卖家声明,平台不代收代缴(直付非托管)
+            quote_outside_template: !!entries && quoteOk, // 直付轨:模板外地区可询价(卖家报运费/时效,确认后付款)
+            note: entries
+                ? (quoteOk ? '下单须选择收货地区;模板内地区运费自动计入,模板外地区(直付)可先询价再付款。' : '下单须选择收货地区;运费按模板计入总额(快照)。未覆盖地区暂不可下单。')
+                : (restricted ? '该商品设有可售地区限制,请选择收货地区确认。' : '该商品不按地区计运费。'),
+        });
+    });
+}

package/dist/pwa/routes/snf.js

@@ -1,5 +1,6 @@
 import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 import { snfSend, snfPullInbox, snfListInbox, snfAck, snfPendingCount, snfVerify, snfDesignate, snfGetDesignation, snfNack, snfListDeadLetter, snfRevive, } from '../../layer2-business/L2-7-snf/snf-engine.js';
+import { isEligibleArbitrator } from '../arbitrator-lifecycle.js'; // 仲裁能力唯一源=active 白名单(verify 是争议证据面,不认 legacy role)
 export function registerSnfRoutes(app, deps) {
     const { db, auth } = deps;
     app.post('/api/snf/send', (req, res) => {
@@ -105,7 +106,9 @@ export function registerSnfRoutes(app, deps) {
         if (!r)
             return void res.status(404).json({ error: '消息不存在' });
         const uid = user.id;
-        if (uid !== r.sender_id && uid !== r.recipient_id && user.role !== 'arbitrator' && user.role !== 'admin') {
+        // 仲裁员认 active 白名单(争议证据验签是仲裁工作面);legacy role 旁路移除 —— 否则 role-only/已吊销账号可按 id
+        //   探测任意用户间私信的存在性+签名有效性,而真·白名单仲裁员(role=buyer)反被 403。admin 保持原样。
+        if (uid !== r.sender_id && uid !== r.recipient_id && !isEligibleArbitrator(db, uid).ok && user.role !== 'admin') {
             return void res.status(403).json({ error: '无权验证' });
         }
         res.json(await snfVerify(db, req.params.id));

package/dist/pwa/routes/webauthn.js

@@ -74,13 +74,13 @@ export function registerWebauthnRoutes(app, deps) {
         if (!user)
             return;
         const purpose = String(req.body?.purpose || '').trim();
-        const allowed = new Set(['withdraw', 'change-password', 'reveal-key', 'region', 'delete_passkey', 'governance_apply', 'governance_activate', 'governance_resign', 'governance_appeal_resolve', 'rewards_apply', 'rewards_deactivate', 'identity_claim', 'operator_claim_unlink', 'direct_pay_disclosure_ack', 'direct_pay_order_action', 'direct_receive_production_confirm', 'direct_pay_aml_review', 'direct_pay_kyb_ingress', 'direct_pay_sanctions_ingress', 'direct_pay_aml_ingress', 'direct_pay_admin_readiness', 'direct_pay_deferral_approve', 'direct_pay_deferral_reject', 'direct_pay_product_verify', 'direct_pay_store_verify', 'direct_pay_fee_prepay_record', 'direct_pay_fee_adjust', 'direct_pay_fee_refund', 'direct_receive_account_manage']);
+        const allowed = new Set(['withdraw', 'change-password', 'reveal-key', 'region', 'delete_passkey', 'governance_apply', 'governance_activate', 'governance_resign', 'governance_appeal_resolve', 'rewards_apply', 'rewards_deactivate', 'identity_claim', 'operator_claim_unlink', 'direct_pay_disclosure_ack', 'direct_pay_order_action', 'direct_receive_production_confirm', 'direct_receive_bond_refund', 'direct_pay_bond_slash', 'direct_pay_aml_review', 'direct_pay_kyb_ingress', 'direct_pay_sanctions_ingress', 'direct_pay_aml_ingress', 'direct_pay_admin_readiness', 'direct_pay_deferral_approve', 'direct_pay_deferral_reject', 'direct_pay_product_verify', 'direct_pay_store_verify', 'direct_pay_fee_prepay_record', 'direct_pay_fee_adjust', 'direct_pay_fee_refund', 'direct_receive_account_manage', 'platform_receive_account_manage', 'direct_pay_fee_prepay_reject', 'direct_pay_fee_prepay_request_approve', 'direct_pay_payment_info_reveal', 'arbitrator_grant', 'arbitrator_suspend', 'arbitrator_reinstate', 'arbitrator_revoke', 'arbitrate', 'agent_pair_approve', 'agent_permission_approve']);
         if (!allowed.has(purpose))
             return void res.status(400).json({ error: 'invalid purpose' });
         const purpose_data = req.body?.purpose_data ?? null;
         const creds = await dbAll('SELECT id, transports FROM webauthn_credentials WHERE user_id = ?', [user.id]);
         if (creds.length === 0)
-            return void res.status(403).json({ error: '尚未注册任何 Passkey' });
+            return void res.status(403).json({ error: '尚未注册任何 Passkey', error_code: 'NO_PASSKEY_REGISTERED' }); // 前端据此才提示注册;已注册者的取消/设备失败不误导去注册
         const opts = await generateAuthenticationOptions({
             rpID: rpId,
             // H-1: 闸门必须真正 UV，不接受 "硬件按一下" 兜底
@@ -196,5 +196,5 @@ export function registerWebauthnRoutes(app, deps) {
     // RFC-020 PR-B — agent delegation grants (issue/read/revoke). Co-registered with the
     // Passkey security routes so the money-dense server.ts stays untouched. Safe scopes
     // only; risk scopes default-hard-reject. Reuses db/auth/generateId from WebauthnDeps.
-    registerAgentGrantsRoutes(app, { db, auth, generateId, rateLimitOk });
+    registerAgentGrantsRoutes(app, { db, auth, generateId, rateLimitOk, requireHumanPresence });
 }

package/dist/pwa/server.js

@@ -41,6 +41,14 @@ import { ensureEvidenceColumns, uploadEvidence, listEvidence as listEvidenceFile
 import { cleanupOrphanNotePhotos, } from '../layer2-business/L2-notes/note-photo-storage.js';
 import { initAnchorRegistrySchema, retireAnchorsByTarget, reclaimRetiredAnchors, retireIdleAnchors, userReferralVolume, computeTierLetter, } from '../layer2-business/L2-anchor-registry/anchor-registry.js';
 import { initDisputeSchema, createDispute, respondToDispute, arbitrateDispute, getOrderDispute, getDisputeDetails, getOpenDisputes, checkDisputeTimeouts, initEvidenceRequestSchema, requestEvidence, getEvidenceRequests, addPartyEvidence, } from '../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
+import { initMutualCancelSchema } from '../layer3-trust/L3-1-dispute-engine/mutual-cancel.js';
+import { registerMutualCancelRoutes } from './routes/mutual-cancel.js';
+import { initDirectPayCancelRefundSchema } from '../direct-pay-cancel-refund.js';
+import { registerDirectPayCancelRefundRoutes } from './routes/direct-pay-cancel-refund.js';
+import { registerDirectPayReturnsRoutes } from './routes/direct-pay-returns.js';
+import { registerDirectPayPendingAcceptRoutes } from './routes/direct-pay-pending-accept.js';
+import { registerShippingTemplateRoutes } from './routes/shipping-templates.js';
+import { registerBondSellerRoutes } from './routes/bond-seller.js'; // 协商取消(disputed) + 直付取消退款握手(accepted):域 schema + 端点
 import { initNotificationSchema, notifyTransition, setPushCallback, scanDeadlineReminders, } from '../layer2-business/L2-6-notifications/notification-engine.js';
 import { initSkillMarketSchema } from '../layer4-economics/L4-4-skill-market/skill-listing-engine.js';
 import { computeAgentPassport } from '../layer1-agent/L1-2-identity/agent-passport.js';
@@ -154,6 +162,7 @@ import { registerExternalAnchorsRoutes } from './routes/external-anchors.js';
 import { registerAnchorsRoutes } from './routes/anchors.js';
 // 仲裁员申请 (#1013 Phase 44) — 4 user + 3 admin endpoints
 import { registerArbitratorRoutes } from './routes/arbitrator.js';
+import { isEligibleArbitrator as isEligibleArbitratorImpl } from './arbitrator-lifecycle.js'; // PR-B: active-whitelist-only 授权源
 // Governance onboarding (W3.5-B 实施 #1093 阶段 1) — 2 user endpoints
 import { registerGovernanceOnboardingRoutes } from './routes/governance-onboarding.js';
 import { startAutoDeactivateCron, runAutoDeactivateSweep } from './routes/governance-auto-deactivate.js';
@@ -250,11 +259,15 @@ import { registerOrdersActionRoutes } from './routes/orders-action.js';
 import { registerOrdersCreateRoutes } from './routes/orders-create.js';
 import { registerDirectPayDisclosureAckRoutes } from './routes/direct-pay-disclosure-acks.js'; // PR-4d: Direct Pay 风险披露 ack 端点(薄 adapter)
 import { registerDirectReceivePaymentInstructionRoutes } from './routes/direct-receive-payment-instructions.js';
-import { registerDirectReceiveAccountsRoutes } from './routes/direct-receive-accounts.js'; // PR-4f-a instruction CRUD + Phase C1 multi-account+QR
-import { registerDirectPayAvailabilityRoutes } from './routes/direct-pay-availability.js'; // PR-4a: Direct Pay 可用性只读(控制面 SSOT)
-import { registerAdminDirectReceiveDepositsRoutes } from './routes/admin-direct-receive-deposits.js'; // PR-4b-3: ROOT 生产保证金 receipt 确认(fail-closed scaffold)
+import { registerDirectReceiveAccountsRoutes } from './routes/direct-receive-accounts.js';
+import { registerFeePrepayRequestRoutes } from './routes/fee-prepay-requests.js'; // PR-4f-a instruction CRUD + Phase C1 multi-account+QR + 平台服务费预充值申请(卖家侧)
+import { registerDirectPayAvailabilityRoutes } from './routes/direct-pay-availability.js';
+import { registerSellerDirectPayReportRoutes } from './routes/seller-directpay-report.js'; // PR-4a 可用性 + 卖家直付销售统计/对账/平台费明细(只读)
+import { registerAdminDirectReceiveDepositsRoutes } from './routes/admin-direct-receive-deposits.js';
+import { registerPlatformReceiveAccountsRoutes } from './routes/platform-receive-accounts.js'; // PR-4b-3 ROOT 生产保证金 + 平台多收款方式 admin 管理(fee 预充值申请流前置)
 // Disputes 读端点 (#1013 Phase 86) — 5 endpoints (list/similar/detail/evidence-list/parties)
 import { registerDisputesReadRoutes } from './routes/disputes-read.js';
+import { isArbitrationReadAdmin } from './arbitration-read-admin.js'; // 争议详情只读 admin 门(与后台列表授权一致)
 // Disputes 写端点 (#1013 Phase 87) — 5 endpoints (respond/arbitrate/add-evidence/evidence-blob/request-evidence)
 import { registerDisputesWriteRoutes } from './routes/disputes-write.js';
 // Products 声明 (#1013 Phase 88) — 2 endpoints (POST claim + GET claims)
@@ -395,6 +408,8 @@ const settleClaimTask = (taskId) => settleClaimTaskRaw(db, generateId, taskId);
 const notifyEligibleVerifiers = (args) => notifyEligibleVerifiersRaw(db, generateId, args);
 initSystemUser(db);
 initDisputeSchema(db);
+initMutualCancelSchema(db);
+initDirectPayCancelRefundSchema(db); // + mutual_cancel_proposals / direct_pay_cancel_requests 表
 initNotificationSchema(db);
 initSkillSchema(db);
 initSkillMarketSchema(db);
@@ -843,10 +858,10 @@ const DEFAULT_PARAMS = [
     // ⚠️ Codex #111:stake-required 模式(=1)【尚未实现】—— 下单不锁 stake、settleFault 仍按 stake_backing=0 不没收,
     //   开启会给出虚假"真没收"协议语义。故 max 锁 0(不可开启);待 Phase 3 钱路径迁移实现真锁(下单原子锁 balance→staked)再放开。
     { key: 'require_seller_stake', value: '0', type: 'number', description: 'RFC-008 是否要求卖家质押(0=起步免赔付/零门槛)。⚠️ stake-required(=1)未实现、暂锁 0 不可开启,见 Phase 3', category: 'fee', min: 0, max: 0 },
-    // RFC-008 stage 2:违约罚没率,【与质押率解耦】(低质押=低摩擦 + 高罚没=强威慑,单一费率做不到)。
-    //   背书订单:penalty = fault_penalty_rate × total,先扣 staked(封顶背书)再扣自由 balance(责任自负,真可执行)。
+    // RFC-008 stage 2:违约罚没率,【与质押率解耦】(低质押=低摩擦+高罚没=强威慑)。背书订单:penalty=rate×total,先扣 staked(封顶背书)再扣自由 balance(责任自负)。
     //   起步免赔付(stake_backing=0):仍 0 没收,绝不碰新商家自由余额。settleFault 按订单 stake_backing 判定。
     { key: 'fault_penalty_rate', value: '0.30', type: 'number', description: 'RFC-008 违约罚没率(与质押率解耦;背书订单 staked 不足扣自由 balance;起步免赔付订单不适用)', category: 'fee', min: 0, max: 0.50 },
+    { key: 'trade.platform_region_blocklist', value: '[]', type: 'json', description: '跨境 S1 平台合规禁售地区(JSON 数组大写区码,如 ["KP"]):建单 PRODUCT_RESTRICTED 硬拒,商家不可放宽;默认空。admin PATCH 有 JSON+区码校验', category: 'system' },
     // RFC-007 stage 3：客观理由拒单的【举证窗口】小时数。卖家声称客观无责拒单 → 临时判责,此窗口内可开仲裁(stage 5)举证;
     //   到期无人仲裁 → 自动终结为违约。窗口内买家 escrow 暂不退(随终结/翻案一次性结算),0=不给窗口(直接违约)。
     { key: 'decline_contest_window_hours', value: '24', type: 'number', description: 'RFC-007 客观拒单举证窗口(小时);到期未仲裁则终结为违约', category: 'limit', min: 0, max: 168 },
@@ -1373,11 +1388,7 @@ try {
 }
 catch { }
 // 2026-05-22: 复合索引 — GET /api/shares/dashboard bought_products 5 子查询性能优化
-// note_count / first_note_id 用：owner_id + related_order_id + type + status
-try {
-    db.exec("CREATE INDEX IF NOT EXISTS idx_share_owner_order_type ON shareables(owner_id, related_order_id, type, status)");
-}
-catch { }
+// note_count / first_note_id 用的 idx_share_owner_order_type 已移至下方 related_order_id ALTER 之后(此处列尚不存在,先建=fresh 库永缺该索引)
 // product_share_count 用：owner_id + related_product_id + status（避免回表）
 try {
     db.exec("CREATE INDEX IF NOT EXISTS idx_share_owner_product ON shareables(owner_id, related_product_id, status)");
@@ -1423,6 +1434,10 @@ try {
     db.exec("CREATE INDEX IF NOT EXISTS idx_share_order ON shareables(related_order_id) WHERE related_order_id IS NOT NULL");
 }
 catch { }
+try {
+    db.exec("CREATE INDEX IF NOT EXISTS idx_share_owner_order_type ON shareables(owner_id, related_order_id, type, status)");
+}
+catch { }
 // 笔记图片 hash 索引 / Wave A 购物表（心愿单 · 商品Q&A · 优惠券）→ server-schema.ts
 // 纯幂等建表/建索引 DDL，原位调用保持 boot 顺序不变
 initNotePhotoIndexSchema(db);
@@ -1668,13 +1683,12 @@ catch { }
 for (const stmt of [
     'ALTER TABLE products ADD COLUMN claim_loss_count INTEGER DEFAULT 0',
     'ALTER TABLE secondhand_items ADD COLUMN claim_loss_count INTEGER DEFAULT 0',
-    'ALTER TABLE auctions ADD COLUMN claim_loss_count INTEGER DEFAULT 0',
 ]) {
     try {
         db.exec(stmt);
     }
     catch { }
-}
+} // auctions 的同名 ALTER 在 auctions CREATE 之后(此处表尚不存在,先跑=fresh 库永缺列 — 铁律:ALTER AFTER CREATE)
 // P2P 原生商店 — 卖家本地节点存详情，WebAZ 只锚定 hash + 关键字段
 for (const stmt of [
     'ALTER TABLE products ADD COLUMN p2p_mode INTEGER DEFAULT 0',
@@ -2019,10 +2033,10 @@ try {
           read       INTEGER DEFAULT 0,
           created_at TEXT DEFAULT (datetime('now')),
           wish_id    TEXT,
-          actions    TEXT
+          actions    TEXT, template_key TEXT, params TEXT
         );
-        INSERT INTO notifications_new (id, user_id, order_id, type, title, body, read, created_at, wish_id, actions)
-          SELECT id, user_id, order_id, type, title, body, read, created_at, wish_id, actions FROM notifications;
+        INSERT INTO notifications_new (id, user_id, order_id, type, title, body, read, created_at, wish_id, actions, template_key, params)
+          SELECT id, user_id, order_id, type, title, body, read, created_at, wish_id, actions, template_key, params FROM notifications;
         DROP TABLE notifications;
         ALTER TABLE notifications_new RENAME TO notifications;
         CREATE INDEX IF NOT EXISTS idx_notif_user ON notifications(user_id, read, created_at DESC);
@@ -2420,11 +2434,15 @@ try {
     db.exec('CREATE INDEX IF NOT EXISTS idx_auctions_deadline ON auctions(status, deadline_at)');
 }
 catch { }
-// AUC P1：反狙击延长上限
+// AUC P1：反狙击延长上限;claim_loss_count 从 Sprint 4 数组移来(那里先于本表 CREATE,fresh 库静默失败)
 try {
     db.exec('ALTER TABLE auctions ADD COLUMN max_extends INTEGER DEFAULT 10');
 }
 catch { }
+try {
+    db.exec('ALTER TABLE auctions ADD COLUMN claim_loss_count INTEGER DEFAULT 0');
+}
+catch { }
 try {
     db.exec('ALTER TABLE auctions ADD COLUMN extends_used INTEGER DEFAULT 0');
 }
@@ -4121,15 +4139,15 @@ app.use((req, res, next) => {
                 action, cap: capCheck.cap, used: capCheck.used, level: lvlForCap,
             });
         }
-        // Phase 3c：风险闸 — 高风险 agent 敏感写降速/暂停(只罚高风险,无责零成本)
+        // Phase 3c:风险闸 — 高风险 agent 敏感写降速/暂停。真人豁免(Tina 案二连,同 #241 原则):绑 Passkey=真人,敏感操作已有 Passkey 仪式把守;风险分含结构罚(同 IP 注册簇)+30 天半衰期,"30 秒重试"对真人=死锁
         const agentRisk = riskInfo.risk;
-        if (agentRisk >= 100) {
+        if (agentRisk >= 100 && !riskInfo.hasPasskey) {
             return void res.status(403).json({
                 error: 'agent 风险分已达上限，敏感操作已暂停 — 请在「我的 Agents」查看并申诉',
                 error_code: 'AGENT_RISK_SUSPENDED', action, risk: agentRisk,
             });
         }
-        if (agentRisk >= 70) {
+        if (agentRisk >= 70 && !riskInfo.hasPasskey) {
             res.setHeader('Retry-After', '30');
             return void res.status(429).json({
                 error: `agent 风险分偏高(${agentRisk}/100)，敏感操作已降速，请 30 秒后重试`,
@@ -4169,7 +4187,8 @@ app.use((req, res, next) => {
             }
         }
     }
-    // 分档 rate limit
+    if (riskInfo.hasPasskey || req.path === '/api/signaling/poll' || req.path === '/api/snf/pending')
+        return next(); // 分档 rate limit 前的真人豁免(Tina 案修复):绑 Passkey=真人本人/监护(PWA 页面加载+轮询天然高频,agent 约束原则=真人豁免,不进速率桶不触发 rate_limit_abuse strike);高频轮询端点亦不计 agent 配额
     const repRow = db.prepare(`SELECT level FROM agent_reputation WHERE api_key = ?`).get(apiKey);
     const level = repRow?.level || 'new';
     const cap = getAgentRateCap(level);
@@ -4475,9 +4494,12 @@ registerAgentReputationRoutes(app, {
 registerUsersPublicRoutes(app, { db, auth, noteAuthenticityBadges });
 registerDirectPayDisclosureAckRoutes(app, { db, auth, generateId, consumeGateToken }); // PR-4d
 registerDirectReceivePaymentInstructionRoutes(app, { db, auth, generateId });
-registerDirectReceiveAccountsRoutes(app, { db, auth, generateId, consumeGateToken }); // PR-4f-a + Phase C1
-registerDirectPayAvailabilityRoutes(app, { db, auth, getProtocolParam, generateId }); // PR-4a + 缓交 apply/status
-registerAdminDirectReceiveDepositsRoutes(app, { db, requireRootAdmin: (req, res) => requireRootAdmin(req, res), consumeGateToken, logAdminAction, getProtocolParam }); // PR-4b-3 + readiness
+registerDirectReceiveAccountsRoutes(app, { db, auth, generateId, consumeGateToken });
+registerFeePrepayRequestRoutes(app, { db, auth, generateId }); // PR-4f-a + Phase C1 + fee 预充值申请
+registerDirectPayAvailabilityRoutes(app, { db, auth, getProtocolParam, generateId });
+registerSellerDirectPayReportRoutes(app, { db, auth }); // PR-4a + 缓交 + 卖家直付销售统计/对账/平台费明细(只读)
+registerAdminDirectReceiveDepositsRoutes(app, { db, requireRootAdmin: (req, res) => requireRootAdmin(req, res), consumeGateToken, logAdminAction, getProtocolParam });
+registerPlatformReceiveAccountsRoutes(app, { db, requireRootAdmin: (req, res) => requireRootAdmin(req, res), generateId, consumeGateToken, logAdminAction }); // PR-4b-3 + readiness + 平台多收款方式 admin CRUD(root+Passkey)
 // RFC-004 build_feedback — agent-native "use → build" 反馈管道
 registerBuildFeedbackRoutes(app, {
     db, auth,
@@ -5845,25 +5867,20 @@ function getArbitratorState(userId) {
         state = 'rejected';
     if (wl)
         state = 'approved';
-    return { state, application: app ?? null, whitelist: wl ?? null };
+    // PR-E:真实运行时能力字段。前端必须以 can_arbitrate 为准(state='approved' 不区分 suspended/revoked)。
+    const arbitrator_status = wl ? (wl.status ?? 'active') : 'none'; // active / suspended / revoked / none
+    return { state, can_arbitrate: isEligibleArbitrator(userId).ok, arbitrator_status, application: app ?? null, whitelist: wl ?? null };
 }
-// 仲裁员身份判定（内部 role + 外部 whitelist 双通道）— 用于 /api/disputes/:id/arbitrate 守门
+// 仲裁员身份判定 — PR-B:唯一授权源 = active arbitrator_whitelist(role='arbitrator' 旁路已移除)。域逻辑见 arbitrator-lifecycle.ts。
 function isEligibleArbitrator(userId) {
-    const u = db.prepare("SELECT role FROM users WHERE id = ?").get(userId);
-    if (!u)
-        return { ok: false, reason: '用户不存在' };
-    if (u.role === 'arbitrator')
-        return { ok: true, via: 'role' };
-    const wl = db.prepare("SELECT user_id FROM arbitrator_whitelist WHERE user_id = ?").get(userId);
-    if (wl)
-        return { ok: true, via: 'whitelist' };
-    return { ok: false, reason: '非仲裁员 — 需 role=arbitrator（内部）或 arbitrator_whitelist（外部）' };
+    return isEligibleArbitratorImpl(db, userId);
 }
 // #1013 Phase 44: 4 user + 3 admin arbitrator endpoints 已迁出到 routes/arbitrator.ts
 registerArbitratorRoutes(app, {
     db, generateId, auth,
     requireArbitrationAdmin: (req, res) => requireAdminPermission(req, res, 'arbitration'),
     checkArbitratorEligibility, getArbitratorState, errorRes, logAdminAction,
+    consumeGateToken, // PR-B: grant/suspend/reinstate/revoke 的 purpose-bound 真人 Passkey
     ARB_STAKE_REQUIRED, ARB_APP_REJECT_COOLDOWN_DAYS,
 });
 // Governance onboarding (W3.5-B #1093) — apply + quiz + cases + admin activation + resign/appeal + auto_deactivate audit
@@ -6061,7 +6078,7 @@ registerSellerQuotaRoutes(app, {
 registerDisputesReadRoutes(app, {
     db, auth, errorRes,
     getOpenDisputes, getDisputeDetails, getEvidenceRequests, listEvidenceFiles,
-    isEligibleArbitrator,
+    isEligibleArbitrator, isArbitrationAdmin: isArbitrationReadAdmin, // 后者=争议详情只读 admin 门,与后台列表 /admin/disputes 同款授权(单一真相源 arbitration-read-admin.ts)
 });
 // #1013 Phase 87: 5 disputes 写端点已迁出（包括 234 行 arbitrate）
 // FUND_BASE_RATE 是 const 函数在文件下游定义；用 getter 包一层避免 TDZ
@@ -6074,8 +6091,14 @@ registerDisputesWriteRoutes(app, {
     FUND_BASE_RATE: () => FUND_BASE_RATE(),
     settleCommission, depositToFund, calculatePv,
     recordDisputeReputation, issueAgentStrike, publishDisputeCase, logAdminAction, snfSend,
-    getProtocolParam,
+    getProtocolParam, notifyTransition,
 });
+registerMutualCancelRoutes(app, { db, auth, generateId, errorRes });
+registerDirectPayCancelRefundRoutes(app, { db, auth, generateId, errorRes, consumeGateToken });
+registerDirectPayReturnsRoutes(app, { db, auth, generateId, errorRes, consumeGateToken });
+registerDirectPayPendingAcceptRoutes(app, { db, auth, errorRes, getProtocolParam });
+registerShippingTemplateRoutes(app, { db, auth, errorRes });
+registerBondSellerRoutes(app, { db, auth, generateId, errorRes, getProtocolParam }); // 协商取消(disputed)+ 直付取消退款握手(accepted):关单手术均内部 db.transaction 原子
 // lightAuthGuard：轻量 Authorization 头守门（在 raw 解析之前挡掉无 auth 请求）
 // 被 Phase 13 shareables（视频上传）+ Phase 87 disputes evidence-blob 共享
 function lightAuthGuard(req, res, next) {

package/dist/runtime/agent-grant-scopes.js

@@ -27,6 +27,13 @@ export const SAFE_SCOPES = [
     'list_product_draft',
     'product_publish_request',
     'draft_order',
+    // Seller-scoped read/draft surfaces (Catalog Agent role) — read the seller's own catalog + propose
+    //   drafts/pricing/publish-REQUESTS. NONE of these publish, accept orders, ship, or move money.
+    'seller_profile_read',
+    'seller_products_read',
+    'seller_inventory_read',
+    'seller_product_draft',
+    'seller_pricing_suggestion',
 ];
 /**
  * Real actions that WILL require a live Passkey each time — but are NOT yet gated
@@ -119,10 +126,71 @@ export function grantIsActive(grant, nowIso) {
 }
 /** Short-lived bearer policy for SAFE scopes (RFC-020 bearer-first; PoP before risk/longer). */
 export const GRANT_TTL_DEFAULT_SEC = 3600; // 1h
-export const GRANT_TTL_MAX_SEC = 24 * 3600; // 24h cap — short-lived only
+export const GRANT_TTL_MAX_SEC = 24 * 3600; // 24h cap — short-lived only (legacy webaz_pair bearer)
 export function clampTtlSeconds(requested) {
     const n = Number(requested);
     if (!Number.isFinite(n) || n <= 0)
         return GRANT_TTL_DEFAULT_SEC;
     return Math.min(Math.floor(n), GRANT_TTL_MAX_SEC);
 }
+export const PERMISSION_BUNDLES = {
+    catalog_agent: {
+        key: 'catalog_agent',
+        label: 'Catalog Agent',
+        scopes: ['read_public', 'profile_read', 'search', 'seller_profile_read', 'seller_products_read', 'seller_inventory_read', 'seller_product_draft', 'seller_pricing_suggestion', 'product_publish_request'],
+        human_summary: '选品、商品草稿、库存字段检查、价格建议、上架请求。它不能发布商品、不能接单、不能发货、不能动用资金。',
+        human_summary_en: 'Sourcing, product drafts, inventory-field checks, pricing suggestions, and publish REQUESTS. It cannot publish products, accept orders, ship, or move funds.',
+    },
+};
+/** Resolve a bundle key → its safe scopes + human summary, or null if unknown. */
+export function resolveBundle(key) {
+    return (typeof key === 'string' && Object.prototype.hasOwnProperty.call(PERMISSION_BUNDLES, key)) ? PERMISSION_BUNDLES[key] : null;
+}
+/** INVARIANT check (acceptance #7): a bundle must be all-safe. Returns the offending non-safe scopes. */
+export function bundleNonSafeScopes(bundle) {
+    return bundle.scopes.filter(s => classifyScope(s) !== 'safe');
+}
+// Load-time assertion: no bundle may ship with a risk/never/unknown scope (fail LOUD at import, not runtime).
+for (const b of Object.values(PERMISSION_BUNDLES)) {
+    const bad = bundleNonSafeScopes(b);
+    if (bad.length)
+        throw new Error(`Permission bundle '${b.key}' contains non-safe scope(s): ${bad.join(', ')} — bundles are safe-only (RFC-020)`);
+}
+export const DURATION_SECONDS = { '1h': 3600, '24h': 86400, '7d': 604800, '30d': 2592000 };
+/**
+ * Which durations a set of scopes may be granted for, capped by the HIGHEST risk tier present:
+ *   - never-delegable / unknown  → []            (cannot be granted at all)
+ *   - risk (high)                → ['once']       (single Passkey each time; NEVER long-term)
+ *   - safe (low/medium)          → once…30d       (long-term ok)
+ */
+export function allowedDurationsForScopes(scopes) {
+    const tiers = scopes.map(classifyScope);
+    if (tiers.some(t => t === 'never_delegable' || t === 'unknown'))
+        return [];
+    if (tiers.some(t => t === 'risk'))
+        return ['once'];
+    return ['once', '1h', '24h', '7d', '30d'];
+}
+export function durationAllowedForScopes(scopes, duration) {
+    return typeof duration === 'string' && allowedDurationsForScopes(scopes).includes(duration);
+}
+/** Suggested default: 7d for long-term-eligible safe scopes; else the safest available (once). */
+export function suggestedDurationForScopes(scopes) {
+    const a = allowedDurationsForScopes(scopes);
+    return a.includes('7d') ? '7d' : (a[0] ?? 'once');
+}
+/** Grant lifetime in seconds for an approved (non-'once') duration. 'once' handled separately (single-use). */
+export function durationToSeconds(duration) {
+    return duration === 'once' ? 0 : DURATION_SECONDS[duration];
+}
+/** Coarse risk label for the human-facing request card. */
+export function riskLevelForScopes(scopes) {
+    const tiers = scopes.map(classifyScope);
+    if (tiers.some(t => t === 'never_delegable' || t === 'unknown'))
+        return 'blocked';
+    if (tiers.some(t => t === 'risk'))
+        return 'high';
+    if (scopes.includes('product_publish_request'))
+        return 'medium'; // request-only (still human-gated to publish), flag as medium
+    return 'low';
+}