@seasonkoh/webaz 0.1.27 → 0.1.29

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -13,8 +13,8 @@
  *   webaz_wallet        查看钱包余额
  *   …（39 工具,完整定义见下方 TOOLS 数组;数量以 TOOLS.length 为准）
  *
- * 双模(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ SANDBOX(本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
- * 关联 / Related: AGENTS.md · RFC-003(双模) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
+ * 三态(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ NETWORK 只读(无 key,公共读走 webaz.xyz)/ SANDBOX(仅 WEBAZ_MODE=sandbox,本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
+ * 关联 / Related: AGENTS.md · RFC-003(三态:network / network_readonly / sandbox) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
  *   #6 不滥用(agent 责任制 + Iron-Rule 真人动作)· 生产端点在 src/pwa(NETWORK 共用)
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -23,6 +23,13 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 import { setSeamDb } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(本进程注入)
+import { applyWebazRuntimeSchema } from '../../runtime/apply-webaz-runtime-schema.js'; // 与 PWA 同源的纯 schema 桥(防 MCP fresh DB 漂移)
+import { generateCodeVerifier, pkceChallengeS256 } from '../../runtime/agent-pairing.js'; // RFC-020 PR-C1 — PKCE 配对
+import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode, resolveMode } from './network-mode.js'; // RFC-003 网络门(可单测)+ 模式解析(单一真相源)
+import { homedir } from 'node:os';
+import { join as pathJoin } from 'node:path';
+import { existsSync as fsExists, mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { transition, getOrderStatus, initSystemUser, } from '../../layer0-foundation/L0-2-state-machine/engine.js';
 import { initDisputeSchema, createDispute, respondToDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
 import { initNotificationSchema, notifyTransition, getNotifications, getUnreadCount, markRead, } from '../../layer2-business/L2-6-notifications/notification-engine.js';
@@ -38,7 +45,7 @@ const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/
 // 2026-06-01: phase A pre-launch 默认 OFF(opt-in)— W8 public launch 时翻回 default ON + 加 README 披露段
 // Phase A pre-launch: telemetry default OFF (opt-in). Flip to default ON at W8 launch + add README disclosure section.
 const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() === 'on';
-// ─── RFC-003 P0: 双模(NETWORK / SANDBOX)骨架 ─────────────────────
+// ─── RFC-003 P0: 三态(network_readonly / network / sandbox)骨架 ─────────────────────
 // NETWORK = 带 api_key 调 webaz.xyz/api(加入共享生产网络);SANDBOX = 本地 SQLite(离线试玩,与全网隔离)。
 // P0 不迁移任何工具(NETWORK_TOOLS 为空)→ 一切仍走本地 = 零行为变化;P1/P2 逐个把工具名加入集合切到网络。
 const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
@@ -52,67 +59,14 @@ export function resolveMcpApiKey(args, envKey = WEBAZ_API_KEY) {
     const explicit = typeof args?.api_key === 'string' ? args.api_key.trim() : '';
     return explicit || envKey;
 }
-const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
 // 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
 // network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
 //   需身份的写/读返回"设 WEBAZ_API_KEY(到 #welcome 申请邀请)"。离线本地 playground 改为【显式】 WEBAZ_MODE=sandbox。
 //   —— 治"装完=空沙盒劝退"的死首体验;route/guard 与 network 同路(见 isNetworkMode),只是无 Bearer + 文案不同。
-const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
-    : WEBAZ_MODE_ENV === 'sandbox' ? 'sandbox'
-        : WEBAZ_MODE_ENV === 'network_readonly' ? 'network_readonly'
-            : (WEBAZ_API_KEY ? 'network' : 'network_readonly');
+// 单一真相源:resolveMode(见 network-mode.ts),CLI 的 --mode/--doctor 用同一函数,杜绝漂移。
+const MODE = resolveMode(process.env);
 // network 或 network_readonly 都"走真网络"(后者无 Bearer)。sandbox 才是本地。
 const isNetworkMode = () => MODE === 'network' || MODE === 'network_readonly';
-// 已迁移到 NETWORK 的工具名。P1/P2 逐个加入;未在集合里的工具仍走 sandbox(本地)。
-// P1(读工具): 纯公开读,无写无 Passkey,作"MCP 连得上生产网络"的首验证。
-const NETWORK_TOOLS = new Set([
-    'webaz_price_history',
-    'webaz_leaderboard',
-    'webaz_verify_price',
-    'webaz_place_order',
-    'webaz_list_product',
-    'webaz_update_order',
-    'webaz_search',
-    'webaz_get_status',
-    'webaz_feedback',
-    'webaz_contribute',
-    // Batch 1(只读 + 低危自身写):走 webaz.xyz Bearer api_key。
-    'webaz_notifications',
-    'webaz_nearby',
-    'webaz_profile',
-    'webaz_shareables',
-    'webaz_mykey',
-    // Batch 2(低危写,无钱无 escrow):走 webaz.xyz Bearer api_key。
-    // 注:share_link 暂不迁(无对应服务端端点,需新建,留待后续)。
-    'webaz_follows',
-    'webaz_like',
-    'webaz_blocklist',
-    'webaz_default_address',
-    'webaz_chat',
-    'webaz_rfq',
-    'webaz_referral',
-    // Batch 3(商务):secondhand/skill_market/auction 纯 pwaApi(mode-aware 自动走网络);
-    // skill 直连本地引擎,加了显式 apiCall network 分支。
-    'webaz_secondhand',
-    'webaz_skill',
-    'webaz_skill_market',
-    'webaz_auction',
-    // Batch 4(资金/质押,守恒由服务端 RFC-014 保证;wallet 只读,写=Passkey 仅 PWA):
-    'webaz_wallet',
-    'webaz_trial',
-    'webaz_charity',
-    'webaz_bid',
-    'webaz_auto_bid',
-    // Batch 5(铁律/敏感):claim_verify 纯 pwaApi(真人门由服务端 require_human_presence 强制);
-    // dispute view/list_open/respond/add_evidence 走网络,arbitrate 仅返回 Passkey 指引;
-    // rotate_key/revoke_key 仅返回 Passkey 指引(不本地校验)。
-    'webaz_dispute',
-    'webaz_claim_verify',
-    'webaz_rotate_key',
-    'webaz_revoke_key',
-    // #1122:share_link 现有服务端端点 /api/share-link,可走网络。
-    'webaz_share_link',
-]);
 const recentCalls = [];
 function pushRecentCall(c) {
     recentCalls.push(c);
@@ -124,9 +78,8 @@ function pushRecentCall(c) {
 function toolBackend(tool) {
     return (isNetworkMode() && NETWORK_TOOLS.has(tool)) ? 'network' : 'sandbox';
 }
-// 未在 NETWORK_TOOLS 名单、但 NETWORK 模式下仍可本地运行的"自省/引导"工具(非数据操作)。
-// info = 本地自省(并拉 live 网络状态);register = 引导真人去 webaz.xyz。其余未迁工具一律硬失败。
-const NETWORK_SELF_AWARE = new Set(['webaz_info', 'webaz_register']);
+// NETWORK_SELF_AWARE imported from ./network-mode.ts (info = local introspection;
+// register = redirect human to webaz.xyz). Everything else un-migrated hard-fails.
 // RFC-003 Batch 0 安全网:NETWORK 模式下调用【未迁移】工具时的诚实拒绝(而非静默落本地沙盒)。
 // 否则带 key 的用户调未迁工具会被悄悄喂本地结果——写操作=幻影操作(根本没到 webaz.xyz)。
 function networkMigrationPending(tool) {
@@ -180,6 +133,200 @@ async function apiCall(path, opts = {}) {
         return { error: `网络错误:${msg}`, network_error: true };
     }
 }
+// ─────────────────────────── RFC-020 PR-C1: webaz_pair (pairing + local credential storage) ───────────────────────────
+// C1 scope: pairing / consent / retrieval / LOCAL credential storage ONLY. The grant is
+// NOT wired into any business tool (that is PR-C2 — per-request scope enforcement + audit).
+// The raw bearer appears exactly once, in the server→MCP retrieval response; it is written
+// straight to the OS secret store (Keychain → 0600 file fallback) and NEVER returned to the
+// user / chat / tool-response / log. webaz_pair returns only a credential handle + status.
+const WEBAZ_DIR = pathJoin(homedir(), '.webaz');
+const PENDING_PATH = pathJoin(WEBAZ_DIR, 'pairing-pending.json'); // holds the PKCE verifier between start→complete
+const CRED_FALLBACK_PATH = pathJoin(WEBAZ_DIR, 'credentials'); // 0600 fallback when Keychain unavailable
+const KEYCHAIN_SERVICE = 'webaz-grant';
+function ensureWebazDir() { if (!fsExists(WEBAZ_DIR))
+    mkdirSync(WEBAZ_DIR, { recursive: true, mode: 0o700 }); }
+function write0600(path, data) { ensureWebazDir(); writeFileSync(path, data, { mode: 0o600 }); try {
+    chmodSync(path, 0o600);
+}
+catch { /* best effort */ } }
+/** Store the raw bearer in the OS secret store; never log it. Returns an opaque handle. */
+function storeGrantCredential(grantId, token) {
+    // macOS Keychain first (non-interactive upsert). Any failure → strict-perms file fallback.
+    if (process.platform === 'darwin') {
+        try {
+            execFileSync('security', ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', grantId, '-w', token], { stdio: ['ignore', 'ignore', 'ignore'] });
+            return `keychain:${KEYCHAIN_SERVICE}/${grantId}`;
+        }
+        catch { /* fall through to file */ }
+    }
+    let store = {};
+    try {
+        if (fsExists(CRED_FALLBACK_PATH))
+            store = JSON.parse(readFileSync(CRED_FALLBACK_PATH, 'utf8'));
+    }
+    catch {
+        store = {};
+    }
+    store[grantId] = { token, stored_at: new Date().toISOString() };
+    write0600(CRED_FALLBACK_PATH, JSON.stringify(store, null, 2));
+    return `file:~/.webaz/credentials#${grantId}`;
+}
+// Non-secret index of the current grant (grant_id + handle + metadata) so the stored
+// credential can be resolved back without re-pairing. The SECRET (token) lives only in
+// the OS secret store / 0600 file — never in this pointer.
+const CRED_POINTER_PATH = pathJoin(WEBAZ_DIR, 'grant-current.json');
+function saveGrantPointer(grantId, handle, capabilities, expiresAt) {
+    write0600(CRED_POINTER_PATH, JSON.stringify({ grant_id: grantId, handle, capabilities: capabilities ?? null, expires_at: expiresAt ?? null, stored_at: new Date().toISOString() }));
+}
+function readGrantPointer() {
+    try {
+        return fsExists(CRED_POINTER_PATH) ? JSON.parse(readFileSync(CRED_POINTER_PATH, 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the stored grant bearer (reverse of storeGrantCredential). Returns null if not paired.
+ * ⚠️ The returned `token` is the RAW bearer — pass it only as an Authorization header; NEVER log it,
+ * print it, or return it in a tool response.
+ */
+export function resolveGrantCredential() {
+    const ptr = readGrantPointer();
+    if (!ptr?.grant_id)
+        return null;
+    let token = '';
+    if (typeof ptr.handle === 'string' && ptr.handle.startsWith('keychain:') && process.platform === 'darwin') {
+        try {
+            token = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', ptr.grant_id, '-w'], { encoding: 'utf8' }).trim();
+        }
+        catch {
+            token = '';
+        }
+    }
+    if (!token) { // file fallback (also covers keychain-read failure)
+        try {
+            const store = JSON.parse(readFileSync(CRED_FALLBACK_PATH, 'utf8'));
+            token = store[ptr.grant_id]?.token || '';
+        }
+        catch {
+            token = '';
+        }
+    }
+    if (!token)
+        return null;
+    return { grant_id: ptr.grant_id, token, handle: ptr.handle, capabilities: ptr.capabilities, expires_at: ptr.expires_at };
+}
+function savePending(pairingId, codeVerifier) {
+    write0600(PENDING_PATH, JSON.stringify({ pairing_id: pairingId, code_verifier: codeVerifier, started_at: new Date().toISOString() }));
+}
+function readPending() {
+    try {
+        return fsExists(PENDING_PATH) ? JSON.parse(readFileSync(PENDING_PATH, 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function clearPending() { try {
+    if (fsExists(PENDING_PATH))
+        unlinkSync(PENDING_PATH);
+}
+catch { /* best effort */ } }
+export async function handlePair(args) {
+    // Mode isolation (fail-closed): every webaz_pair action (start / complete / verify) talks to the
+    // LIVE webaz.xyz API. In explicit sandbox mode (local-only) we must NOT touch the live network.
+    if (!isNetworkMode()) {
+        return {
+            _mode: MODE,
+            error: 'webaz_pair requires NETWORK mode — you are in sandbox (local-only, isolated from webaz.xyz). Unset WEBAZ_MODE (or set WEBAZ_MODE=network / network_readonly) to pair with / verify against a real human account.',
+            error_code: 'PAIRING_REQUIRES_NETWORK',
+        };
+    }
+    const action = args.action || 'start';
+    if (action === 'start') {
+        const caps = Array.isArray(args.capabilities) && args.capabilities.length
+            ? args.capabilities.map(c => ({ capability: String(c) }))
+            : [{ capability: 'read_public' }, { capability: 'search' }]; // default: minimal safe scopes
+        const verifier = generateCodeVerifier();
+        const challenge = pkceChallengeS256(verifier);
+        const resp = await apiCall('/api/agent-grants/pair/start', {
+            method: 'POST',
+            body: {
+                code_challenge: challenge,
+                capabilities: caps,
+                agent_label: typeof args.agent_label === 'string' ? args.agent_label : undefined,
+                reason: typeof args.reason === 'string' ? args.reason : undefined, // free-text reason only
+            },
+        });
+        if (resp.error)
+            return resp;
+        savePending(String(resp.pairing_id), verifier); // verifier stays LOCAL; never sent until retrieve
+        return {
+            status: 'awaiting_human_approval',
+            pairing_id: resp.pairing_id,
+            user_code: resp.user_code,
+            approve_url: `${WEBAZ_API_URL}${String(resp.approve_url || '')}`,
+            expires_at: resp.expires_at,
+            next: `Ask the human to open approve_url (logged in at webaz.xyz) and approve. Then call webaz_pair again with action="complete".`,
+            capabilities_requested: caps.map(c => c.capability),
+            note: 'Safe scopes only. The credential is delivered once on completion and stored in your OS secret store — it is never shown here.',
+        };
+    }
+    if (action === 'complete') {
+        const pending = readPending();
+        if (!pending)
+            return { error: 'no pending pairing — run webaz_pair (action="start") first', error_code: 'NO_PENDING_PAIRING' };
+        const resp = await apiCall(`/api/agent-grants/pair/${pending.pairing_id}/retrieve`, {
+            method: 'POST',
+            body: { code_verifier: pending.code_verifier },
+        });
+        if (resp.error) {
+            // not approved yet → keep pending so the human can still approve + a later retry works
+            if (resp.http_status === 409)
+                return { status: 'not_ready', detail: resp.error, hint: 'Human has not approved yet (or it expired). Approve, then call action="complete" again.' };
+            clearPending();
+            return resp;
+        }
+        const token = String(resp.token || '');
+        const grantId = String(resp.grant_id || '');
+        if (!token || !grantId) {
+            clearPending();
+            return { error: 'retrieval returned no credential', error_code: 'RETRIEVE_EMPTY' };
+        }
+        const handle = storeGrantCredential(grantId, token); // raw bearer goes straight to secret store
+        saveGrantPointer(grantId, handle, resp.capabilities, resp.expires_at); // non-secret index for later resolve
+        clearPending();
+        return {
+            status: 'stored',
+            credential_handle: handle, // opaque handle — NOT the token
+            grant_id: grantId,
+            capabilities: resp.capabilities,
+            expires_at: resp.expires_at,
+            note: 'Credential stored in your OS secret store (raw token NOT shown; server keeps only a hash). Use webaz_pair action="verify" to confirm it; the server enforces active/expiry/revoked/scope on every call. Safe scopes only.',
+        };
+    }
+    if (action === 'verify') {
+        // Consume the stored grant against a SAFE grant-gated route (read_public). The SERVER is authoritative:
+        // it re-checks active/expiry/revoked/subject-suspension/scope + audits on EVERY call. We resolve the
+        // bearer from the secret store and attach it; the raw token is never printed. Safe scopes only — no
+        // business tool and no risk scope is wired to grants here.
+        const cred = resolveGrantCredential();
+        if (!cred)
+            return { status: 'not_paired', error_code: 'NO_GRANT_CREDENTIAL', hint: 'No stored grant. Run webaz_pair action="start", have the human approve, then action="complete".' };
+        const resp = await apiCall('/api/agent-grants/whoami', { method: 'GET', apiKey: cred.token });
+        if (resp.error) {
+            return { status: 'grant_invalid', grant_id: cred.grant_id, error: resp.error, error_code: resp.error_code, hint: 'Grant is no longer valid (revoked / expired / suspended). Re-pair with webaz_pair action="start".' };
+        }
+        return {
+            status: 'active',
+            grant: resp.grant, // SERVER-AUTHORITATIVE principal (grant_id/human_id/agent_label/capability)
+            local_cache: { capabilities: cred.capabilities, expires_at: cred.expires_at }, // advisory only, may be stale — NOT authoritative
+            note: 'Grant verified LIVE by the server (per-call: active/expiry/revoked/subject-suspension/scope + audited). `grant` is authoritative; `local_cache` is advisory. Safe scopes only; no business tool or risk scope consumes this grant.',
+        };
+    }
+    return { error: `unknown action "${action}" — use "start" | "complete" | "verify"`, error_code: 'BAD_ACTION' };
+}
 // 启动 banner(stderr)+ status 声明用 —— 让用户/agent 一眼知道现在是真网络还是沙盒
 function modeBanner() {
     if (MODE === 'network') {
@@ -195,6 +342,13 @@ function modeBanner() {
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
 setSeamDb(db); // RFC-016 Phase 1:注入异步 DB seam(本进程)—— 共享引擎迁 seam 后 MCP 进程也能用,否则 dbOne/dbAll 抛"未初始化"
+// MCP fresh-DB schema bridge: apply the SAME pure schema helpers the PWA boot
+// runs (incl. product_aliases + users.permanent_code/handle/region), so an
+// MCP-initialized DB is schema-complete for the sandbox tool path WITHOUT first
+// booting the PWA server. Pure idempotent DDL only — no business writes, no
+// money/order/status path. (MCP_PRODUCT_COLS below now overlaps the products
+// columns and is redundant-but-harmless; left untouched to avoid scope creep.)
+applyWebazRuntimeSchema(db);
 initSystemUser(db);
 initDisputeSchema(db);
 initNotificationSchema(db);
@@ -325,6 +479,26 @@ No auth required, no parameters needed.
             properties: {},
         },
     },
+    {
+        name: 'webaz_pair',
+        description: `Pair this agent with a human's WebAZ account via a Passkey-approved, scoped, short-lived **delegation grant** (RFC-020) — NOT by pasting a permanent api_key. Two steps:
+1. action="start" → returns an approve_url + short user_code. The human opens it at webaz.xyz (logged in) and approves the server-shown consent (safe scopes only).
+2. action="complete" → retrieves the credential ONCE (PKCE) and stores it in your OS secret store (macOS Keychain → ~/.webaz/credentials 0600 fallback). Returns only a credential_handle + status — the raw token is never shown.
+3. action="verify" → uses the stored grant against a safe read endpoint to confirm it is still valid. The server re-checks active/expiry/revoked/suspension/scope and audits the call every time. Returns the grant principal/status; never the raw token.
+
+Scopes: SAFE only (read_public, profile_read, search, list_product_draft, product_publish_request, draft_order). Risk scopes (place_order/wallet/refund/...) and never-delegable actions (withdraw/key-change/vote/...) are hard-rejected.
+
+NOTE: this consumes the grant only on safe read paths; no business tool and no risk scope is wired to grants. No account is created (registration stays human-only at webaz.xyz).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['start', 'complete', 'verify'], description: 'start a pairing, complete it after the human approves, or verify the stored grant (default: start)' },
+                capabilities: { type: 'array', items: { type: 'string' }, description: 'Requested SAFE scopes (default: read_public, search). Non-safe scopes are rejected.' },
+                agent_label: { type: 'string', description: 'Human-friendly name for this agent (shown in the consent screen)' },
+                reason: { type: 'string', description: 'Free-text reason shown to the human (you cannot relabel the scopes)' },
+            },
+        },
+    },
     {
         name: 'webaz_register',
         // was ~1732 chars, now ~780 chars
@@ -1722,10 +1896,10 @@ async function handleInfo() {
                     ? '🟢 NETWORK（只读）：无 api_key。公共读（搜索/榜单/价格史/浏览）打 webaz.xyz 真网络（见 network_live）。要交易（注册/下单/上架等）请设 WEBAZ_API_KEY —— 到 ' + WEBAZ_API_URL + '/#welcome 申请邀请。'
                     : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离（显式 dev/demo 模式）。任何计数 / 账号 / 订单仅本机有效。不设 WEBAZ_MODE 则默认走真网络只读。',
             phase: 'pre_launch',
-            real_users_on_canonical: 0,
+            // 真实用户/规模【不在此硬编码】—— 网络模式下 network_live(上方,实时拉 /api/protocol-status)带有 real_users_on_canonical 真值。
             canonical_endpoint: 'https://webaz.xyz',
             economic_flow: 'simulated WAZ (test currency, 1 WAZ ≈ 1 USDC peg is a模拟基准, not a real exchange rate). No fiat/crypto settles yet.',
-            disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 live_stats / 工具示例所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
+            disclaimer: '本协议尚未公开上线(pre-launch),无真实经济流转。真实用户/规模请以 network_live(本次从 webaz.xyz 实时拉取的 /api/protocol-status,含 real_users_on_canonical)为准;下方 live_stats / 工具示例的所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
         },
         description: 'WebAZ is a decentralized commerce protocol. Every transaction flows through a state machine; each state transition needs proof-of-action from the responsible party. Any timeout-without-action: protocol auto-rules default + executes remedy. / WebAZ 是去中心化商业协议;每笔交易通过状态机流转,每次状态转移需对应责任方的操作证明;超时未操作则协议自动判违约并执行处置。',
         // 给【终端用户/买家】的价值主张 —— 陌生 agent / 普通买家先要知道"对我有什么用",而非只读抽象 tagline + 技术 description。
@@ -1819,7 +1993,7 @@ function handleRegister(args) {
             ],
             register_url: WEBAZ_API_URL,
             why_not_agent_self_register: 'agent 自助注册会绕过邀请 / captcha / 真人 Passkey 责任制，破坏协议的可问责性（#6 不滥用 / CHARTER §4 I-5）。',
-            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（或清空 WEBAZ_API_KEY），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
+            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（本机沙盒需显式开启；无 key 仍是 NETWORK 只读，不会进沙盒），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
         };
     }
     // ─── SANDBOX 模式：本机建测试账号（显著标注，仅本机有效，与 webaz.xyz 全网隔离）──
@@ -2347,8 +2521,8 @@ async function handleListProduct(args) {
       id, seller_id, title, description, price, stock, category, stake_amount,
       specs, brand, model, source_price,
       ship_regions, handling_hours, estimated_days, fragile,
-      return_days, return_condition, warranty_days
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?)
+      return_days, return_condition, warranty_days, currency
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, 'WAZ')
   `).run(id, user.id, args.title, args.description, price, args.stock ?? 1, args.category ?? null, stakeAmount, specsJson, args.brand ?? null, args.model ?? null, args.source_price != null ? Number(args.source_price) : null, args.ship_regions ?? '全国', args.handling_hours != null ? Number(args.handling_hours) : 24, estJson, args.fragile ? 1 : 0, args.return_days != null ? Number(args.return_days) : 7, args.return_condition ?? '', args.warranty_days != null ? Number(args.warranty_days) : 0);
     // 注：per-order stake 模型不在此 lock — 移到 place_order 时按订单总额锁
     // S2/S3/S4 新字段：通过 HTTP PUT 走标准校验路径（i18n 语言白名单 / origin_claims 4KB+sha256 / 库存阈值）
@@ -3536,13 +3710,18 @@ async function handleReferral(args) {
                 state = 'never_activated';
                 note = 'Rewards inactive — attributions recorded; commissions held in pending_commission_escrow (30d window per protocol_params.rewards_opt_in.escrow_days) until you activate via PWA #me.';
             }
-            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'").get(userId);
-            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'").get(userId);
+            // RFC-018: matures_at IS NULL = opt-out escrow only (clearing rows auto-mature; surfaced separately in PR3).
+            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NULL").get(userId);
+            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired' AND matures_at IS NULL").get(userId);
+            // RFC-018 clearing window: opted-in commission accrued but not yet matured into the wallet
+            // (matures_at NOT NULL). Distinct from opt-out escrow above — pure read, surfaced for the agent.
+            const clearing = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NOT NULL").get(userId);
             return {
                 state,
                 opted_in: optIn === 1,
                 note,
                 pending_escrow: { count: pending.n, total_amount: pending.total },
+                clearing: { count: clearing.n, total_amount: clearing.total }, // RFC-018: accrued, maturing after the return window (not yet paid)
                 expired_to_charity: { count: expired.n, total_amount: expired.total },
                 spec: 'RFC-002 §3.5 — rewards / share-commission opt-in (RFC-002)',
             };
@@ -4948,7 +5127,7 @@ export async function startMCPServer() {
             // ─── RFC-003 Batch 0 安全网:NETWORK 模式下未迁移的工具【硬失败】,不静默落本地沙盒 ───
             // 例外:info / register(NETWORK_SELF_AWARE)有专门 network-aware 处理,照常放行。
             let handled = false;
-            if (isNetworkMode() && !NETWORK_TOOLS.has(name) && !NETWORK_SELF_AWARE.has(name)) {
+            if (isNetworkMode() && !toolAllowedInNetworkMode(name)) {
                 result = networkMigrationPending(name);
                 handled = true;
             }
@@ -4957,6 +5136,9 @@ export async function startMCPServer() {
                     case 'webaz_info':
                         result = await handleInfo();
                         break;
+                    case 'webaz_pair':
+                        result = await handlePair(args);
+                        break;
                     case 'webaz_register':
                         result = handleRegister(args);
                         break;

package/dist/layer4-economics/L4-4-skill-market/skill-engine.js

@@ -5,7 +5,7 @@
  * 核心思路：解决冷启动——现有 Amazon/Shopify 卖家零成本接入新渠道。
  *
  * Skill 类型：
- *   catalog_sync      - 目录同步（把外部店铺接入 DCP 搜索）
+ *   catalog_sync      - 目录同步（把外部店铺接入 WebAZ 搜索）
  *   auto_accept       - 自动接单（买家下单后立即接受，无需等待）
  *   price_negotiation - 价格协商（允许 Agent 在限定范围内议价）
  *   quality_guarantee - 质量承诺（额外质押，增强买家信心）
@@ -67,8 +67,8 @@ export const SKILL_TYPE_META = {
         label: '目录同步',
         label_en: 'Catalog sync',
         icon: '🔄',
-        description: '将卖家的外部商品目录（Amazon/Shopify/自定义）同步到 DCP，买家 Agent 订阅后可优先发现这些商品。',
-        description_en: 'Sync seller external catalogs (Amazon/Shopify/custom) to DCP — subscribed buyer agents discover these first.',
+        description: '将卖家的外部商品目录（Amazon/Shopify/自定义）同步到 WebAZ，买家 Agent 订阅后可优先发现这些商品。',
+        description_en: 'Sync seller external catalogs (Amazon/Shopify/custom) to WebAZ — subscribed buyer agents discover these first.',
     },
     auto_accept: {
         label: '自动接单',
@@ -95,7 +95,7 @@ export const SKILL_TYPE_META = {
         label: '质量承诺',
         label_en: 'Quality guarantee',
         icon: '🛡️',
-        description: '卖家额外质押 DCP 作为质量保证金，问题订单买家可获得额外赔偿。',
+        description: '卖家额外质押 WAZ 作为质量保证金，问题订单买家可获得额外赔偿。',
         description_en: 'Seller stakes extra WAZ as quality bond — buyer gets additional compensation on disputes.',
     },
     instant_ship: {

package/dist/ledger.js

@@ -1,9 +1,18 @@
 import { toUnits, toDecimal } from './money.js';
 /** 读某用户钱包当前余额(整数 base-units)。无钱包行 → 全 0。 */
 export function walletUnits(db, userId) {
-    const r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned FROM wallets WHERE user_id = ?')
-        .get(userId);
-    return { balance: toUnits(r?.balance ?? 0), staked: toUnits(r?.staked ?? 0), escrowed: toUnits(r?.escrowed ?? 0), earned: toUnits(r?.earned ?? 0) };
+    // fee_staked 是 Direct Pay 新增列。向后兼容缺该列的库(迁移前 / 测试用最小 schema):
+    //   先按含 fee_staked 查;若该列不存在(no such column)→ 退回 4 列查,fee_staked=0。
+    let r;
+    try {
+        r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned, COALESCE(fee_staked,0) fee_staked FROM wallets WHERE user_id = ?')
+            .get(userId);
+    }
+    catch {
+        r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned FROM wallets WHERE user_id = ?')
+            .get(userId);
+    }
+    return { balance: toUnits(r?.balance ?? 0), staked: toUnits(r?.staked ?? 0), escrowed: toUnits(r?.escrowed ?? 0), earned: toUnits(r?.earned ?? 0), fee_staked: toUnits(r?.fee_staked ?? 0) };
 }
 /**
  * 对钱包字段施加整数单位 delta,以【绝对值】落库(读当前→加 delta→写 toDecimal)。

package/dist/mcp.js

@@ -4,12 +4,31 @@
  *
  * 运行:npm run mcp(或 npx @seasonkoh/webaz);通过 stdio 与 Claude 等 MCP 客户端通信。
  * 工具实现都在 src/layer1-agent/L1-1-mcp-server/server.ts(本文件只是 bootstrap)。
- * 双模:配 WEBAZ_API_KEY → NETWORK(调 webaz.xyz 共享网络);否则 SANDBOX(本机库)。详见 RFC-003。
+ * 模式:配 WEBAZ_API_KEY → NETWORK(可交易,调 webaz.xyz 共享网络);无 key → NETWORK 只读(公共读走 webaz.xyz);
+ *   仅 WEBAZ_MODE=sandbox 才用本机库(与全网隔离,dev/demo)。默认【不是】sandbox。详见 RFC-003。
  *
- * 关联 / Related: AGENTS.md(项目地图) · RFC-003(双模) · RFC-004(webaz_feedback)
+ * 关联 / Related: AGENTS.md(项目地图) · RFC-003(三态:network / network_readonly / sandbox) · RFC-004(webaz_feedback)
  */
-import { startMCPServer } from './layer1-agent/L1-1-mcp-server/server.js';
-startMCPServer().catch((err) => {
+// ⚠️ 只【静态】import cli.js(纯:version + network-mode,无副作用)。【不】静态 import server.js ——
+//   server.js 顶层会 initDatabase()/建 schema,静态 import 会让 --version/--help/--mode 也触发 DB 副作用
+//   (写 ~/.webaz/*.db)+ 加载整个 server(#186 审计 P1)。故 server.js 只在真正启动时【动态】import。
+import { cliQuickResponse, runDoctor } from './layer1-agent/L1-1-mcp-server/cli.js';
+async function main() {
+    const argv = process.argv.slice(2);
+    const quick = cliQuickResponse(argv, process.env); // --version / --help / --mode(纯,不碰 DB/server)
+    if (quick !== null) {
+        console.log(quick);
+        process.exit(0);
+    }
+    if (argv.includes('--doctor')) {
+        console.log(await runDoctor(process.env));
+        process.exit(0);
+    }
+    // 只有真正启动 stdio server 时才动态加载 server.js(此时才允许 DB 初始化等副作用)。
+    const { startMCPServer } = await import('./layer1-agent/L1-1-mcp-server/server.js');
+    await startMCPServer();
+}
+main().catch((err) => {
     console.error('MCP Server 启动失败：', err);
     process.exit(1);
 });

package/dist/merchant-bond-domain.js

@@ -0,0 +1,64 @@
+/**
+ * Merchant Base-Bond (v1 collateral-only) — domain skeleton (PR1, testnet/dev scaffold).
+ *
+ * 设计真相源:docs/modules/MERCHANT-BASE-BOND-DESIGN.INTERNAL.md(v1 candidate-locked)。
+ * 本模块是【纯域逻辑骨架】:状态机 + 资格派生 + 类型。**不写 DB、不接任何 live 路径、不碰资金。**
+ *
+ * v1 已锁(见设计稿 §12):
+ *  - 链上非托管锁仓合约持有 collateral;买家货款永不进合约;平台费【不上链】(链下账务)。
+ *  - slash 仅治理触发 + 链上硬约束(v1 无自动/小额 slash)。
+ *  - 合约 v1 不可升级;链 = Base + 白名单 USDC(单链);入门门 = 单一 base_bond_min_units(不分档)。
+ *  - wallet rotation = seller 签名 + WebAZ 授权;治理仅紧急。
+ *  - 计价用 base_bond_min_units(USDC 整数单位),不引预言机。
+ *
+ * ⚠️ MERCHANT_BOND_V1_ENABLED 默认 false:整套 v1 在 testnet/dev scaffold 阶段【关闭】,
+ *   mainnet + 真实 USDC 需先过 法务 + 外部合约审计 + Holden 批准(设计稿 §9)。
+ */
+/** 全局开关:v1 默认关闭(PR1 scaffold)。真实启用前永远 false。 */
+export const MERCHANT_BOND_V1_ENABLED = false;
+/** v1 链:Base + 白名单 USDC(单链;仅 chain profile 占位,无多链抽象)。 */
+export const MERCHANT_BOND_CHAIN_PROFILE = {
+    key: 'base',
+    // 真实 chainId / USDC 地址 / 确认数 N 在 mainnet 接入时由治理/配置定稿(政策参数);此处仅占位。
+    chainId: null,
+    usdcAddress: null,
+    minConfirmations: null,
+};
+/** Seller 生命周期状态(枚举;`paused` 不是 seller 状态,pause 是正交 flags)。 */
+export const BOND_STATUS = {
+    NONE: 'none',
+    PENDING_CONFIRMATIONS: 'pending_confirmations',
+    ACTIVE: 'active',
+    COOLING: 'cooling',
+    WITHDRAWABLE: 'withdrawable',
+    WITHDRAWN: 'withdrawn',
+    SLASHED_BELOW_MIN: 'slashed_below_min',
+};
+/** 合法状态转移(域层薄校验;真相仍以链上合约 event 为准)。 */
+const VALID_TRANSITIONS = {
+    [BOND_STATUS.NONE]: [BOND_STATUS.PENDING_CONFIRMATIONS],
+    [BOND_STATUS.PENDING_CONFIRMATIONS]: [BOND_STATUS.ACTIVE, BOND_STATUS.NONE],
+    [BOND_STATUS.ACTIVE]: [BOND_STATUS.COOLING, BOND_STATUS.SLASHED_BELOW_MIN],
+    [BOND_STATUS.COOLING]: [BOND_STATUS.WITHDRAWABLE, BOND_STATUS.ACTIVE],
+    [BOND_STATUS.WITHDRAWABLE]: [BOND_STATUS.WITHDRAWN, BOND_STATUS.ACTIVE],
+    [BOND_STATUS.WITHDRAWN]: [],
+    [BOND_STATUS.SLASHED_BELOW_MIN]: [BOND_STATUS.ACTIVE],
+};
+export function canTransitionBond(from, to) {
+    return (VALID_TRANSITIONS[from] || []).includes(to);
+}
+/**
+ * 资格派生(单一真相函数:readiness 与 create gate 必须都调它,定义逐字一致)。
+ * fail-closed:开关关 / 未绑钱包 / 未确认 / 状态非 active / 担保不足 → false。
+ * v1 入门门 = 单一 base_bond_min_units(不分档)。
+ */
+export function deriveSellerHasProductionBaseBondLocked(view, baseBondMinUnits) {
+    if (!MERCHANT_BOND_V1_ENABLED)
+        return false; // v1 scaffold 默认关 → 永远不翻真实资格
+    if (!view)
+        return false;
+    return view.walletBound
+        && view.confirmed
+        && view.status === BOND_STATUS.ACTIVE
+        && view.collateralUnits >= baseBondMinUnits;
+}