@seasonkoh/webaz 0.1.27 → 0.1.28

package/README.md

@@ -79,7 +79,7 @@ WebAZ deliberately separates **principle** (permanent) from **mechanism** (tunab
 - Money flows are fully parameterized and on-chain-auditable. The operator earns only an explicit platform fee + risk-event slashing — most of it rerouted to a public-good fund. Full walk-through: [`docs/ECONOMIC-MODEL.md`](docs/ECONOMIC-MODEL.md).
 - The constitution (meta-rules) and amendment thresholds live in [`docs/CHARTER.md`](docs/CHARTER.md) / [`docs/META-RULES-FULL.md`](docs/META-RULES-FULL.md).
 
-> **No MLM / matching-reward engine.** The binary/PV matching-reward engine has been **excised** from the public code (`src/pwa/internal/pv-settlement.ts` is a permanent no-op stub). PV is a **participation record only — not income, not redeemable, no entitlement.** See [`docs/REWARD-ENGINES-DECOUPLING.md`](docs/REWARD-ENGINES-DECOUPLING.md).
+> Matching rewards are disabled by default; PV / position is a participation record only — not income, not redeemable, no entitlement. See [`docs/REWARD-ENGINES-DECOUPLING.md`](docs/REWARD-ENGINES-DECOUPLING.md).
 
 **Fund split** (current `protocol_params` defaults, DAO-adjustable; 100-unit shop order):
 

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

@@ -0,0 +1,69 @@
+/**
+ * RFC-003 — MCP NETWORK-mode tool gating (pure, testable; no I/O).
+ *
+ * In `network` / `network_readonly` mode the dispatcher hard-fails any tool that is
+ * NOT allowed through, so an un-migrated tool can't silently fall back to the local
+ * sandbox (a write would become a phantom op). This module holds the allow-sets +
+ * the predicate so the gate decision is unit-testable without booting the stdio
+ * server. (Extracted from server.ts; behavior unchanged except adding webaz_pair.)
+ */
+// Tools that talk to the live webaz.xyz network (Bearer api_key where needed).
+// Un-listed tools run sandbox (local). `_mode` annotation = network for these.
+export const NETWORK_TOOLS = new Set([
+    // RFC-020 onboarding/auth: pairing is the no-key credential bootstrap — it MUST be
+    // reachable in the default network_readonly install (you pair to GET a credential).
+    'webaz_pair',
+    '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。
+    'webaz_follows',
+    'webaz_like',
+    'webaz_blocklist',
+    'webaz_default_address',
+    'webaz_chat',
+    'webaz_rfq',
+    'webaz_referral',
+    // Batch 3(商务):
+    '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(铁律/敏感):
+    'webaz_dispute',
+    'webaz_claim_verify',
+    'webaz_rotate_key',
+    'webaz_revoke_key',
+    // #1122:share_link 现有服务端端点 /api/share-link,可走网络。
+    'webaz_share_link',
+]);
+// Not in NETWORK_TOOLS but still allowed to run in NETWORK mode as self-aware /
+// onboarding tools (non-data ops): info = local introspection; register = redirect
+// the human to webaz.xyz. Everything else un-migrated hard-fails.
+export const NETWORK_SELF_AWARE = new Set(['webaz_info', 'webaz_register']);
+/**
+ * In NETWORK / network_readonly mode, may this tool proceed (vs migration-pending
+ * hard-fail)? True for migrated network tools and the self-aware onboarding tools.
+ */
+export function toolAllowedInNetworkMode(tool) {
+    return NETWORK_TOOLS.has(tool) || NETWORK_SELF_AWARE.has(tool);
+}

package/dist/layer1-agent/L1-1-mcp-server/server.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 } 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';
@@ -63,56 +70,6 @@ const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
             : (WEBAZ_API_KEY ? 'network' : 'network_readonly');
 // 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 +81,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 +136,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 +345,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 +482,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
@@ -4948,7 +5125,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 +5134,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;