@ai_mind/dsh-a2a 1.1.0 → 1.1.2

package/README.md

@@ -228,6 +228,16 @@ JSON-RPC 方法名：`SendMessage`、`SendStreamingMessage`、`GetTask`、`ListT
 
 凭据来源（可组合）：`auth.clients[{id,token}]`、`auth.tokens[]`、`auth.token`、`auth.tokenEnv`（环境变量，支持逗号/换行分隔多个）。启用鉴权后 Agent Card 会自动声明 `securitySchemes` 与 `securityRequirements`。
 
+内联令牌可以直接写在插件配置里（设置页的「A2A 访问令牌（内联）」字段等价）：
+
+```yaml
+auth:
+  mode: bearer
+  token: 'your-long-random-token'
+```
+
+> 在设置页输入令牌时，如果 `auth.mode` 还是 `none`，保存会自动切换为 `bearer`。令牌不会回显；它会以明文保存在 profile 的 `cordis.patch.yml`（权限 600），生产环境建议改用 `auth.tokenEnv` 或 `auth.clients`。
+
 **每个凭据是一个独立的租户边界**：任务与 Push 配置按凭据 id 隔离，客户端 A 看不到客户端 B 的任务。未鉴权时所有 loopback 调用方共享 `anonymous` 作用域。
 
 ### 默认安全姿态
@@ -237,7 +247,7 @@ JSON-RPC 方法名：`SendMessage`、`SendStreamingMessage`、`GetTask`、`ListT
 - 请求体默认上限 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。
 
@@ -299,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`。
+
 ---
 
 ## 配置参考
@@ -316,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

@@ -72,11 +72,11 @@ window.__ModuleLoader__.load({
       saveError: '保存失败',
       reload: '重新读取',
       dirty: '有未保存的修改',
-      token: '访问令牌',
-      tokenHint: '写回 profile YAML；推荐改用 auth.tokenEnv 从环境变量读取。',
-      tokenPlaceholder: '留空保持不变',
+      token: 'A2A 访问令牌（内联）',
+      tokenHint: '保存后写入插件配置的 auth.token；如果鉴权模式为 none，会自动切换为 bearer。值不会回显。',
+      tokenPlaceholder: '输入新的访问令牌',
       clearToken: '清除已保存的内联令牌',
-      tokenConfigured: '已配置内联令牌',
+      tokenConfigured: '已配置内联令牌（值不会回显）',
       tokenNotConfigured: '未配置内联令牌',
       tokenEnvConfigured: '环境变量已配置：{name}',
       openCard: '打开 Agent Card',
@@ -183,11 +183,11 @@ window.__ModuleLoader__.load({
       saveError: 'Save failed',
       reload: 'Reload',
       dirty: 'Unsaved changes',
-      token: 'Access token',
-      tokenHint: 'Stored in the profile YAML. Prefer auth.tokenEnv instead.',
-      tokenPlaceholder: 'Leave empty to keep',
+      token: 'A2A access token (inline)',
+      tokenHint: 'Saved as auth.token in the plugin config. A mode of "none" switches to bearer automatically. The value is never echoed.',
+      tokenPlaceholder: 'Enter a new access token',
       clearToken: 'Clear the saved inline token',
-      tokenConfigured: 'Inline token configured',
+      tokenConfigured: 'Inline token configured (value is never shown)',
       tokenNotConfigured: 'No inline token',
       tokenEnvConfigured: 'Environment variable: {name}',
       openCard: 'Open Agent Card',
@@ -653,7 +653,7 @@ window.__ModuleLoader__.load({
         const secretBlock = panel
           ? h(
               'div',
-              { className: 'a2aui-group' },
+              { className: 'a2aui-group', key: 'inline-token' },
               h('h5', { className: 'a2aui-group-title' }, t('token')),
               h(
                 'div',
@@ -704,8 +704,8 @@ window.__ModuleLoader__.load({
             ? h(
                 'div',
                 { className: 'a2aui-form' },
-                ...groups.map(([group, fields]) =>
-                  h(
+                ...groups.flatMap(([group, fields]) => {
+                  const node = h(
                     'div',
                     { className: 'a2aui-group', key: group },
                     h('h5', { className: 'a2aui-group-title' }, groupLabel(t, group)),
@@ -717,9 +717,9 @@ window.__ModuleLoader__.load({
                         h('div', null, renderControl(field)),
                       ),
                     ),
-                  ),
-                ),
-                secretBlock,
+                  )
+                  return group === 'auth' ? [node, secretBlock] : [node]
+                }),
                 h(
                   'div',
                   { className: 'a2aui-form-foot' },

package/lib/panel.js

@@ -286,7 +286,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.0' },
+      plugin: { name: PLUGIN_NAME, version: '1.1.2' },
       mountPath,
       ...payload,
       ...(typeof status === 'function' ? { server: status() } : {}),
@@ -342,6 +342,9 @@ export function createPanelRouter({ ctx, config, mountPath, logger, status, heal
         if (typeof body.token !== 'string') throw new Error('token must be a string')
         if (body.token.trim() === '') throw new Error('token must not be empty')
         setAt(next, 'auth.token', body.token)
+        // A token with auth.mode "none" would be stored but never used. Treat
+        // an explicitly supplied token as the intent to enable bearer auth.
+        if ((next.auth?.mode ?? 'none') === 'none') setAt(next, 'auth.mode', 'bearer')
       }
 
       const normalized = normalizeConfig(next)
@@ -380,7 +383,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.0' },
+      plugin: { name: PLUGIN_NAME, version: '1.1.2' },
       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.0",
+  "version": "1.1.2",
   "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",