@twinsearth/w2m-dsh-plugin 2.2.6 → 3.1.0

package/src/decision-center/lib/ssrf-guard.mjs

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// ssrf-guard — AI / 出站端点的最小 SSRF 防护：
+//   * 字面量私网 IP：默认拒绝，除非显式 allowlist
+//   * 云元数据地址/主机名：永远拒绝（allowlist 也不能放行）
+//   * hostname：配置时只做语法检查；请求前做一次 DNS 解析，
+//     解析到私网/元数据则拒绝（防“公网域名解析到内网”的常见 SSRF）
+//
+// 诚实边界：DNS 预检与 fetch 的真实解析之间仍有 TOCTOU 窗口（DNS rebinding），
+// Node fetch 没有 pinned-lookup 接口；因此这里只做“高置信拦截”，不宣称完备。
+import net from 'node:net'
+import dns from 'node:dns/promises'
+
+const METADATA_HOSTS = new Set([
+  'metadata.google.internal',
+  'metadata.goog',
+  'instance-data',
+])
+
+const METADATA_ADDRESSES = new Set([
+  '169.254.169.254', // AWS / GCP / Azure IMDS
+  '100.100.100.200', // Alibaba Cloud
+  '192.0.0.192', // Oracle Cloud
+  'fd00:ec2::254', // AWS IPv6 IMDS
+])
+
+export function normalizeHost(value) {
+  let host = String(value ?? '').trim().toLowerCase()
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1)
+  return host.replace(/\.$/, '')
+}
+
+export function isMetadataAddress(value) {
+  return METADATA_ADDRESSES.has(normalizeHost(value))
+}
+
+export function isMetadataHost(value) {
+  return METADATA_HOSTS.has(normalizeHost(value))
+}
+
+const inV4Range = (parts, base, bits) => {
+  if (!Array.isArray(parts) || parts.length !== 4) return false
+  let value = 0
+  for (const part of parts) value = (value << 8) | part
+  const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0
+  return (value & mask) === (base & mask)
+}
+
+function ipv4Parts(ip) {
+  const parts = ip.split('.').map(Number)
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null
+  return parts
+}
+
+function ipv4ToInt(parts) {
+  return (((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0
+}
+
+export function isPrivateIpv4(ip) {
+  const parts = ipv4Parts(ip)
+  if (!parts) return false
+  const value = ipv4ToInt(parts)
+  // RFC1918
+  if (inV4Range(parts, ipv4ToInt([10, 0, 0, 0]), 8)) return true
+  if (inV4Range(parts, ipv4ToInt([172, 16, 0, 0]), 12)) return true
+  if (inV4Range(parts, ipv4ToInt([192, 168, 0, 0]), 16)) return true
+  // loopback / link-local / unspecified
+  if (inV4Range(parts, ipv4ToInt([127, 0, 0, 0]), 8)) return true
+  if (inV4Range(parts, ipv4ToInt([169, 254, 0, 0]), 16)) return true
+  if (inV4Range(parts, ipv4ToInt([0, 0, 0, 0]), 8)) return true
+  // CGNAT / benchmark / multicast / reserved
+  if (inV4Range(parts, ipv4ToInt([100, 64, 0, 0]), 10)) return true
+  if (inV4Range(parts, ipv4ToInt([198, 18, 0, 0]), 15)) return true
+  if (inV4Range(parts, ipv4ToInt([198, 51, 100, 0]), 24)) return true
+  if (inV4Range(parts, ipv4ToInt([203, 0, 113, 0]), 24)) return true
+  if (((value & 0xF0000000) >>> 0) === 0xE0000000) return true // multicast
+  if (((value & 0xF0000000) >>> 0) === 0xF0000000) return true // reserved
+  return false
+}
+
+function ipv6Groups(ip) {
+  const raw = normalizeHost(ip)
+  if (!raw.includes(':')) return null
+  const [head, tail] = raw.split('::')
+  const parse = (segment) => segment.length === 0 ? [] : segment.split(':')
+  let groups = []
+  if (raw.includes('::')) groups = [...parse(head), ...Array(8 - parse(head).length - parse(tail ?? '').length).fill('0'), ...parse(tail ?? '')]
+  else groups = raw.split(':')
+  if (groups.length !== 8) return null
+  return groups.map((group) => parseInt(group || '0', 16)).filter((part) => Number.isInteger(part))
+}
+
+export function isPrivateIpv6(ip) {
+  const raw = normalizeHost(ip)
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(raw)
+  if (mapped) return isPrivateIpv4(mapped[1])
+  const groups = ipv6Groups(raw)
+  if (!groups) return false
+  if (groups.every((group, index) => (index < 7 ? group === 0 : group === 1))) return true // ::1
+  if (groups.every((group) => group === 0)) return true // ::
+  if ((groups[0] & 0xFE00) === 0xFC00) return true // fc00::/7
+  if ((groups[0] & 0xFFC0) === 0xFE80) return true // fe80::/10
+  if ((groups[0] & 0xFF00) === 0xFF00) return true // multicast
+  // IPv4-mapped ::ffff:a.b.c.d
+  if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xFFFF) {
+    const v4 = `${groups[6] >> 8}.${groups[6] & 0xFF}.${groups[7] >> 8}.${groups[7] & 0xFF}`
+    return isPrivateIpv4(v4)
+  }
+  return false
+}
+
+export function isPrivateAddress(ip) {
+  const host = normalizeHost(ip)
+  const family = net.isIP(host)
+  if (family === 4) return isPrivateIpv4(host)
+  if (family === 6) return isPrivateIpv6(host)
+  return false
+}
+
+/** 同步分类：仅处理字面量 IP 与元数据主机名；DNS 主机名留给请求前预检。 */
+export function classifyEndpointHost(hostname, { allowHosts = [] } = {}) {
+  const host = normalizeHost(hostname)
+  const allowed = new Set((Array.isArray(allowHosts) ? allowHosts : []).map(normalizeHost))
+  if (isMetadataHost(host)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata' }
+  const family = net.isIP(host)
+  if (family === 0) {
+    if (host === 'localhost') return { ok: true, kind: 'loopback' }
+    return { ok: true, kind: 'hostname' }
+  }
+  if (isMetadataAddress(host)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata' }
+  if (family === 4 && inV4Range(ipv4Parts(host) ?? [], ipv4ToInt([127, 0, 0, 0]), 8)) return { ok: true, kind: 'loopback' }
+  if (family === 6) {
+    const groups = ipv6Groups(host)
+    if (groups && groups.every((group, index) => (index < 7 ? group === 0 : group === 1))) return { ok: true, kind: 'loopback' }
+  }
+  if ((family === 4 && isPrivateIpv4(host)) || (family === 6 && isPrivateIpv6(host))) {
+    if (allowed.has(host)) return { ok: true, kind: 'private-allowlisted' }
+    return { ok: false, reason: 'private-address-blocked', kind: 'private' }
+  }
+  return { ok: true, kind: family === 4 ? 'public-ipv4' : 'public-ipv6' }
+}
+
+/** 请求前 DNS 预检；解析失败视为 NXDOMAIN（交给 fetch 失败，不视为 SSRF）。 */
+export async function assertEndpointSafe(hostname, { allowHosts = [], resolve = dns.lookup, timeoutMs = 1500 } = {}) {
+  const sync = classifyEndpointHost(hostname, { allowHosts })
+  if (!sync.ok) return sync
+  if (sync.kind !== 'hostname') return sync
+  const host = normalizeHost(hostname)
+  const allowed = new Set((Array.isArray(allowHosts) ? allowHosts : []).map(normalizeHost))
+  // 明确的 metadata 主机名已在 sync 拦截；其余做一次解析。
+  let addresses = []
+  try {
+    const result = await Promise.race([
+      resolve(host, { all: true, verbatim: true }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('dns-timeout')), timeoutMs).unref?.()),
+    ])
+    addresses = Array.isArray(result) ? result : (result?.address ? [result] : [])
+  } catch (error) {
+    return { ok: true, kind: 'hostname-unresolved', detail: String(error?.message ?? error) }
+  }
+  for (const entry of addresses) {
+    const address = normalizeHost(entry?.address ?? entry)
+    if (isMetadataAddress(address)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata', address }
+    if (isPrivateAddress(address) && !allowed.has(host)) {
+      return { ok: false, reason: 'private-address-blocked', kind: 'private', address }
+    }
+  }
+  return { ok: true, kind: 'hostname-public', addresses: addresses.map((entry) => normalizeHost(entry?.address ?? entry)) }
+}

package/src/decision-center/mount.mjs

@@ -0,0 +1,26 @@
+/**
+ * Mount wrapper for W2M's decision center.
+ *
+ * The ported plugin module (`./index.mjs`) is kept verbatim in shape: it provides the store service
+ * and registers the Agent tool. Fang's routes lived in its orchestrator, a component W2M does not
+ * have, so this wrapper attaches them to the same Cordis context the plugin was applied to -- one
+ * mount point for a profile row, and the subpath export stays a seam rather than a second
+ * implementation.
+ */
+import { apply as applyCenter, Config, _internals, inject, name } from './index.mjs';
+import { registerDecisionCenterRoutes } from './routes.mjs';
+
+export { Config, _internals, inject, name };
+
+/**
+ * Apply the decision center and mount its HTTP surface.
+ *
+ * @param {object} ctx Cordis context.
+ * @param {object} config plugin configuration (see `Config`).
+ * @returns {unknown} whatever the ported apply returns.
+ */
+export function apply(ctx, config) {
+  const result = applyCenter(ctx, config);
+  registerDecisionCenterRoutes(ctx);
+  return result;
+}

package/src/decision-center/routes.mjs

@@ -0,0 +1,356 @@
+/**
+ * HTTP surface of W2M's decision center: `/api/w2m/decisions*`.
+ *
+ * Ported from the Fang orchestrator's route block (`src/plugins/orchestrator.mjs`, the
+ * `api/decisions*` handlers) with three mechanical differences:
+ *
+ *   * the prefix is `/api/w2m/decisions` instead of `${prefix}/api/decisions`;
+ *   * the handlers answer Web `Request`/`Response` through the host's Connection fetch registry
+ *     instead of Node's `req`/`res`, which is the only shape a W2M plugin can register;
+ *   * the two SSE endpoints stream through a `ReadableStream` body, carrying the same event names
+ *     (`ready`, `ticket`, `ping`) and payloads the Fang helper emits.
+ *
+ * The decision-center service is read from the plugin's own Cordis context, so the routes never
+ * capture an instance: a store that is disposed and re-provided is picked up by the next request.
+ */
+import { SERVICE, bus } from './kernel.mjs';
+
+/** Route prefix shared with lib/client.js. */
+export const DECISION_ROUTE_PREFIX = '/api/w2m/decisions';
+
+const NO_STORE = { 'cache-control': 'no-store' };
+const EVENT_TOPICS = Object.freeze(['fang/decision-created', 'fang/decision-updated']);
+const MAX_EVENT_STREAMS = 20;
+
+function json(status, body, headers = {}) {
+  return Response.json(body, { status, headers: { ...NO_STORE, ...headers } });
+}
+
+function centerOf(ctx) {
+  try {
+    return ctx.get(SERVICE.decisionCenter);
+  } catch {
+    return undefined;
+  }
+}
+
+async function bodyOf(request) {
+  try {
+    const value = await request.json();
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function unavailable() {
+  return json(503, { ok: false, error: 'decision-center-unavailable' });
+}
+
+function queryOf(request) {
+  try {
+    return new URL(request.url, 'http://127.0.0.1').searchParams;
+  } catch {
+    return new URLSearchParams();
+  }
+}
+
+/**
+ * Serve one SSE stream over the fetch API.
+ *
+ * @param {object} options
+ * @param {object} options.center decision-center service (read-only here)
+ * @param {(send: (event: string, data: unknown) => void) => (() => void)} options.pump
+ *   registers the stream's work and returns its disposer.
+ * @returns {Response}
+ */
+function sseResponse({ center, pump }) {
+  const encoder = new TextEncoder();
+  let closed = false;
+  let dispose = () => {};
+  let heartbeat = null;
+  const body = new ReadableStream({
+    start(controller) {
+      const send = (event, data) => {
+        if (closed) return false;
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+          return true;
+        } catch {
+          closed = true;
+          return false;
+        }
+      };
+      let initial = null;
+      try {
+        initial = typeof center?.list === 'function' ? center.list({ includeArchived: false }) : null;
+      } catch {
+        initial = null;
+      }
+      send('ready', {
+        at: Date.now(),
+        rev: Number(initial?.rev) || 0,
+        counts: initial?.counts ?? null,
+      });
+      const extra = pump(send);
+      const cleanups = typeof extra === 'function' ? [extra] : [];
+      const listeners = EVENT_TOPICS.map((topic) => {
+        const handler = (ticket) => {
+          send('ticket', {
+            at: Date.now(),
+            type: topic.endsWith('-created') ? 'created' : 'updated',
+            rev: Number(ticket?.rev) || 0,
+            ids: ticket?.id ? [String(ticket.id)] : [],
+            ticket,
+          });
+        };
+        return bus.on(topic, handler);
+      });
+      heartbeat = setInterval(() => {
+        if (!send('ping', { at: Date.now() })) return;
+      }, 15000);
+      heartbeat.unref?.();
+      dispose = () => {
+        if (closed) return;
+        closed = true;
+        for (const off of listeners) {
+          try {
+            if (typeof off === 'function') off();
+          } catch {
+            /* ignore */
+          }
+        }
+        for (const cleanup of cleanups) {
+          try {
+            cleanup();
+          } catch {
+            /* ignore */
+          }
+        }
+        if (heartbeat !== null) clearInterval(heartbeat);
+        try {
+          controller.close();
+        } catch {
+          /* already closed */
+        }
+      };
+    },
+    cancel() {
+      try {
+        dispose();
+      } catch {
+        /* ignore */
+      }
+    },
+  });
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store, no-cache, must-revalidate',
+      'x-accel-buffering': 'no',
+    },
+  });
+}
+
+/**
+ * Mount every decision route on the host's Connection fetch registry.
+ *
+ * @param {object} ctx Cordis context the decision-center plugin was applied to.
+ * @returns {{mounted: boolean, reason: string|null}}
+ */
+export function registerDecisionCenterRoutes(ctx) {
+  const status = { mounted: false, reason: 'the host has no Connection service' };
+  if (typeof ctx?.inject !== 'function') return status;
+  ctx.inject(['connection'], (webCtx) => {
+    const registry = webCtx?.connection?.fetch;
+    if (registry === undefined || typeof registry.register !== 'function') {
+      status.reason = 'the connection service carries no fetch registry';
+      return;
+    }
+    let streams = 0;
+    const register = (path, methods, fetch) => {
+      registry.register({ path, methods, requestBody: 'buffered', fetch });
+    };
+
+    // GET /api/w2m/decisions — pending tickets plus counts.
+    register(`${DECISION_ROUTE_PREFIX}`, ['GET'], (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.list !== 'function') return unavailable();
+      const query = queryOf(request);
+      const out = center.list({
+        includeArchived: query.get('includeArchived') === '1' || query.get('includeArchived') === 'true',
+        since: Number(query.get('since')) || 0,
+      });
+      return json(200, { ok: true, ...out });
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/quota`, ['GET'], () => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.quotaStatus !== 'function') return unavailable();
+      return json(200, center.quotaStatus());
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/item`, ['GET'], (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.get !== 'function') return unavailable();
+      const ticket = center.get(String(queryOf(request).get('id') ?? ''));
+      return ticket ? json(200, { ok: true, ticket }) : json(404, { ok: false, error: 'not-found' });
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/forks`, ['GET'], () => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.forkAggregation !== 'function') return unavailable();
+      return json(200, center.forkAggregation());
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/producers`, ['GET'], () => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.producerCatalog !== 'function') return unavailable();
+      return json(200, center.producerCatalog());
+    });
+
+    // External-producer bridge: ingest only, ticket source marked external:<producer>.
+    register(`${DECISION_ROUTE_PREFIX}/ingest`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.ingest !== 'function') return unavailable();
+      const body = await bodyOf(request);
+      const out = center.ingest(body ?? {});
+      const statusCode = out.ok
+        ? 200
+        : out.reason === 'title-required' ||
+            out.reason === 'options-required' ||
+            out.reason === 'gray-is-terminal'
+          ? 400
+          : 409;
+      return json(statusCode, out);
+    });
+
+    // Live push: one authenticated SSE stream per client, polled fallback stays available.
+    register(`${DECISION_ROUTE_PREFIX}/events`, ['GET'], () => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.list !== 'function') return unavailable();
+      if (streams >= MAX_EVENT_STREAMS) return json(429, { ok: false, error: 'too-many-event-streams' });
+      streams += 1;
+      const response = sseResponse({
+        center,
+        pump: () => () => {
+          streams = Math.max(0, streams - 1);
+        },
+      });
+      return response;
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/resolve`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.resolve !== 'function') return unavailable();
+      const body = await bodyOf(request);
+      if (Array.isArray(body?.ids)) {
+        if (typeof center.resolveMany !== 'function')
+          return json(503, { ok: false, error: 'decision-center-batch-unavailable' });
+        return json(
+          200,
+          center.resolveMany(body.ids, { option: body?.option, by: body?.by ?? 'w2m-api', note: body?.note }),
+        );
+      }
+      const resolveOptions = { by: body?.by ?? 'w2m-api', note: body?.note };
+      if (body?.custom !== undefined) resolveOptions.custom = body.custom;
+      const out =
+        body?.actionId !== undefined && typeof center.resolveAction === 'function'
+          ? center.resolveAction(body?.id, body.actionId, body?.payload, resolveOptions)
+          : center.resolve(body?.id, body?.option, resolveOptions);
+      const statusCode = out.ok
+        ? 200
+        : out.reason === 'not-found'
+          ? 404
+          : out.reason === 'option-required' || out.reason === 'unknown-option'
+            ? 400
+            : 409;
+      return json(statusCode, out);
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/abandon`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.abandon !== 'function') return unavailable();
+      const body = await bodyOf(request);
+      if (Array.isArray(body?.ids)) {
+        if (typeof center.abandonMany !== 'function')
+          return json(503, { ok: false, error: 'decision-center-batch-unavailable' });
+        return json(200, center.abandonMany(body.ids, { by: body?.by ?? 'w2m-api', note: body?.note }));
+      }
+      const out = center.abandon(body?.id, { by: body?.by ?? 'w2m-api', note: body?.note });
+      return json(out.ok ? 200 : out.reason === 'not-found' ? 404 : 409, out);
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/ai`, ['GET'], () => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.aiStatus !== 'function') return unavailable();
+      return json(200, { ok: true, ...center.aiStatus() });
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/ai/test`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.testAi !== 'function') return unavailable();
+      const out = await center.testAi((await bodyOf(request)) ?? {});
+      return json(out.ok ? 200 : out.status === 429 ? 429 : 400, out);
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/ai/config`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.configureAi !== 'function') return unavailable();
+      const out = center.configureAi((await bodyOf(request)) ?? {});
+      return json(out.ok ? 200 : 400, out);
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/ai/advise/stream`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.advise !== 'function') return unavailable();
+      const body = await bodyOf(request);
+      const id = String(body?.id ?? '');
+      return sseResponse({
+        center,
+        pump: (send) => {
+          let cancelled = false;
+          send('start', { id });
+          void (async () => {
+            try {
+              const out =
+                typeof center.adviseStream === 'function'
+                  ? await center.adviseStream(id, (delta, text) => {
+                      if (!cancelled) send('delta', { delta, text });
+                    })
+                  : await center.advise(id);
+              if (!cancelled)
+                send(out.ok ? 'done' : 'error', out.ok ? { advice: out.advice, ticket: out.ticket } : out);
+            } catch (error) {
+              if (!cancelled) send('error', { ok: false, error: String(error?.message ?? error) });
+            }
+          })();
+          return () => {
+            cancelled = true;
+          };
+        },
+      });
+    });
+
+    register(`${DECISION_ROUTE_PREFIX}/ai/advise`, ['POST'], async (request) => {
+      const center = centerOf(ctx);
+      if (center === undefined || typeof center.advise !== 'function') return unavailable();
+      const body = await bodyOf(request);
+      const out = await center.advise(body?.id);
+      const limited =
+        out?.reason === 'ai-rate-limited' ||
+        out?.reason === 'ai-circuit-open' ||
+        out?.reason === 'ai-daily-quota-exceeded';
+      const headers =
+        limited && Number.isFinite(out?.retryAfterMs) && out.retryAfterMs > 0
+          ? { 'retry-after': String(Math.ceil(out.retryAfterMs / 1000)) }
+          : {};
+      return json(out.ok ? 200 : out.reason === 'not-found' ? 404 : limited ? 429 : 409, out, headers);
+    });
+
+    status.mounted = true;
+    status.reason = null;
+  });
+  return status;
+}