@ai_mind/dsh-a2a 0.0.0-stage → 1.0.0

package/lib/card.js

@@ -0,0 +1,214 @@
+/**
+ * Agent Card construction and JWS signing for A2A v1.0.
+ *
+ * The public card is served at the well-known URI. Optional JWS signatures
+ * follow RFC 7515 over the RFC 8785 canonical form computed by the official
+ * SDK, so a card signed here verifies with any conforming A2A client.
+ *
+ * @module @ai_mind/dsh-a2a/card
+ */
+
+import { readFileSync } from 'node:fs'
+import { createPrivateKey } from 'node:crypto'
+import { A2A_PROTOCOL_VERSION, generateAgentCardSignature } from '@a2a-js/sdk'
+import { trimTrailingSlash } from './util.js'
+
+/** Security scheme name advertised for bearer or API-key authentication. */
+export const SECURITY_SCHEME_NAME = 'a2a'
+
+/** @returns {boolean} whether the deployment requires credentials. */
+export function isAuthEnabled(config, credentials) {
+  return config.auth.mode !== 'none' && credentials.length > 0
+}
+
+/**
+ * Build the `securitySchemes` / `securityRequirements` pair for the public
+ * card. An unsecured deployment returns empty objects.
+ *
+ * @param {object} config
+ * @param {{ id: string, token: string }[]} credentials
+ * @returns {{ securitySchemes: object, securityRequirements: object[] }}
+ */
+export function buildSecurity(config, credentials) {
+  if (!isAuthEnabled(config, credentials)) {
+    return { securitySchemes: {}, securityRequirements: [] }
+  }
+  if (config.auth.mode === 'bearer') {
+    return {
+      securitySchemes: {
+        [SECURITY_SCHEME_NAME]: {
+          httpAuthSecurityScheme: {
+            scheme: 'Bearer',
+            bearerFormat: 'opaque',
+            description: 'Send the configured A2A access token as an HTTP Bearer credential.',
+          },
+        },
+      },
+      securityRequirements: [{ schemes: { [SECURITY_SCHEME_NAME]: { list: [] } } }],
+    }
+  }
+  return {
+    securitySchemes: {
+      [SECURITY_SCHEME_NAME]: {
+        apiKeySecurityScheme: {
+          location: 'header',
+          name: config.auth.headerName,
+          description: `Send the configured A2A access token in the ${config.auth.headerName} header.`,
+        },
+      },
+    },
+    securityRequirements: [{ schemes: { [SECURITY_SCHEME_NAME]: { list: [] } } }],
+  }
+}
+
+/** Drop absent optional entries so the served card stays ProtoJSON-clean. */
+function compactSkill(skill) {
+  const result = {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    tags: skill.tags ?? [],
+  }
+  if (skill.examples?.length) result.examples = skill.examples
+  if (skill.inputModes?.length) result.inputModes = skill.inputModes
+  if (skill.outputModes?.length) result.outputModes = skill.outputModes
+  if (skill.securityRequirements?.length) result.securityRequirements = skill.securityRequirements
+  return result
+}
+
+/**
+ * Assemble the Agent Card for this deployment.
+ *
+ * @param {Readonly<object>} config
+ * @param {object} options
+ * @param {string} options.publicBaseUrl absolute origin, no trailing slash
+ * @param {{ id: string, token: string }[]} options.credentials
+ * @returns {object} an A2A v1.0 AgentCard in ProtoJSON shape
+ */
+export function buildAgentCard(config, { publicBaseUrl, credentials }) {
+  const base = trimTrailingSlash(publicBaseUrl)
+  const endpoint = `${base}${config.server.mountPath}`
+  const security = buildSecurity(config, credentials)
+
+  const card = {
+    name: config.card.name,
+    description: config.card.description,
+    supportedInterfaces: [
+      {
+        url: endpoint,
+        protocolBinding: 'JSONRPC',
+        tenant: '',
+        protocolVersion: A2A_PROTOCOL_VERSION,
+      },
+      {
+        url: `${endpoint}/rest`,
+        protocolBinding: 'HTTP+JSON',
+        tenant: '',
+        protocolVersion: A2A_PROTOCOL_VERSION,
+      },
+    ],
+    version: config.card.version,
+    capabilities: {
+      streaming: config.server.streaming,
+      pushNotifications: config.server.pushNotifications,
+      extendedAgentCard: config.server.extendedCard,
+    },
+    securitySchemes: security.securitySchemes,
+    securityRequirements: security.securityRequirements,
+    defaultInputModes: config.card.defaultInputModes,
+    defaultOutputModes: config.card.defaultOutputModes,
+    skills: config.card.skills.map(compactSkill),
+    signatures: [],
+  }
+
+  if (config.card.extensions.length > 0) {
+    card.capabilities.extensions = config.card.extensions.map((extension) => {
+      const value = {
+        uri: extension.uri,
+        description: extension.description ?? '',
+        required: extension.required === true,
+      }
+      if (extension.params !== undefined) value.params = extension.params
+      return value
+    })
+  }
+  if (config.card.provider) card.provider = config.card.provider
+  if (config.card.documentationUrl) card.documentationUrl = config.card.documentationUrl
+  if (config.card.iconUrl) card.iconUrl = config.card.iconUrl
+
+  return card
+}
+
+/**
+ * Build the authenticated extended card: the public card with additional
+ * skills and optional description overrides.
+ *
+ * @param {Readonly<object>} config
+ * @param {object} options same options as {@link buildAgentCard}
+ * @returns {object}
+ */
+export function buildExtendedCard(config, options) {
+  const card = buildAgentCard(config, options)
+  const extended = config.card.extended
+  if (extended.description) card.description = extended.description
+  if (extended.documentationUrl) card.documentationUrl = extended.documentationUrl
+  if (extended.skills.length > 0) {
+    const seen = new Set(card.skills.map((skill) => skill.id))
+    for (const skill of extended.skills) {
+      if (seen.has(skill.id)) continue
+      card.skills.push(compactSkill(skill))
+    }
+  }
+  return card
+}
+
+/**
+ * Create the JWS signature generator, or `null` when signing is disabled.
+ * Signatures are cached for `signing.cacheSeconds` keyed on the card content.
+ *
+ * @param {Readonly<object>} config
+ * @param {{ warn: (message: string) => void }} logger
+ * @returns {Promise<((card: object) => Promise<object>) | null>}
+ */
+export function createCardSigner(config) {
+  if (!config.signing.enabled) return null
+
+  let pem = config.signing.privateKeyPem
+  if (!pem) {
+    try {
+      pem = readFileSync(config.signing.privateKeyFile, 'utf8')
+    } catch (error) {
+      throw new Error(`a2a: cannot read signing.privateKeyFile "${config.signing.privateKeyFile}": ${error.message}`)
+    }
+  }
+  let key
+  try {
+    key = createPrivateKey({ key: pem, format: 'pem' })
+  } catch (error) {
+    throw new Error(`a2a: signing key is not a valid PEM private key: ${error.message}`)
+  }
+
+  const header = { alg: config.signing.algorithm, typ: 'JOSE', kid: config.signing.keyId }
+  if (config.signing.jku) header.jku = config.signing.jku
+  const sign = generateAgentCardSignature(key, header)
+
+  const cacheMs = config.signing.cacheSeconds * 1000
+  let cacheKey
+  let cacheValue
+  let cacheAt = 0
+
+  return async (card) => {
+    const body = JSON.stringify(card)
+    const now = Date.now()
+    if (cacheMs > 0 && cacheValue !== undefined && cacheKey === body && now - cacheAt < cacheMs) {
+      return cacheValue
+    }
+    const signed = await sign(structuredClone(card))
+    if (cacheMs > 0) {
+      cacheKey = body
+      cacheValue = signed
+      cacheAt = now
+    }
+    return signed
+  }
+}

package/lib/client-discovery.js

@@ -0,0 +1,58 @@
+/**
+ * Hot-install discovery for the browser half.
+ *
+ * `@deepseek-ai/dsh-client-modules` caches, per Loader specifier, whether that
+ * package carries a `dsh.client` half. A profile that installed this bundle
+ * while it had no browser half keeps a negative verdict for the process
+ * lifetime, so adding `client.js` to an already-loaded package would otherwise
+ * only appear after a restart.
+ *
+ * This shim clears that one negative verdict and asks the scanner to reconcile
+ * the row once. It touches only the scanner's public-ish compiled fields and
+ * silently degrades to "client half appears after restart" when they are
+ * absent or changed. On a fresh boot the package is scanned with `dsh.client`
+ * already present and the shim is a no-op.
+ *
+ * @module @ai_mind/dsh-a2a/client-discovery
+ */
+
+import { errorMessage } from './util.js'
+
+const PACKAGE_NAME = '@ai_mind/dsh-a2a'
+
+/**
+ * Ask the client-module scanner to re-read this package's manifest.
+ *
+ * @param {object} ctx owning Cordis context
+ * @param {{ info: Function, warn: Function }} logger
+ * @returns {boolean} whether a reconciliation was triggered
+ */
+export function ensureClientHalfDiscovered(ctx, logger) {
+  const scanner = ctx.get?.('clientModules')
+  if (scanner === undefined || scanner === null) return false
+  if (!(scanner.pkgMeta instanceof Map) || !(scanner.dirty instanceof Set) || typeof scanner.flush !== 'function') {
+    return false
+  }
+  if (scanner.table instanceof Map && scanner.table.has(PACKAGE_NAME)) return false
+
+  const suffix = `\u0000${PACKAGE_NAME}`
+  let cleared = 0
+  for (const key of [...scanner.pkgMeta.keys()]) {
+    if (typeof key === 'string' && key.endsWith(suffix)) {
+      scanner.pkgMeta.delete(key)
+      cleared += 1
+    }
+  }
+
+  scanner.dirty.add(PACKAGE_NAME)
+  try {
+    scanner.flush((error) => {
+      logger.warn(`[a2a] client module discovery failed: ${errorMessage(error)}`)
+    })
+  } catch (error) {
+    logger.warn(`[a2a] client module discovery failed: ${errorMessage(error)}`)
+    return false
+  }
+  if (cleared > 0) logger.info('[a2a] cleared a cached "no browser half" verdict and re-scanned the package')
+  return true
+}