@ai_mind/dsh-a2a 0.0.0-stage → 1.1.0

package/lib/config.js

@@ -0,0 +1,576 @@
+/**
+ * A2A server configuration: defaults, normalization and validation.
+ *
+ * The loader passes the row's `config` as plain JSON (YAML scalars already
+ * resolved), so validation happens here at activation time and fails loudly
+ * with the offending path. `normalizeConfig` returns a deep-frozen object the
+ * rest of the plugin can treat as immutable.
+ *
+ * @module @ai_mind/dsh-a2a/config
+ */
+
+import { isIP } from 'node:net'
+import { isPlainObject, deepMerge, deepFreeze } from './util.js'
+
+/** Error raised for an invalid plugin configuration. */
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'A2AConfigError'
+  }
+}
+
+/** Paths whose prefix already belongs to the Harness Web GUI. */
+const RESERVED_MOUNT_PREFIXES = ['/api', '/plugins', '/.well-known']
+
+/** Default Agent Card describing what a Harness agent can do. */
+const DEFAULT_SKILLS = [
+  {
+    id: 'general',
+    name: 'General-purpose coding assistant',
+    description:
+      'Answers questions, writes and edits code, runs commands, and completes multi-step tasks in the session workspace.',
+    tags: ['general', 'coding', 'analysis', 'files', 'automation'],
+    examples: [
+      'Summarize the repository in this workspace.',
+      'Fix the failing test and explain the root cause.',
+    ],
+  },
+]
+
+/** Complete default configuration. */
+export const DEFAULT_CONFIG = {
+  enabled: true,
+  server: {
+    mountPath: '/a2a',
+    cardPath: '/.well-known/agent-card.json',
+    publicUrl: null,
+    host: '127.0.0.1',
+    port: null,
+    trustProxy: false,
+    streaming: true,
+    pushNotifications: true,
+    extendedCard: false,
+    cardCacheSeconds: 300,
+    health: true,
+    logRequests: false,
+    cors: {
+      enabled: false,
+      origins: [],
+      allowCredentials: false,
+      maxAgeSeconds: 600,
+    },
+  },
+  card: {
+    name: 'DeepSeek Harness Agent',
+    description:
+      'A DeepSeek Harness agent exposed over the Agent2Agent protocol. It can read and write files, run commands, search the web, and carry out multi-step tasks in its workspace.',
+    version: '1.0.0',
+    provider: null,
+    documentationUrl: null,
+    iconUrl: null,
+    defaultInputModes: ['text/plain', 'application/json', 'image/png', 'image/jpeg', 'image/webp'],
+    defaultOutputModes: ['text/plain', 'application/json'],
+    skills: DEFAULT_SKILLS,
+    extensions: [],
+    extended: {
+      description: null,
+      documentationUrl: null,
+      skills: [],
+    },
+  },
+  auth: {
+    mode: 'none',
+    tokens: [],
+    clients: [],
+    token: null,
+    tokenEnv: null,
+    headerName: 'x-api-key',
+    allowRemoteUnauthenticated: false,
+    realm: 'a2a',
+  },
+  agent: {
+    preset: null,
+    provider: null,
+    model: null,
+    reasoningEffort: null,
+    maxTokens: null,
+    cwd: null,
+    sandboxMode: 'workspace-write',
+    approvalPolicy: 'never',
+    maxConcurrentTasks: 4,
+    queueTimeoutMs: 60000,
+    turnTimeoutMs: 900000,
+    contextIdleTtlMs: 900000,
+  },
+  limits: {
+    maxRequestBytes: 8 * 1024 * 1024,
+    maxFileBytes: 16 * 1024 * 1024,
+    maxPromptChars: 200000,
+    maxArtifactChars: 200000,
+  },
+  files: {
+    enabled: true,
+    directory: '.a2a-inbox',
+    retentionMs: 24 * 60 * 60 * 1000,
+  },
+  tasks: {
+    ttlMs: 24 * 60 * 60 * 1000,
+    maxTasks: 2000,
+    sweepIntervalMs: 60000,
+  },
+  push: {
+    allowPrivateTargets: false,
+    timeoutMs: 5000,
+  },
+  signing: {
+    enabled: false,
+    privateKeyPem: null,
+    privateKeyFile: null,
+    keyId: null,
+    algorithm: 'ES256',
+    jku: null,
+    cacheSeconds: 300,
+  },
+  logging: {
+    requests: false,
+  },
+}
+
+const TOP_LEVEL_KEYS = new Set(Object.keys(DEFAULT_CONFIG))
+
+const SECTION_KEYS = {
+  server: new Set(Object.keys(DEFAULT_CONFIG.server)),
+  'server.cors': new Set(Object.keys(DEFAULT_CONFIG.server.cors)),
+  card: new Set(Object.keys(DEFAULT_CONFIG.card)),
+  'card.provider': new Set(['organization', 'url']),
+  'card.extended': new Set(Object.keys(DEFAULT_CONFIG.card.extended)),
+  auth: new Set(Object.keys(DEFAULT_CONFIG.auth)),
+  'auth.clients': new Set(['id', 'token']),
+  agent: new Set(Object.keys(DEFAULT_CONFIG.agent)),
+  limits: new Set(Object.keys(DEFAULT_CONFIG.limits)),
+  files: new Set(Object.keys(DEFAULT_CONFIG.files)),
+  tasks: new Set(Object.keys(DEFAULT_CONFIG.tasks)),
+  push: new Set(Object.keys(DEFAULT_CONFIG.push)),
+  signing: new Set(Object.keys(DEFAULT_CONFIG.signing)),
+  logging: new Set(Object.keys(DEFAULT_CONFIG.logging)),
+  skills: new Set(['id', 'name', 'description', 'tags', 'examples', 'inputModes', 'outputModes', 'securityRequirements']),
+  extensions: new Set(['uri', 'description', 'required', 'params']),
+}
+
+/** Throw a configuration error with its exact path. */
+function fail(path, message) {
+  throw new ConfigError(`${path}: ${message}`)
+}
+
+/** Reject unknown keys so a typo cannot silently fall back to a default. */
+function checkKeys(value, path) {
+  if (!isPlainObject(value)) return
+  const allowed = SECTION_KEYS[path]
+  if (allowed === undefined) return
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) fail(path, `unknown field "${key}"`)
+  }
+}
+
+function expectObject(value, path) {
+  if (!isPlainObject(value)) fail(path, 'must be an object')
+  return value
+}
+
+function expectBoolean(value, path) {
+  if (typeof value !== 'boolean') fail(path, 'must be a boolean')
+  return value
+}
+
+function expectString(value, path, { allowEmpty = false } = {}) {
+  if (typeof value !== 'string') fail(path, 'must be a string')
+  if (!allowEmpty && value.trim() === '') fail(path, 'must not be empty')
+  return value
+}
+
+function expectNullableString(value, path, options) {
+  if (value === null || value === undefined) return null
+  return expectString(value, path, options)
+}
+
+function expectInteger(value, path, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (!Number.isInteger(value)) fail(path, 'must be an integer')
+  if (value < min || value > max) fail(path, `must be between ${min} and ${max}`)
+  return value
+}
+
+function expectEnum(value, path, allowed) {
+  if (!allowed.includes(value)) fail(path, `must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}`)
+  return value
+}
+
+function expectStringArray(value, path, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value)) fail(path, 'must be an array of strings')
+  const items = value.map((item, index) => expectString(item, `${path}[${index}]`, { allowEmpty: false }))
+  if (nonEmpty && items.length === 0) fail(path, 'must contain at least one entry')
+  return items
+}
+
+function validatePath(value, path, { reserved = false } = {}) {
+  expectString(value, path)
+  if (!value.startsWith('/')) fail(path, 'must start with "/"')
+  if (value === '/') fail(path, 'must not be the server root')
+  if (value.endsWith('/')) fail(path, 'must not end with "/"')
+  if (/[?#\s]/.test(value)) fail(path, 'must not contain whitespace, "?" or "#"')
+  if (reserved) {
+    for (const prefix of RESERVED_MOUNT_PREFIXES) {
+      if (value === prefix || value.startsWith(`${prefix}/`)) {
+        fail(path, `"${value}" collides with a Harness Web route (${RESERVED_MOUNT_PREFIXES.join(', ')})`)
+      }
+    }
+  }
+  return value
+}
+
+function validateSkills(value, path) {
+  if (!Array.isArray(value)) fail(path, 'must be an array')
+  return value.map((skill, index) => {
+    const at = `${path}[${index}]`
+    expectObject(skill, at)
+    checkKeys(skill, 'skills')
+    const id = expectString(skill.id, `${at}.id`)
+    const name = expectString(skill.name, `${at}.name`)
+    const description = expectString(skill.description, `${at}.description`)
+    const tags = expectStringArray(skill.tags ?? [], `${at}.tags`)
+    const result = { id, name, description, tags }
+    if (skill.examples !== undefined) result.examples = expectStringArray(skill.examples, `${at}.examples`)
+    if (skill.inputModes !== undefined) result.inputModes = expectStringArray(skill.inputModes, `${at}.inputModes`)
+    if (skill.outputModes !== undefined) result.outputModes = expectStringArray(skill.outputModes, `${at}.outputModes`)
+    if (skill.securityRequirements !== undefined) {
+      if (!Array.isArray(skill.securityRequirements)) fail(`${at}.securityRequirements`, 'must be an array')
+      result.securityRequirements = skill.securityRequirements
+    }
+    return result
+  })
+}
+
+function validateExtensions(value, path) {
+  if (!Array.isArray(value)) fail(path, 'must be an array')
+  return value.map((extension, index) => {
+    const at = `${path}[${index}]`
+    expectObject(extension, at)
+    checkKeys(extension, 'extensions')
+    return {
+      uri: expectString(extension.uri, `${at}.uri`),
+      description: expectNullableString(extension.description, `${at}.description`) ?? '',
+      required: extension.required === undefined ? false : expectBoolean(extension.required, `${at}.required`),
+      params: extension.params === undefined ? undefined : extension.params,
+    }
+  })
+}
+
+function validateCors(cors, path) {
+  expectObject(cors, path)
+  checkKeys(cors, 'server.cors')
+  const result = {
+    enabled: expectBoolean(cors.enabled, `${path}.enabled`),
+    origins: expectStringArray(cors.origins, `${path}.origins`),
+    allowCredentials: expectBoolean(cors.allowCredentials, `${path}.allowCredentials`),
+    maxAgeSeconds: expectInteger(cors.maxAgeSeconds, `${path}.maxAgeSeconds`, { min: 0, max: 86400 }),
+  }
+  if (result.allowCredentials && result.origins.includes('*')) {
+    fail(`${path}.origins`, 'a wildcard origin cannot be combined with allowCredentials')
+  }
+  return result
+}
+
+function validateClients(auth, path) {
+  if (!Array.isArray(auth.clients)) fail(`${path}.clients`, 'must be an array')
+  const seen = new Set()
+  return auth.clients.map((client, index) => {
+    const at = `${path}.clients[${index}]`
+    expectObject(client, at)
+    checkKeys(client, 'auth.clients')
+    const id = expectString(client.id, `${at}.id`)
+    if (seen.has(id)) fail(`${at}.id`, `duplicate client id "${id}"`)
+    seen.add(id)
+    return { id, token: expectString(client.token, `${at}.token`) }
+  })
+}
+
+function validateSigning(signing, path) {
+  expectObject(signing, path)
+  checkKeys(signing, 'signing')
+  const enabled = expectBoolean(signing.enabled, `${path}.enabled`)
+  const result = {
+    enabled,
+    privateKeyPem: expectNullableString(signing.privateKeyPem, `${path}.privateKeyPem`, { allowEmpty: false }),
+    privateKeyFile: expectNullableString(signing.privateKeyFile, `${path}.privateKeyFile`, { allowEmpty: false }),
+    keyId: expectNullableString(signing.keyId, `${path}.keyId`, { allowEmpty: false }),
+    algorithm: expectEnum(signing.algorithm, `${path}.algorithm`, [
+      'ES256',
+      'ES384',
+      'ES512',
+      'RS256',
+      'RS384',
+      'RS512',
+      'PS256',
+      'PS384',
+      'PS512',
+      'EdDSA',
+    ]),
+    jku: expectNullableString(signing.jku, `${path}.jku`, { allowEmpty: false }),
+    cacheSeconds: expectInteger(signing.cacheSeconds, `${path}.cacheSeconds`, { min: 0, max: 86400 }),
+  }
+  if (enabled) {
+    if (!result.privateKeyPem && !result.privateKeyFile) {
+      fail(`${path}.privateKeyPem`, 'signing requires privateKeyPem or privateKeyFile')
+    }
+    if (result.privateKeyPem && result.privateKeyFile) {
+      fail(`${path}.privateKeyFile`, 'set only one of privateKeyPem and privateKeyFile')
+    }
+    if (!result.keyId) fail(`${path}.keyId`, 'signing requires keyId')
+  }
+  return result
+}
+
+/**
+ * Merge user configuration over the defaults and validate it.
+ *
+ * @param {unknown} raw the loader-provided row configuration
+ * @returns {Readonly<object>} a validated, deep-frozen configuration
+ * @throws {ConfigError} on any invalid or unknown field
+ */
+export function normalizeConfig(raw) {
+  if (raw !== undefined && raw !== null && !isPlainObject(raw)) {
+    throw new ConfigError('config: must be a mapping')
+  }
+  const merged = deepMerge(DEFAULT_CONFIG, raw ?? {})
+
+  for (const key of Object.keys(merged)) {
+    if (!TOP_LEVEL_KEYS.has(key)) throw new ConfigError(`config: unknown field "${key}"`)
+  }
+
+  // server
+  expectObject(merged.server, 'server')
+  checkKeys(merged.server, 'server')
+  merged.server.mountPath = validatePath(merged.server.mountPath, 'server.mountPath', { reserved: true })
+  merged.server.cardPath = validatePath(merged.server.cardPath, 'server.cardPath')
+  merged.server.publicUrl = expectNullableString(merged.server.publicUrl, 'server.publicUrl', { allowEmpty: false })
+  merged.server.host = expectString(merged.server.host, 'server.host')
+  if (merged.server.host !== 'localhost' && isIP(merged.server.host) === 0) {
+    fail('server.host', 'must be an IPv4/IPv6 literal or "localhost"')
+  }
+  merged.server.port =
+    merged.server.port === null || merged.server.port === undefined
+      ? null
+      : expectInteger(merged.server.port, 'server.port', { min: 1, max: 65535 })
+  if (merged.server.publicUrl !== null) {
+    let url
+    try {
+      url = new URL(merged.server.publicUrl)
+    } catch {
+      fail('server.publicUrl', 'must be an absolute http(s) URL')
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      fail('server.publicUrl', 'must use http or https')
+    }
+    if (url.search || url.hash) fail('server.publicUrl', 'must not contain a query string or fragment')
+    merged.server.publicUrl = merged.server.publicUrl.replace(/\/+$/, '')
+  }
+  merged.server.trustProxy = expectBoolean(merged.server.trustProxy, 'server.trustProxy')
+  merged.server.streaming = expectBoolean(merged.server.streaming, 'server.streaming')
+  merged.server.pushNotifications = expectBoolean(merged.server.pushNotifications, 'server.pushNotifications')
+  merged.server.extendedCard = expectBoolean(merged.server.extendedCard, 'server.extendedCard')
+  merged.server.cardCacheSeconds = expectInteger(merged.server.cardCacheSeconds, 'server.cardCacheSeconds', {
+    min: 0,
+    max: 86400,
+  })
+  merged.server.health = expectBoolean(merged.server.health, 'server.health')
+  merged.server.logRequests = expectBoolean(merged.server.logRequests, 'server.logRequests')
+  merged.server.cors = validateCors(merged.server.cors, 'server.cors')
+
+  // card
+  expectObject(merged.card, 'card')
+  checkKeys(merged.card, 'card')
+  merged.card.name = expectString(merged.card.name, 'card.name')
+  merged.card.description = expectString(merged.card.description, 'card.description')
+  merged.card.version = expectString(merged.card.version, 'card.version')
+  merged.card.documentationUrl = expectNullableString(merged.card.documentationUrl, 'card.documentationUrl', {
+    allowEmpty: false,
+  })
+  merged.card.iconUrl = expectNullableString(merged.card.iconUrl, 'card.iconUrl', { allowEmpty: false })
+  if (merged.card.provider !== null) {
+    expectObject(merged.card.provider, 'card.provider')
+    checkKeys(merged.card.provider, 'card.provider')
+    merged.card.provider = {
+      organization: expectString(merged.card.provider.organization, 'card.provider.organization'),
+      url: expectString(merged.card.provider.url, 'card.provider.url'),
+    }
+  }
+  merged.card.defaultInputModes = expectStringArray(merged.card.defaultInputModes, 'card.defaultInputModes', {
+    nonEmpty: true,
+  })
+  merged.card.defaultOutputModes = expectStringArray(merged.card.defaultOutputModes, 'card.defaultOutputModes', {
+    nonEmpty: true,
+  })
+  merged.card.skills = validateSkills(merged.card.skills, 'card.skills')
+  if (merged.card.skills.length === 0) fail('card.skills', 'must contain at least one skill')
+  merged.card.extensions = validateExtensions(merged.card.extensions, 'card.extensions')
+  expectObject(merged.card.extended, 'card.extended')
+  checkKeys(merged.card.extended, 'card.extended')
+  merged.card.extended = {
+    description: expectNullableString(merged.card.extended.description, 'card.extended.description', {
+      allowEmpty: false,
+    }),
+    documentationUrl: expectNullableString(merged.card.extended.documentationUrl, 'card.extended.documentationUrl', {
+      allowEmpty: false,
+    }),
+    skills: validateSkills(merged.card.extended.skills ?? [], 'card.extended.skills'),
+  }
+
+  // auth
+  expectObject(merged.auth, 'auth')
+  checkKeys(merged.auth, 'auth')
+  merged.auth.mode = expectEnum(merged.auth.mode, 'auth.mode', ['none', 'bearer', 'apiKey'])
+  merged.auth.tokens = expectStringArray(merged.auth.tokens, 'auth.tokens')
+  merged.auth.clients = validateClients(merged.auth, 'auth')
+  merged.auth.token = expectNullableString(merged.auth.token, 'auth.token', { allowEmpty: false })
+  merged.auth.tokenEnv = expectNullableString(merged.auth.tokenEnv, 'auth.tokenEnv', { allowEmpty: false })
+  merged.auth.headerName = expectString(merged.auth.headerName, 'auth.headerName').toLowerCase()
+  if (!/^[a-z0-9!#$%&'*+.^_`|~-]+$/.test(merged.auth.headerName)) {
+    fail('auth.headerName', 'must be a valid HTTP header name')
+  }
+  merged.auth.allowRemoteUnauthenticated = expectBoolean(
+    merged.auth.allowRemoteUnauthenticated,
+    'auth.allowRemoteUnauthenticated',
+  )
+  merged.auth.realm = expectString(merged.auth.realm, 'auth.realm')
+
+  // agent
+  expectObject(merged.agent, 'agent')
+  checkKeys(merged.agent, 'agent')
+  merged.agent.preset = expectNullableString(merged.agent.preset, 'agent.preset', { allowEmpty: false })
+  merged.agent.provider = expectNullableString(merged.agent.provider, 'agent.provider', { allowEmpty: false })
+  merged.agent.model = expectNullableString(merged.agent.model, 'agent.model', { allowEmpty: false })
+  if ((merged.agent.provider === null) !== (merged.agent.model === null)) {
+    fail('agent.model', 'provider and model must be configured together')
+  }
+  merged.agent.reasoningEffort = expectNullableString(merged.agent.reasoningEffort, 'agent.reasoningEffort', {
+    allowEmpty: false,
+  })
+  merged.agent.maxTokens =
+    merged.agent.maxTokens === null
+      ? null
+      : expectInteger(merged.agent.maxTokens, 'agent.maxTokens', { min: 1, max: 10000000 })
+  merged.agent.cwd = expectNullableString(merged.agent.cwd, 'agent.cwd', { allowEmpty: false })
+  if (merged.agent.cwd !== null && !merged.agent.cwd.startsWith('/')) {
+    fail('agent.cwd', 'must be an absolute path')
+  }
+  merged.agent.sandboxMode = expectEnum(merged.agent.sandboxMode, 'agent.sandboxMode', [
+    'inherit',
+    'read-only',
+    'workspace-write',
+    'danger-full-access',
+  ])
+  merged.agent.approvalPolicy = expectEnum(merged.agent.approvalPolicy, 'agent.approvalPolicy', ['inherit', 'ask', 'never'])
+  merged.agent.maxConcurrentTasks = expectInteger(merged.agent.maxConcurrentTasks, 'agent.maxConcurrentTasks', {
+    min: 1,
+    max: 64,
+  })
+  merged.agent.queueTimeoutMs = expectInteger(merged.agent.queueTimeoutMs, 'agent.queueTimeoutMs', {
+    min: 0,
+    max: 3600000,
+  })
+  merged.agent.turnTimeoutMs = expectInteger(merged.agent.turnTimeoutMs, 'agent.turnTimeoutMs', {
+    min: 1000,
+    max: 86400000,
+  })
+  merged.agent.contextIdleTtlMs = expectInteger(merged.agent.contextIdleTtlMs, 'agent.contextIdleTtlMs', {
+    min: 0,
+    max: 86400000,
+  })
+
+  // limits
+  expectObject(merged.limits, 'limits')
+  checkKeys(merged.limits, 'limits')
+  for (const [key, min, max] of [
+    ['maxRequestBytes', 1024, 256 * 1024 * 1024],
+    ['maxFileBytes', 0, 256 * 1024 * 1024],
+    ['maxPromptChars', 1024, 10000000],
+    ['maxArtifactChars', 1024, 10000000],
+  ]) {
+    merged.limits[key] = expectInteger(merged.limits[key], `limits.${key}`, { min, max })
+  }
+
+  // files
+  expectObject(merged.files, 'files')
+  checkKeys(merged.files, 'files')
+  merged.files.enabled = expectBoolean(merged.files.enabled, 'files.enabled')
+  merged.files.directory = expectString(merged.files.directory, 'files.directory')
+  if (merged.files.directory.startsWith('/') || merged.files.directory.includes('..')) {
+    fail('files.directory', 'must be a relative path inside the workspace without ".."')
+  }
+  merged.files.retentionMs = expectInteger(merged.files.retentionMs, 'files.retentionMs', {
+    min: 0,
+    max: 30 * 86400000,
+  })
+
+  // tasks
+  expectObject(merged.tasks, 'tasks')
+  checkKeys(merged.tasks, 'tasks')
+  merged.tasks.ttlMs = expectInteger(merged.tasks.ttlMs, 'tasks.ttlMs', { min: 0, max: 30 * 86400000 })
+  merged.tasks.maxTasks = expectInteger(merged.tasks.maxTasks, 'tasks.maxTasks', { min: 1, max: 100000 })
+  merged.tasks.sweepIntervalMs = expectInteger(merged.tasks.sweepIntervalMs, 'tasks.sweepIntervalMs', {
+    min: 5000,
+    max: 3600000,
+  })
+
+  // push
+  expectObject(merged.push, 'push')
+  checkKeys(merged.push, 'push')
+  merged.push.allowPrivateTargets = expectBoolean(merged.push.allowPrivateTargets, 'push.allowPrivateTargets')
+  merged.push.timeoutMs = expectInteger(merged.push.timeoutMs, 'push.timeoutMs', { min: 100, max: 60000 })
+
+  // signing
+  merged.signing = validateSigning(merged.signing, 'signing')
+
+  // logging
+  expectObject(merged.logging, 'logging')
+  checkKeys(merged.logging, 'logging')
+  merged.logging.requests = expectBoolean(merged.logging.requests, 'logging.requests')
+
+  merged.enabled = expectBoolean(merged.enabled, 'enabled')
+
+  return deepFreeze(merged)
+}
+
+/**
+ * Resolve the configured bearer/API-key credentials, including environment
+ * variables. Called at mount time so a restart picks up rotated secrets.
+ *
+ * @param {Readonly<object>} config normalized configuration
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ id: string, token: string }[]}
+ */
+export function resolveCredentials(config, env = process.env) {
+  const clients = new Map()
+  for (const client of config.auth.clients) clients.set(client.id, client.token)
+  config.auth.tokens.forEach((token, index) => {
+    const id = config.auth.tokens.length === 1 ? 'default' : `token-${index + 1}`
+    if (!clients.has(id)) clients.set(id, token)
+  })
+  if (config.auth.token) {
+    if (!clients.has('default')) clients.set('default', config.auth.token)
+  }
+  if (config.auth.tokenEnv) {
+    const raw = env[config.auth.tokenEnv]
+    if (typeof raw === 'string' && raw.trim() !== '') {
+      const values = raw
+        .split(/[\n,]/)
+        .map((value) => value.trim())
+        .filter(Boolean)
+      values.forEach((token, index) => {
+        const id = values.length === 1 ? 'env' : `env-${index + 1}`
+        if (!clients.has(id)) clients.set(id, token)
+      })
+    }
+  }
+  return [...clients].map(([id, token]) => ({ id, token }))
+}