@seasonkoh/webaz 0.1.7 → 0.1.9

package/dist/pwa/routes/welcome.js

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+const SUB_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const VALID_ROLE_PREFS = new Set(['buyer', 'seller', 'creator', 'verifier', 'arbitrator', 'other']);
+export function registerWelcomeRoutes(app, deps) {
+    const { db, generateId, getUser, clientIpHash, clientUaHash, requireSupportAdmin } = deps;
+    // ─── admin 端 ─────────────────────────────────────────────
+    app.get('/api/admin/public-ideas', (req, res) => {
+        const admin = requireSupportAdmin(req, res);
+        if (!admin)
+            return;
+        const status = req.query.status ? String(req.query.status) : null;
+        const where = ["content NOT LIKE 'WELCOME_EMAIL_SUBSCRIBE:%'"]; // 旧前缀数据兼容：排除被迁过的邮箱订阅
+        const args = [];
+        if (status) {
+            where.push('status = ?');
+            args.push(status);
+        }
+        const whereClause = `WHERE ${where.join(' AND ')}`;
+        const rows = db.prepare(`
+      SELECT id, user_id, contact, content, status, created_at
+      FROM public_ideas ${whereClause}
+      ORDER BY created_at DESC LIMIT 500
+    `).all(...args);
+        const counts = db.prepare(`SELECT
+      SUM(CASE WHEN status='new' THEN 1 ELSE 0 END) as st_new,
+      SUM(CASE WHEN status='triaged' THEN 1 ELSE 0 END) as st_triaged,
+      SUM(CASE WHEN status='resolved' THEN 1 ELSE 0 END) as st_resolved,
+      SUM(CASE WHEN status='spam' THEN 1 ELSE 0 END) as st_spam,
+      COUNT(*) as total
+      FROM public_ideas WHERE content NOT LIKE 'WELCOME_EMAIL_SUBSCRIBE:%'`).get();
+        // P1 审计：admin 读 PII 留痕
+        try {
+            db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail)
+                  VALUES (?, ?, 'read_public_ideas', 'public_ideas', NULL, ?)`)
+                .run(generateId('aud'), admin.id, JSON.stringify({ count: rows.length, status }));
+        }
+        catch { }
+        res.json({ items: rows, counts });
+    });
+    app.patch('/api/admin/public-ideas/:id', (req, res) => {
+        const admin = requireSupportAdmin(req, res);
+        if (!admin)
+            return;
+        const newStatus = String(req.body?.status || '');
+        if (!['new', 'triaged', 'resolved', 'spam'].includes(newStatus))
+            return void res.status(400).json({ error: 'status 取值非法' });
+        const r = db.prepare("UPDATE public_ideas SET status=? WHERE id=?").run(newStatus, req.params.id);
+        if (r.changes === 0)
+            return void res.status(404).json({ error: '记录不存在' });
+        try {
+            db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail)
+                  VALUES (?, ?, 'patch_public_idea', 'public_ideas', ?, ?)`)
+                .run(generateId('aud'), admin.id, req.params.id, JSON.stringify({ status: newStatus }));
+        }
+        catch { }
+        res.json({ ok: true, status: newStatus });
+    });
+    // 2026-05-25 admin 查邮箱订阅 — 独立端点，与建议分开
+    app.get('/api/admin/email-subscriptions', (req, res) => {
+        const admin = requireSupportAdmin(req, res);
+        if (!admin)
+            return;
+        const includeUnsub = req.query.include_unsubscribed === '1';
+        const HANDLE_STATES = ['pending', 'contacted', 'invited', 'done'];
+        const statusFilter = HANDLE_STATES.includes(String(req.query.handle_status || '')) ? String(req.query.handle_status) : '';
+        const conds = [];
+        const args = [];
+        if (!includeUnsub)
+            conds.push('unsubscribed_at IS NULL');
+        if (statusFilter) {
+            conds.push("COALESCE(handle_status,'pending') = ?");
+            args.push(statusFilter);
+        }
+        const where = conds.length ? `WHERE ${conds.join(' AND ')}` : '';
+        const rows = db.prepare(`
+      SELECT id, email, source, role_preference, note, consent_at, unsubscribed_at, user_id, created_at,
+             COALESCE(handle_status,'pending') as handle_status, handled_at
+      FROM email_subscriptions ${where}
+      ORDER BY created_at DESC LIMIT 500
+    `).all(...args);
+        const counts = db.prepare(`SELECT
+      COUNT(*) as total,
+      SUM(CASE WHEN unsubscribed_at IS NULL THEN 1 ELSE 0 END) as active,
+      SUM(CASE WHEN unsubscribed_at IS NOT NULL THEN 1 ELSE 0 END) as unsubscribed,
+      SUM(CASE WHEN COALESCE(handle_status,'pending') = 'pending'   THEN 1 ELSE 0 END) as st_pending,
+      SUM(CASE WHEN handle_status = 'contacted' THEN 1 ELSE 0 END) as st_contacted,
+      SUM(CASE WHEN handle_status = 'invited'   THEN 1 ELSE 0 END) as st_invited,
+      SUM(CASE WHEN handle_status = 'done'      THEN 1 ELSE 0 END) as st_done
+      FROM email_subscriptions`).get();
+        try {
+            db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail)
+                  VALUES (?, ?, 'read_email_subscriptions', 'email_subscriptions', NULL, ?)`)
+                .run(generateId('aud'), admin.id, JSON.stringify({ count: rows.length, include_unsubscribed: includeUnsub }));
+        }
+        catch { }
+        res.json({ items: rows, counts });
+    });
+    // 2026-05-29: admin 标记申请处理状态（pending→contacted→invited→done）— 不动 POST 提交逻辑
+    app.patch('/api/admin/email-subscriptions/:id/status', (req, res) => {
+        const admin = requireSupportAdmin(req, res);
+        if (!admin)
+            return;
+        const HANDLE_STATES = ['pending', 'contacted', 'invited', 'done'];
+        const status = String((req.body || {}).status || '');
+        if (!HANDLE_STATES.includes(status))
+            return void res.status(400).json({ error: 'status 必须是 pending/contacted/invited/done' });
+        const row = db.prepare('SELECT id, handle_status FROM email_subscriptions WHERE id = ?').get(req.params.id);
+        if (!row)
+            return void res.status(404).json({ error: '记录不存在' });
+        db.prepare("UPDATE email_subscriptions SET handle_status = ?, handled_at = datetime('now'), handled_by = ? WHERE id = ?")
+            .run(status, admin.id, req.params.id);
+        try {
+            db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail)
+                  VALUES (?, ?, 'update_email_subscription_status', 'email_subscriptions', ?, ?)`)
+                .run(generateId('aud'), admin.id, req.params.id, JSON.stringify({ from: row.handle_status || 'pending', to: status }));
+        }
+        catch { }
+        res.json({ success: true, status });
+    });
+    // ─── 公开端 ───────────────────────────────────────────────
+    // 2026-05-24 首屏「我有建议」— 公开提交（无需登录）
+    // 反 bot：honeypot 字段 + 单 IP+UA 联合 rate limit 5/h + 内容 hash 去重 1h
+    app.post('/api/public-ideas', (req, res) => {
+        // 蜜罐字段 `_hp`：bot 倾向于填所有 input；真人不会看到（前端 display:none）
+        if (req.body?._hp)
+            return void res.status(400).json({ error: 'invalid' }); // 不告诉 bot 真原因
+        const content = String(req.body?.content || '').trim();
+        const contact = String(req.body?.contact || '').trim().slice(0, 200);
+        if (content.length < 10 || content.length > 2000) {
+            return void res.status(400).json({ error: '内容 10-2000 字' });
+        }
+        const ipHash = clientIpHash(req);
+        const uaHash = clientUaHash(req);
+        // IP+UA 联合：5/h（之前是仅 IP，NAT 误伤）
+        const recent = db.prepare(`SELECT COUNT(*) as n FROM public_ideas
+      WHERE (ip_hash = ? OR ua_hash = ?) AND created_at > datetime('now', '-1 hour')`).get(ipHash, uaHash).n;
+        if (recent >= 5)
+            return void res.status(429).json({ error: '提交过于频繁，请稍后再试' });
+        // 内容去重：1h 内同 ip+content 不重复落库
+        const dup = db.prepare(`SELECT 1 FROM public_ideas
+      WHERE ip_hash = ? AND content = ? AND created_at > datetime('now', '-1 hour')`).get(ipHash, content);
+        if (dup)
+            return void res.status(409).json({ error: '请勿重复提交相同内容' });
+        const userId = getUser(req)?.id || null;
+        const id = generateId('idea');
+        db.prepare(`INSERT INTO public_ideas (id, user_id, contact, content, ip_hash, ua_hash) VALUES (?,?,?,?,?,?)`)
+            .run(id, userId, contact || null, content, ipHash, uaHash);
+        res.json({ ok: true, id });
+    });
+    // 2026-05-25 邮箱订阅独立端点（替代旧 WELCOME_EMAIL_SUBSCRIBE: 前缀 hack）
+    // 2026-05-26 加 role_preference + note 字段（welcome 表单丰富化）
+    app.post('/api/email-subscriptions', (req, res) => {
+        if (req.body?._hp)
+            return void res.status(400).json({ error: 'invalid' }); // honeypot
+        const email = String(req.body?.email || '').trim().toLowerCase();
+        const source = String(req.body?.source || 'welcome').slice(0, 30);
+        if (!email || !SUB_EMAIL_RE.test(email) || email.length > 200) {
+            return void res.status(400).json({ error: '邮箱格式无效' });
+        }
+        // role_preference 可选；非法值视为 null（不报错，前端 select 也限了枚举）
+        const rolePrefRaw = String(req.body?.role_preference || '').trim().toLowerCase();
+        const rolePref = VALID_ROLE_PREFS.has(rolePrefRaw) ? rolePrefRaw : null;
+        // note 可选；trim + 500 截断
+        const noteRaw = String(req.body?.note || '').trim();
+        const note = noteRaw ? noteRaw.slice(0, 500) : null;
+        const ipHash = clientIpHash(req);
+        // rate limit: 单 IP 1h 最多 3 次（防爆破探测同人多邮箱）
+        const recent = db.prepare(`SELECT COUNT(*) as n FROM email_subscriptions
+      WHERE ip_hash = ? AND created_at > datetime('now', '-1 hour')`).get(ipHash).n;
+        if (recent >= 3)
+            return void res.status(429).json({ error: '提交过于频繁，请稍后再试' });
+        // 已存在（active）→ 幂等返回 ok（不暴露"该邮箱已订阅"避免邮箱枚举）
+        // 但若提供了新 role/note，更新这俩字段（用户可能回来补充）
+        const exist = db.prepare(`SELECT id, unsubscribed_at FROM email_subscriptions WHERE email = ?`).get(email);
+        if (exist) {
+            const sets = [];
+            const args = [];
+            if (exist.unsubscribed_at) {
+                sets.push("unsubscribed_at = NULL", "consent_at = datetime('now')");
+            }
+            if (rolePref) {
+                sets.push("role_preference = ?");
+                args.push(rolePref);
+            }
+            if (note) {
+                sets.push("note = ?");
+                args.push(note);
+            }
+            if (sets.length > 0) {
+                args.push(exist.id);
+                db.prepare(`UPDATE email_subscriptions SET ${sets.join(', ')} WHERE id = ?`).run(...args);
+            }
+            return void res.json({ ok: true, id: exist.id, status: 'subscribed' });
+        }
+        const id = generateId('eml');
+        const token = createHash('sha256').update(id + email + Math.random()).digest('hex').slice(0, 32);
+        const userId = getUser(req)?.id || null;
+        db.prepare(`INSERT INTO email_subscriptions (id, email, source, role_preference, note, unsubscribe_token, ip_hash, user_id) VALUES (?,?,?,?,?,?,?,?)`)
+            .run(id, email, source, rolePref, note, token, ipHash, userId);
+        res.json({ ok: true, id, status: 'subscribed', unsubscribe_url: `/unsubscribe?t=${token}` });
+    });
+    // 公开退订端点 — 接受 GET（邮件里的链接）+ POST（页面按钮）
+    function doUnsubscribe(token) {
+        if (!token || token.length !== 32)
+            return { ok: false, error: 'invalid_token' };
+        const row = db.prepare(`SELECT id, email, unsubscribed_at FROM email_subscriptions WHERE unsubscribe_token = ?`).get(token);
+        if (!row)
+            return { ok: false, error: 'token_not_found' };
+        if (row.unsubscribed_at)
+            return { ok: true, email: row.email }; // 已退订也返 ok（幂等）
+        db.prepare(`UPDATE email_subscriptions SET unsubscribed_at = datetime('now') WHERE id = ?`).run(row.id);
+        return { ok: true, email: row.email };
+    }
+    app.post('/api/email-subscriptions/unsubscribe', (req, res) => {
+        const r = doUnsubscribe(String(req.body?.token || ''));
+        res.status(r.ok ? 200 : 400).json(r);
+    });
+    // 浏览器友好的退订页（GET）
+    app.get('/unsubscribe', (req, res) => {
+        const r = doUnsubscribe(String(req.query?.t || ''));
+        const okHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>已退订 — webaz</title><meta name="viewport" content="width=device-width,initial-scale=1"><style>body{font-family:-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#FAFAFA;color:#18181B}main{text-align:center;padding:32px}h1{font-size:22px;font-weight:600;margin:0 0 12px}p{font-size:14px;color:#71717A;margin:0 0 8px}a{color:#6366f1;text-decoration:none;font-size:13px}</style></head><body><main><h1>✓ 已退订 / Unsubscribed</h1><p>${r.email ? `<code>${r.email}</code>` : ''}</p><p>不会再收到 webaz 的邮件。<br>You won't receive emails from webaz anymore.</p><a href="/">← 返回首页 / Back</a></main></body></html>`;
+        const errHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>退订链接无效</title><style>body{font-family:-apple-system,sans-serif;text-align:center;padding:80px 20px;color:#18181B}p{color:#71717A}</style></head><body><h1>退订链接无效</h1><p>${r.error}</p><a href="/">← 返回首页</a></body></html>`;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.send(r.ok ? okHtml : errHtml);
+    });
+}

package/dist/pwa/routes/wishlist-qa.js

@@ -0,0 +1,135 @@
+export function registerWishlistQaRoutes(app, deps) {
+    const { db, generateId, auth, isTrustedRole, errorRes } = deps;
+    // ─── Wave A-1: 心愿单 ────────────────────────────────────
+    app.post('/api/wishlist/:product_id', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (isTrustedRole(user))
+            return void errorRes(res, 403, 'TRUSTED_ROLE_NO_TRADE', '受信角色无购物功能');
+        const p = db.prepare('SELECT id, price, status, seller_id FROM products WHERE id = ?').get(req.params.product_id);
+        if (!p)
+            return void res.status(404).json({ error: '商品不存在' });
+        if (p.seller_id === user.id)
+            return void res.status(400).json({ error: '不可收藏自己的商品' });
+        const note = req.body?.note ? String(req.body.note).slice(0, 200) : null;
+        db.prepare(`INSERT OR REPLACE INTO user_wishlist (user_id, product_id, note, price_at_add) VALUES (?,?,?,?)`)
+            .run(user.id, req.params.product_id, note, p.price);
+        res.json({ success: true });
+    });
+    app.delete('/api/wishlist/:product_id', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        db.prepare('DELETE FROM user_wishlist WHERE user_id = ? AND product_id = ?').run(user.id, req.params.product_id);
+        res.json({ success: true });
+    });
+    app.get('/api/wishlist', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        // 过滤已删除商品（已下架但 status=warehouse 仍显示让买家可见）
+        const rows = db.prepare(`
+      SELECT w.product_id, w.note, w.price_at_add, w.notify_price_drop, w.notify_back_in_stock, w.created_at,
+             p.title, p.price as current_price, p.stock, p.status as product_status,
+             p.category, p.claim_loss_count,
+             u.name as seller_name, u.handle as seller_handle
+      FROM user_wishlist w
+      JOIN products p ON p.id = w.product_id
+      JOIN users u ON u.id = p.seller_id
+      WHERE w.user_id = ? AND p.status != 'deleted'
+      ORDER BY w.created_at DESC LIMIT 200
+    `).all(user.id);
+        for (const r of rows) {
+            const cur = Number(r.current_price);
+            const old = Number(r.price_at_add || cur);
+            r.price_delta = Math.round((cur - old) * 100) / 100;
+            r.price_delta_pct = old > 0 ? Math.round((cur - old) / old * 1000) / 10 : 0;
+        }
+        res.json({ items: rows });
+    });
+    app.get('/api/wishlist/:product_id/check', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const exists = db.prepare('SELECT 1 FROM user_wishlist WHERE user_id = ? AND product_id = ?').get(user.id, req.params.product_id);
+        res.json({ in_wishlist: !!exists });
+    });
+    // ─── Wave A-2: 商品 Q&A ─────────────────────────────────
+    app.post('/api/products/:product_id/qa', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (isTrustedRole(user))
+            return void errorRes(res, 403, 'TRUSTED_ROLE_NO_QA', '受信角色不参与商品 Q&A');
+        const p = db.prepare('SELECT id, seller_id, status FROM products WHERE id = ?').get(req.params.product_id);
+        if (!p)
+            return void res.status(404).json({ error: '商品不存在' });
+        if (p.seller_id === user.id)
+            return void res.status(400).json({ error: '卖家不可对自己商品提问（请用 description 直接说明）' });
+        if (p.status !== 'active')
+            return void res.status(400).json({ error: '仅在售商品可提问' });
+        const question = String(req.body?.question || '').trim();
+        if (question.length < 6 || question.length > 500)
+            return void res.status(400).json({ error: 'question 长度需 6-500 字' });
+        const id = generateId('qa');
+        db.prepare(`INSERT INTO product_qa (id, product_id, asker_id, seller_id, question) VALUES (?,?,?,?,?)`)
+            .run(id, req.params.product_id, user.id, p.seller_id, question);
+        try {
+            db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
+                .run(generateId('ntf'), p.seller_id, '收到商品提问', question.slice(0, 80) + (question.length > 80 ? '...' : ''), null);
+        }
+        catch { }
+        res.json({ success: true, id });
+    });
+    app.post('/api/products/:product_id/qa/:qa_id/answer', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const qa = db.prepare('SELECT id, seller_id, answer FROM product_qa WHERE id = ? AND product_id = ?').get(req.params.qa_id, req.params.product_id);
+        if (!qa)
+            return void res.status(404).json({ error: '提问不存在' });
+        if (qa.seller_id !== user.id)
+            return void res.status(403).json({ error: '仅卖家可回答' });
+        if (qa.answer)
+            return void res.status(409).json({ error: '已回答过 — 编辑请联系 admin' });
+        const answer = String(req.body?.answer || '').trim();
+        if (answer.length < 2 || answer.length > 1000)
+            return void res.status(400).json({ error: 'answer 长度需 2-1000 字' });
+        db.prepare(`UPDATE product_qa SET answer = ?, answered_at = datetime('now') WHERE id = ?`).run(answer, req.params.qa_id);
+        try {
+            const asker = db.prepare('SELECT asker_id, question FROM product_qa WHERE id = ?').get(req.params.qa_id);
+            db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
+                .run(generateId('ntf'), asker.asker_id, '卖家回答了你的提问', answer.slice(0, 80) + (answer.length > 80 ? '...' : ''), null);
+        }
+        catch { }
+        res.json({ success: true });
+    });
+    app.get('/api/products/:product_id/qa', (req, res) => {
+        // 公开列表（不需要登录，但只返回 is_public=1）
+        const rows = db.prepare(`
+      SELECT qa.id, qa.question, qa.answer, qa.answered_at, qa.helpful_count, qa.created_at,
+             ua.name as asker_name, ua.handle as asker_handle
+      FROM product_qa qa JOIN users ua ON ua.id = qa.asker_id
+      WHERE qa.product_id = ? AND qa.is_public = 1
+      ORDER BY qa.answered_at IS NULL ASC, qa.helpful_count DESC, qa.created_at DESC LIMIT 50
+    `).all(req.params.product_id);
+        res.json({ items: rows });
+    });
+    app.post('/api/products/:product_id/qa/:qa_id/helpful', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        // 防重复 — 每用户每条 QA 仅可 +1
+        try {
+            db.prepare(`INSERT INTO product_qa_helpful_voters (qa_id, user_id) VALUES (?, ?)`).run(req.params.qa_id, user.id);
+        }
+        catch {
+            const qa = db.prepare(`SELECT helpful_count FROM product_qa WHERE id = ?`).get(req.params.qa_id);
+            return void res.json({ success: false, already_voted: true, helpful_count: qa?.helpful_count || 0 });
+        }
+        db.prepare(`UPDATE product_qa SET helpful_count = COALESCE(helpful_count, 0) + 1 WHERE id = ? AND product_id = ?`)
+            .run(req.params.qa_id, req.params.product_id);
+        res.json({ success: true });
+    });
+}

package/dist/pwa/security/ssrf.js

@@ -0,0 +1,110 @@
+// SSRF 防护：hostname 黑名单 + safeFetch redirect 守门 + undici Agent socket 层 IP 校验
+// 三层防御：
+//   ① isPrivateOrInternalHost — hostname 文本检查（快路径，挡显式 IP / localhost / .local）
+//   ② safeFetch — redirect: 'manual' + 每跳重验，挡 302→私网 跳板
+//   ③ ssrfAgent (undici) — DNS 解析后的 IP 校验，挡 DNS rebinding（attacker.com TTL=0 解析到 169.254）
+import * as dns from 'dns';
+import { Agent } from 'undici';
+// IP 黑名单 — 解析后的 IP 直接判
+export function isIpPrivate(ip) {
+    const h = ip.toLowerCase();
+    // IPv4 私网 / 保留段
+    const m4 = h.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (m4) {
+        const [a, b] = m4.slice(1).map(Number);
+        if (a === 127)
+            return true; // loopback
+        if (a === 10)
+            return true; // 10/8
+        if (a === 192 && b === 168)
+            return true; // 192.168/16
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16-31/12
+        if (a === 169 && b === 254)
+            return true; // link-local (AWS / GCP metadata)
+        if (a === 0)
+            return true; // 0.0.0.0/8
+    }
+    // IPv6 简单黑名单
+    if (h === '::1' || h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80'))
+        return true;
+    return false;
+}
+// hostname 文本检查（不做 DNS 解析）
+export function isPrivateOrInternalHost(url) {
+    try {
+        const u = new URL(url);
+        let h = u.hostname.toLowerCase();
+        if (h.startsWith('[') && h.endsWith(']'))
+            h = h.slice(1, -1);
+        if (!h)
+            return true;
+        if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.local'))
+            return true;
+        return isIpPrivate(h);
+    }
+    catch {
+        return true;
+    }
+}
+export function ssrfLookup(hostname, options, callback) {
+    const opts = typeof options === 'function' ? {} : (options || {});
+    const cb = typeof options === 'function' ? options : callback;
+    dns.lookup(hostname, opts, (err, address, family) => {
+        if (err)
+            return cb(err);
+        if (Array.isArray(address)) {
+            // options.all === true → 多 IP 数组
+            const safe = address.filter(a => !isIpPrivate(a.address));
+            if (safe.length === 0) {
+                const e = new Error('ssrf_resolved_to_private_ip');
+                e.code = 'ENOTFOUND';
+                return cb(e);
+            }
+            return cb(null, safe, family);
+        }
+        if (isIpPrivate(String(address))) {
+            const e = new Error('ssrf_resolved_to_private_ip');
+            e.code = 'ENOTFOUND';
+            return cb(e);
+        }
+        cb(null, address, family);
+    });
+}
+// 单例 Agent — 注入 ssrfLookup 拦截 DNS 解析层
+export const ssrfAgent = new Agent({
+    connect: {
+        lookup: ssrfLookup,
+    },
+});
+// SSRF-safe redirect-following fetch.
+// 三层防御组合：safeFetch (hostname check + per-hop) + ssrfAgent (DNS rebinding 拦截)
+// 抛出 ssrf_blocked / ssrf_bad_scheme / ssrf_bad_redirect / ssrf_too_many_redirects /
+// ssrf_resolved_to_private_ip (DNS 层) 中之一时表示拦截
+export async function safeFetch(initialUrl, init = {}, maxHops = 5) {
+    let url = initialUrl;
+    for (let hop = 0; hop <= maxHops; hop++) {
+        if (!/^https?:\/\//i.test(url))
+            throw new Error('ssrf_bad_scheme');
+        if (isPrivateOrInternalHost(url))
+            throw new Error('ssrf_blocked');
+        // dispatcher 选项是 undici 扩展，标准 RequestInit 不含
+        const resp = await fetch(url, { ...init, redirect: 'manual', dispatcher: ssrfAgent });
+        if (resp.status >= 300 && resp.status < 400) {
+            const loc = resp.headers.get('location');
+            if (!loc)
+                return resp;
+            let next;
+            try {
+                next = new URL(loc, url).href;
+            }
+            catch {
+                throw new Error('ssrf_bad_redirect');
+            }
+            url = next;
+            continue;
+        }
+        return resp;
+    }
+    throw new Error('ssrf_too_many_redirects');
+}