@seasonkoh/webaz 0.1.24 → 0.1.26

package/dist/pwa/routes/auth-register.js

@@ -1,9 +1,53 @@
+import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerAuthRegisterRoutes(app, deps) {
     // VALID_REGIONS + INVITE_ROTATION_HANDLES 通过 deps.X 在 handler 内延迟读
     // （server.ts 用 getter 注入；destructure at register-time would trigger TDZ 因为它们在下方 const）
-    const { db, errorRes, INTERNAL_AUDITOR_ID, isAllowedSponsor, resolveUserRef, generateId, generateSecureKey, generatePermanentCode, deriveHandle, clientIpHash, clientUaHash, pickPreferredSide, joinPowerLeg, inviteRotationLookup, recordSession, broadcastSystemEvent } = deps;
+    const { db, errorRes, INTERNAL_AUDITOR_ID, isAllowedSponsor, resolveInviteCodeRef, generateId, generateSecureKey, generatePermanentCode, deriveHandle, clientIpHash, clientUaHash, pickPreferredSide, joinPowerLeg, inviteRotationLookup, issueCode, findActiveCode, canDeliverCodes, emailDeliveryNotConfigured, recordSession, broadcastSystemEvent } = deps;
+    // CODE_TTL_MIN / MAX_CODE_ATTEMPTS 通过 deps.X 在 handler 内延迟读(它们在 server.ts 是后置 const,
+    // register-time destructure 会触发 TDZ)。
+    const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+    const normEmail = (raw) => String(raw || '').trim().toLowerCase();
+    // IP 级发码限流(5/min)— 防爆破列举邮箱 / 刷验证码
+    const regCodeHits = new Map();
+    // 注册邮箱验证:发码到邮箱(purpose='register',无账号故 user_id='')。
+    // 注册场景需明确告知"邮箱已占用"(无法防枚举,标准取舍),但限流 + captcha 兜底。
+    app.post('/api/register/send-code', async (req, res) => {
+        const email = normEmail(req.body?.email);
+        if (!email || !EMAIL_RE.test(email))
+            return void errorRes(res, 400, 'EMAIL_INVALID', '请填写有效邮箱');
+        if (!canDeliverCodes()) {
+            const u = emailDeliveryNotConfigured();
+            return void res.status(u.status).json({ error: u.error, error_code: u.error_code });
+        }
+        const ip = req.ip || '';
+        if (ip) {
+            const now = Date.now();
+            const rec = regCodeHits.get(ip);
+            if (rec && now - rec.firstAt < 60_000) {
+                rec.count++;
+                if (rec.count > 5)
+                    return void errorRes(res, 429, 'CODE_RATE_LIMITED', '发送过于频繁，请 1 分钟后再试');
+            }
+            else {
+                regCodeHits.set(ip, { count: 1, firstAt: now });
+            }
+            if (regCodeHits.size > 1000) {
+                for (const [k, v] of regCodeHits)
+                    if (now - v.firstAt > 60_000)
+                        regCodeHits.delete(k);
+            }
+        }
+        const dup = await dbOne("SELECT 1 FROM users WHERE lower(email) = ? AND email_verified = 1 AND id NOT IN ('sys_protocol', ?) LIMIT 1", [email, INTERNAL_AUDITOR_ID]);
+        if (dup)
+            return void errorRes(res, 409, 'EMAIL_TAKEN', '该邮箱已注册，请直接登录或用 #recover 找回');
+        const issued = await issueCode('', 'email', email, 'register');
+        if (!issued.ok) {
+            return void res.status(issued.status || 503).json({ error: issued.error || '验证码发送失败，请稍后再试', error_code: issued.error_code || 'EMAIL_DELIVERY_FAILED' });
+        }
+        res.json({ success: true, notice: '验证码已发送至邮箱，请查收（含垃圾箱）', expires_in_min: deps.CODE_TTL_MIN });
+    });
     app.post('/api/register', async (req, res) => {
-        const { name, role, sponsor_id, region, placement_inviter_id, placement_side, turnstile_token } = req.body;
+        const { name, role, sponsor_id, region, placement_inviter_id, turnstile_token } = req.body;
         const validRoles = ['buyer', 'seller'];
         if (!name?.trim())
             return void errorRes(res, 400, 'NAME_REQUIRED', '请填写名称');
@@ -39,11 +83,37 @@ export function registerAuthRegisterRoutes(app, deps) {
         const trimmed = name.trim();
         if (trimmed.length < 2 || trimmed.length > 40)
             return void errorRes(res, 400, 'NAME_LENGTH', '名称长度需在 2–40 个字符之间');
-        const dup = db.prepare("SELECT 1 FROM users WHERE name = ? AND id NOT IN ('sys_protocol', ?) LIMIT 1").get(trimmed, INTERNAL_AUDITOR_ID);
+        const dup = await dbOne("SELECT 1 FROM users WHERE name = ? AND id NOT IN ('sys_protocol', ?) LIMIT 1", [trimmed, INTERNAL_AUDITOR_ID]);
         if (dup)
             return void errorRes(res, 409, 'NAME_TAKEN', '该名称已被占用，请换一个');
+        // ── 邮箱验证优先注册 ────────────────────────────────────────
+        // PWA 人类路径强制:必须先 /register/send-code 拿验证码,提交时带 email + code,校验通过才建号 + email_verified=1。
+        // 这样每个新 PWA 账号天生有 verified 邮箱 → #recover 永远可用。
+        // agent/MCP 注册走 handleRegister 直插库(自托管 key,不需邮件找回),不经此端点,不受影响。
+        const email = normEmail(req.body?.email);
+        const code = String(req.body?.code || '').trim();
+        if (!email || !code)
+            return void errorRes(res, 400, 'EMAIL_VERIFICATION_REQUIRED', '注册需先验证邮箱:请填写邮箱并输入收到的验证码');
+        if (!EMAIL_RE.test(email))
+            return void errorRes(res, 400, 'EMAIL_INVALID', '邮箱格式不正确');
+        const emailDup = await dbOne("SELECT 1 FROM users WHERE lower(email) = ? AND email_verified = 1 AND id NOT IN ('sys_protocol', ?) LIMIT 1", [email, INTERNAL_AUDITOR_ID]);
+        if (emailDup)
+            return void errorRes(res, 409, 'EMAIL_TAKEN', '该邮箱已注册，请直接登录或用 #recover 找回');
+        // 校验注册验证码(按 email 查,purpose='register')。错码计数,超限作废,均【不建号】。
+        const codeRow = findActiveCode('email', email, 'register');
+        if (!codeRow)
+            return void errorRes(res, 400, 'CODE_EXPIRED', '验证码已过期或未发送，请重新获取');
+        if (String(codeRow.code) !== code) {
+            const attempts = Number(codeRow.attempts || 0) + 1;
+            if (attempts >= deps.MAX_CODE_ATTEMPTS) {
+                await dbRun("UPDATE verification_codes SET attempts = ?, used_at = datetime('now') WHERE id = ?", [attempts, codeRow.id]);
+                return void errorRes(res, 400, 'CODE_TOO_MANY', '错误次数过多，验证码已作废，请重新获取');
+            }
+            await dbRun("UPDATE verification_codes SET attempts = ? WHERE id = ?", [attempts, codeRow.id]);
+            return void errorRes(res, 400, 'CODE_INVALID', `验证码错误（剩余 ${deps.MAX_CODE_ATTEMPTS - attempts} 次）`);
+        }
         const ROLE_WHITELIST = [];
-        const requireRef = db.prepare("SELECT value FROM system_state WHERE key='require_ref_to_register'").get()?.value === '1';
+        const requireRef = (await dbOne("SELECT value FROM system_state WHERE key='require_ref_to_register'", []))?.value === '1';
         // 2026-05-30 合规复审:取消 china 豁免——D1b 引入时保留 china 通道是为获客,
         // 但合规上正好反向(china 是 MLM 风险最高地区,豁免反而把最高风险地区做成最容易进)。
         // 全球统一需邀请。第三方尽调报告风险 1 + 问题 1 的回应。
@@ -53,20 +123,18 @@ export function registerAuthRegisterRoutes(app, deps) {
         let sponsorId = null;
         let sponsorPath = null;
         let sponsorSkipped = null;
-        let sponsorRawRef = (sponsor_id && typeof sponsor_id === 'string') ? sponsor_id.trim() : '';
-        let suffixSide = null;
-        const sufM = sponsorRawRef.match(/^(.+?)-([lLrR])$/);
-        if (sufM) {
-            sponsorRawRef = sufM[1];
-            suffixSide = sufM[2].toLowerCase() === 'l' ? 'left' : 'right';
-        }
+        // invite codes ONLY: 6-7 char permanent_code with optional -L/-R side. usr_xxx / @handle / handle are
+        // no longer accepted as a registration sponsor (anti-ambiguity; narrows the public invite surface).
+        const sponsorRawRef = (sponsor_id && typeof sponsor_id === 'string') ? sponsor_id.trim() : '';
+        let resolvedSponsorId = null;
         if (sponsorRawRef) {
-            const resolvedSponsorId = resolveUserRef(sponsorRawRef);
-            if (!resolvedSponsorId || resolvedSponsorId === 'sys_protocol' || resolvedSponsorId === INTERNAL_AUDITOR_ID) {
-                return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码无效：${sponsorRawRef.slice(0, 24)}（请检查或留空跳过）`);
+            const ref = resolveInviteCodeRef(sponsorRawRef);
+            if (!ref) {
+                return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码无效：${sponsorRawRef.slice(0, 24)}（仅接受 6-7 位永久码；请检查或留空跳过）`);
             }
-            const sponsor = db.prepare("SELECT id, sponsor_path FROM users WHERE id = ?")
-                .get(resolvedSponsorId);
+            resolvedSponsorId = ref.userId;
+            // pre-public: 去左右码 — 邀请码自带的 -L/-R 侧别一律忽略,放置永远自动(见下)
+            const sponsor = await dbOne("SELECT id, sponsor_path FROM users WHERE id = ?", [ref.userId]);
             if (!sponsor) {
                 return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码对应用户不存在：${sponsorRawRef.slice(0, 24)}`);
             }
@@ -90,21 +158,29 @@ export function registerAuthRegisterRoutes(app, deps) {
         const ipHash = clientIpHash(req);
         const uaHash = clientUaHash(req);
         // Phase 3a：注册限频 — 同 IP 每小时最多 5 个新账号(挡批量刷号)
-        const recentReg = db.prepare(`SELECT COUNT(*) AS n FROM registration_audit_log WHERE ip_hash = ? AND created_at > datetime('now','-1 hour')`).get(ipHash).n;
+        const recentReg = (await dbOne(`SELECT COUNT(*) AS n FROM registration_audit_log WHERE ip_hash = ? AND created_at > datetime('now','-1 hour')`, [ipHash])).n;
         if (recentReg >= 5) {
             return void errorRes(res, 429, 'REGISTER_RATE_LIMITED', '注册过于频繁 — 同一网络每小时最多 5 个新账号，请稍后再试');
         }
         const registerTx = db.transaction(() => {
-            db.prepare(`INSERT INTO users (id, name, role, roles, api_key, sponsor_id, sponsor_path, region, permanent_code, handle)
-                  VALUES (?,?,?,?,?,?,?,?,?,?)`)
-                .run(id, trimmed, role, JSON.stringify([role]), apiKey, sponsorId, sponsorPath, userRegion, permaCode, userHandle);
+            db.prepare(`INSERT INTO users (id, name, role, roles, api_key, sponsor_id, sponsor_path, region, permanent_code, handle, email, email_verified)
+                  VALUES (?,?,?,?,?,?,?,?,?,?,?,1)`)
+                .run(id, trimmed, role, JSON.stringify([role]), apiKey, sponsorId, sponsorPath, userRegion, permaCode, userHandle, email);
+            // 消费注册验证码(单次性)— 与建号同一事务,失败则整体回滚,不留"码已用但没建号"
+            db.prepare("UPDATE verification_codes SET used_at = datetime('now') WHERE id = ?").run(codeRow.id);
             db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?,1000)').run(id);
             db.prepare(`INSERT INTO registration_audit_log (user_id, ip_hash, ua_hash, sponsor_id) VALUES (?,?,?,?)`)
                 .run(id, ipHash, uaHash, sponsorId);
-            let effectiveInviter = placement_inviter_id ? resolveUserRef(String(placement_inviter_id).replace(/-[lLrR]$/, '')) : null;
-            let effectiveSide = (placement_side === 'left' || placement_side === 'right') ? placement_side : suffixSide;
-            if (!effectiveInviter && sponsorRawRef)
-                effectiveInviter = resolveUserRef(sponsorRawRef);
+            // placement inviter is invite-code-only too (the sponsor code, or an explicit placement_inviter_id code)
+            let effectiveInviter = resolvedSponsorId;
+            // pre-public 去左右码:不再接受用户/邀请码指定的左右侧,放置侧别永远由系统自动决定(pickPreferredSide)
+            let effectiveSide = null;
+            if (placement_inviter_id) {
+                const p = resolveInviteCodeRef(String(placement_inviter_id));
+                if (p) {
+                    effectiveInviter = p.userId;
+                }
+            }
             if (effectiveInviter && !effectiveSide) {
                 try {
                     effectiveSide = pickPreferredSide(effectiveInviter);
@@ -118,10 +194,15 @@ export function registerAuthRegisterRoutes(app, deps) {
                 const inviter = db.prepare("SELECT id FROM users WHERE id = ? AND id NOT IN ('sys_protocol', ?) LIMIT 1")
                     .get(effectiveInviter, INTERNAL_AUDITOR_ID);
                 if (inviter) {
+                    // do NOT swallow: a known inviter+side that fails to place would leave a placement orphan
+                    // (sponsor recorded but absent from the binary tree). Fail-closed → rethrow so the whole
+                    // registration transaction rolls back (no users / wallet / audit rows persist).
                     try {
                         placement = joinPowerLeg(inviter.id, effectiveSide, id);
                     }
-                    catch { }
+                    catch (e) {
+                        throw new Error('PLACEMENT_FAILED:' + e.message);
+                    }
                 }
             }
             const rotationEnabled = db.prepare("SELECT value FROM system_state WHERE key='invite_rotation_enabled'").get()?.value === '1';
@@ -141,7 +222,10 @@ export function registerAuthRegisterRoutes(app, deps) {
             txResult = registerTx();
         }
         catch (e) {
-            console.error('[register-tx]', e.message);
+            const msg = e.message;
+            console.error('[register-tx]', msg);
+            if (msg.startsWith('PLACEMENT_FAILED:'))
+                return void errorRes(res, 409, 'PLACEMENT_FAILED', '注册挂靠失败，请重试或联系支持（未创建账号）');
             return void res.status(500).json({ error: '注册写入失败，请重试' });
         }
         const { placement, effectiveInviter, effectiveSide } = txResult;
@@ -158,6 +242,7 @@ export function registerAuthRegisterRoutes(app, deps) {
             sponsor_id: sponsorId, region: userRegion,
             permanent_code: permaCode,
             handle: userHandle,
+            email, email_verified: true,
             placement: placement ? { inviter_id: effectiveInviter, side: effectiveSide, depth: placement.depth } : null,
             ...(sponsorSkipped ? { sponsor_skipped: sponsorSkipped } : {}),
         });

package/dist/pwa/routes/auth-sessions.js

@@ -1,15 +1,17 @@
+import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerAuthSessionsRoutes(app, deps) {
-    const { db, auth, verifyPassword, recordSession, generateSecureKey } = deps;
-    app.get('/api/auth/sessions', (req, res) => {
+    // db 已全量走 RFC-016 异步 seam(dbOne/dbAll/dbRun),不再直接用 deps.db
+    const { auth, verifyPassword, recordSession, generateSecureKey } = deps;
+    app.get('/api/auth/sessions', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const currentKey = req.headers.authorization?.replace('Bearer ', '') ?? '';
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT id, ip, user_agent, fingerprint_hash, created_at, last_seen_at, revoked_at, api_key
       FROM user_sessions WHERE user_id = ? AND revoked_at IS NULL
       ORDER BY last_seen_at DESC LIMIT 30
-    `).all(user.id);
+    `, [user.id]);
         res.json({
             sessions: rows.map(r => ({
                 id: r.id,
@@ -23,23 +25,23 @@ export function registerAuthSessionsRoutes(app, deps) {
         });
     });
     // 远程吊销某个会话（不影响当前 session）
-    app.post('/api/auth/sessions/:id/revoke', (req, res) => {
+    app.post('/api/auth/sessions/:id/revoke', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const sid = req.params.id;
-        const row = db.prepare("SELECT user_id, api_key FROM user_sessions WHERE id = ?").get(sid);
+        const row = await dbOne("SELECT user_id, api_key FROM user_sessions WHERE id = ?", [sid]);
         if (!row || row.user_id !== user.id)
             return void res.status(404).json({ error: '会话不存在' });
         const currentKey = req.headers.authorization?.replace('Bearer ', '') ?? '';
         if (row.api_key === currentKey)
             return void res.json({ error: '不能吊销当前会话，请改用「全部登出」' });
-        db.prepare("UPDATE user_sessions SET revoked_at = datetime('now') WHERE id = ?").run(sid);
+        await dbRun("UPDATE user_sessions SET revoked_at = datetime('now') WHERE id = ?", [sid]);
         res.json({ ok: true });
     });
     // 一键全登出：rotate users.api_key + 吊销所有 session
     // 要求密码二次验证（防 api_key 被盗后攻击者锁死真用户）
-    app.post('/api/auth/logout-all', (req, res) => {
+    app.post('/api/auth/logout-all', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -49,9 +51,8 @@ export function registerAuthSessionsRoutes(app, deps) {
         if (!verifyPassword(pwd, user.password_hash))
             return void res.json({ error: '密码错误' });
         const newKey = generateSecureKey('key');
-        db.prepare("UPDATE users SET api_key = ? WHERE id = ?").run(newKey, user.id);
-        db.prepare("UPDATE user_sessions SET revoked_at = datetime('now') WHERE user_id = ? AND revoked_at IS NULL")
-            .run(user.id);
+        await dbRun("UPDATE users SET api_key = ? WHERE id = ?", [newKey, user.id]);
+        await dbRun("UPDATE user_sessions SET revoked_at = datetime('now') WHERE user_id = ? AND revoked_at IS NULL", [user.id]);
         // 为新 key 建一个 session 行（让当前发起者继续可用）
         try {
             recordSession(user.id, newKey, req);

package/dist/pwa/routes/blocklist.js

@@ -1,6 +1,8 @@
+import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerBlocklistRoutes(app, deps) {
-    const { db, auth } = deps;
-    app.post('/api/blocklist/:user_id', (req, res) => {
+    // db 已走 RFC-016 异步 seam(dbOne/dbAll/dbRun),不再直接用 deps.db
+    const { auth } = deps;
+    app.post('/api/blocklist/:user_id', async (req, res) => {
         const me = auth(req, res);
         if (!me)
             return;
@@ -9,52 +11,51 @@ export function registerBlocklistRoutes(app, deps) {
             return void res.json({ error: '不能拉黑自己' });
         if (target === 'sys_protocol')
             return void res.json({ error: '不能拉黑系统账户' });
-        const exists = db.prepare("SELECT 1 FROM users WHERE id = ?").get(target);
+        const exists = await dbOne("SELECT 1 FROM users WHERE id = ?", [target]);
         if (!exists)
             return void res.json({ error: '用户不存在' });
         const reason = (req.body?.reason || '').toString().slice(0, 200);
-        db.prepare("INSERT OR IGNORE INTO user_blocklist (blocker_id, blocked_id, reason) VALUES (?, ?, ?)")
-            .run(me.id, target, reason || null);
+        await dbRun("INSERT OR IGNORE INTO user_blocklist (blocker_id, blocked_id, reason) VALUES (?, ?, ?)", [me.id, target, reason || null]);
         res.json({ ok: true });
     });
-    app.delete('/api/blocklist/:user_id', (req, res) => {
+    app.delete('/api/blocklist/:user_id', async (req, res) => {
         const me = auth(req, res);
         if (!me)
             return;
-        db.prepare("DELETE FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ?").run(me.id, req.params.user_id);
+        await dbRun("DELETE FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ?", [me.id, req.params.user_id]);
         res.json({ ok: true });
     });
     // D-2: 列表
-    app.get('/api/blocklist', (req, res) => {
+    app.get('/api/blocklist', async (req, res) => {
         const me = auth(req, res);
         if (!me)
             return;
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT b.blocked_id, b.reason, b.created_at,
         u.name, u.handle, u.role
       FROM user_blocklist b
       JOIN users u ON u.id = b.blocked_id
       WHERE b.blocker_id = ?
       ORDER BY b.created_at DESC LIMIT 200
-    `).all(me.id);
+    `, [me.id]);
         res.json({ items: rows });
     });
-    app.get('/api/blocklist/me', (req, res) => {
+    app.get('/api/blocklist/me', async (req, res) => {
         const me = auth(req, res);
         if (!me)
             return;
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT b.blocked_id, b.reason, b.created_at, u.name as blocked_name, u.role as blocked_role
       FROM user_blocklist b LEFT JOIN users u ON u.id = b.blocked_id
       WHERE b.blocker_id = ? ORDER BY b.created_at DESC
-    `).all(me.id);
+    `, [me.id]);
         res.json({ blocked: rows });
     });
-    app.get('/api/blocklist/:user_id/status', (req, res) => {
+    app.get('/api/blocklist/:user_id/status', async (req, res) => {
         const me = auth(req, res);
         if (!me)
             return;
-        const row = db.prepare("SELECT 1 FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ?").get(me.id, req.params.user_id);
+        const row = await dbOne("SELECT 1 FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ?", [me.id, req.params.user_id]);
         res.json({ blocked: !!row });
     });
 }

package/dist/pwa/routes/build-feedback.js

@@ -1,9 +1,10 @@
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 import { submitBuildFeedback, listMyBuildFeedback, getBuildFeedback, adminListBuildFeedback, adminUpdateBuildFeedback, triagePendingBuildFeedback, } from '../../layer2-business/L2-8-feedback/build-feedback-engine.js';
 export function registerBuildFeedbackRoutes(app, deps) {
     const { db, auth, requireSupportAdmin } = deps;
-    const hasPasskey = (userId) => ((db.prepare('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?').get(userId)?.n) || 0) > 0;
+    const hasPasskey = async (userId) => (((await dbOne('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?', [userId]))?.n) || 0) > 0;
     // ── 提交 ──────────────────────────────────────────────
-    app.post('/api/build-feedback', (req, res) => {
+    app.post('/api/build-feedback', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -11,7 +12,7 @@ export function registerBuildFeedbackRoutes(app, deps) {
         // 分级门(RFC-004 精确化 2026-06-05):
         //   「报告问题」(ux_issue/bug = 用)→ 登录即可,不要 Passkey(没 Passkey 也要能报问题)
         //   「建设平台」(proposal = 建)→ 必须 Passkey(真人锚点,后期贡献/奖励才有归属)
-        if (String(type) === 'proposal' && !hasPasskey(user.id)) {
+        if (String(type) === 'proposal' && !(await hasPasskey(user.id))) {
             return void res.status(403).json({
                 error: '提交「改进提案 / proposal」需先绑定 Passkey 成为可问责真人 —— 提案是建设行为,被采纳会记入共建信誉,需真人锚点。报告 bug / 体验问题无需 Passkey。请在 webaz.xyz「我的」绑定 Passkey。',
                 error_code: 'PROPOSAL_REQUIRES_PASSKEY',
@@ -29,28 +30,28 @@ export function registerBuildFeedbackRoutes(app, deps) {
         res.json(result);
     });
     // ── 闭环:我的反馈进度 ──(必须在 /:id 之前声明)──────────
-    app.get('/api/build-feedback/mine', (req, res) => {
+    app.get('/api/build-feedback/mine', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        res.json({ feedback: listMyBuildFeedback(db, user.id) });
+        res.json({ feedback: await listMyBuildFeedback(db, user.id) });
     });
-    app.get('/api/build-feedback/:id', (req, res) => {
+    app.get('/api/build-feedback/:id', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const isAdmin = !!(user.is_admin || user.admin_permissions); // 宽松判定;admin 端点另有严格门
-        const row = getBuildFeedback(db, String(req.params.id), user.id, !!isAdmin);
+        const row = await getBuildFeedback(db, String(req.params.id), user.id, !!isAdmin);
         if (!row)
             return void res.status(404).json({ error: '反馈不存在或无权查看' });
         res.json(row);
     });
     // ── maintainer triage ────────────────────────────────
-    app.get('/api/admin/build-feedback', (req, res) => {
+    app.get('/api/admin/build-feedback', async (req, res) => {
         if (!requireSupportAdmin(req, res))
             return;
         const status = typeof req.query.status === 'string' ? req.query.status : undefined;
-        res.json({ feedback: adminListBuildFeedback(db, status) });
+        res.json({ feedback: await adminListBuildFeedback(db, status) });
     });
     // RFC-005 Phase 2:AI 自动 triage(advisory)— 批量处理 received 反馈:去重 + 标风险/摘要 + 置 triaged。
     // 不 resolve、不记功(人类的)。无 AI key 时只做确定性去重 + 置 triaged。

package/dist/pwa/routes/build-reputation.js

@@ -1,10 +1,14 @@
 import { getBuildProfile } from '../../layer2-business/L2-9-contribution/build-reputation-engine.js';
+import { withUncommittedValueBoundary } from '../../layer2-business/L2-9-contribution/contribution-display-envelope.js';
 export function registerBuildReputationRoutes(app, deps) {
     const { db, auth } = deps;
-    app.get('/api/build-reputation/me', (req, res) => {
+    // PR-5A/5B: this legacy RFC-006 contributor dashboard is a contribution display surface, so its
+    // response is wrapped in the uncommitted-value boundary (RFC-017 I-12 / §7) — build_points/tier express
+    // BUILD reputation (coordination layer) only and promise no economic value.
+    app.get('/api/build-reputation/me', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        res.json(getBuildProfile(db, user.id));
+        res.json(withUncommittedValueBoundary(await getBuildProfile(db, user.id)));
     });
 }

package/dist/pwa/routes/build-tasks.js

@@ -1,4 +1,8 @@
-import { createBuildTask, listBuildTasks, getBuildTask, claimBuildTask, submitBuildTask, releaseBuildTask, resolveBuildTask, } from '../../layer2-business/L2-9-contribution/build-tasks-engine.js';
+import { createBuildTask, claimBuildTask, submitBuildTask, releaseBuildTask, resolveBuildTask, } from '../../layer2-business/L2-9-contribution/build-tasks-engine.js';
+// PR9C-1 — read/filter the build_tasks core + PR9B agent metadata (member scope; restricted/internal hidden).
+import { listBuildTasksWithAgentMetadata, getBuildTaskWithAgentMetadata, validateTaskFilters, withContributionReadEnvelope } from '../../layer2-business/L2-9-contribution/build-task-read.js';
+// PR9C-2 — participation guard (claim/submit/release): restricted/internal 404 no-leak, auto_claimable, canonical PR.
+import { guardParticipation, validatePrRefAgainstCanonical } from '../../layer2-business/L2-9-contribution/build-task-participation.js';
 export function registerBuildTasksRoutes(app, deps) {
     const { db, auth, requireSupportAdmin } = deps;
     app.post('/api/build-tasks', (req, res) => {
@@ -11,53 +15,81 @@ export function registerBuildTasksRoutes(app, deps) {
             return void res.status(result.error_code === 'RATE_LIMITED' ? 429 : 400).json(result);
         res.json(result);
     });
+    // PR9C-1: list now returns build_tasks core + parsed agent_metadata (null for old tasks) under the
+    // uncommitted value_boundary; member scope hides restricted/internal. Bad filter → fail-closed 400.
     app.get('/api/build-tasks', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const status = typeof req.query.status === 'string' ? req.query.status : undefined;
-        const area = typeof req.query.area === 'string' ? req.query.area : undefined;
-        const claimerId = req.query.mine === '1' ? user.id : undefined;
-        res.json({ tasks: listBuildTasks(db, { status, area, claimerId }) });
+        const v = validateTaskFilters(req.query);
+        if (!v.ok)
+            return void res.status(400).json({ error: v.detail, error_code: v.code });
+        if (req.query.mine === '1')
+            v.filters.claimerId = user.id;
+        const tasks = listBuildTasksWithAgentMetadata(db, v.filters, 'member');
+        res.json(withContributionReadEnvelope({ tasks }));
     });
     app.get('/api/build-tasks/:id', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const row = getBuildTask(db, String(req.params.id));
-        if (!row)
+        const task = getBuildTaskWithAgentMetadata(db, String(req.params.id), 'member'); // null → not found OR restricted/internal (no leak)
+        if (!task)
             return void res.status(404).json({ error: '任务不存在' });
-        res.json(row);
+        // backward-compat: spread the legacy build_tasks fields + events at top level; only append the new fields.
+        res.json(withContributionReadEnvelope(task));
     });
+    // PR9C-2: participation guard runs BEFORE the engine — restricted/internal → 404 no-leak; metadata public
+    // task → claim respects auto_claimable. Success appends value_boundary + canonical_contribution_target only.
     app.post('/api/build-tasks/:id/claim', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
+        const g = guardParticipation(db, String(req.params.id), 'claim');
+        if (!g.ok)
+            return void res.status(g.status).json({ error: g.message, error_code: g.code });
         const result = claimBuildTask(db, String(req.params.id), user.id, (req.body ?? {}).provenance);
         if ('error' in result) {
             const code = result.error_code === 'NOT_FOUND' ? 404 : result.error_code === 'TOO_MANY_CLAIMS' ? 429 : 409;
             return void res.status(code).json(result);
         }
-        res.json(result);
+        res.json(withContributionReadEnvelope(result));
     });
     app.post('/api/build-tasks/:id/submit', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const { pr_ref, note } = req.body ?? {};
-        const result = submitBuildTask(db, String(req.params.id), user.id, pr_ref, note);
+        const g = guardParticipation(db, String(req.params.id), 'submit');
+        if (!g.ok)
+            return void res.status(g.status).json({ error: g.message, error_code: g.code });
+        const { pr_ref, note, verification_summary } = req.body ?? {};
+        // anti GitHub-target confusion: a PR must target the canonical repo (the response shows where to submit).
+        const pr = validatePrRefAgainstCanonical(pr_ref);
+        if (!pr.ok)
+            return void res.status(400).json(withContributionReadEnvelope({ error: pr.message, error_code: pr.code }));
+        // submit evidence (design contract): a PR/ref alone is not enough — the contributor must summarize what
+        // they ran/verified (the task's verification_commands + results). Fail-closed; stored in the event log.
+        const vs = typeof verification_summary === 'string' ? verification_summary.trim() : '';
+        if (vs.length < 1)
+            return void res.status(400).json(withContributionReadEnvelope({ error: 'submit requires a verification_summary — summarize what you ran/verified (the task verification_commands and their results)', error_code: 'VERIFICATION_SUMMARY_REQUIRED' }));
+        if (vs.length > 2000)
+            return void res.status(400).json(withContributionReadEnvelope({ error: 'verification_summary too long (max 2000 chars)', error_code: 'VERIFICATION_SUMMARY_TOO_LONG' }));
+        const result = submitBuildTask(db, String(req.params.id), user.id, pr_ref, note, vs);
         if ('error' in result)
             return void res.status(result.error_code === 'NOT_FOUND' ? 404 : 400).json(result);
-        res.json(result);
+        res.json(withContributionReadEnvelope(result));
     });
     app.post('/api/build-tasks/:id/release', (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
+        const g = guardParticipation(db, String(req.params.id), 'release');
+        if (!g.ok)
+            return void res.status(g.status).json({ error: g.message, error_code: g.code });
         const result = releaseBuildTask(db, String(req.params.id), user.id);
         if ('error' in result)
             return void res.status(result.error_code === 'NOT_FOUND' ? 404 : 400).json(result);
-        res.json(result);
+        res.json(withContributionReadEnvelope(result));
     });
     // 验收终态 —— 仅 admin/maintainer(验收=真人,RFC-006 不变量 2;不发奖励/不记信誉)
     app.post('/api/admin/build-tasks/:id/resolve', (req, res) => {