@seasonkoh/webaz 0.1.29 → 0.1.31

package/dist/pwa/routes/agent-grants.js

@@ -1,12 +1,16 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
-import { initAgentDelegationGrantsSchema, initAgentPairingSchema, initAgentGrantAuthLogSchema } from '../../runtime/webaz-schema-helpers.js';
-import { validateRequestedCapabilities, clampTtlSeconds, grantIsActive } from '../../runtime/agent-grant-scopes.js';
+import { initAgentDelegationGrantsSchema, initAgentPairingSchema, initAgentGrantAuthLogSchema, initAgentPermissionRequestsSchema } from '../../runtime/webaz-schema-helpers.js';
+import { validateRequestedCapabilities, clampTtlSeconds, grantIsActive, resolveBundle, durationAllowedForScopes, suggestedDurationForScopes, durationToSeconds, riskLevelForScopes } from '../../runtime/agent-grant-scopes.js';
 import { generateUserCode, verifyPkceS256, clampPairingTtlSeconds, pairingApprovable, pairingRetrievable } from '../../runtime/agent-pairing.js';
 import { verifyGrantToken } from '../../runtime/agent-grant-verifier.js';
 // Bounds on a pairing request (anti-bloat for the anonymous start endpoint).
 const MAX_CAPABILITIES = 12;
 const MAX_CONSTRAINTS_JSON = 2000;
+// Thrown inside the approve transaction when the grant is no longer active (revoked/expired in the race
+// window) — rolls the whole tx back so the request claim + expansion + audit are all-or-nothing.
+class GrantInactiveError extends Error {
+}
 function safeParseCaps(json) {
     try {
         return JSON.parse(String(json));
@@ -28,11 +32,23 @@ function consentView(p) {
     };
 }
 export function registerAgentGrantsRoutes(app, deps) {
-    const { db, auth, generateId, rateLimitOk } = deps;
+    const { db, auth, generateId, rateLimitOk, requireHumanPresence, createProductDraftHandler } = deps;
     // PWA runtime self-init (MCP gets the tables via applyWebazRuntimeSchema). Idempotent.
     initAgentDelegationGrantsSchema(db);
     initAgentPairingSchema(db);
     initAgentGrantAuthLogSchema(db);
+    initAgentPermissionRequestsSchema(db);
+    // Resolve the ACTIVE grant behind a gtk_ bearer (no scope check) — used to bind a permission request to
+    // (grant_id, human_id). Returns null on missing/expired/revoked. token_hash lookup mirrors the verifier.
+    async function resolveActiveGrantByBearer(req) {
+        const bearer = (req.header('authorization') || '').replace(/^Bearer\s+/i, '');
+        if (!bearer.startsWith('gtk_'))
+            return null;
+        const g = await dbOne('SELECT grant_id, human_id, agent_label, capabilities, status, expires_at, revoked_at FROM agent_delegation_grants WHERE token_hash = ?', [createHash('sha256').update(bearer).digest('hex')]);
+        if (!g || !grantIsActive(g, new Date().toISOString()))
+            return null;
+        return { grant_id: g.grant_id, human_id: g.human_id, agent_label: g.agent_label, capabilities: g.capabilities };
+    }
     // ─────────────────────────── RFC-020 PR-C2a: opt-in grant-scope enforcement ───────────────────────────
     // EXPLICIT, per-route, per-SAFE-scope. NOT global auth — a gtk_* token is accepted ONLY by routes that
     // deliberately mount requireAgentGrantScope(scope); auth()/api_key is untouched and never accepts gtk_*.
@@ -60,8 +76,25 @@ export function registerAgentGrantsRoutes(app, deps) {
             }
         }
         // Deny path: return the denial regardless of audit (no access is granted, so nothing to fail closed on).
-        if (!r.ok)
+        if (!r.ok) {
+            // Structured permission_required (RFC-020): the agent IS validly connected but its grant simply lacks
+            //   this SAFE scope. Instead of a bare 403, hand it the exact next step — ask the human to expand the
+            //   grant (approval_url + the create-request call), then retry this same request. Other grant failures
+            //   (no/expired/revoked/suspended grant) stay plain: those aren't "request more", they must re-pair.
+            if (r.error_code === 'SCOPE_NOT_GRANTED') {
+                return void res.status(403).json({
+                    error: `this action needs the "${scope}" permission, which your grant does not carry`,
+                    error_code: 'PERMISSION_REQUIRED',
+                    required_scope: scope,
+                    missing_scopes: [scope],
+                    approval_url: '/#agent-approvals',
+                    retry_after_approval: true,
+                    request_permission: { method: 'POST', endpoint: '/api/agent-grants/permission-requests', body: { scopes: [scope] } },
+                    note: 'Ask the human to approve at approval_url; on approval your existing grant is expanded — then retry this request.',
+                });
+            }
             return void res.status(r.status).json({ error: r.error, error_code: r.error_code });
+        }
         // Success path: FAIL CLOSED if the authorization could not be audited — a grant-authorized request
         // must never proceed unaudited (RFC-020 invariant). Better to deny (503, retryable) than act unaccountably.
         if (!audited)
@@ -75,6 +108,211 @@ export function registerAgentGrantsRoutes(app, deps) {
         const p = req.agentGrant;
         res.json({ grant: p, note: 'Authorized via delegation grant (safe scope read_public). This is a grant principal, not a human session.' });
     });
+    // First REAL grant-consumed seller surface (Catalog Agent): read the grant human's OWN catalog. Read-only,
+    //   money fields (commission/stake) excluded. A grant that lacks seller_products_read → structured
+    //   permission_required (see requireAgentGrantScope) so the agent can request → human approves → retry.
+    //   The consumption (allow AND the permission_required deny) is audited by the middleware.
+    app.get('/api/agent/seller/products', requireAgentGrantScope('seller_products_read'), async (req, res) => {
+        const p = req.agentGrant;
+        const rows = await dbAll("SELECT id, title, status, price, currency, stock, category, created_at, updated_at FROM products WHERE seller_id = ? AND status != 'deleted' ORDER BY created_at DESC LIMIT 200", [p.human_id]);
+        res.json({ seller_id: p.human_id, agent_label: p.agent_label, count: rows.length, products: rows, note: 'Seller-owned catalog read via delegation grant (safe scope seller_products_read). Read-only; no money/commission fields.' });
+    });
+    // POST create a DRAFT product via a delegation grant (Catalog Agent, safe scope seller_product_draft). The
+    //   draft is FORCED to status='warehouse' (not public/sellable). PUBLISHING STAYS HUMAN-ONLY — the human
+    //   flips warehouse→active in the existing 我的商品→仓库 UI (publish is never delegated to a grant, matching
+    //   the taxonomy). Reuses the SAME product-create validation as the human POST /api/products
+    //   (createProductDraftHandler) so the agent path can't drift. Audited by the middleware. Lightweight signal:
+    //   a notification tells the human a draft is waiting to review + publish.
+    if (createProductDraftHandler) {
+        app.post('/api/agent/seller/products', requireAgentGrantScope('seller_product_draft'), async (req, res) => {
+            const p = req.agentGrant;
+            const human = await dbOne('SELECT id, role FROM users WHERE id = ?', [p.human_id]);
+            if (!human || human.role !== 'seller')
+                return void res.status(403).json({ error: 'the grant owner is not a seller — product drafts need a seller account', error_code: 'NOT_A_SELLER' });
+            await createProductDraftHandler(req, res, human, {
+                forceStatus: 'warehouse',
+                skipExternalLinkEffects: true, // a SAFE draft grant must never trigger wallet debit / verify_tasks / auto-verified links (source_url stays inert metadata)
+                onCreated: async (productId) => {
+                    try {
+                        await dbRun("INSERT INTO notifications (id, user_id, type, title, body) VALUES (?,?,?,?,?)", [generateId('ntf'), p.human_id, 'agent_product_draft', 'AI 助手起草了商品草稿', `${p.agent_label || 'An agent'} 起草了商品草稿 ${productId}，请到「我的商品 → 仓库」审核并发布。`]);
+                    }
+                    catch (e) {
+                        console.error('[agent-grant draft notify]', e.message);
+                    }
+                },
+            });
+        });
+    }
+    // helpers for the permission-request flow ----------------------------------------------------------------
+    const parseCapList = (json) => { try {
+        const a = JSON.parse(json);
+        return Array.isArray(a) ? a : [];
+    }
+    catch {
+        return [];
+    } };
+    const scopeNames = (json) => parseCapList(json).map(c => (typeof c === 'string' ? c : c?.capability)).filter((s) => typeof s === 'string');
+    // Returns true iff the audit row was durably written. Callers on the grant-authorized SUCCESS path MUST
+    // fail closed when this is false (RFC-020 invariant: a grant-authorized action is audited or it does not
+    // happen) — parity with the requireAgentGrantScope middleware above.
+    const auditGrant = async (grantId, humanId, cap, outcome, errorCode) => {
+        try {
+            await dbRun('INSERT INTO agent_grant_auth_log (grant_id, human_id, capability, outcome, error_code) VALUES (?,?,?,?,?)', [grantId, humanId, cap, outcome, errorCode ?? null]);
+            return true;
+        }
+        catch (e) {
+            console.error('[agent-grant] audit write failed:', e.message);
+            return false;
+        }
+    };
+    const bundleSummary = (key) => { const b = key ? resolveBundle(key) : null; return b ? b.human_summary : null; };
+    // GET verify — grant-authed. Returns the FULL grant (scopes, bundle, expiry, status), not just read_public.
+    //   Audited (acceptance #8: every grant use logs). Never returns the raw token/api_key.
+    app.get('/api/agent-grants/verify', async (req, res) => {
+        const g = await resolveActiveGrantByBearer(req);
+        if (!g) {
+            return void res.status(401).json({ error: 'active delegation grant required', error_code: 'GRANT_REQUIRED' });
+        }
+        const full = await dbOne('SELECT grant_id, human_id, agent_label, capabilities, status, expires_at, permission_bundle FROM agent_delegation_grants WHERE grant_id = ?', [g.grant_id]);
+        // Fail closed: a grant-authorized read is audited or it does not proceed (parity with requireAgentGrantScope).
+        if (!(await auditGrant(g.grant_id, g.human_id, 'grant:verify', 'allow')))
+            return void res.status(503).json({ error: 'authorization audit unavailable; refusing to proceed unaudited', error_code: 'GRANT_AUDIT_FAILED' });
+        res.json({ grant: { grant_id: full.grant_id, human_id: full.human_id, agent_label: full.agent_label, scopes: scopeNames(full.capabilities), permission_bundle: full.permission_bundle, expires_at: full.expires_at, status: full.status }, note: 'Full grant principal — all authorized scopes/bundle/expiry/status. Not a human session; never authorizes risk/never-delegable actions.' });
+    });
+    // POST create a permission request — the AGENT (holding its current grant) asks for MORE scope / a bundle.
+    //   Bound to (human_id, grant_id) from the grant bearer. Rate-limited. Safe-only: risk/never-delegable are
+    //   NOT grantable (they need a per-action live Passkey, not a persistent grant) → structured reject.
+    app.post('/api/agent-grants/permission-requests', async (req, res) => {
+        if (!rateLimitOk(`agent_perm_req:${req.ip || 'anon'}`, 20, 60_000))
+            return void res.status(429).json({ error: 'too_many_permission_requests', retry_after_s: 60 });
+        const g = await resolveActiveGrantByBearer(req);
+        if (!g)
+            return void res.status(401).json({ error: 'an active delegation grant is required to request more permissions (pair first with webaz_pair)', error_code: 'GRANT_REQUIRED' });
+        const body = (req.body || {});
+        const bundleKey = typeof body.bundle === 'string' ? body.bundle : null;
+        const bundle = bundleKey ? resolveBundle(bundleKey) : null;
+        if (bundleKey && !bundle)
+            return void res.status(400).json({ error: 'unknown permission bundle', error_code: 'UNKNOWN_BUNDLE' });
+        const scopes = bundle ? [...bundle.scopes] : (Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === 'string') : []);
+        if (scopes.length === 0)
+            return void res.status(400).json({ error: 'bundle or scopes required', error_code: 'NO_SCOPES' });
+        const v = validateRequestedCapabilities(scopes.map(s => ({ capability: s })));
+        if (!v.ok)
+            return void res.status(403).json({ error: 'permission_not_grantable', error_code: 'PERMISSION_NOT_GRANTABLE', rejected: v.rejected, note: 'Only safe (read/draft) scopes can be granted. Risk actions (order/publish/refund/…) require the human to act with a live Passkey — they are never delegated to a persistent grant.' });
+        const risk = riskLevelForScopes(scopes);
+        const duration = durationAllowedForScopes(scopes, body.duration) ? body.duration : suggestedDurationForScopes(scopes);
+        const id = generateId('apr');
+        const reqTtlIso = new Date(Date.now() + 7 * 86400_000).toISOString(); // request auto-expires in 7d if unanswered
+        await dbRun('INSERT INTO agent_permission_requests (id, human_id, grant_id, agent_label, requested_scopes, permission_bundle, reason, task_context, risk_level, duration, status, expires_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)', [id, g.human_id, g.grant_id, g.agent_label, JSON.stringify(scopes), bundleKey, typeof body.reason === 'string' ? body.reason.slice(0, 280) : null, typeof body.task_context === 'string' ? body.task_context.slice(0, 500) : null, risk, duration, 'pending', reqTtlIso]);
+        res.status(201).json({ approval_id: id, approval_url: '/#agent-approvals', status: 'pending', risk_level: risk, requested_scopes: scopes, permission_bundle: bundleKey, human_summary: bundleSummary(bundleKey), suggested_duration: duration, note: 'Ask the human to open approve_url (logged in) and approve. On approval your existing grant is expanded; then retry.' });
+    });
+    // GET list this human's PENDING permission requests (for #agent-approvals). Human-authed.
+    app.get('/api/agent-grants/permission-requests', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rows = await dbAll("SELECT id, agent_label, requested_scopes, permission_bundle, reason, task_context, risk_level, duration, created_at, expires_at FROM agent_permission_requests WHERE human_id = ? AND status = 'pending' AND expires_at > ? ORDER BY created_at DESC LIMIT 100", [user.id, new Date().toISOString()]);
+        res.json({ requests: rows.map(r => ({ ...r, requested_scopes: scopeNames(String(r.requested_scopes)), human_summary: bundleSummary(r.permission_bundle) })) });
+    });
+    // GET list the requests THIS grant created — GRANT-authed (the agent, via webaz_pair), so an agent can poll
+    //   its own request status (pending/approved/rejected/expired) without hitting the target surface. Bound to
+    //   grant_id: an agent sees ONLY its own requests, never the human's other agents'. Audited (fail-closed).
+    app.get('/api/agent-grants/my-permission-requests', async (req, res) => {
+        if (!rateLimitOk(`agent_perm_list:${req.ip || 'anon'}`, 30, 60_000))
+            return void res.status(429).json({ error: 'too_many_requests', error_code: 'GRANT_RATE_LIMITED', retry_after_s: 60 });
+        const g = await resolveActiveGrantByBearer(req);
+        if (!g)
+            return void res.status(401).json({ error: 'an active delegation grant is required (pair first with webaz_pair)', error_code: 'GRANT_REQUIRED' });
+        const rows = await dbAll('SELECT id, requested_scopes, permission_bundle, risk_level, duration, status, created_at, expires_at, approved_at FROM agent_permission_requests WHERE grant_id = ? ORDER BY created_at DESC LIMIT 50', [g.grant_id]);
+        if (!(await auditGrant(g.grant_id, g.human_id, 'grant:list_requests', 'allow')))
+            return void res.status(503).json({ error: 'authorization audit unavailable; refusing to proceed unaudited', error_code: 'GRANT_AUDIT_FAILED' });
+        res.json({ requests: rows.map(r => ({ ...r, requested_scopes: scopeNames(String(r.requested_scopes)), human_summary: bundleSummary(r.permission_bundle) })) });
+    });
+    // RFC-020: expanding an agent grant is a privilege escalation (like initial pairing) — a stolen web session
+    //   must NOT widen an agent from read_public to a long-term bundle. So a LIVE Passkey bound to this request_id
+    //   is required. Grant-active is checked BEFORE claiming the request, and the expand is guarded + reversible,
+    //   so a mid-flight expire/revoke can never strand a phantom 'approved'.
+    // POST approve — human-authed + live Passkey; expands the bound grant (union scopes + bundle + extend expiry). Audited.
+    app.post('/api/agent-grants/permission-requests/:id/approve', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const now = new Date().toISOString();
+        const r = await dbOne('SELECT human_id, grant_id, requested_scopes, permission_bundle, duration, status, expires_at FROM agent_permission_requests WHERE id = ?', [req.params.id]);
+        if (!r)
+            return void res.status(404).json({ error: 'permission_request_not_found' });
+        if (r.human_id !== user.id)
+            return void res.status(403).json({ error: 'not your permission request' });
+        if (r.status !== 'pending' || r.expires_at <= now)
+            return void res.status(409).json({ error: 'permission_request_not_pending', status: r.status });
+        // Live Passkey, bound to THIS request (a token minted for request A can't approve B).
+        const hp = requireHumanPresence(user.id, 'agent_permission_approve', (req.body || {}).webauthn_token, 'require_human_presence_for_agent_permission_approve', (data) => { try {
+            return typeof data === 'object' && data !== null && data.request_id === req.params.id;
+        }
+        catch {
+            return false;
+        } });
+        if (!hp.ok)
+            return void res.status(412).json({ error: hp.reason, error_code: hp.error_code });
+        const reqScopes = scopeNames(r.requested_scopes);
+        // Defense in depth: re-validate safe-only + duration allowed at approval time.
+        if (!validateRequestedCapabilities(reqScopes.map(s => ({ capability: s }))).ok)
+            return void res.status(403).json({ error: 'permission_not_grantable', error_code: 'PERMISSION_NOT_GRANTABLE' });
+        if (!durationAllowedForScopes(reqScopes, r.duration))
+            return void res.status(403).json({ error: 'duration_not_allowed_for_risk', error_code: 'DURATION_NOT_ALLOWED' });
+        // (P2) Verify the grant is ACTIVE *before* claiming the request — never leave a phantom 'approved'.
+        const grant = await dbOne('SELECT grant_id, capabilities, status, expires_at, revoked_at FROM agent_delegation_grants WHERE grant_id = ?', [r.grant_id]);
+        if (!grant || !grantIsActive(grant, now))
+            return void res.status(409).json({ error: 'grant_inactive', error_code: 'GRANT_INACTIVE', note: 'the agent grant expired or was revoked; re-pair (this request stays pending)' });
+        // Union new scopes into the grant; set bundle; extend expiry (never shorten). 'once' → short 1h window.
+        const union = [...new Set([...scopeNames(grant.capabilities), ...reqScopes])].map(s => ({ capability: s, constraints: {} }));
+        const secs = durationToSeconds(r.duration) || 3600;
+        const newExpiry = new Date(Date.now() + secs * 1000).toISOString();
+        const expiresAt = newExpiry > grant.expires_at ? newExpiry : grant.expires_at;
+        // ATOMIC (RFC-020 invariant: a grant expansion is audited-or-it-does-not-happen; parity with arbitrator
+        //   approve). CAS-claim the request + guarded-expand the grant + write the audit row in ONE sync
+        //   db.transaction. If the audit INSERT throws, OR the grant was revoked in the race window (guarded
+        //   WHERE → 0 rows → GrantInactiveError), the WHOLE tx rolls back: scopes unchanged, request stays pending.
+        let outcome;
+        try {
+            outcome = db.transaction(() => {
+                const claimed = db.prepare("UPDATE agent_permission_requests SET status='approved', approved_at=? WHERE id=? AND status='pending'").run(now, req.params.id);
+                if (claimed.changes !== 1)
+                    return 'not_pending';
+                const expanded = db.prepare("UPDATE agent_delegation_grants SET capabilities=?, permission_bundle=COALESCE(?, permission_bundle), expires_at=? WHERE grant_id=? AND status='active' AND revoked_at IS NULL").run(JSON.stringify(union), r.permission_bundle, expiresAt, grant.grant_id);
+                if (expanded.changes !== 1)
+                    throw new GrantInactiveError();
+                db.prepare('INSERT INTO agent_grant_auth_log (grant_id, human_id, capability, outcome, error_code) VALUES (?,?,?,?,?)').run(grant.grant_id, user.id, `permission_request:approve:${r.permission_bundle || reqScopes.join(',')}`, 'allow', null);
+                return 'expanded';
+            })();
+        }
+        catch (e) {
+            if (e instanceof GrantInactiveError)
+                return void res.status(409).json({ error: 'grant_inactive', error_code: 'GRANT_INACTIVE', note: 'the agent grant was revoked while approving; request stays pending' });
+            console.error('[agent-grant] approve tx failed (audit unavailable?):', e.message);
+            return void res.status(503).json({ error: 'authorization audit unavailable; refusing to expand unaudited', error_code: 'GRANT_AUDIT_FAILED' });
+        }
+        if (outcome === 'not_pending')
+            return void res.status(409).json({ error: 'permission_request_not_pending' });
+        res.json({ success: true, grant_id: grant.grant_id, scopes: union.map(u => u.capability), permission_bundle: r.permission_bundle, expires_at: expiresAt });
+    });
+    // POST reject — human-authed. Terminal 'rejected'; nothing is granted.
+    app.post('/api/agent-grants/permission-requests/:id/reject', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = await dbOne('SELECT human_id, status FROM agent_permission_requests WHERE id = ?', [req.params.id]);
+        if (!r)
+            return void res.status(404).json({ error: 'permission_request_not_found' });
+        if (r.human_id !== user.id)
+            return void res.status(403).json({ error: 'not your permission request' });
+        if (r.status !== 'pending')
+            return void res.status(409).json({ error: 'permission_request_not_pending', status: r.status });
+        const rj = await dbRun("UPDATE agent_permission_requests SET status='rejected' WHERE id=? AND status='pending'", [req.params.id]);
+        if (!rj || rj.changes !== 1)
+            return void res.status(409).json({ error: 'permission_request_not_pending' });
+        res.json({ success: true, status: 'rejected' });
+    });
     // ─────────────────────────── RFC-020 PR-C1: pairing (device-flow + PKCE) ───────────────────────────
     // C1 = pairing + credential delivery ONLY. No grant is consumed by any tool here (that is PR-C2).
     // (pair 1) Agent starts a pairing — UNAUTHENTICATED (agent has no credential yet). Safe scopes only.
@@ -135,6 +373,17 @@ export function registerAgentGrantsRoutes(app, deps) {
             return void res.status(404).json({ error: 'pairing_not_found' });
         if (!pairingApprovable(p, now))
             return void res.status(409).json({ error: 'pairing_not_pending_or_expired', status: p.status });
+        // 人工在场 gate:批准 = 真人 Passkey/WebAuthn 确认(默认必需,param 可关)。挡"账号被静默批准"。
+        //   注:这挡的是"是不是真人在批",不挡 illicit-consent(人被骗批错 agent)—— 那由前端强制口令核对 + safe-scope 兜底。
+        //   token 必须【绑定这个配对码】(purpose_data.user_code === :user_code)—— 防"为批 A 拿到的 token 被首次提交去批 B"(与 delete_passkey 绑 credential_id 同法)。
+        const hp = requireHumanPresence(user.id, 'agent_pair_approve', (req.body || {}).webauthn_token, 'require_human_presence_for_agent_pair_approve', (data) => { try {
+            return typeof data === 'object' && data !== null && data.user_code === req.params.user_code;
+        }
+        catch {
+            return false;
+        } });
+        if (!hp.ok)
+            return void res.status(412).json({ error: hp.reason, error_code: hp.error_code });
         // Re-validate scopes at approval time (defense in depth) — must still be safe-only.
         const caps = safeParseCaps(p.capabilities);
         const v = validateRequestedCapabilities(caps);
@@ -142,11 +391,31 @@ export function registerAgentGrantsRoutes(app, deps) {
             return void res.status(403).json({ error: 'pairing_rejected', rejected: v.rejected });
         const grantId = generateId('grt');
         const expiresAt = new Date(Date.now() + clampTtlSeconds(undefined) * 1000).toISOString();
+        // 先【CAS 抢占】pending 配对(唯一赢家),再插 grant —— 竞态下输家 changes!==1 直接 409、不插任何 grant,
+        //   杜绝"插了 grant 但配对更新失败"留下 token_hash NULL 的 orphan grant(污染连接记录)。
+        const claimed = await dbRun("UPDATE agent_pairing_sessions SET status='approved', human_id=?, grant_id=?, approved_at=? WHERE user_code=? AND status='pending'", [user.id, grantId, now, req.params.user_code]);
+        if (!claimed || claimed.changes !== 1)
+            return void res.status(409).json({ error: 'pairing_not_pending_or_expired' });
         // Grant created WITHOUT a token (token_hash NULL) — the bearer is minted only at retrieval.
         await dbRun('INSERT INTO agent_delegation_grants (grant_id, human_id, agent_label, capabilities, token_hash, human_confirm_required, status, expires_at) VALUES (?,?,?,?,?,?,?,?)', [grantId, user.id, p.agent_label || null, JSON.stringify(caps), null, 0, 'active', expiresAt]);
-        await dbRun("UPDATE agent_pairing_sessions SET status='approved', human_id=?, grant_id=?, approved_at=? WHERE user_code=? AND status='pending'", [user.id, grantId, now, req.params.user_code]);
         res.json({ success: true, grant_id: grantId, capabilities: caps });
     });
+    // (pair 3b) Human rejects — human-authenticated. Terminal 'rejected' → agent's retrieve fails clearly (no silent lingering).
+    //   拒绝是保护性动作,无需 Passkey(不签发任何凭证)。幂等:仅 pending 可拒。
+    app.post('/api/agent-grants/pair/:user_code/reject', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const p = await dbOne('SELECT status FROM agent_pairing_sessions WHERE user_code = ?', [req.params.user_code]);
+        if (!p)
+            return void res.status(404).json({ error: 'pairing_not_found' });
+        if (p.status !== 'pending')
+            return void res.status(409).json({ error: 'pairing_not_pending', status: p.status });
+        const r = await dbRun("UPDATE agent_pairing_sessions SET status='rejected', human_id=? WHERE user_code=? AND status='pending'", [user.id, req.params.user_code]);
+        if (!r || r.changes !== 1)
+            return void res.status(409).json({ error: 'pairing_not_pending' });
+        res.json({ success: true, status: 'rejected' });
+    });
     // (pair 4) Agent retrieves the credential ONCE via PKCE verifier — UNAUTHENTICATED (PKCE-gated).
     app.post('/api/agent-grants/pair/:pairing_id/retrieve', async (req, res) => {
         const now = new Date().toISOString();
@@ -180,36 +449,16 @@ export function registerAgentGrantsRoutes(app, deps) {
             expires_at: grant.expires_at,
         });
     });
-    // ── Issue a grant (human-authenticated). Safe scopes only; risk/never-delegable rejected. ──
-    app.post('/api/agent-grants', async (req, res) => {
+    // ── Direct grant issuance is DISABLED — single blessed path is the Passkey pairing flow. ──
+    //   旧的"仅登录即直接 mint 原文 bearer"入口会旁路 #pair 的真人 Passkey 批准,削弱"human Passkey-approves
+    //   agent delegation"的安全叙事。零消费方(前端/MCP/测试均不用),故降级为不可用,统一走 pairing。
+    app.post('/api/agent-grants', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const body = (req.body || {});
-        const caps = Array.isArray(body.capabilities) ? body.capabilities : [];
-        const v = validateRequestedCapabilities(caps);
-        if (!v.ok) {
-            // Fail-closed: any risk / never-delegable / unknown scope rejects the whole request.
-            return void res.status(403).json({ error: 'grant_rejected', rejected: v.rejected });
-        }
-        const ttl = clampTtlSeconds(body.ttl_seconds);
-        const grantId = generateId('grt');
-        const token = `gtk_${randomBytes(32).toString('hex')}`; // bearer — shown once
-        const tokenHash = createHash('sha256').update(token).digest('hex');
-        const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
-        const label = typeof body.agent_label === 'string' ? body.agent_label.slice(0, 120) : null;
-        const capsJson = JSON.stringify(v.safe.map(c => ({
-            capability: c,
-            constraints: (caps.find(x => x?.capability === c)?.constraints) || {},
-        })));
-        await dbRun('INSERT INTO agent_delegation_grants (grant_id, human_id, agent_label, capabilities, token_hash, human_confirm_required, status, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [grantId, user.id, label, capsJson, tokenHash, 0, 'active', expiresAt]);
-        res.status(201).json({
-            grant_id: grantId,
-            token,
-            token_note: 'Shown once — store securely. The server keeps only a hash; it cannot show this again.',
-            capabilities: JSON.parse(capsJson),
-            expires_at: expiresAt,
-            note: 'Bearer-first grant for safe scopes only. Risk scopes are not delegable until their route has a live-Passkey gate; PoP binding is required before any risk scope or longer-lived delegation (RFC-020).',
+        return void res.status(410).json({
+            error: 'USE_PAIRING_FLOW', error_code: 'USE_PAIRING_FLOW',
+            note: 'Direct grant issuance is disabled. Start pairing with webaz_pair (action=start); the human approves at /#pair with a Passkey, then the agent retrieves the credential with its PKCE verifier. No endpoint mints a bearer without a live Passkey ceremony bound to the pairing.',
         });
     });
     // ── Read: the human's connected agents (no secrets) + recent-use from the audit log (PR-D). ──

package/dist/pwa/routes/analytics.js

@@ -141,6 +141,8 @@ export function registerAnalyticsRoutes(app, deps) {
         SUM(CASE WHEN status = 'cancelled' THEN 1 ELSE 0 END) as cancelled_orders,
         SUM(CASE WHEN status IN ('paid','accepted','shipped','picked_up','in_transit','delivered','confirmed') THEN 1 ELSE 0 END) as in_progress_orders,
         COALESCE(SUM(CASE WHEN status = 'completed' THEN total_amount ELSE 0 END), 0) as gmv,
+        COALESCE(SUM(CASE WHEN status = 'completed' AND COALESCE(payment_rail,'escrow') = 'escrow' THEN total_amount ELSE 0 END), 0) as gmv_escrow,
+        COALESCE(SUM(CASE WHEN status = 'completed' AND payment_rail = 'direct_p2p' THEN total_amount ELSE 0 END), 0) as gmv_direct_pay,
         COALESCE(AVG(CASE WHEN status = 'completed' THEN total_amount END), 0) as aov
       FROM orders WHERE seller_id = ? AND created_at > datetime('now', '-' || ? || ' days')
     `, [user.id, windowDays]));

package/dist/pwa/routes/arbitrator.js

@@ -1,8 +1,42 @@
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { grantArbitrator, grantArbitratorTx, suspendArbitrator, reinstateArbitrator, revokeArbitrator, listArbitrators } from '../arbitrator-lifecycle.js'; // PR-B/PR-C.2 生产仲裁员生命周期域逻辑
 export function registerArbitratorRoutes(app, deps) {
     // 只读/单写站点走 RFC-016 异步 seam;db 保留:apply/withdraw/approve/reject 是
     // stake 资金路径,状态翻转 + 钱包扣/退必须原子(db.transaction + CAS),Phase 3 迁 pg 行锁。
-    const { db, generateId, auth, requireArbitrationAdmin, checkArbitratorEligibility, getArbitratorState, errorRes, logAdminAction, ARB_STAKE_REQUIRED, ARB_APP_REJECT_COOLDOWN_DAYS, } = deps;
+    const { db, generateId, auth, requireArbitrationAdmin, checkArbitratorEligibility, getArbitratorState, errorRes, logAdminAction, consumeGateToken, ARB_STAKE_REQUIRED, ARB_APP_REJECT_COOLDOWN_DAYS, } = deps;
+    // ── PR-B:生产仲裁员生命周期(grant/suspend/reinstate/revoke)。门(四端点共用):ROOT/admin auth +
+    //   现场真人 Passkey(purpose 绑动作 + purpose_data.user_id 绑目标,杜绝跨动作/跨目标复用)+ admin_audit_log(含失败留痕)。
+    //   域逻辑(active-only 授权源 / revoked 终态 / 拒非人类)在 arbitrator-lifecycle.ts;此处只做 auth + Passkey + 审计。
+    const arbLifecycle = (action, purpose, fn) => (req, res) => {
+        const admin = requireArbitrationAdmin(req, res);
+        if (!admin)
+            return;
+        const userId = String((action === 'grant' ? req.body?.user_id : req.params.user_id) || '');
+        const note = (req.body?.note ?? null);
+        if (!userId)
+            return void errorRes(res, 400, 'MISSING_USER_ID', '缺少目标 user_id');
+        const gate = consumeGateToken(admin.id, req.body?.webauthn_token, purpose, (d) => d?.user_id === userId);
+        if (!gate.ok) {
+            logAdminAction(admin.id, `arbitrator.${action}`, 'user', userId, { ok: false, gate: gate.reason }); // ROOT 尝试也留痕(purpose 不符/无 token)
+            return void errorRes(res, 412, 'HUMAN_PRESENCE_REQUIRED', gate.reason || '此操作需现场真人 Passkey 确认');
+        }
+        const r = fn(userId, admin.id, note);
+        logAdminAction(admin.id, `arbitrator.${action}`, 'user', userId, { ok: r.ok, error_code: r.error_code, note });
+        if (!r.ok)
+            return void errorRes(res, 409, r.error_code || 'ARB_MUTATION_FAILED', r.error || '操作失败');
+        res.json({ success: true, user_id: userId, action });
+    };
+    app.post('/api/admin/arbitrators/grant', arbLifecycle('grant', 'arbitrator_grant', (userId, adminId, note) => grantArbitrator(db, { userId, grantedBy: adminId, note })));
+    app.post('/api/admin/arbitrators/:user_id/suspend', arbLifecycle('suspend', 'arbitrator_suspend', (userId, _a, note) => suspendArbitrator(db, { userId, note })));
+    app.post('/api/admin/arbitrators/:user_id/reinstate', arbLifecycle('reinstate', 'arbitrator_reinstate', (userId, _a, note) => reinstateArbitrator(db, { userId, note })));
+    app.post('/api/admin/arbitrators/:user_id/revoke', arbLifecycle('revoke', 'arbitrator_revoke', (userId, _a, note) => revokeArbitrator(db, { userId, note })));
+    // 名册(admin 只读,无需 Passkey)。含 active/suspended/revoked 全量 + 状态。
+    app.get('/api/admin/arbitrators', (req, res) => {
+        const admin = requireArbitrationAdmin(req, res);
+        if (!admin)
+            return;
+        res.json({ arbitrators: listArbitrators(db) });
+    });
     app.get('/api/arbitrator/eligibility', (req, res) => {
         const user = auth(req, res);
         if (!user)
@@ -123,30 +157,49 @@ export function registerArbitratorRoutes(app, deps) {
         const admin = requireArbitrationAdmin(req, res);
         if (!admin)
             return;
-        const { note } = req.body;
+        const note = (req.body?.note ?? null);
         const appRow = await dbOne("SELECT id, user_id, status FROM arbitrator_applications WHERE id = ?", [req.params.id]);
         if (!appRow)
             return void res.json({ error: '申请不存在' });
         if (appRow.status !== 'pending')
             return void res.json({ error: '该申请不在待审状态' });
-        // 原子段:CAS 翻转 pending→approved + 入白名单仅在本请求真翻转时(防并发双批准)
+        // PR-B:批准 = 现场真人 Passkey(purpose 绑目标 user_id)+ 走【统一】grantArbitrator(含 revoked-terminal +
+        //   拒 system/agent/无 Passkey)。绝不 INSERT OR REPLACE 白名单(那会复活被撤销用户)。审计成功与失败。
+        const gate = consumeGateToken(admin.id, req.body?.webauthn_token, 'arbitrator_grant', (d) => d?.user_id === appRow.user_id);
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'arbitrator.approve', 'user', appRow.user_id, { ok: false, gate: gate.reason });
+            return void errorRes(res, 412, 'HUMAN_PRESENCE_REQUIRED', gate.reason || '此操作需现场真人 Passkey 确认');
+        }
+        // PR-C.2 原子:grant 白名单 + 翻转申请状态在【同一事务】。任一失败一起回滚 —— 杜绝"grant 成功但申请已被并发撤回/拒绝"。
+        let gErr = null;
+        let raced = false;
         try {
             db.transaction(() => {
-                const cas = db.prepare("UPDATE arbitrator_applications SET status='approved', reviewed_at=datetime('now'), reviewed_by=?, decision_note=? WHERE id=? AND status='pending'")
-                    .run(admin.id, note || null, appRow.id);
-                if (cas.changes === 0)
-                    throw new Error('ARB_RACE');
-                db.prepare(`INSERT OR REPLACE INTO arbitrator_whitelist (user_id, note, is_system, granted_by, stake_amount) VALUES (?,?,0,?,?)`)
-                    .run(appRow.user_id, note || '外部仲裁员批准', admin.id, ARB_STAKE_REQUIRED);
+                const g = grantArbitratorTx(db, { userId: appRow.user_id, grantedBy: admin.id, note: note ?? '外部申请批准' });
+                if (!g.ok) {
+                    gErr = g.error_code || 'GRANT_FAILED';
+                    throw new Error('ARB_ABORT');
+                } // 回滚(此时未写 CAS)
+                const cas = db.prepare("UPDATE arbitrator_applications SET status='approved', reviewed_at=datetime('now'), reviewed_by=?, decision_note=? WHERE id=? AND status='pending'").run(admin.id, note, appRow.id);
+                if (cas.changes === 0) {
+                    raced = true;
+                    throw new Error('ARB_ABORT');
+                } // 并发已改状态 → 回滚 grant
             })();
         }
         catch (e) {
-            if (e.message === 'ARB_RACE')
-                return void res.json({ error: '该申请不在待审状态' });
-            console.error('[arbitrator approve tx]', e.message);
-            return void res.status(500).json({ error: '批准失败,请重试' });
+            if (e.message !== 'ARB_ABORT')
+                throw e;
+        }
+        if (raced) {
+            logAdminAction(admin.id, 'arbitrator.approve', 'user', appRow.user_id, { ok: false, raced: true });
+            return void res.json({ error: '该申请不在待审状态' });
+        }
+        if (gErr) {
+            logAdminAction(admin.id, 'arbitrator.approve', 'user', appRow.user_id, { ok: false, error_code: gErr });
+            return void errorRes(res, 409, gErr, '批准失败');
         }
-        logAdminAction(admin.id, 'approve_arbitrator', 'user', appRow.user_id, { note });
+        logAdminAction(admin.id, 'arbitrator.approve', 'user', appRow.user_id, { ok: true });
         res.json({ success: true });
     });
     app.post('/api/admin/arbitrator-applications/:id/reject', async (req, res) => {