@ai_mind/dsh-a2a 0.0.0-stage → 1.1.0

package/lib/store.js

@@ -0,0 +1,288 @@
+/**
+ * Task and push-notification storage for the A2A server.
+ *
+ * `A2ATaskStore` implements the SDK's `TaskStore` contract with:
+ *   - per-(tenant, authenticated client) isolation, so one credential never
+ *     sees another client's tasks;
+ *   - the SDK-compatible cursor pagination, descending status-time ordering
+ *     and `includeArtifacts` semantics required by `ListTasks`;
+ *   - TTL and capacity eviction, but only for tasks in a terminal state so an
+ *     in-flight execution can never be dropped from under its event bus.
+ *
+ * `GuardedPushNotificationStore` adds webhook URL validation (SSRF guard) and
+ * a per-task configuration cap in front of the SDK's in-memory store.
+ *
+ * @module @ai_mind/dsh-a2a/store
+ */
+
+import { RequestMalformedError } from '@a2a-js/sdk/errors'
+import { newId, parsePublicHttpUrl } from './util.js'
+
+/** Terminal A2A task states (COMPLETED, FAILED, CANCELED, REJECTED). */
+const TERMINAL_STATES = new Set([3, 4, 5, 7])
+
+/** Default page size used when the request omits `pageSize`, per the spec. */
+const DEFAULT_PAGE_SIZE = 50
+const MAX_PAGE_SIZE = 100
+
+function isTerminal(task) {
+  return TERMINAL_STATES.has(task?.status?.state)
+}
+
+/** @returns {string} the isolation key for one call context. */
+function scopeKey(context) {
+  const tenant = typeof context?.tenant === 'string' ? context.tenant : ''
+  const owner = typeof context?.user?.userName === 'string' ? context.user.userName : ''
+  return `${tenant}\u0000${owner}`
+}
+
+function encodePageToken(timestamp, id) {
+  return Buffer.from(JSON.stringify({ t: timestamp, i: id }), 'utf8').toString('base64url')
+}
+
+function decodePageToken(token) {
+  try {
+    const parsed = JSON.parse(Buffer.from(String(token), 'base64url').toString('utf8'))
+    if (typeof parsed?.t !== 'string' || typeof parsed?.i !== 'string') return null
+    return { timestamp: parsed.t, id: parsed.i }
+  } catch {
+    return null
+  }
+}
+
+function lastTimestamp(task) {
+  return typeof task?.status?.timestamp === 'string' ? task.status.timestamp : ''
+}
+
+/**
+ * Task store with owner scoping, cursor pagination and bounded retention.
+ */
+export class A2ATaskStore {
+  /** @type {Map<string, Map<string, { task: object, updatedAt: number }>>} */
+  #buckets = new Map()
+  #ttlMs
+  #maxTasks
+  #logger
+  #saved = 0
+  #terminalCount = 0
+
+  /**
+   * @param {object} options
+   * @param {number} options.ttlMs retention for terminal tasks (0 disables time-based eviction)
+   * @param {number} options.maxTasks global capacity for terminal tasks
+   * @param {{ warn: (...args: unknown[]) => void }} options.logger
+   */
+  constructor({ ttlMs, maxTasks, logger }) {
+    this.#ttlMs = ttlMs
+    this.#maxTasks = maxTasks
+    this.#logger = logger
+  }
+
+  #bucket(context) {
+    return this.#buckets.get(scopeKey(context))
+  }
+
+  async save(task, context) {
+    if (task === undefined || task === null || typeof task.id !== 'string' || task.id === '') {
+      throw new Error('a2a: task store save requires a task with a non-empty id')
+    }
+    const key = scopeKey(context)
+    let bucket = this.#buckets.get(key)
+    if (bucket === undefined) {
+      bucket = new Map()
+      this.#buckets.set(key, bucket)
+    }
+    const previous = bucket.get(task.id)
+    const wasTerminal = previous !== undefined && isTerminal(previous.task)
+    const nowTerminal = isTerminal(task)
+    if (!wasTerminal && nowTerminal) this.#terminalCount += 1
+    if (wasTerminal && !nowTerminal) this.#terminalCount -= 1
+    // Retention follows the task's own status time (the durable "last update"
+    // fact), falling back to arrival time when a client supplied no timestamp.
+    const statusTime = Date.parse(task.status?.timestamp ?? '')
+    const updatedAt = Number.isFinite(statusTime) ? statusTime : Date.now()
+    bucket.set(task.id, { task: structuredClone(task), updatedAt })
+    this.#saved += 1
+    this.#evictOverflow()
+  }
+
+  async load(taskId, context) {
+    const entry = this.#bucket(context)?.get(taskId)
+    return entry === undefined ? undefined : structuredClone(entry.task)
+  }
+
+  async list(params, context) {
+    const {
+      contextId,
+      status,
+      pageSize = DEFAULT_PAGE_SIZE,
+      pageToken,
+      statusTimestampAfter,
+      includeArtifacts = false,
+    } = params ?? {}
+
+    const bucket = this.#bucket(context)
+    let tasks = bucket === undefined ? [] : [...bucket.values()].map((entry) => entry.task)
+
+    if (contextId) tasks = tasks.filter((task) => task.contextId === contextId)
+    if (status !== undefined && status !== 0) tasks = tasks.filter((task) => task.status?.state === status)
+    if (statusTimestampAfter) {
+      const threshold = new Date(statusTimestampAfter).getTime()
+      if (Number.isFinite(threshold)) {
+        tasks = tasks.filter((task) => {
+          const timestamp = lastTimestamp(task)
+          return timestamp !== '' && new Date(timestamp).getTime() > threshold
+        })
+      }
+    }
+
+    tasks.sort((left, right) => {
+      const timeLeft = lastTimestamp(left)
+      const timeRight = lastTimestamp(right)
+      if (timeRight !== timeLeft) return timeRight.localeCompare(timeLeft)
+      return right.id.localeCompare(left.id)
+    })
+
+    const totalSize = tasks.length
+
+    if (pageToken) {
+      const cursor = decodePageToken(pageToken)
+      if (cursor === null) {
+        tasks = []
+      } else {
+        const index = tasks.findIndex(
+          (task) => lastTimestamp(task) === cursor.timestamp && task.id === cursor.id,
+        )
+        tasks = index === -1 ? [] : tasks.slice(index + 1)
+      }
+    }
+
+    const size = Math.min(
+      Math.max(Number.isInteger(pageSize) ? pageSize : DEFAULT_PAGE_SIZE, 1),
+      MAX_PAGE_SIZE,
+    )
+    const page = tasks.slice(0, size)
+    const resultTasks = page.map((task) => {
+      const copy = structuredClone(task)
+      if (!includeArtifacts) copy.artifacts = []
+      return copy
+    })
+
+    let nextPageToken = ''
+    if (page.length > 0 && tasks.length > page.length) {
+      const last = page[page.length - 1]
+      nextPageToken = encodePageToken(lastTimestamp(last), last.id)
+    }
+
+    return { tasks: resultTasks, nextPageToken, pageSize: size, totalSize }
+  }
+
+  /**
+   * Remove terminal tasks older than the TTL and, when over capacity, the
+   * oldest terminal tasks until the store fits.
+   *
+   * @param {number} [now]
+   * @returns {{ expired: number, evicted: number }}
+   */
+  sweep(now = Date.now()) {
+    let expired = 0
+    if (this.#ttlMs > 0) {
+      for (const [key, bucket] of this.#buckets) {
+        for (const [id, entry] of bucket) {
+          if (!isTerminal(entry.task)) continue
+          if (now - entry.updatedAt < this.#ttlMs) continue
+          bucket.delete(id)
+          this.#terminalCount -= 1
+          expired += 1
+        }
+        if (bucket.size === 0) this.#buckets.delete(key)
+      }
+    }
+    const evicted = this.#evictOverflow()
+    return { expired, evicted }
+  }
+
+  /** Enforce `maxTasks` by dropping the oldest terminal entries. */
+  #evictOverflow() {
+    if (this.#terminalCount <= this.#maxTasks) return 0
+    const candidates = []
+    for (const [key, bucket] of this.#buckets) {
+      for (const [id, entry] of bucket) {
+        if (!isTerminal(entry.task)) continue
+        candidates.push({ key, id, updatedAt: entry.updatedAt })
+      }
+    }
+    candidates.sort((left, right) => left.updatedAt - right.updatedAt)
+    let removed = 0
+    for (const candidate of candidates) {
+      if (this.#terminalCount <= this.#maxTasks) break
+      const bucket = this.#buckets.get(candidate.key)
+      if (bucket === undefined) continue
+      if (bucket.delete(candidate.id)) {
+        this.#terminalCount -= 1
+        removed += 1
+        if (bucket.size === 0) this.#buckets.delete(candidate.key)
+      }
+    }
+    if (removed > 0) {
+      this.#logger.warn(`[a2a] task store at capacity; evicted ${removed} terminal task(s)`)
+    }
+    return removed
+  }
+
+  /** @returns {{ tasks: number, scopes: number, saved: number, terminal: number }} */
+  stats() {
+    let tasks = 0
+    for (const bucket of this.#buckets.values()) tasks += bucket.size
+    return { tasks, scopes: this.#buckets.size, saved: this.#saved, terminal: this.#terminalCount }
+  }
+}
+
+/**
+ * Validate push-notification webhook targets before the SDK persists them.
+ *
+ * The A2A spec lets clients supply an arbitrary webhook URL; without a guard a
+ * remote caller could make the Host POST to internal services (SSRF).
+ */
+export class GuardedPushNotificationStore {
+  #inner
+  #allowPrivate
+  #maxConfigs
+  #logger
+
+  constructor(inner, { allowPrivateTargets, maxConfigsPerTask = 10, logger }) {
+    this.#inner = inner
+    this.#allowPrivate = allowPrivateTargets
+    this.#maxConfigs = maxConfigsPerTask
+    this.#logger = logger
+  }
+
+  async save(taskId, context, pushNotificationConfig) {
+    try {
+      parsePublicHttpUrl(pushNotificationConfig?.url, { allowPrivate: this.#allowPrivate })
+    } catch (error) {
+      this.#logger.warn(`[a2a] rejected push notification config for task ${taskId}: ${error.message}`)
+      throw new RequestMalformedError(error.message)
+    }
+    const existing = await this.#inner.load(taskId, context)
+    if (existing.length >= this.#maxConfigs && !pushNotificationConfig.id) {
+      throw new RequestMalformedError(`push notification configuration limit reached (${this.#maxConfigs})`)
+    }
+    if (!pushNotificationConfig.id) pushNotificationConfig.id = newId()
+    return this.#inner.save(taskId, context, pushNotificationConfig)
+  }
+
+  load(taskId, context) {
+    return this.#inner.load(taskId, context)
+  }
+
+  loadWithMetadata(taskId, context) {
+    return this.#inner.loadWithMetadata(taskId, context)
+  }
+
+  delete(taskId, context, configId) {
+    return this.#inner.delete(taskId, context, configId)
+  }
+}
+
+export { TERMINAL_STATES }

package/lib/util.js

@@ -0,0 +1,221 @@
+/**
+ * Small, dependency-free helpers shared by the A2A server modules.
+ *
+ * Everything here is protocol- or platform-level plumbing, deliberately free
+ * of DeepSeek Harness imports so the modules can be unit-tested in isolation.
+ *
+ * @module @ai_mind/dsh-a2a/util
+ */
+
+import { randomUUID, timingSafeEqual } from 'node:crypto'
+import { isIP } from 'node:net'
+
+/** @returns {boolean} whether `value` is a plain object (not an array/null/class instance). */
+export function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/** Deep-clone a JSON-compatible value. */
+export function cloneJson(value) {
+  return value === undefined ? undefined : structuredClone(value)
+}
+
+/**
+ * Merge `patch` into `base` recursively. Arrays and scalars replace the base
+ * value; plain objects merge. `undefined` values in `patch` are ignored so a
+ * parsed YAML document cannot erase a default by omission.
+ *
+ * @param {object} base
+ * @param {object} patch
+ * @returns {object} a fresh merged object
+ */
+export function deepMerge(base, patch) {
+  const result = isPlainObject(base) ? structuredClone(base) : {}
+  if (!isPlainObject(patch)) return result
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value)
+    } else {
+      result[key] = cloneJson(value)
+    }
+  }
+  return result
+}
+
+/** Recursively freeze a JSON-compatible value in place and return it. */
+export function deepFreeze(value) {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value
+  Object.freeze(value)
+  for (const child of Object.values(value)) deepFreeze(child)
+  return value
+}
+
+/** @returns {string} a fresh RFC 4122 version 4 UUID. */
+export function newId() {
+  return randomUUID()
+}
+
+/** @returns {string} the current time as a millisecond-precision ISO 8601 UTC string. */
+export function nowIso() {
+  return new Date().toISOString()
+}
+
+/**
+ * Compare two strings without leaking their contents through timing.
+ *
+ * @param {string} left
+ * @param {string} right
+ * @returns {boolean}
+ */
+export function constantTimeEqual(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false
+  const a = Buffer.from(left, 'utf8')
+  const b = Buffer.from(right, 'utf8')
+  if (a.length !== b.length) {
+    // Still consume a comparison to keep the failure path uniform.
+    timingSafeEqual(a, a)
+    return false
+  }
+  return timingSafeEqual(a, b)
+}
+
+/** @returns {boolean} whether a socket address names the local host. */
+export function isLoopbackAddress(address) {
+  if (typeof address !== 'string' || address.length === 0) return false
+  const bare = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address
+  if (bare === '::1' || bare === '0:0:0:0:0:0:0:1') return true
+  const zone = bare.indexOf('%')
+  const host = zone === -1 ? bare : bare.slice(0, zone)
+  if (host === '::1') return true
+  if (isIP(host) === 4) {
+    const [a] = host.split('.').map(Number)
+    return a === 127
+  }
+  return false
+}
+
+/**
+ * Classify a URL host as an internal address that a remote push-notification
+ * target must not reach by default.
+ *
+ * Literal addresses and well-known local names are rejected. DNS names are not
+ * resolved here (the HTTP client resolves them at delivery time), so this is a
+ * first-line SSRF guard rather than a complete one; deployments that must not
+ * reach internal networks should also enforce egress policy at the network
+ * layer.
+ *
+ * @param {string} hostname a URL hostname without brackets or port
+ * @returns {boolean}
+ */
+export function isPrivateHostname(hostname) {
+  if (typeof hostname !== 'string') return true
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (host === 'localhost' || host.endsWith('.localhost')) return true
+  if (host.endsWith('.local') || host.endsWith('.internal')) return true
+  const family = isIP(host)
+  if (family === 4) {
+    const parts = host.split('.').map(Number)
+    const [a, b] = parts
+    if (a === 0 || a === 10 || a === 127) return true
+    if (a === 169 && b === 254) return true
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 192 && b === 168) return true
+    if (a === 100 && b >= 64 && b <= 127) return true
+    if (a === 198 && (b === 18 || b === 19)) return true
+    if (a >= 224) return true
+    return false
+  }
+  if (family === 6) {
+    if (host === '::' || host === '::1') return true
+    const first = host.split(':')[0]
+    const firstValue = Number.parseInt(first || '0', 16)
+    if (Number.isFinite(firstValue)) {
+      if ((firstValue & 0xfe00) === 0xfc00) return true // fc00::/7 unique local
+      if ((firstValue & 0xffc0) === 0xfe80) return true // fe80::/10 link local
+      if (firstValue === 0) return true // ::ffff:0:0/96, ::/128
+    }
+    if (host.startsWith('::ffff:')) return isPrivateHostname(host.slice('::ffff:'.length))
+    return false
+  }
+  return false
+}
+
+/**
+ * Validate a push-notification URL and, when private targets are not allowed,
+ * reject loopback/link-local/private destinations.
+ *
+ * @param {unknown} value candidate URL
+ * @param {{ allowPrivate?: boolean }} [options]
+ * @returns {URL} the parsed URL
+ * @throws {Error} when the URL is not an acceptable HTTP(S) target
+ */
+export function parsePublicHttpUrl(value, options = {}) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('push notification URL must be a non-empty string')
+  }
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`push notification URL is not a valid absolute URL: ${value}`)
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`push notification URL must use http(s), got ${url.protocol}`)
+  }
+  if (url.username || url.password) {
+    throw new Error('push notification URL must not embed credentials')
+  }
+  if (!options.allowPrivate && isPrivateHostname(url.hostname)) {
+    throw new Error(
+      `push notification URL targets a private or loopback host (${url.hostname}); ` +
+        'set push.allowPrivateTargets=true to permit internal webhooks',
+    )
+  }
+  return url
+}
+
+/** Truncate a string to at most `max` characters, appending a marker. */
+export function truncate(value, max, marker = '\n…[truncated]') {
+  if (typeof value !== 'string' || value.length <= max) return value
+  return value.slice(0, Math.max(0, max - marker.length)) + marker
+}
+
+/** @returns {string} a human-readable message for any thrown value. */
+export function errorMessage(error) {
+  if (error instanceof Error) return error.message || error.name
+  if (typeof error === 'string') return error
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}
+
+/**
+ * Make a user-supplied file name safe to join under a directory.
+ * Path separators, control characters and leading dots are neutralized.
+ *
+ * @param {string | undefined} name
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function safeFileName(name, fallback = 'attachment') {
+  const base = typeof name === 'string' && name.trim() !== '' ? name : fallback
+  const cleaned = base
+    .replace(/[\\/]+/g, '_')
+    .replace(/[\u0000-\u001f\u007f]/g, '_')
+    .replace(/^\.+/, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  const bounded = cleaned.slice(0, 120)
+  return bounded.length > 0 ? bounded : fallback
+}
+
+/** Normalize an origin/base URL by dropping trailing slashes. */
+export function trimTrailingSlash(value) {
+  return typeof value === 'string' ? value.replace(/\/+$/, '') : value
+}
+

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "A2A Server",
+    "description": "Exposes this DeepSeek Harness agent to other agents over the Agent2Agent (A2A) protocol v1.0, with JSON-RPC and HTTP+JSON bindings, streaming, tasks and signed Agent Cards."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "A2A 服务端",
+    "description": "通过 Agent2Agent（A2A）v1.0 协议把本机 DeepSeek Harness 智能体暴露给其他智能体，支持 JSON-RPC 与 HTTP+JSON 两种绑定、流式响应、任务管理与签名 Agent Card。"
+  }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@ai_mind/dsh-a2a",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "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",
+  "keywords": [
+    "a2a",
+    "agent2agent",
+    "deepseek",
+    "harness",
+    "dsh",
+    "agent",
+    "json-rpc",
+    "sse"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/**/*.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "1.3.0",
+    "express": "^5.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}