@microsoft/agents-hosting 1.7.0-beta.1.g8bcd4f11a7 → 1.7.1

package/src/auth/jwt-middleware.ts

@@ -4,8 +4,10 @@
  */
 
 import { AuthConfiguration, resolveAuthority } from './authConfiguration'
-import { Response, NextFunction } from 'express'
 import { Request } from './request'
+import { WebResponse, NextFunction } from '../interfaces/webResponse'
+import { Errors } from '../errorHelper'
+import { ExceptionHelper } from '@microsoft/agents-activity'
 import jwksRsa, { JwksClient, SigningKey } from 'jwks-rsa'
 import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from 'jsonwebtoken'
 import { debug } from '@microsoft/agents-telemetry'
@@ -64,7 +66,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
   logger.debug('jwt.decode ', JSON.stringify(payload))
 
   if (!payload) {
-    throw new Error('invalid token')
+    throw ExceptionHelper.generateException(Error, Errors.InvalidJwtToken)
   }
   const audience = payload.aud
 
@@ -73,7 +75,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     : undefined
 
   if (!matchingEntry) {
-    const err = new Error('Audience mismatch')
+    const err = ExceptionHelper.generateException(Error, Errors.JwtAudienceMismatch)
     logger.error(err.message, audience)
     throw err
   }
@@ -119,13 +121,78 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
   })
 }
 
+/**
+ * Determines whether an `Authorization` header value is present (non-empty).
+ *
+ * The {@link Request} contract allows `string | string[] | undefined` because
+ * different web frameworks surface headers differently. This treats an empty
+ * string or empty array as "absent" so callers can distinguish a missing header
+ * (anonymous / 401) from a present-but-malformed one (always 401).
+ * @param authorization The raw `Authorization` header value.
+ * @returns `true` when a non-empty header value is present.
+ */
+function hasAuthorizationHeader (authorization: string | string[] | undefined): boolean {
+  if (Array.isArray(authorization)) {
+    return authorization.some((value) => typeof value === 'string' && value.trim().length > 0)
+  }
+  return typeof authorization === 'string' && authorization.trim().length > 0
+}
+
+/**
+ * Parses a single `Authorization` header value and returns its bearer token.
+ *
+ * Validates the `Bearer <token>` scheme, returning `undefined` for anything
+ * malformed (wrong scheme, missing token, or extra whitespace-delimited parts).
+ * @param headerValue A single `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the value is absent or malformed.
+ */
+function parseBearerValue (headerValue: string | undefined): string | undefined {
+  if (typeof headerValue !== 'string') {
+    return undefined
+  }
+  const parts = headerValue.trim().split(/\s+/)
+  if (parts.length !== 2) {
+    return undefined
+  }
+  const [scheme, token] = parts
+  if (scheme.toLowerCase() !== 'bearer' || !token) {
+    return undefined
+  }
+  return token
+}
+
+/**
+ * Extracts the bearer token from a raw `Authorization` header value.
+ *
+ * On Node's core HTTP parser (which both Express and Fastify use) `Authorization`
+ * is always surfaced as a single string holding the *first* header line —
+ * duplicate `Authorization` headers are discarded, not comma-joined. The
+ * `string[]` case is handled only because the {@link Request} contract permits
+ * it for non-Node frameworks; when an array is supplied, every entry is inspected
+ * and the first valid `Bearer <token>` is returned (the bearer value is not
+ * assumed to be first). Returns `undefined` for anything malformed so the caller
+ * can emit a consistent 401 instead of throwing.
+ * @param authorization The raw `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the header is absent or malformed.
+ */
+function extractBearerToken (authorization: string | string[] | undefined): string | undefined {
+  const values = Array.isArray(authorization) ? authorization : [authorization]
+  for (const value of values) {
+    const token = parseBearerValue(value)
+    if (token) {
+      return token
+    }
+  }
+  return undefined
+}
+
 /**
  * Middleware to authorize JWT tokens.
  * @param authConfig The authentication configuration.
  * @returns An Express middleware function.
  */
 export const authorizeJWT = (authConfig: AuthConfiguration) => {
-  return async function (req: Request, res: Response, next: NextFunction) {
+  return async function (req: Request, res: WebResponse, next: NextFunction) {
     let failed = false
     logger.debug('authorizing jwt')
     if (req.method !== 'POST' && req.method !== 'GET') {
@@ -133,9 +200,8 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
       logger.warn('Method not allowed', req.method)
       res.status(405).send({ 'jwt-auth-error': 'Method not allowed' })
     } else {
-      const authHeader = req.headers.authorization as string
-      if (authHeader) {
-        const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
+      const token = extractBearerToken(req.headers.authorization)
+      if (token) {
         try {
           const user = await verifyToken(token, authConfig)
           logger.debug('token verified for ', user)
@@ -143,8 +209,21 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
         } catch (err: Error | any) {
           failed = true
           logger.error(err)
-          res.status(401).send({ 'jwt-auth-error': err.message })
+          // Emit only the human-readable description rather than the
+          // ExceptionHelper-formatted "[code] - description - helplink" string,
+          // so the wire format does not leak internal error codes or help links.
+          // Fall back to a stable string so a thrown non-Error (no description/
+          // message) never serializes to an empty `{}` and drops the detail.
+          const wireMessage: string = err?.description ?? err?.message ?? 'unauthorized'
+          res.status(401).send({ 'jwt-auth-error': wireMessage })
         }
+      } else if (hasAuthorizationHeader(req.headers.authorization)) {
+        // Header is present but not a well-formed `Bearer <token>` (e.g. wrong
+        // scheme, missing token, or an array value). Respond with a consistent
+        // 401 rather than letting malformed input throw before authorization.
+        failed = true
+        logger.warn('malformed authorization header')
+        res.status(401).send({ 'jwt-auth-error': 'invalid authorization header' })
       } else {
         if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
           logger.info('using anonymous auth')

package/src/auth/msal/msalTokenProvider.ts

@@ -284,7 +284,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (typeof authConfigOrScope === 'string') {
       // Called as getAccessToken(scope)
         if (!this.connectionSettings) {
-          throw new Error('Connection settings must be provided to constructor when calling getAccessToken(scope)')
+          throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAccessTokenScope)
         }
         authConfig = this.connectionSettings
         actualScope = authConfigOrScope
@@ -378,7 +378,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (Array.isArray(authConfigOrScopes)) {
       // Called as acquireTokenOnBehalfOf(scopes, oboAssertion)
         if (!this.connectionSettings) {
-          throw new Error('Connection settings must be provided to constructor when calling acquireTokenOnBehalfOf(scopes, oboAssertion)')
+          throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForAcquireTokenOnBehalfOf)
         }
         authConfig = this.connectionSettings
         actualScopes = authConfigOrScopes
@@ -399,7 +399,7 @@ export class MsalTokenProvider implements AuthProvider {
         scopes: actualScopes
       })
       if (!token?.accessToken) {
-        throw new Error('Failed to acquire token on behalf of user')
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenOnBehalfOf)
       }
 
       return token.accessToken
@@ -412,7 +412,7 @@ export class MsalTokenProvider implements AuthProvider {
       record({ agenticInstanceId: agentAppInstanceId })
 
       if (!this.connectionSettings) {
-        throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+        throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticInstanceToken)
       }
 
       const instanceTokenCacheKey = MsalTokenProvider.cacheKey(
@@ -444,7 +444,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
 
       if (!token?.accessToken) {
-        throw new Error(`Failed to acquire instance token for agent instance: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForAgentInstance, undefined, { agentAppInstanceId })
       }
 
       this.cacheAgenticAuthenticationResult(instanceTokenCacheKey, token)
@@ -494,7 +494,7 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireTokenForAgenticScenarios (tenantId: string, clientId: string, clientAssertion: string | undefined, scopes: string[], tokenBodyParameters: { [key: string]: any }): Promise<string | null> {
     if (!this.connectionSettings) {
-      throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticInstanceToken)
     }
 
     logger.debug('acquireTokenForAgenticScenarios clientId=%s tenantId=%s scopes=%o grant_type=%s', clientId, tenantId, scopes, tokenBodyParameters.grant_type)
@@ -585,7 +585,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
 
       if (!token) {
-        throw new Error(`Failed to acquire instance token for user token: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForUserToken, undefined, { agentAppInstanceId })
       }
 
       return token
@@ -594,7 +594,7 @@ export class MsalTokenProvider implements AuthProvider {
 
   public async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     if (!this.connectionSettings?.clientId) {
-      throw new Error('Connection settings must be provided when calling getAgenticApplicationToken')
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticApplicationToken)
     }
     logger.debug('getAgenticApplicationToken clientId=%s tenantId=%s agentAppInstanceId=%s', this.connectionSettings.clientId, tenantId, agentAppInstanceId)
 
@@ -605,7 +605,7 @@ export class MsalTokenProvider implements AuthProvider {
       if (!this.connectionSettings.idpmResource) {
         resource = 'api://AzureAdTokenExchange/.default'
       } else if (!URL.canParse(this.connectionSettings.idpmResource)) {
-        throw new Error('idpmResource must be a valid absolute URI')
+        throw ExceptionHelper.generateException(Error, Errors.IdpmResourceAbsoluteUriRequired)
       } else {
         resource = this.connectionSettings.idpmResource
       }
@@ -617,7 +617,7 @@ export class MsalTokenProvider implements AuthProvider {
       })
       const tokenResult = await msiApp.acquireToken({ resource })
       if (!tokenResult?.accessToken) {
-        throw new Error(`Failed to acquire token via IdentityProxyManager for agent instance: ${agentAppInstanceId}`)
+        throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenViaIdentityProxyManagerForAgentInstance, undefined, { agentAppInstanceId })
       }
       logger.debug('getAgenticApplicationToken via IdentityProxyManager clientId=%s resource=%s', this.connectionSettings.clientId, resource)
       return tokenResult.accessToken
@@ -655,7 +655,7 @@ export class MsalTokenProvider implements AuthProvider {
     })
 
     if (!token) {
-      throw new Error(`Failed to acquire token for agent instance: ${agentAppInstanceId}`)
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireInstanceTokenForAgentInstance, undefined, { agentAppInstanceId })
     }
 
     return token
@@ -780,7 +780,7 @@ export class MsalTokenProvider implements AuthProvider {
       azureRegion: authConfig.azureRegion
     })
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using certificate')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingCertificate)
     }
     return token.accessToken
   }
@@ -799,7 +799,7 @@ export class MsalTokenProvider implements AuthProvider {
       azureRegion: authConfig.azureRegion
     })
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using client secret')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingClientSecret)
     }
     return token.accessToken
   }
@@ -824,7 +824,7 @@ export class MsalTokenProvider implements AuthProvider {
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using FIC client assertion')
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using FIC client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingFICClientAssertion)
     }
     return token.accessToken
   }
@@ -850,7 +850,7 @@ export class MsalTokenProvider implements AuthProvider {
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using WID client assertion')
     if (!token?.accessToken) {
-      throw new Error('Failed to acquire token using WID client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireTokenUsingWIDClientAssertion)
     }
     return token.accessToken
   }
@@ -874,7 +874,7 @@ export class MsalTokenProvider implements AuthProvider {
     })
     logger.debug('got token for FIC')
     if (!response?.accessToken) {
-      throw new Error('Failed to acquire external token for FIC client assertion')
+      throw ExceptionHelper.generateException(Error, Errors.FailedToAcquireExternalTokenForFICClientAssertion)
     }
     return response.accessToken
   }

package/src/baseAdapter.ts

@@ -6,11 +6,12 @@
 import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet'
 import { TurnContext } from './turnContext'
 import { debug } from '@microsoft/agents-telemetry'
-import { Activity, ConversationReference } from '@microsoft/agents-activity'
+import { Activity, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import { AttachmentData } from './connector-client/attachmentData'
 import { AttachmentInfo } from './connector-client/attachmentInfo'
 import { JwtPayload } from 'jsonwebtoken'
+import { Errors } from './errorHelper'
 
 const logger = debug('agents:base-adapter')
 
@@ -202,7 +203,7 @@ export abstract class BaseAdapter {
         if (err instanceof Error) {
           await this.onTurnError(pContext.proxy, err)
         } else {
-          throw new Error('Unknown error type: ' + err.message)
+          throw ExceptionHelper.generateException(Error, Errors.UnknownErrorType, undefined, { errorMessage: err.message })
         }
       } else {
         throw err

package/src/cloudAdapter.ts

@@ -6,8 +6,8 @@
 import { AgentHandler, INVOKE_RESPONSE_KEY } from './activityHandler'
 import { BaseAdapter } from './baseAdapter'
 import { TurnContext } from './turnContext'
-import { Response } from 'express'
 import { Request } from './auth/request'
+import { WebResponse } from './interfaces/webResponse'
 import { ConnectorClient } from './connector-client/connectorClient'
 import { AuthConfiguration, getAuthConfigWithDefaults } from './auth/authConfiguration'
 import { AuthProvider } from './auth/authProvider'
@@ -289,7 +289,7 @@ export class CloudAdapter extends BaseAdapter {
    */
   protected resolveIfConnectorClientIsNeeded (activity: Activity): boolean {
     if (!activity) {
-      throw new TypeError('`activity` parameter required')
+      throw ExceptionHelper.generateException(TypeError, Errors.ActivityParameterRequired)
     }
 
     switch (activity.deliveryMode) {
@@ -392,7 +392,7 @@ export class CloudAdapter extends BaseAdapter {
             headers
           )
         } else {
-          throw new Error('Could not create connector client for agentic user')
+          throw ExceptionHelper.generateException(Error, Errors.CannotCreateConnectorClientForAgenticUser)
         }
       } else {
         // ABS tokens will not have an azp/appid so use the botframework scope.
@@ -580,7 +580,7 @@ export class CloudAdapter extends BaseAdapter {
    */
   public async process (
     request: Request,
-    res: Response,
+    res: WebResponse,
     logic: (context: TurnContext) => Promise<void>,
     headerPropagation?: HeaderPropagationDefinition): Promise<void> {
     return trace(AdapterTraceDefinitions.process, async ({ record }) => {
@@ -609,7 +609,7 @@ export class CloudAdapter extends BaseAdapter {
         res.end()
       }
       if (!request.body) {
-        throw new TypeError('`request.body` parameter required, make sure express.json() is used as middleware')
+        throw ExceptionHelper.generateException(TypeError, Errors.MissingRequestBody)
       }
       const incoming = normalizeIncomingActivity(request.body!)
       const activity = Activity.fromObject(incoming)
@@ -726,11 +726,11 @@ export class CloudAdapter extends BaseAdapter {
   async updateActivity (context: TurnContext, activity: Activity): Promise<ResourceResponse | void> {
     return trace(AdapterTraceDefinitions.updateActivity, async ({ record }) => {
       if (!context) {
-        throw new TypeError('`context` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
       }
 
       if (!activity) {
-        throw new TypeError('`activity` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ActivityParameterRequired)
       }
 
       record({ activity })
@@ -758,7 +758,7 @@ export class CloudAdapter extends BaseAdapter {
   async deleteActivity (context: TurnContext, reference: Partial<ConversationReference>): Promise<void> {
     return trace(AdapterTraceDefinitions.deleteActivity, async ({ record }) => {
       if (!context) {
-        throw new TypeError('`context` parameter required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContextParameterRequired)
       }
 
       if (!reference || !reference.serviceUrl || (reference.conversation == null) || !reference.conversation.id || !reference.activityId) {
@@ -791,7 +791,7 @@ export class CloudAdapter extends BaseAdapter {
       }
 
       if (!botAppIdOrIdentity) {
-        throw new TypeError('continueConversation: botAppIdOrIdentity is required')
+        throw ExceptionHelper.generateException(TypeError, Errors.ContinueConversationBotAppIdOrIdentityRequired)
       }
       const botAppId = typeof botAppIdOrIdentity === 'string' ? botAppIdOrIdentity : botAppIdOrIdentity.aud as string
 
@@ -911,10 +911,10 @@ export class CloudAdapter extends BaseAdapter {
     logic: (context: TurnContext) => Promise<void>
   ): Promise<void> {
     if (typeof serviceUrl !== 'string' || !serviceUrl) {
-      throw new TypeError('`serviceUrl` must be a non-empty string')
+      throw ExceptionHelper.generateException(TypeError, Errors.ServiceUrlRequired)
     }
-    if (!conversationParameters) throw new TypeError('`conversationParameters` must be defined')
-    if (!logic) throw new TypeError('`logic` must be defined')
+    if (!conversationParameters) throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
+    if (!logic) throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
 
     const identity = CloudAdapter.createIdentity(audience)
     const restClient = await this.createConnectorClient(serviceUrl, audience, identity)

package/src/createCloudAdapter.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActivityHandler } from './activityHandler'
+import { AgentApplication } from './app/agentApplication'
+import { AuthConfiguration } from './auth/authConfiguration'
+import { CloudAdapter } from './cloudAdapter'
+import { HeaderPropagationDefinition } from './headerPropagation'
+import { TurnState } from './app/turnState'
+
+/**
+ * Result of creating a CloudAdapter from an agent.
+ */
+export interface CloudAdapterResult {
+  adapter: CloudAdapter
+  headerPropagation: HeaderPropagationDefinition | undefined
+}
+
+/**
+ * Creates a CloudAdapter for the given agent.
+ *
+ * If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused.
+ * Otherwise, a new CloudAdapter is created.
+ *
+ * @param agent - The AgentApplication or ActivityHandler instance.
+ * @param authConfig - Optional auth configuration used when creating a new CloudAdapter.
+ * If the agent already has an adapter, that adapter is reused and this value is ignored.
+ * @returns An object containing the CloudAdapter and optional header propagation configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AgentApplication, TurnState, createCloudAdapter } from '@microsoft/agents-hosting';
+ *
+ * const app = new AgentApplication<TurnState>();
+ * const { adapter, headerPropagation } = createCloudAdapter(app, { clientId: process.env.CLIENT_ID });
+ *
+ * // Use the adapter directly with request/response objects compatible with CloudAdapter.process
+ * adapter.process(req, res, (context) => app.run(context), headerPropagation);
+ * ```
+ */
+export const createCloudAdapter = (
+  agent: AgentApplication<TurnState<any, any>> | ActivityHandler,
+  authConfig?: AuthConfiguration
+): CloudAdapterResult => {
+  if (agent instanceof ActivityHandler) {
+    return { adapter: new CloudAdapter(authConfig), headerPropagation: undefined }
+  }
+
+  // AgentApplication: reuse its pre-configured adapter when present, otherwise create one.
+  // headerPropagation is an application-level option, so read it regardless of adapter source.
+  const headerPropagation = agent.options?.headerPropagation
+  const adapter = agent.adapter ?? new CloudAdapter(authConfig)
+  return { adapter, headerPropagation }
+}