@ai_mind/dsh-a2a 1.1.1 → 1.1.3

package/README.md

@@ -247,7 +247,7 @@ auth:
 - 请求体默认上限 8 MiB；单个 `raw` 附件默认上限 16 MiB。
 - 公开卡与受保护端点分离：卡片可公开发现，其余端点一律鉴权。
 
-> **重要**：暴露到公网前请务必配置 `auth`、`server.publicUrl`，并将 `agent.sandboxMode`/`agent.approvalPolicy` 调整到符合你信任模型的取值。A2A 调用方能够让 Agent 在其工作区内执行任务，这与给陌生人一个 Harness 会话等价。
+> **重要**：暴露到公网前请务必配置 `auth`、正确的 `Host`/`X-Forwarded-*`（或 `server.publicUrl`），并将 `agent.sandboxMode`/`agent.approvalPolicy` 调整到符合你信任模型的取值。A2A 调用方能够让 Agent 在其工作区内执行任务，这与给陌生人一个 Harness 会话等价。
 >
 > 强烈建议把 `agent.cwd` 指向一个**专用工作区**（而不是默认的家目录）：`workspace-write` 的边界就是该目录。公网部署还应在反向代理层配置限流、请求体上限与 TLS。
 
@@ -309,11 +309,32 @@ server:
 
 - A2A 在 `http://127.0.0.1:41241/a2a` 单独监听（REST 为 `/a2a/rest`），Agent Card 和 `health` 也在该端口；
 - DSH Web 端口只保留卡片镜像 `/.well-known/agent-card.json`（供设置页发现）和 `<mountPath>/panel` 配置面板（仍使用 GUI 登录凭据，不暴露在 A2A 端口上）；
-- Agent Card 的 `supportedInterfaces` 使用 `http://host:port`；如果前面有反向代理/TLS 终止，设置 `server.publicUrl` 为外部地址；
-- 独立监听本身是 HTTP；公网部署时由反向代理终止 TLS。
+- Agent Card 和 `health` 的 URL 默认根据**请求的 `Host`** 推导；设置 `server.trustProxy: true` 后同时使用 `X-Forwarded-Host` / `X-Forwarded-Proto`。`server.publicUrl` 始终优先；
+- 独立监听本身是 HTTP；公网部署时由反向代理终止 TLS，并转发 `Host` 与 `X-Forwarded-*`。
 
 本仓库的 `cordis.patch.yml` 默认使用 `127.0.0.1:41241`；修改 `server.port`（或在设置页的“监听端口”保存）后插件会重载并切换监听。若端口被占用，设置页会显示监听错误。
 
+### 反向代理
+
+A2A 前面的 Nginx/Caddy 等反代需要保留原始 `Host` 和协议头：
+
+```nginx
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+```
+
+并设置：
+
+```yaml
+server:
+  trustProxy: true
+```
+
+这样 Agent Card 与 `health` 会返回外部 origin（例如 `https://a2a.example.com/a2a`），不需要写死 `publicUrl`。如果代理无法传递这些头，再显式设置 `server.publicUrl`。
+
+> 设置页使用的**卡片镜像**仍位于 DSH Web 的 origin：它使用 `server.publicUrl`，否则使用 A2A 监听地址（独立端口下是 `http://host:port`）。如果 GUI 与 A2A 通过不同外部域名暴露，请设置 `publicUrl`。
+
 ---
 
 ## 配置参考
@@ -326,10 +347,10 @@ enabled: true
 server:
   mountPath: /a2a
   cardPath: /.well-known/agent-card.json
-  publicUrl: null              # 对外可达的 origin；独立端口时默认 http://host:port
+  publicUrl: null              # 显式对外 origin；留空则按请求 Host / X-Forwarded-* 推导
   host: 127.0.0.1              # 独立监听的绑定地址（仅 server.port 非 null 时生效）
   port: null                   # null = 复用 DSH Web 端口；1-65535 = 独立监听
-  trustProxy: false            # 反向代理后设为 true，以使用 X-Forwarded-For
+  trustProxy: false            # 反向代理后设为 true，以使用 X-Forwarded-For 并推导对外地址
   streaming: true
   pushNotifications: true
   extendedCard: false          # 启用鉴权后才生效

package/client.js

@@ -96,6 +96,7 @@ window.__ModuleLoader__.load({
       fieldServerHost: '监听地址',
       fieldServerPort: '监听端口',
       fieldServerMountPath: '挂载路径',
+      fieldServerTrustProxy: '信任代理头（X-Forwarded-*）',
       fieldServerStreaming: '流式 SSE',
       fieldServerPushNotifications: '推送通知',
       fieldServerExtendedCard: '扩展 Agent Card',
@@ -207,6 +208,7 @@ window.__ModuleLoader__.load({
       fieldServerHost: 'Listen host',
       fieldServerPort: 'Listen port',
       fieldServerMountPath: 'Mount path',
+      fieldServerTrustProxy: 'Trust proxy headers (X-Forwarded-*)',
       fieldServerStreaming: 'Streaming SSE',
       fieldServerPushNotifications: 'Push notifications',
       fieldServerExtendedCard: 'Extended Agent Card',

package/lib/panel.js

@@ -41,6 +41,7 @@ const FIELDS = [
     placeholder: '留空 = 复用 DSH 端口',
   },
   { path: 'server.mountPath', type: 'string', group: 'server' },
+  { path: 'server.trustProxy', type: 'boolean', group: 'server' },
   { path: 'server.streaming', type: 'boolean', group: 'server' },
   { path: 'server.pushNotifications', type: 'boolean', group: 'server' },
   { path: 'server.extendedCard', type: 'boolean', group: 'server' },
@@ -286,7 +287,7 @@ export function createPanelRouter({ ctx, config, mountPath, logger, status, heal
     res.setHeader('Cache-Control', 'no-store')
     res.json({
       ok: true,
-      plugin: { name: PLUGIN_NAME, version: '1.1.1' },
+      plugin: { name: PLUGIN_NAME, version: '1.1.3' },
       mountPath,
       ...payload,
       ...(typeof status === 'function' ? { server: status() } : {}),
@@ -383,7 +384,7 @@ export function createPanelRouter({ ctx, config, mountPath, logger, status, heal
     logger.info('[a2a] configuration updated from the settings panel')
     res.json({
       ok: true,
-      plugin: { name: PLUGIN_NAME, version: '1.1.1' },
+      plugin: { name: PLUGIN_NAME, version: '1.1.3' },
       mountPath,
       ...describe(live, liveEntry, []),
       ...(typeof status === 'function' ? { server: status() } : {}),

package/lib/server.js

@@ -16,6 +16,7 @@
  */
 
 import http from 'node:http'
+import { createHash } from 'node:crypto'
 import { isIP } from 'node:net'
 import express from 'express'
 import { A2A_PROTOCOL_VERSION } from '@a2a-js/sdk'
@@ -23,8 +24,9 @@ import {
   DefaultPushNotificationSender,
   DefaultRequestHandler,
   InMemoryPushNotificationStore,
+  STATE_HEADERS_KEY,
 } from '@a2a-js/sdk/server'
-import { agentCardHandler, jsonRpcHandler, restHandler } from '@a2a-js/sdk/server/express'
+import { jsonRpcHandler, restHandler } from '@a2a-js/sdk/server/express'
 import { buildAgentCard, buildExtendedCard, createCardSigner, isAuthEnabled } from './card.js'
 import { createAuthenticator } from './auth.js'
 import { createPanelRouter } from './panel.js'
@@ -62,6 +64,42 @@ function formatUrlHost(host) {
   return isIP(host) === 6 ? `[${host}]` : host
 }
 
+/** First value of a possibly repeated HTTP header. */
+function firstHeader(value) {
+  if (Array.isArray(value)) return value[0]
+  return typeof value === 'string' ? value : undefined
+}
+
+/**
+ * Derive the externally visible origin from the request headers.
+ *
+ * `server.publicUrl` always wins. When `server.trustProxy` is enabled, the
+ * first `X-Forwarded-Host` / `X-Forwarded-Proto` values are honored so a
+ * reverse proxy can preserve its external origin. Otherwise the raw `Host`
+ * header is used. Returns null when no usable host is present.
+ *
+ * @param {Record<string, string|string[]|undefined>} headers
+ * @param {Readonly<object>} config
+ * @param {string} fallbackProtocol protocol to use without a forwarded proto
+ * @returns {string|null}
+ */
+function baseFromHeaders(headers, config, fallbackProtocol = 'http') {
+  if (config.server.publicUrl) return trimTrailingSlash(config.server.publicUrl)
+  const trusted = config.server.trustProxy === true
+  const forwardedHost = firstHeader(headers?.['x-forwarded-host'])
+  const host = trusted && forwardedHost ? forwardedHost.split(',')[0].trim() : firstHeader(headers?.host)
+  if (!host) return null
+  const forwardedProto = firstHeader(headers?.['x-forwarded-proto'])
+  const protocol = trusted && forwardedProto ? forwardedProto.split(',')[0].trim() : fallbackProtocol
+  try {
+    const url = new URL(`${protocol}://${host}`)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+    return trimTrailingSlash(url.origin)
+  } catch {
+    return null
+  }
+}
+
 /**
  * Derive the externally visible origin.
  *
@@ -75,8 +113,8 @@ function resolvePublicBase(config, webServer, logger) {
     const host = config.server.host
     if (host === '0.0.0.0' || host === '::') {
       logger.warn(
-        `[a2a] server.host ${host} is a wildcard; advertising a loopback URL. ` +
-          'Set server.publicUrl to the address remote A2A clients should use.',
+        `[a2a] server.host ${host} is a wildcard; the static fallback advertises a loopback URL. ` +
+          'Agent Card and health use the request Host; set server.publicUrl only if the proxy cannot forward Host/forwarded headers.',
       )
     }
     const advertised = host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host
@@ -274,6 +312,17 @@ export class A2AService {
         ? undefined
         : new DefaultPushNotificationSender(pushStore, { timeout: config.push.timeoutMs })
 
+    const extendedAgentCardProvider = extendedCard
+      ? async (context) => {
+          const headers =
+            context?.state?.get?.(STATE_HEADERS_KEY) ?? context?.state?.get?.('headers') ?? {}
+          const base = baseFromHeaders(headers, config, 'http')
+          return base === null
+            ? extendedAgentCard
+            : buildExtendedCard(effective, { publicBaseUrl: base, credentials })
+        }
+      : undefined
+
     const requestHandler = new DefaultRequestHandler(
       baseCard,
       taskStore,
@@ -281,11 +330,54 @@ export class A2AService {
       undefined,
       pushStore,
       pushSender,
-      extendedCard ? async () => extendedAgentCard : undefined,
+      extendedAgentCardProvider,
       signer ?? undefined,
       { validateInputModes: true },
     )
 
+    const serveCard = async (req, res, base) => {
+      try {
+        const card = buildAgentCard(effective, { publicBaseUrl: base, credentials })
+        const served = signer === null ? card : await signer(card)
+        const body = JSON.stringify(served)
+        res.setHeader('ETag', `W/"${createHash('sha256').update(body).digest('hex').slice(0, 16)}"`)
+        res.setHeader('Vary', 'Host, X-Forwarded-Host, X-Forwarded-Proto')
+        res.setHeader(
+          'Cache-Control',
+          config.server.publicUrl && config.server.cardCacheSeconds > 0
+            ? `public, max-age=${config.server.cardCacheSeconds}`
+            : 'no-cache',
+        )
+        if (req.fresh) {
+          res.statusCode = 304
+          res.end()
+          return
+        }
+        res.setHeader('Content-Type', JSON_CONTENT_TYPE)
+        res.statusCode = 200
+        res.end(body)
+      } catch (error) {
+        logger.warn(`[a2a] agent card generation failed: ${errorMessage(error)}`)
+        if (!res.headersSent) {
+          res.statusCode = 500
+          res.setHeader('Content-Type', JSON_CONTENT_TYPE)
+          res.end(JSON.stringify({ error: 'INTERNAL', message: 'cannot generate the Agent Card' }))
+        } else if (!res.writableEnded) {
+          res.end()
+        }
+      }
+    }
+    const dynamicCardHandler = (req, res) =>
+      serveCard(req, res, baseFromHeaders(req.headers, config, req.protocol) ?? publicBaseUrl)
+    // The DSH origin only mirrors the card for panel discovery; its interfaces
+    // must point at the A2A listener (or publicUrl), not at the GUI origin.
+    const mirrorCardHandler = (req, res) =>
+      serveCard(
+        req,
+        res,
+        config.server.publicUrl ? trimTrailingSlash(config.server.publicUrl) : publicBaseUrl,
+      )
+
     const authenticator = createAuthenticator({
       config,
       credentials,
@@ -293,14 +385,10 @@ export class A2AService {
       isRestBinding: (req) => isRestBinding(req, mountPath),
     })
 
-    const cardRouter = agentCardHandler({
-      agentCardProvider: requestHandler,
-      cache: { maxAge: config.server.cardCacheSeconds },
-    })
     const jsonRpcRouter = jsonRpcHandler({ requestHandler, userBuilder: authenticator.userBuilder })
     const restRouter = restHandler({ requestHandler, userBuilder: authenticator.userBuilder })
-    const healthSnapshot = () =>
-      this.#health({ runtime, executor, taskStore, authenticator, publicBaseUrl, extendedCard })
+    const healthSnapshot = (base = publicBaseUrl) =>
+      this.#health({ runtime, executor, taskStore, authenticator, publicBaseUrl: base, extendedCard })
     const panelRouter = createPanelRouter({
       ctx: this.#ctx,
       config,
@@ -389,8 +477,9 @@ export class A2AService {
 
     const a2aApp = express()
     applyCommon(a2aApp)
-    // The Agent Card is discovery metadata and stays public.
-    a2aApp.use(config.server.cardPath, cardRouter)
+    // The Agent Card is discovery metadata and stays public. Its interface URLs
+    // are derived per request so a reverse proxy's external Host is preserved.
+    a2aApp.get(config.server.cardPath, dynamicCardHandler)
     if (!standalone) {
       // In shared mode the panel is part of the same app and must precede the
       // A2A auth middleware.
@@ -411,8 +500,9 @@ export class A2AService {
     })
     if (config.server.health) {
       a2aApp.get(`${mountPath}/health`, (req, res) => {
+        const base = baseFromHeaders(req.headers, config, req.protocol) ?? publicBaseUrl
         res.setHeader('Cache-Control', 'no-store')
-        res.json(healthSnapshot())
+        res.json(healthSnapshot(base))
       })
     }
     a2aApp.use((req, res) => {
@@ -493,7 +583,11 @@ export class A2AService {
       // Discovery stays reachable on the Harness Web origin in both modes: in
       // shared mode it is the endpoint, and in standalone mode it bootstraps
       // the settings panel (the card itself points at the dedicated port).
-      registerRoute({ kind: 'exact', path: config.server.cardPath }, callA2A, 'agent card')
+      registerRoute(
+        { kind: 'exact', path: config.server.cardPath },
+        standalone ? mirrorCardHandler : callA2A,
+        standalone ? 'agent card mirror' : 'agent card',
+      )
       if (standalone) {
         registerRoute(
           { kind: 'prefix', path: `${mountPath}/panel` },
@@ -618,6 +712,8 @@ export class A2AService {
   #health({ runtime, executor, taskStore, authenticator, publicBaseUrl, extendedCard }) {
     const config = this.#config
     const mounted = this.#mounted
+    const server = this.serverStatus()
+    server.publicUrl = publicBaseUrl
     return {
       status: 'ok',
       protocolVersion: A2A_PROTOCOL_VERSION,
@@ -625,7 +721,7 @@ export class A2AService {
       version: config.card.version,
       publicUrl: publicBaseUrl,
       uptimeSeconds: mounted === undefined ? 0 : Math.round((Date.now() - mounted.startedAt) / 1000),
-      server: this.serverStatus(),
+      server,
       interfaces: [
         { protocolBinding: 'JSONRPC', url: `${publicBaseUrl}${config.server.mountPath}` },
         { protocolBinding: 'HTTP+JSON', url: `${publicBaseUrl}${config.server.mountPath}/rest` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai_mind/dsh-a2a",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Production A2A (Agent2Agent) v1.0 server for DeepSeek Harness agents: JSON-RPC + HTTP+JSON bindings, streaming, tasks, push notifications and signed Agent Cards.",
   "type": "module",
   "license": "MIT",