@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.6.1

package/src/cloudAdapter.ts

@@ -16,7 +16,7 @@ import { MsalConnectionManager } from './auth/msalConnectionManager'
 import { Activity, ActivityEventNames, ActivityTypes, Channels, ConversationReference, DeliveryModes, ConversationParameters, RoleTypes, ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from './errorHelper'
 import { ResourceResponse } from './connector-client/resourceResponse'
-import * as uuid from 'uuid'
+import { randomUUID } from 'crypto'
 import { debug } from '@microsoft/agents-telemetry'
 import { StatusCodes } from './statusCodes'
 import { InvokeResponse } from './invoke/invokeResponse'
@@ -28,8 +28,11 @@ import { HeaderPropagation, HeaderPropagationCollection, HeaderPropagationDefini
 import { JwtPayload } from 'jsonwebtoken'
 import { getTokenServiceEndpoint } from './oauth/customUserTokenAPI'
 import { Connections } from './auth/connections'
+import { parseBooleanEnv, suggestClosest } from './utils/env'
 import { trace } from '@microsoft/agents-telemetry'
 import { AdapterTraceDefinitions } from './observability'
+import { applyAgenticHeaders } from './getProductInfo'
+
 const logger = debug('agents:cloud-adapter')
 
 /**
@@ -41,22 +44,238 @@ const logger = debug('agents:cloud-adapter')
  * flow between agents and users across different channels, handling activities, attachments,
  * and conversation continuations.
  */
+/**
+ * Optional configuration for {@link CloudAdapter} runtime behavior.
+ *
+ * Defaults are conservative and match the .NET SDK's `AdapterOptions` defaults.
+ *
+ * Each option can also be supplied via an environment variable using the
+ * convention `CloudAdapterOptions__<propertyName>` — for example
+ * `CloudAdapterOptions__validateServiceUrl=true`. The prefix matches the
+ * .NET SDK's `IConfiguration.GetSection("CloudAdapterOptions")` section name,
+ * so a shared environment can configure both SDKs from the same variables.
+ * Both the `CloudAdapterOptions__` prefix and the property name are matched
+ * case-insensitively, so hosts that uppercase env-var names (some PaaS
+ * platforms) still work. Values supplied directly to the constructor always
+ * win over environment variables.
+ */
+export interface CloudAdapterOptions {
+  /**
+   * When `true`, the default `onTurnError` handler includes `error.stack` in
+   * its log output. Defaults to `false`.
+   *
+   * Env var: `CloudAdapterOptions__emitStackTrace`.
+   */
+  emitStackTrace?: boolean
+
+  /**
+   * When `true`, an inbound activity whose `serviceUrl` host does not match
+   * the `serviceurl` claim on the caller's identity is rejected with HTTP 400.
+   * When `false` (default for backward compatibility), the mismatch is logged
+   * as a warning but the activity is still processed.
+   *
+   * **Recommended for production.** Setting this to `true` (either directly or
+   * via `CloudAdapterOptions__validateServiceUrl=true`) defends against
+   * confused-deputy / SSRF-style attacks where an attacker with a valid token
+   * for one service URL tries to send activities targeting a different one.
+   *
+   * Env var: `CloudAdapterOptions__validateServiceUrl`.
+   */
+  validateServiceUrl?: boolean
+}
+
+const DEFAULT_CLOUD_ADAPTER_OPTIONS: Required<CloudAdapterOptions> = {
+  emitStackTrace: false,
+  validateServiceUrl: false
+}
+
+/** Env-var prefix for {@link CloudAdapterOptions} (matches .NET config section). */
+const CLOUD_ADAPTER_OPTIONS_ENV_PREFIX = 'CloudAdapterOptions__'
+const CLOUD_ADAPTER_OPTIONS_ENV_PREFIX_UPPER = CLOUD_ADAPTER_OPTIONS_ENV_PREFIX.toUpperCase()
+
+/**
+ * Declarative env-var parser for {@link CloudAdapterOptions}.
+ *
+ * Shape mirrors `envParser<K>` introduced in PR #1119
+ * (`packages/agents-hosting/src/auth/settings.ts`) so this loader can be
+ * swapped for the shared utility once that lands. Each entry is a
+ * `(rawValue) => parsedValue | undefined` function. Lookups are
+ * case-insensitive via the `upperKeys` map, matching the upstream
+ * convention and accommodating hosts that uppercase env-var names.
+ *
+ * Adding a new option to `CloudAdapterOptions` only requires adding an
+ * entry here.
+ */
+const cloudAdapterOptionsParser = (() => {
+  const schema: {
+    [K in keyof Required<CloudAdapterOptions>]: (raw: string | undefined) => CloudAdapterOptions[K]
+  } = {
+    emitStackTrace: parseBooleanEnv,
+    validateServiceUrl: parseBooleanEnv
+  }
+  const keys = Object.keys(schema) as Array<keyof CloudAdapterOptions>
+  const upperKeys = keys.reduce<Record<string, keyof CloudAdapterOptions>>((acc, key) => {
+    acc[key.toUpperCase()] = key
+    return acc
+  }, {})
+  return {
+    schema,
+    keys,
+    /**
+     * Resolves an env-var property name (case-insensitive) to its canonical
+     * `CloudAdapterOptions` key, or `undefined` when the name is unknown.
+     */
+    resolveKey (property: string): keyof CloudAdapterOptions | undefined {
+      return upperKeys[property.toUpperCase()]
+    }
+  }
+})()
+
+/**
+ * Per-process dedup set for configuration warnings. Without this, every
+ * `new CloudAdapter()` re-scans `process.env` and re-emits warnings for any
+ * typo'd `CloudAdapterOptions__*` key (or unparseable value), which spams
+ * stderr in multi-adapter scenarios (tests, proactive flows, DI containers).
+ */
+const warnedConfigKeys = new Set<string>()
+
+function emitConfigWarning (envKey: string, message: string): void {
+  if (warnedConfigKeys.has(envKey)) return
+  warnedConfigKeys.add(envKey)
+  // Visible by default (writes synchronously to stderr) so users see typos
+  // and bad values without having to opt in via `DEBUG=agents:cloud-adapter:*`.
+  // Hosts that want to route or suppress can intercept `console.warn` or
+  // subscribe to the `agents:cloud-adapter:warn` debug namespace below.
+  console.warn(`[agents:cloud-adapter] ${message}`)
+  logger.warn(message)
+}
+
+/**
+ * Scans `process.env` for keys with the `CloudAdapterOptions__` prefix
+ * (case-insensitive) and returns the parsed partial options. Unknown keys
+ * and values that fail to parse are warned about once per process via
+ * `console.warn` (so they are visible by default without enabling debug)
+ * and through the `agents:cloud-adapter:warn` debug channel for log
+ * aggregators. Hosts that want to route or suppress these diagnostics can
+ * intercept `console.warn` or filter the debug namespace.
+ */
+function loadCloudAdapterOptionsFromEnv (): CloudAdapterOptions {
+  const result: CloudAdapterOptions = {}
+  for (const [envKey, rawValue] of Object.entries(process.env)) {
+    const upper = envKey.toUpperCase()
+    if (!upper.startsWith(CLOUD_ADAPTER_OPTIONS_ENV_PREFIX_UPPER)) continue
+    const property = envKey.substring(CLOUD_ADAPTER_OPTIONS_ENV_PREFIX.length)
+    const canonical = cloudAdapterOptionsParser.resolveKey(property)
+    if (!canonical) {
+      const suggestion = suggestClosest(property, cloudAdapterOptionsParser.keys as readonly string[], 4)
+      const hint = suggestion ? ` Did you mean "${CLOUD_ADAPTER_OPTIONS_ENV_PREFIX}${suggestion}"?` : ''
+      emitConfigWarning(envKey, `Unknown CloudAdapterOptions env var: ${envKey} (ignored).${hint}`)
+      continue
+    }
+    const parsed = cloudAdapterOptionsParser.schema[canonical](rawValue) as any
+    if (parsed !== undefined) {
+      (result as any)[canonical] = parsed
+    } else if (rawValue !== undefined && rawValue.trim() !== '') {
+      // Known key, recognized but unparseable value (e.g. `yes`, `on`, `enabled`).
+      // For a security-relevant flag like `validateServiceUrl`, silent
+      // fallthrough is the dangerous failure mode — surface it.
+      // Note: parseBooleanEnv treats whitespace-only as unset, so don't warn
+      // on `'   '`; only warn when the user actually typed something.
+      emitConfigWarning(
+        `${envKey}=${rawValue}`,
+        `Ignored ${envKey}=${rawValue}; expected one of true/false/1/0.`
+      )
+    }
+  }
+  return result
+}
+
+/**
+ * Resolves a `CloudAdapterOptions` instance from an explicit argument or, if
+ * absent, from environment variables. Values supplied in the explicit object
+ * win over env vars.
+ */
+function resolveCloudAdapterOptions (options?: CloudAdapterOptions): Required<CloudAdapterOptions> {
+  const fromEnv = loadCloudAdapterOptionsFromEnv()
+  return {
+    emitStackTrace: options?.emitStackTrace ?? fromEnv.emitStackTrace ?? DEFAULT_CLOUD_ADAPTER_OPTIONS.emitStackTrace,
+    validateServiceUrl: options?.validateServiceUrl ?? fromEnv.validateServiceUrl ?? DEFAULT_CLOUD_ADAPTER_OPTIONS.validateServiceUrl
+  }
+}
+
+/**
+ * Removes CR/LF and other control characters from an attacker-controllable
+ * string before interpolating it into a log message, to prevent log forging
+ * / log injection (OWASP A09). Truncates excessively long values.
+ */
+function sanitizeForLog (value: string, max = 256): string {
+  // Strip C0 (\x00-\x1f) + DEL (\x7f) + C1 (\x80-\x9f) controls plus U+2028
+  // LINE SEPARATOR / U+2029 PARAGRAPH SEPARATOR — some log viewers and
+  // terminals treat them as line breaks, which would re-open the log-
+  // injection vector that the ASCII strip closes.
+  // eslint-disable-next-line no-control-regex
+  const cleaned = value.replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, '?')
+  return cleaned.length > max ? cleaned.slice(0, max) + '…' : cleaned
+}
+
+/**
+ * Truncates a JSON-serialized activity for log lines so a malformed or
+ * pathologically large inbound payload can't blow up the log pipeline.
+ */
+function truncateActivityForLog (activity: unknown, max = 1024): string {
+  try {
+    const json = JSON.stringify(activity)
+    if (!json) return '<unserializable>'
+    // Strip C0/DEL/C1 controls + U+2028/U+2029 from the serialized form so
+    // attacker-controlled fields (e.g. activity.text) can't forge log lines.
+    // eslint-disable-next-line no-control-regex
+    const sanitized = json.replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, '?')
+    return sanitized.length > max ? `${sanitized.slice(0, max)}…(truncated)` : sanitized
+  } catch {
+    return '<unserializable>'
+  }
+}
+
 export class CloudAdapter extends BaseAdapter {
+  protected readonly authConfig: AuthConfiguration
+  protected _agentName?: string
+
   /**
    * Client for connecting to the Azure Bot Service
    */
   connectionManager: Connections
 
+  private readonly _options: Required<CloudAdapterOptions>
+
   /**
    * Creates an instance of CloudAdapter.
    * @param authConfig - The authentication configuration for securing communications.
    * @param authProvider - No longer used.
    * @param userTokenClient - No longer used.
+   * @param options - Optional runtime behavior overrides. See {@link CloudAdapterOptions}.
    */
-  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient) {
+  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions) {
     super()
-    authConfig = getAuthConfigWithDefaults(authConfig)
+    this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig)
     this.connectionManager = new MsalConnectionManager(undefined, undefined, authConfig)
+    this._options = resolveCloudAdapterOptions(options)
+
+    // Install a CloudAdapter-aware default `onTurnError` that honors
+    // `emitStackTrace`. The base class default only logs the message; we
+    // preserve that user-facing behavior (trace + messages) but add an
+    // optional stack trace for operators when explicitly opted in.
+    this.onTurnError = async (context: TurnContext, error: Error) => {
+      const detail = this._options.emitStackTrace && error?.stack ? error.stack : `${error}`
+      logger.error(`\n [onTurnError] unhandled error: ${detail}`)
+      await context.sendTraceActivity(
+        'OnTurnError Trace',
+        `${error}`,
+        'https://www.botframework.com/schemas/error',
+        'TurnError'
+      )
+      await context.sendActivity('The agent encountered an error or bug.')
+      await context.sendActivity('To continue to run this agent, please fix the source code.')
+    }
   }
 
   /**
@@ -103,7 +322,7 @@ export class CloudAdapter extends BaseAdapter {
     headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
     return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
-      record({ serviceUrl, scope })
+      record({ serviceUrl, scopes: [scope] })
 
       // get the correct token provider
       const tokenProvider = this.connectionManager.getTokenProvider(identity, serviceUrl)
@@ -144,7 +363,7 @@ export class CloudAdapter extends BaseAdapter {
       let connectorClient
       const tokenProvider = this.connectionManager.getTokenProviderFromActivity(identity, activity)
       const isAgentic = activity.isAgenticRequest()
-      let scope
+      const scopes: string[] = []
       if (isAgentic) {
         logger.debug('Activity is from an agentic source, using special scope', activity.recipient)
         const agenticInstanceId = activity.getAgenticInstanceId()
@@ -159,8 +378,13 @@ export class CloudAdapter extends BaseAdapter {
             headers
           )
         } else if (activity.recipient?.role?.toLowerCase() === RoleTypes.AgenticUser.toLowerCase() && agenticInstanceId && agenticUserId) {
-          scope = tokenProvider.connectionSettings?.scope ?? ApxProductionScope
-          const token = await tokenProvider.getAgenticUserToken(activity.getAgenticTenantId() ?? '', agenticInstanceId, agenticUserId, [scope])
+          const configuredScopes = tokenProvider.connectionSettings?.scopes
+          if (configuredScopes?.length) {
+            scopes.push(...configuredScopes)
+          } else {
+            scopes.push(tokenProvider.connectionSettings?.scope ?? ApxProductionScope)
+          }
+          const token = await tokenProvider.getAgenticUserToken(activity.getAgenticTenantId() ?? '', agenticInstanceId, agenticUserId, scopes)
 
           connectorClient = ConnectorClient.createClientWithToken(
             activity.serviceUrl!,
@@ -173,8 +397,8 @@ export class CloudAdapter extends BaseAdapter {
       } else {
         // ABS tokens will not have an azp/appid so use the botframework scope.
         // Otherwise use the appId.  This will happen when communicating back to another agent.
-        scope = identity.azp ?? identity.appid ?? 'https://api.botframework.com'
-        const token = await tokenProvider.getAccessToken(scope)
+        scopes.push(identity.azp ?? identity.appid ?? 'https://api.botframework.com')
+        const token = await tokenProvider.getAccessToken(scopes[0])
         connectorClient = ConnectorClient.createClientWithToken(
           activity.serviceUrl!,
           token,
@@ -183,7 +407,7 @@ export class CloudAdapter extends BaseAdapter {
       }
       record({
         serviceUrl: activity.serviceUrl,
-        scope,
+        scopes,
         activityIsAgentic: isAgentic
       })
       return connectorClient
@@ -201,6 +425,14 @@ export class CloudAdapter extends BaseAdapter {
     } as JwtPayload
   }
 
+  /**
+   * Sets the agent name for M365 agent header propagation.
+   * @param agentName The human-friendly agent name to set for header propagation.
+   */
+  public setAgentName (agentName?: string): void {
+    this._agentName = agentName
+  }
+
   /**
    * Sets the connector client on the turn context.
    *
@@ -355,7 +587,7 @@ export class CloudAdapter extends BaseAdapter {
       const headers = new HeaderPropagation(request.headers)
       if (headerPropagation && typeof headerPropagation === 'function') {
         headerPropagation(headers)
-        logger.debug('Headers to propagate: ', headers)
+        logger.debug('Headers to propagate: ', { keys: Object.keys(headers.outgoing) })
       }
 
       const end = (status: StatusCodes, body?: unknown, isInvokeResponseOrExpectReplies: boolean = false) => {
@@ -388,11 +620,20 @@ export class CloudAdapter extends BaseAdapter {
       record({ activity })
 
       if (!this.isValidChannelActivity(activity)) {
+        logger.warn(`BadRequest: invalid activity body: ${truncateActivityForLog(activity)}`)
+        return end(StatusCodes.BAD_REQUEST)
+      }
+
+      if (!this.validateServiceUrl(request.user, activity)) {
         return end(StatusCodes.BAD_REQUEST)
       }
 
       logger.debug('Received activity: ', activity)
 
+      if (isAgentic) {
+        applyAgenticHeaders(headers, activity, this._agentName)
+      }
+
       const context = new TurnContext(this, activity, request.user!)
       // if Delivery Mode == ExpectReplies, we don't need a connector client.
       if (this.resolveIfConnectorClientIsNeeded(activity)) {
@@ -441,6 +682,41 @@ export class CloudAdapter extends BaseAdapter {
     return true
   }
 
+  /**
+   * Compares the host of `activity.serviceUrl` against the `serviceurl` claim
+   * on the caller's identity. When enabled and the hosts differ (or either
+   * URL is malformed), the request is rejected with HTTP 400; when disabled,
+   * the mismatch is logged as a warning.
+   *
+   * @returns `true` if the activity should continue processing; `false` if it
+   * should be rejected with a 400.
+   */
+  private validateServiceUrl (identity: JwtPayload | undefined, activity: Activity): boolean {
+    if (!identity) return true
+    if (!activity.serviceUrl) return true
+
+    const claimValue = identity.serviceurl
+    if (typeof claimValue !== 'string') return true
+
+    let claimHost: string | undefined
+    let activityHost: string | undefined
+    try { claimHost = new URL(claimValue).hostname.toLowerCase() } catch { /* invalid */ }
+    try { activityHost = new URL(activity.serviceUrl).hostname.toLowerCase() } catch { /* invalid */ }
+
+    if (claimHost && activityHost && claimHost === activityHost) {
+      return true
+    }
+
+    const safeClaim = sanitizeForLog(claimValue)
+    const safeServiceUrl = sanitizeForLog(activity.serviceUrl)
+    if (this._options.validateServiceUrl) {
+      logger.error(`Invalid service URL Claim='${safeClaim}', ServiceUrl='${safeServiceUrl}'`)
+      return false
+    }
+    logger.warn(`Invalid service URL Claim='${safeClaim}', ServiceUrl='${safeServiceUrl}'`)
+    return true
+  }
+
   /**
    * Updates an activity.
    * @param context - The TurnContext for the current turn.
@@ -599,7 +875,7 @@ export class CloudAdapter extends BaseAdapter {
     activity.name = ActivityEventNames.CreateConversation
     activity.channelId = channelId
     activity.serviceUrl = serviceUrl
-    activity.id = createdConversationId ?? uuid.v4()
+    activity.id = createdConversationId ?? randomUUID()
     activity.conversation = {
       conversationType: undefined,
       id: createdConversationId!,
@@ -609,6 +885,9 @@ export class CloudAdapter extends BaseAdapter {
     }
     activity.channelData = conversationParameters.channelData
     activity.recipient = conversationParameters.agent
+    // For 1:1 conversations members[0] is the target user; for channel conversations
+    // (where members is absent) we fall back to the agent so from.id is always present.
+    activity.from = conversationParameters.members?.[0] ?? conversationParameters.agent
 
     return activity
   }