@ai_mind/dsh-a2a 0.0.0-stage → 1.1.0

package/cordis.patch.yml

@@ -0,0 +1,26 @@
+# dsh-a2a bundle patch: mounts the A2A (Agent2Agent) v1.0 server row.
+#
+# Defaults below are safe for a loopback deployment. The row listens on its
+# own port (127.0.0.1:41241) so A2A traffic does not share the DSH Web port;
+# set `server.port: null` to reuse the DSH listener again. To expose the agent
+# to other hosts, set `server.publicUrl` and enable `auth` in the profile patch:
+#
+#   - id: a2a-server
+#     name: '@ai_mind/dsh-a2a'
+#     config:
+#       server:
+#         publicUrl: 'https://agent.example.com'
+#       auth:
+#         mode: bearer
+#         tokenEnv: A2A_AUTH_TOKEN
+#
+# A patch replaces the targeted row's whole `config`, so restate every field
+# you keep from this file when overriding the row.
+- insert:
+    - id: a2a-server
+      name: '@ai_mind/dsh-a2a'
+      config:
+        enabled: true
+        server:
+          host: 127.0.0.1
+          port: 41241

package/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="A2A server">
+  <defs>
+    <linearGradient id="a2a-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#2f6df6"/>
+      <stop offset="1" stop-color="#7b3cf0"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="url(#a2a-bg)"/>
+  <circle cx="18" cy="32" r="7" fill="none" stroke="#ffffff" stroke-width="3.5"/>
+  <circle cx="46" cy="32" r="7" fill="none" stroke="#ffffff" stroke-width="3.5"/>
+  <path d="M25.5 32h13" stroke="#ffffff" stroke-width="3.5" stroke-linecap="round"/>
+  <path d="M32 25.5l6.5 6.5-6.5 6.5" fill="none" stroke="#ffffff" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="18" cy="32" r="2.2" fill="#ffffff"/>
+  <circle cx="46" cy="32" r="2.2" fill="#ffffff"/>
+</svg>

package/index.js

@@ -0,0 +1,59 @@
+/**
+ * @ai_mind/dsh-a2a — an Agent2Agent (A2A) v1.0 server for DeepSeek Harness.
+ *
+ * The plugin exposes the local Harness agent over the official A2A protocol:
+ * JSON-RPC and HTTP+JSON bindings, blocking and streaming message sends, task
+ * listing/cancellation/resubscription, push notifications, and JWS-signed
+ * Agent Cards. It mounts on the Harness Web server, so the reachable origin is
+ * the same listener that serves the GUI.
+ *
+ * Configuration lives on the bundle row; see README.md for every field.
+ *
+ * @module @ai_mind/dsh-a2a
+ */
+
+import { A2AService } from './lib/server.js'
+import { normalizeConfig } from './lib/config.js'
+import { ensureClientHalfDiscovered } from './lib/client-discovery.js'
+
+/** Diagnostic plugin name shown in loader errors. */
+export const name = 'a2a-server'
+
+/**
+ * The server cannot work without the agent registry: every A2A task is
+ * executed by a real Harness agent.
+ */
+export const inject = ['agents']
+
+/**
+ * Mount the A2A server.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {unknown} rawConfig the bundle row's `config`
+ */
+export function apply(ctx, rawConfig) {
+  let config
+  try {
+    config = normalizeConfig(rawConfig)
+  } catch (error) {
+    throw new Error(`a2a: invalid configuration: ${error.message}`)
+  }
+  if (!config.enabled) {
+    ctx.logger?.info?.('[a2a] plugin is disabled by config')
+    return
+  }
+
+  const service = new A2AService(ctx, config)
+  ctx.effect(() => () => service.dispose(), 'a2a: service lifecycle')
+
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() => service.mount(webCtx.webServer), 'a2a: http routes')
+  })
+
+  // A profile that installed an older build without a browser half keeps a
+  // negative discovery verdict for this specifier; reconcile it so the
+  // settings panel appears without a restart.
+  ctx.inject(['clientModules'], (clientCtx) => {
+    ensureClientHalfDiscovered(clientCtx, service.logger)
+  })
+}

package/lib/auth.js

@@ -0,0 +1,196 @@
+/**
+ * Authentication for the A2A endpoint.
+ *
+ * Three modes are supported:
+ *   - `none`   : no credentials; only loopback callers are admitted unless
+ *                `auth.allowRemoteUnauthenticated` is explicitly enabled.
+ *   - `bearer` : `Authorization: Bearer <token>`
+ *   - `apiKey` : a configurable header carrying the token (default `x-api-key`)
+ *
+ * The public Agent Card stays reachable without credentials (it must be, for
+ * discovery); every other route is protected.
+ *
+ * @module @ai_mind/dsh-a2a/auth
+ */
+
+import { constantTimeEqual, isLoopbackAddress } from './util.js'
+
+/** Credential extractors per auth mode. */
+const EXTRACTORS = {
+  bearer(req) {
+    const header = req.headers.authorization
+    if (typeof header !== 'string') return null
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(header)
+    return match ? match[1] : null
+  },
+  apiKey(req, config) {
+    const raw = req.headers[config.auth.headerName]
+    if (typeof raw === 'string' && raw.trim() !== '') return raw.trim()
+    if (Array.isArray(raw) && typeof raw[0] === 'string') return raw[0].trim()
+    return null
+  },
+}
+
+/**
+ * Write a 401 in the shape of the binding the caller used.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {object} options
+ * @param {string} options.message
+ * @param {string} options.challenge
+ * @param {string} options.contentType
+ * @param {boolean} options.restBinding
+ */
+function writeUnauthorized(req, res, { message, challenge, contentType, restBinding }) {
+  if (res.headersSent) return
+  res.statusCode = 401
+  res.setHeader('Content-Type', contentType)
+  res.setHeader('WWW-Authenticate', challenge)
+  res.setHeader('Cache-Control', 'no-store')
+  const details = [
+    {
+      '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+      reason: 'UNAUTHENTICATED',
+      domain: 'a2a-protocol.org',
+      metadata: { path: String(req.url ?? '') },
+    },
+  ]
+  if (restBinding) {
+    res.end(
+      JSON.stringify({
+        error: { code: 401, status: 'UNAUTHENTICATED', message, details },
+      }),
+    )
+    return
+  }
+  res.end(
+    JSON.stringify({
+      jsonrpc: '2.0',
+      id: null,
+      error: { code: -32000, message, data: details },
+    }),
+  )
+}
+
+/**
+ * Create the authenticator for one mounted deployment.
+ *
+ * @param {object} options
+ * @param {Readonly<object>} options.config normalized configuration
+ * @param {{ id: string, token: string }[]} options.credentials resolved secrets
+ * @param {{ warn: (...args: unknown[]) => void, info: (...args: unknown[]) => void }} options.logger
+ * @param {(req: import('node:http').IncomingMessage) => boolean} options.isRestBinding
+ * @returns {{
+ *   enabled: boolean,
+ *   middleware: import('express').RequestHandler,
+ *   userBuilder: (req: import('node:http').IncomingMessage) => object,
+ *   describe: () => object,
+ * }}
+ */
+export function createAuthenticator({ config, credentials, logger, isRestBinding }) {
+  const mode = config.auth.mode
+  const enabled = mode !== 'none'
+  if (enabled && credentials.length === 0) {
+    throw new Error(
+      `a2a: auth.mode is "${mode}" but no credentials are configured; ` +
+        'set auth.tokens, auth.token, auth.clients or auth.tokenEnv',
+    )
+  }
+
+  const challenge =
+    mode === 'bearer'
+      ? `Bearer realm="${config.auth.realm}"`
+      : `ApiKey realm="${config.auth.realm}", header="${config.auth.headerName}"`
+
+  const contentType = 'application/a2a+json'
+  let warnedRemote = false
+
+  /** @returns {{ id: string } | null} */
+  function identify(req) {
+    const extractor = EXTRACTORS[mode]
+    if (extractor === undefined) return null
+    const presented = extractor(req, config)
+    if (presented === null) return null
+    let matched = null
+    for (const credential of credentials) {
+      // Every candidate is compared so timing does not reveal which one matched.
+      if (constantTimeEqual(presented, credential.token) && matched === null) matched = credential
+    }
+    return matched === null ? null : { id: matched.id }
+  }
+
+  function middleware(req, res, next) {
+    const peer = req.ip || req.socket?.remoteAddress || ''
+    const restBinding = isRestBinding(req)
+
+    if (!enabled) {
+      if (!config.auth.allowRemoteUnauthenticated && !isLoopbackAddress(peer)) {
+        if (!warnedRemote) {
+          warnedRemote = true
+          logger.warn(
+            `[a2a] rejected unauthenticated request from ${peer || 'unknown peer'}; ` +
+              'configure auth or set auth.allowRemoteUnauthenticated=true to allow remote callers',
+          )
+        }
+        writeUnauthorized(req, res, {
+          message: 'Unauthenticated: this A2A endpoint only accepts loopback callers without configured credentials.',
+          challenge,
+          contentType,
+          restBinding,
+        })
+        return
+      }
+      next()
+      return
+    }
+
+    const identity = identify(req)
+    if (identity === null) {
+      writeUnauthorized(req, res, {
+        message: 'Unauthenticated: missing or invalid A2A credentials.',
+        challenge,
+        contentType,
+        restBinding,
+      })
+      return
+    }
+    req.a2aClient = identity
+    next()
+  }
+
+  function userBuilder(req) {
+    const identity = req.a2aClient
+    if (!identity) {
+      return {
+        get isAuthenticated() {
+          return false
+        },
+        get userName() {
+          return ''
+        },
+      }
+    }
+    return {
+      get isAuthenticated() {
+        return true
+      },
+      get userName() {
+        return identity.id
+      },
+    }
+  }
+
+  return {
+    enabled,
+    middleware,
+    userBuilder,
+    describe: () => ({
+      mode,
+      enabled,
+      clientCount: credentials.length,
+      header: mode === 'apiKey' ? config.auth.headerName : 'authorization',
+      allowRemoteUnauthenticated: config.auth.allowRemoteUnauthenticated,
+    }),
+  }
+}