@bolloon/bolloon-agent 0.4.33 → 0.5.0

package/dist/ios/routes-chain-index.js

@@ -0,0 +1,108 @@
+/**
+ * routes-chain-index.ts — 链上索引的**只读**HTTP 路由 (P5, ③)
+ * =========================================================================
+ * 刻意独立成文件, **不碰 src/web/server.ts**: 挂载方法见文件末尾注释。
+ * 本模块只暴露**读**接口 (读已落盘索引), 全都不发 RPC、不写盘、不签名:
+ *
+ *   GET /api/chain/index/status
+ *       → 当前索引高度 (lastSyncedBlock) / 最后同步时间 / head / 确认数门槛 / 页大小
+ *   GET /api/chain/index/stats
+ *       → 全量统计: tasks / created / proofSubmitted / released / refunded / disputed / expired
+ *         + byFinality (observed|confirmed|finalized) + suspects (被回退的条数)
+ *   GET /api/chain/index/timeline?taskKey=0x…(64hex)
+ *       → 该 escrow 的事件时间线 (含块号/块哈希/logIndex/解码 args/确认数/finality/suspect)
+ *   GET /api/chain/index/events?blockNumber=..&logIndex=..&limit=..
+ *       → 按 cursor 增量拉取 (严格大于 cursor 的 (blockNumber, logIndex)); 无 cursor = 从头
+ *
+ * 挂载 (在 src/web/server.ts 里加两行即可, 本文件不改它):
+ *   import { registerChainIndexRoutes } from './routes-chain-index.js';
+ *   registerChainIndexRoutes(app);              // app: express.Express (或等价 router 宿主)
+ *
+ * 挂载点可选前缀: registerChainIndexRoutes(app, { basePath: '/api/chain/index' })
+ * 读 SQLite/文件直接读 ~/.bolloon/chain/index.json; 换 HOME 用 opts.home (测试隔离)。
+ * 若还想在网页上触发同步: registerChainIndexRoutes(app, { allowSync: true })
+ *   → 多一个 POST /api/chain/index/sync (body: { fromBlock?: number })。默认关 —— 写操作不默认开放。
+ */
+import { getIndexStatus, getIndexStats, getEscrowTimeline, fetchIndexSince, } from '../agents/chain/chain-index-query.js';
+const isTaskKey = (v) => typeof v === 'string' && /^0x[0-9a-fA-F]{64}$/.test(v);
+export function registerChainIndexRoutes(app, opts = {}) {
+    const base = opts.basePath || '/api/chain/index';
+    const home = opts.home;
+    // ① 当前索引高度 + 最后同步时间
+    app.get(`${base}/status`, (_req, res) => {
+        try {
+            res.json({ ok: true, status: getIndexStatus({ home }) });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // ② 全量统计
+    app.get(`${base}/stats`, (_req, res) => {
+        try {
+            res.json({ ok: true, stats: getIndexStats({ home }) });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // ③ 按 taskKey 查 escrow 时间线
+    app.get(`${base}/timeline`, (req, res) => {
+        const taskKey = String(req.query?.taskKey || '');
+        if (!isTaskKey(taskKey)) {
+            return res.status(400).json({ ok: false, error: 'taskKey 必须是 0x + 64 hex' });
+        }
+        try {
+            const tl = getEscrowTimeline(taskKey, { home });
+            res.json({ ok: true, timeline: tl });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // ④ 按 cursor 增量拉取
+    app.get(`${base}/events`, (req, res) => {
+        const q = req.query || {};
+        const hasCursor = q.blockNumber !== undefined && q.blockNumber !== '';
+        let cursor = null;
+        if (hasCursor) {
+            const bn = Number(q.blockNumber);
+            const li = q.logIndex === undefined || q.logIndex === '' ? 0 : Number(q.logIndex);
+            if (!Number.isInteger(bn) || bn < 0 || !Number.isInteger(li) || li < 0) {
+                return res.status(400).json({ ok: false, error: 'cursor 非法: 需要 blockNumber>=0, logIndex>=0' });
+            }
+            cursor = { blockNumber: bn, logIndex: li };
+        }
+        const limit = q.limit === undefined || q.limit === '' ? 200 : Number(q.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+            return res.status(400).json({ ok: false, error: 'limit 必须 >= 1 的整数' });
+        }
+        try {
+            res.json({ ok: true, page: fetchIndexSince(cursor, { home, limit }) });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // 可选: 触发一次同步 (显式 opt-in)
+    if (opts.allowSync) {
+        app.post(`${base}/sync`, async (req, res) => {
+            if (!opts.sync)
+                return res.status(501).json({ ok: false, error: '未注入 sync 实现' });
+            const fromBlockRaw = req.body?.fromBlock;
+            let fromBlock;
+            if (fromBlockRaw !== undefined && fromBlockRaw !== null && fromBlockRaw !== '') {
+                const n = Number(fromBlockRaw);
+                if (!Number.isInteger(n) || n < 0)
+                    return res.status(400).json({ ok: false, error: 'fromBlock 必须 >= 0 的整数' });
+                fromBlock = n;
+            }
+            try {
+                res.json({ ok: true, result: await opts.sync(fromBlock) });
+            }
+            catch (e) {
+                res.status(500).json({ ok: false, error: String(e?.message || e) });
+            }
+        });
+    }
+}

package/dist/ios/routes-contacts.js

@@ -0,0 +1,420 @@
+/**
+ * routes-contacts.ts — 联系方式 / 授权 / 配对 的桌面端 API (2026-09-19, Phase 5/6)
+ *
+ * 全部返回**脱敏**数据: 完整手机号/邮箱永不出现在响应里。
+ * 与手机端的分工 (leo 冻结):
+ *   手机负责 输入 + OTP 确认 + 生物识别授权 + 展示待发内容 + 批准高风险联系
+ *   桌面负责 长期 Goal/Run、执行、恢复、持久化状态、证据
+ * 同步只传: identityId / contactId / verificationStatus / capability / consentScope / provider /
+ *          secretRef 的关联状态 —— **不传**明文、不传密钥。
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ContactChain } from '../agents/contacts/chain.js';
+const PAIRING_TTL_MS = 5 * 60_000;
+/** 明显的明文联系方式/密钥 —— 同步载荷里出现就直接拒绝 (防止"顺手同步了明文") */
+export function looksLikePlaintextSecret(value) {
+    const walk = (v, pathStr) => {
+        if (v == null)
+            return null;
+        if (typeof v === 'string') {
+            const s = v.trim();
+            if (/\b(sk-[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{12,}|ghp_[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,})\b/.test(s))
+                return `${pathStr}: 疑似密钥明文`;
+            if (/\b(password|passwd|smtp_pass|api_secret|refresh_token|client_secret)\b/i.test(pathStr) && s.length > 0)
+                return `${pathStr}: 疑似秘密字段`;
+            // 明文邮箱/手机号: 只有在 key 明确表示"值"时才拦 (displayValue 是脱敏的, 不会匹配)
+            if (/[^@\s]+@[^@\s]+\.[^@\s]+/.test(s) && !/^\*|@\*/.test(s) && s.includes('*') === false)
+                return `${pathStr}: 疑似邮箱明文`;
+            if (/^\+?\d{8,15}$/.test(s.replace(/[^\d+]/g, '')) && /value|phone|number|to$/i.test(pathStr))
+                return `${pathStr}: 疑似手机号明文`;
+            return null;
+        }
+        if (Array.isArray(v)) {
+            for (let i = 0; i < v.length; i++) {
+                const r = walk(v[i], `${pathStr}[${i}]`);
+                if (r)
+                    return r;
+            }
+            return null;
+        }
+        if (typeof v === 'object') {
+            for (const [k, vv] of Object.entries(v)) {
+                const r = walk(vv, pathStr ? `${pathStr}.${k}` : k);
+                if (r)
+                    return r;
+            }
+            return null;
+        }
+        return null;
+    };
+    return walk(value, '');
+}
+export function registerContactRoutes(app, opts = {}) {
+    const pairs = opts.pairs || new Map();
+    const ownerDidFromDisk = () => {
+        try {
+            const f = path.join(process.env.HOME || os.homedir(), '.bolloon', 'identity', 'user.json');
+            const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+            if (j?.did)
+                return String(j.did);
+        }
+        catch { /* 还没有用户身份 → 用本地占位 */ }
+        return globalThis.__bolloonUserDid || 'did:bolln:local';
+    };
+    const chainFor = (ownerDid) => opts.chain || new ContactChain({
+        home: opts.home,
+        ownerDid: ownerDid || opts.ownerDid || ownerDidFromDisk(),
+        displayName: '本机用户',
+    });
+    const chainOf = (req) => chainFor(String(req?.body?.ownerDid || opts.ownerDid || ''));
+    // ── 列表 (脱敏) ────────────────────────────────────────────────────────────
+    app.get('/api/contacts', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            res.json({
+                ok: true,
+                contacts: await c.listAuthorized(),
+                channels: c.channels(),
+                approvals: (await c.consents.list('pending')).map((a) => ({
+                    consentId: a.consentId, contactId: a.contactId, contactName: a.contactName, channel: a.channel,
+                    provider: a.provider, reallySent: a.reallySent, subject: a.subject, bodyPreview: a.bodyPreview,
+                    goalId: a.goalId, reason: a.reason, createdAt: a.createdAt, expiresAt: a.expiresAt,
+                })),
+                waiting: (await c.store.readLedger({ limit: 200 })).filter((l) => l.activity === 'contact.sent').slice(-10),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 绑定 (Phase 2/3): 输入 → 规范化 → 隐私说明 → 发验证码 → pending ─────────
+    app.post('/api/contacts/bind', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const kind = String(req.body?.kind || '');
+            if (kind !== 'phone' && kind !== 'email')
+                return res.status(400).json({ ok: false, error: 'kind 必须是 phone 或 email' });
+            const r = await c.bind({
+                kind,
+                value: String(req.body?.value || ''),
+                region: req.body?.region ? String(req.body.region) : undefined,
+                provider: req.body?.provider ? String(req.body.provider) : undefined,
+                secretRef: req.body?.secretRef ? String(req.body.secretRef) : undefined,
+                aliases: Array.isArray(req.body?.aliases) ? req.body.aliases.map(String) : undefined,
+                note: req.body?.note ? String(req.body.note) : undefined,
+                source: req.body?.source === 'agent_card' ? 'agent_card' : 'user_input',
+            });
+            if (!r.ok)
+                return res.status(400).json({ ok: false, error: r.error });
+            res.json({
+                ok: true,
+                contactId: r.contact.contactId,
+                displayValue: r.contact.displayValue,
+                verificationStatus: r.contact.verificationStatus,
+                channelLabel: r.channelLabel,
+                challengeId: r.challengeId,
+                // 只有本地落盘通道才回显验证码 (真外发通道不回显, 也不会出现在响应里)
+                otpForLocalSink: r.otpForLocalSink,
+                privacy: '完整手机号/邮箱不会进入 prompt / Run / Git; 外部只看到 已验证/可联系/不可联系/需要重新授权',
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/verify', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.verify({ contactId: String(req.body?.contactId || ''), challengeId: String(req.body?.challengeId || ''), code: String(req.body?.code || '') });
+            if (!r.ok)
+                return res.status(400).json({ ok: false, error: r.error });
+            res.json({ ok: true, contactId: r.contact.contactId, displayValue: r.contact.displayValue, verificationStatus: r.contact.verificationStatus, capabilities: r.contact.capabilities });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/:id/revoke', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.revoke({ contactId: String(req.params.id), by: String(req.body?.by || 'user'), reason: req.body?.reason ? String(req.body.reason) : undefined });
+            if (!r.ok)
+                return res.status(404).json({ ok: false, error: r.error });
+            res.json({ ok: true, evidenceRef: r.evidenceRef, affectedGoals: r.affectedGoals });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 任务级授权 (把联系方式绑定到某个长期任务) ───────────────────────────────
+    app.post('/api/contacts/:id/authorize', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.authorizeForTask({ contactId: String(req.params.id), goalId: String(req.body?.goalId || ''), by: String(req.body?.by || 'user') });
+            if (!r.ok)
+                return res.status(400).json({ ok: false, error: r.error });
+            res.json({ ok: true, contactId: r.contact.contactId, consentScope: r.contact.consentScope });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 预览 (不发送) ──────────────────────────────────────────────────────────
+    app.post('/api/contacts/preview', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.preview({ contactId: String(req.body?.contactId || ''), goalId: req.body?.goalId ? String(req.body.goalId) : undefined, subject: req.body?.subject ? String(req.body.subject) : undefined, body: String(req.body?.body || '') });
+            res.json({ ok: true, allowed: r.decision.allowed, requiresApproval: r.decision.requiresApproval, blockKind: r.decision.blockKind, reallySent: r.decision.reallySent, preview: r.text });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 发送 (走 policy; 需要批准就返回 awaiting_approval) ───────────────────────
+    app.post('/api/contacts/send', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.send({
+                contactId: String(req.body?.contactId || ''),
+                goalId: req.body?.goalId ? String(req.body.goalId) : undefined,
+                runId: req.body?.runId ? String(req.body.runId) : undefined,
+                subject: req.body?.subject ? String(req.body.subject) : undefined,
+                body: String(req.body?.body || ''),
+                requestId: req.body?.requestId ? String(req.body.requestId) : undefined,
+                replyExpected: req.body?.replyExpected !== false,
+            });
+            const code = r.status === 'denied' ? 409 : r.status === 'failed' ? 502 : 200;
+            res.status(code).json({ ok: r.status === 'sent' || r.status === 'awaiting_reply', ...r });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 批准 / 拒绝 (人工授权) ─────────────────────────────────────────────────
+    app.post('/api/contacts/approvals/:id/approve', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.approveAndSend(String(req.params.id), { by: String(req.body?.by || 'user'), via: 'web', body: req.body?.body ? String(req.body.body) : undefined });
+            const code = r.ok ? 200 : (String(r.error || '').includes('not_found') ? 404 : 400);
+            res.status(code).json({ ok: r.ok, error: r.error, status: r.status, requestId: r.requestId });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/approvals/:id/reject', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.consents.reject(String(req.params.id), { by: String(req.body?.by || 'user'), reason: req.body?.reason ? String(req.body.reason) : undefined });
+            const code = r.ok ? 200 : (String(r.error || '').includes('not_found') ? 404 : 400);
+            const cons = r.consent;
+            if (cons) {
+                await c.store.appendLedger({
+                    ts: new Date().toISOString(), activity: 'contact.rejected', contactId: cons.contactId, goalId: cons.goalId,
+                    detail: `人工拒绝 (by ${String(req.body?.by || 'user')}${req.body?.reason ? `, ${req.body.reason}` : ''}) · consent=${cons.consentId}`,
+                });
+            }
+            res.status(code).json({ ok: r.ok, error: r.error });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 回复入口 (通道回调 / 手机转投): 来源校验不过就不唤醒、不入证据 ──────────────
+    app.post('/api/contacts/reply', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.reply({
+                requestId: req.body?.requestId ? String(req.body.requestId) : undefined,
+                threadToken: req.body?.threadToken ? String(req.body.threadToken) : undefined,
+                from: String(req.body?.from || ''),
+                body: String(req.body?.body || ''),
+                eventId: req.body?.eventId ? String(req.body.eventId) : undefined,
+            });
+            const code = r.ok ? 200 : (r.reason === 'source_untrusted' ? 403 : 404);
+            res.status(code).json({ ok: r.ok, woke: r.woke, goalId: r.goalId, reason: r.reason, evidenceRef: r.evidenceRef });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 手机—桌面配对 (Phase 5): 只同步 capability, 不同步明文/密钥 ───────────────
+    app.post('/api/contacts/pairing/challenge', async (_req, res) => {
+        const now = Date.now();
+        const pairingId = `pair-${now.toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+        const p = { pairingId, code: String(crypto.randomInt(0, 1_000_000)).padStart(6, '0'), createdAt: now, expiresAt: now + PAIRING_TTL_MS };
+        pairs.set(pairingId, p);
+        res.json({ ok: true, pairingId, code: p.code, expiresAt: p.expiresAt, note: '手机扫码/深链确认后调 /confirm; 挑战 5 分钟有效且一次性' });
+    });
+    app.post('/api/contacts/pairing/confirm', async (req, res) => {
+        try {
+            const pairingId = String(req.body?.pairingId || '');
+            const p = pairs.get(pairingId);
+            if (!p)
+                return res.status(404).json({ ok: false, error: 'pairing_not_found' });
+            if (p.usedAt)
+                return res.status(409).json({ ok: false, error: 'pairing_already_used' });
+            if (p.expiresAt < Date.now())
+                return res.status(410).json({ ok: false, error: 'pairing_expired' });
+            if (String(req.body?.code || '') !== p.code)
+                return res.status(401).json({ ok: false, error: 'pairing_code_mismatch' });
+            // 明文字段直接拒绝 —— 同步只允许传 capability 视图
+            const incoming = req.body?.contacts;
+            const leak = looksLikePlaintextSecret(incoming);
+            if (leak)
+                return res.status(400).json({ ok: false, error: `同步载荷含明文/秘密, 已拒绝: ${leak}` });
+            p.usedAt = Date.now();
+            p.deviceDid = req.body?.deviceDid ? String(req.body.deviceDid) : undefined;
+            pairs.set(pairingId, p);
+            const accepted = [];
+            const rejected = [];
+            const c = chainOf(req);
+            const allowedKeys = ['contactId', 'kind', 'displayValue', 'verificationStatus', 'capabilities', 'consentScope', 'provider', 'secretRef', 'state'];
+            for (const item of Array.isArray(incoming) ? incoming : []) {
+                const clean = {};
+                for (const k of allowedKeys)
+                    if (item && k in item)
+                        clean[k] = item[k];
+                const known = clean.contactId ? await c.store.getContact(String(clean.contactId)) : null;
+                if (!known)
+                    rejected.push({ contactId: clean.contactId, reason: '桌面端不认识这个 contactId (需要在桌面端绑定/接收能力)' });
+                else
+                    accepted.push({ contactId: known.contactId, displayValue: known.displayValue, verificationStatus: known.verificationStatus, parity: 'capability-only' });
+            }
+            res.json({
+                ok: true, deviceDid: p.deviceDid, accepted, rejected,
+                note: '两端只对齐 contactId/状态/capability; 明文与密钥各自留在本机',
+                evidence: await c.store.appendLedger({
+                    ts: new Date().toISOString(), activity: 'contact.discovered',
+                    detail: `手机—桌面配对完成 (deviceDid=${p.deviceDid || '未提供'}), 接受 ${accepted.length} 项能力, 拒绝 ${rejected.length} 项`,
+                }),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 持久能力授权 (Phase 3/4/8/10): CLI / Web / 手机 读同一份 Grant 事实 ──────
+    app.get('/api/contacts/grants', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const summary = await c.grantsSummary();
+            res.json({
+                ok: true,
+                ...summary,
+                choices: [
+                    { id: 'task_once', label: '仅本次任务' },
+                    { id: 'persistent', label: '长期使用 (推荐)' },
+                    { id: 'full_contact_access', label: '完全授权联系方式能力' },
+                ],
+                willNotGet: ['读取全部邮箱', '读取通讯录', '群发消息', '自动支付/转账', '代表你签署合同', '拿到手机号/邮箱明文'],
+                forbiddenAlways: ['凭证 (密钥/密码)', '银行账号', '支付/转账指令', '合同承诺'],
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/grants', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const choice = ['task_once', 'persistent', 'full_contact_access'].includes(String(req.body?.choice)) ? String(req.body.choice) : 'persistent';
+            const r = await c.authorize({
+                choice,
+                grantedBy: String(req.body?.by || 'user'),
+                grantedVia: req.body?.via === 'mobile' ? 'mobile' : req.body?.via === 'onboard' ? 'onboard' : 'web',
+            });
+            res.json({ ok: r.ok, userLabel: r.userLabel, grant: r.grant });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/grants/:id/:action', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const id = String(req.params.id);
+            const action = String(req.params.action);
+            const by = String(req.body?.by || 'user');
+            if (action === 'pause') {
+                const r = await c.pauseGrant(id, { by });
+                return res.status(r.ok ? 200 : 400).json({ ok: r.ok, error: r.error, grant: r.grant });
+            }
+            if (action === 'resume') {
+                const r = await c.resumeGrant(id, { by });
+                return res.status(r.ok ? 200 : 400).json({ ok: r.ok, error: r.error, grant: r.grant });
+            }
+            if (action === 'revoke') {
+                const r = await c.revokeGrant(id, { by, reason: req.body?.reason ? String(req.body.reason) : undefined });
+                return res.status(r.ok ? 200 : 400).json({ ok: r.ok, error: r.error, affectedGoals: r.affectedGoals });
+            }
+            res.status(400).json({ ok: false, error: `未知动作 ${action}` });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    app.post('/api/contacts/grants/revoke-all', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.revokeAllGrants({ by: String(req.body?.by || 'user'), reason: req.body?.reason ? String(req.body.reason) : undefined });
+            res.json({ ok: true, ...r });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    /** 登记手机设备公钥 (配对阶段; 之后只接受它签名的授权) */
+    app.post('/api/contacts/devices', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const deviceId = String(req.body?.deviceId || '');
+            const publicKeyPem = String(req.body?.publicKeyPem || '');
+            if (!deviceId || !/BEGIN PUBLIC KEY/.test(publicKeyPem))
+                return res.status(400).json({ ok: false, error: 'deviceId/publicKeyPem 必填 (PEM 公钥)' });
+            const d = await c.registerDevice(deviceId, publicKeyPem, req.body?.label ? String(req.body.label) : undefined);
+            res.json({ ok: true, device: { deviceId: d.deviceId, label: d.label, registeredAt: d.registeredAt } });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    /** 手机同步签名 Grant (Phase 4): 验签 → 版本冲突 → 撤销优先 */
+    app.post('/api/contacts/grants/sync', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const incoming = req.body?.grant;
+            if (!incoming?.grantId || !incoming?.signature)
+                return res.status(400).json({ ok: false, error: '需要带签名的 grant (grantId + signature)' });
+            const r = await c.syncGrant(incoming);
+            return res.status(r.ok ? 200 : 409).json({ ok: r.ok, code: r.code, reason: r.reason, grantId: r.grant?.grantId, grantVersion: r.grant?.grantVersion });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    /** 手机撤销 → 桌面立即失效 */
+    app.post('/api/contacts/grants/revoke-sync', async (req, res) => {
+        try {
+            const c = chainOf(req);
+            const r = await c.syncRevocation(String(req.body?.grantId || ''), {
+                by: String(req.body?.by || 'mobile'),
+                reason: req.body?.reason ? String(req.body.reason) : undefined,
+                version: Number(req.body?.version) || undefined,
+                revokedAt: req.body?.revokedAt ? String(req.body.revokedAt) : undefined,
+                signature: req.body?.signature, // 手机签名 (有则验签, 未登记设备一律拒)
+            });
+            res.status(r.ok ? 200 : 400).json({ ok: r.ok, error: r.reason, grant: r.grant });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err?.message || err) });
+        }
+    });
+    // ── 隐藏守卫自检 (验收/测试直接用) ──────────────────────────────────────────
+    app.get('/api/contacts/_selfcheck', (_req, res) => {
+        res.json({ ok: true, plaintextGuard: looksLikePlaintextSecret({ contacts: [{ value: '+8613812345678' }] }) });
+    });
+}

package/dist/ios/routes-onchain-trade.js

@@ -0,0 +1,99 @@
+/**
+ * routes-onchain-trade.ts — 链上任务交易闭环的**只读**HTTP 路由 (P4, ②③)
+ * =========================================================================
+ * 刻意独立成文件, **不碰 src/web/server.ts** (另一个并行任务在动它)。
+ * 只暴露**读**接口 —— 全都不发交易、不签名、不改链、不写盘:
+ *
+ *   GET /api/chain/trade/state?taskKey=0x…(64hex) | taskId=…
+ *       → 该任务在 chain-state.json 里的全部链上记录 (方法/状态/确认数/是否可疑/结果哈希)
+ *   GET /api/chain/trade/recovery?taskKey=… | taskId=…&pendingResultDigest=sha256:…
+ *       → ★ 重启恢复决策: nextAction / mustNotRepay / verified / 为什么 (纯读盘, 不联网)
+ *   GET /api/chain/trade/budget?amount=0.02&taskBudget=0.05
+ *       → M1 预算硬约束预检 (单任务 0.05 / 单次 0.02): 放行 / 哪一层拦下
+ *
+ * 挂载 (在 src/web/server.ts 里加两行即可, 本文件不改它):
+ *   import { registerOnchainTradeRoutes } from './routes-onchain-trade.js';
+ *   registerOnchainTradeRoutes(app);            // app: express.Express
+ *
+ * 挂载点可选: registerOnchainTradeRoutes(app, { basePath: '/api/chain/trade' })
+ * 换 HOME 用 opts.home (测试隔离 / 多 profile)。**没有**任何写接口 ——
+ * 链上写操作必须走 CLI/任务链路 (那里有签名放行闸 + 审计), 不通过 HTTP 裸开。
+ */
+import * as os from 'os';
+import { recoverOnchainTrade, checkOnchainAmount, onchainTaskKey, } from '../agents/chain/onchain-trade.js';
+import { loadChainState, chainStatePath } from '../agents/chain/chain-state-store.js';
+const isTaskKey = (v) => typeof v === 'string' && /^0x[0-9a-fA-F]{64}$/.test(v);
+function homeOf(opts) {
+    return opts.home || process.env.HOME || os.homedir();
+}
+export function registerOnchainTradeRoutes(app, opts = {}) {
+    const base = opts.basePath || '/api/chain/trade';
+    // ① 链上记录 (按 taskKey / taskId 过滤; 不过滤 = 全部)
+    app.get(`${base}/state`, (req, res) => {
+        try {
+            const home = homeOf(opts);
+            const taskKey = String(req.query?.taskKey || '');
+            const taskId = String(req.query?.taskId || '');
+            if (taskKey && !isTaskKey(taskKey))
+                return res.status(400).json({ ok: false, error: 'taskKey 必须是 0x + 64 hex' });
+            const want = (taskKey || (taskId ? onchainTaskKey(taskId) : '')).toLowerCase();
+            const all = Object.values(loadChainState(home).records);
+            const records = want ? all.filter((r) => String(r.taskKey).toLowerCase() === want) : all;
+            res.json({
+                ok: true,
+                statePath: chainStatePath(home),
+                taskKey: want || null,
+                count: records.length,
+                records,
+            });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // ② 重启恢复决策 (纯读盘; 不联网 → 不会把"读不到 RPC"当成"没付款")
+    app.get(`${base}/recovery`, (req, res) => {
+        try {
+            const home = homeOf(opts);
+            const q = req.query || {};
+            const taskKey = String(q.taskKey || '');
+            const taskId = String(q.taskId || '');
+            if (taskKey && !isTaskKey(taskKey))
+                return res.status(400).json({ ok: false, error: 'taskKey 必须是 0x + 64 hex' });
+            if (!taskKey && !taskId)
+                return res.status(400).json({ ok: false, error: '要 taskKey 或 taskId' });
+            const recovery = recoverOnchainTrade({
+                home,
+                ...(taskKey ? { taskKey } : {}),
+                ...(taskId ? { taskId } : {}),
+                ...(q.pendingResultDigest ? { pendingResultDigest: String(q.pendingResultDigest) } : {}),
+            });
+            res.json({ ok: true, recovery });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+    // ③ M1 预算硬约束预检 (付款前必须能看得到; 纯函数, 不碰钱)
+    app.get(`${base}/budget`, (req, res) => {
+        try {
+            const q = req.query || {};
+            const amount = Number(q.amount);
+            if (!Number.isFinite(amount) || amount <= 0)
+                return res.status(400).json({ ok: false, error: 'amount 必须是正数 (USDC)' });
+            const decimals = Number.isFinite(Number(q.decimals)) ? Number(q.decimals) : 6;
+            const atomic = BigInt(Math.round(amount * 10 ** decimals));
+            const d = checkOnchainAmount({
+                amountAtomic: atomic, decimals,
+                budget: {
+                    ...(q.taskBudget !== undefined ? { taskBudget: Number(q.taskBudget) } : {}),
+                    ...(q.perPurchase !== undefined ? { perPurchase: Number(q.perPurchase) } : {}),
+                },
+            });
+            res.json({ ok: true, allowed: d.ok, layer: d.layer ?? null, reason: d.reason, amountUsdc: d.amountUsdc, budget: d.budget, why: d.why });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: String(e?.message || e) });
+        }
+    });
+}

package/dist/ios/routes-x402-info.js

@@ -107,6 +107,7 @@ export function registerX402InfoRoutes(app) {
             const pay = await checkAndSettlePayment({
                 paymentHeader: String(paymentHeader),
                 requirements,
+                expectedItemId: stored.item.id, // 凭据必须绑定这条资源 (防跨资源复用)
             });
             if (!pay.ok) {
                 return res.status(402).json({ ...requirements, error: pay.error });