@microsoft/agents-hosting 1.10.0-beta.8.g158a2c07ad → 1.10.1

package/dist/src/utils/ipAddress.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrivateOrLoopbackAddress = isPrivateOrLoopbackAddress;
+exports.isBlockedOutboundAddress = isBlockedOutboundAddress;
+const node_net_1 = require("node:net");
+function normalizeAddress(address) {
+    const unwrapped = address.startsWith('[') && address.endsWith(']') ? address.slice(1, -1) : address;
+    const version = (0, node_net_1.isIP)(unwrapped);
+    if (version === 0) {
+        return undefined;
+    }
+    return version === 6 ? new URL(`http://[${unwrapped}]`).hostname.slice(1, -1) : unwrapped;
+}
+function mappedIPv4(address) {
+    const match = address.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (!match) {
+        return undefined;
+    }
+    const high = parseInt(match[1], 16);
+    const low = parseInt(match[2], 16);
+    return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
+}
+function isPrivateOrLoopbackAddress(address) {
+    var _a;
+    const normalized = normalizeAddress(address);
+    if (!normalized) {
+        return false;
+    }
+    const ipv4 = (_a = mappedIPv4(normalized)) !== null && _a !== void 0 ? _a : normalized;
+    if ((0, node_net_1.isIP)(ipv4) === 4) {
+        const bytes = ipv4.split('.').map(Number);
+        return bytes[0] === 127 ||
+            bytes[0] === 10 ||
+            (bytes[0] === 172 && bytes[1] >= 16 && bytes[1] <= 31) ||
+            (bytes[0] === 192 && bytes[1] === 168) ||
+            (bytes[0] === 169 && bytes[1] === 254);
+    }
+    if (normalized === '::1') {
+        return true;
+    }
+    const firstHextet = parseInt(normalized.split(':')[0], 16);
+    return (firstHextet & 0xfe00) === 0xfc00 ||
+        (firstHextet & 0xffc0) === 0xfe80 ||
+        (firstHextet & 0xffc0) === 0xfec0;
+}
+function isBlockedOutboundAddress(address) {
+    var _a;
+    const normalized = normalizeAddress(address);
+    if (!normalized) {
+        return true;
+    }
+    const ipv4 = (_a = mappedIPv4(normalized)) !== null && _a !== void 0 ? _a : normalized;
+    const [first, second] = ipv4.split('.').map(Number);
+    // RFC 6598 shared space is outbound-only; it must not become trusted sidecar space.
+    return normalized === '::' ||
+        ipv4 === '0.0.0.0' ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        isPrivateOrLoopbackAddress(normalized);
+}
+//# sourceMappingURL=ipAddress.js.map

package/dist/src/utils/ipAddress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipAddress.js","sourceRoot":"","sources":["../../../src/utils/ipAddress.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;AAEH,uCAA+B;AAE/B,SAAS,gBAAgB,CAAE,OAAe;IACxC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IACnG,MAAM,OAAO,GAAG,IAAA,eAAI,EAAC,SAAS,CAAC,CAAA;IAC/B,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,WAAW,SAAS,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC3F,CAAC;AAED,SAAS,UAAU,CAAE,OAAe;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAA;IACvE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACnC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAClC,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,IAAI,EAAE,CAAA;AAChE,CAAC;AAED,oCAA4C,OAAe;;IACzD,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,IAAI,SAAG,UAAU,CAAC,UAAU,CAAC,mCAAI,UAAU,CAAA;IACjD,IAAI,IAAA,eAAI,EAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACzC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG;YACrB,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE;YACf,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACtD,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;YACtC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAA;IAC1C,CAAC;IAED,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC1D,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,MAAM;QACtC,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,MAAM;QACjC,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,MAAM,CAAA;AACrC,CAAC;AAED,kCAA0C,OAAe;;IACvD,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,IAAI,SAAG,UAAU,CAAC,UAAU,CAAC,mCAAI,UAAU,CAAA;IACjD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACnD,oFAAoF;IACpF,OAAO,UAAU,KAAK,IAAI;QACxB,IAAI,KAAK,SAAS;QAClB,CAAC,KAAK,KAAK,GAAG,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,IAAI,GAAG,CAAC;QAChD,0BAA0B,CAAC,UAAU,CAAC,CAAA;AAC1C,CAAC"}

package/dist/src/utils/outboundUrl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export declare function getHttpsUrl(input: string | URL | null | undefined): URL | undefined;
+export declare function isLocalOrBlockedHost(host: string): boolean;
+export declare function hasAllowedOutboundAddresses(url: URL, allowPrivateNetworkAddresses?: boolean): Promise<boolean>;

package/dist/src/utils/outboundUrl.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHttpsUrl = getHttpsUrl;
+exports.isLocalOrBlockedHost = isLocalOrBlockedHost;
+exports.hasAllowedOutboundAddresses = hasAllowedOutboundAddresses;
+const node_dns_1 = require("node:dns");
+const node_net_1 = require("node:net");
+const agents_telemetry_1 = require("@microsoft/agents-telemetry");
+const ipAddress_1 = require("./ipAddress");
+const logger = (0, agents_telemetry_1.debug)('agents:outboundHostValidator');
+function getHttpsUrl(input) {
+    if (!input) {
+        return undefined;
+    }
+    try {
+        const url = input instanceof URL ? input : new URL(input);
+        return url.protocol === 'https:' && !url.username && !url.password ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLocalOrBlockedHost(host) {
+    const unwrapped = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    return host === 'localhost' || host.endsWith('.localhost') ||
+        ((0, node_net_1.isIP)(unwrapped) !== 0 && (0, ipAddress_1.isBlockedOutboundAddress)(unwrapped));
+}
+async function hasAllowedOutboundAddresses(url, allowPrivateNetworkAddresses = false) {
+    if (allowPrivateNetworkAddresses) {
+        return true;
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if (isLocalOrBlockedHost(host)) {
+        return false;
+    }
+    if ((0, node_net_1.isIP)(host) !== 0) {
+        return true;
+    }
+    try {
+        const addresses = await node_dns_1.promises.lookup(host, { all: true });
+        return addresses.length > 0 && addresses.every(({ address }) => !(0, ipAddress_1.isBlockedOutboundAddress)(address));
+    }
+    catch {
+        logger.warn(`Attachment destination DNS lookup failed. Host='${host}'`);
+        return false;
+    }
+}
+//# sourceMappingURL=outboundUrl.js.map

package/dist/src/utils/outboundUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundUrl.js","sourceRoot":"","sources":["../../../src/utils/outboundUrl.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAEH,uCAA0C;AAC1C,uCAA+B;AAC/B,kEAAmD;AACnD,2CAAsD;AAEtD,MAAM,MAAM,GAAG,IAAA,wBAAK,EAAC,8BAA8B,CAAC,CAAA;AAEpD,qBAA6B,KAAsC;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;QACzD,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAA;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,8BAAsC,IAAY;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACvF,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QACxD,CAAC,IAAA,eAAI,EAAC,SAAS,CAAC,KAAK,CAAC,IAAI,IAAA,oCAAwB,EAAC,SAAS,CAAC,CAAC,CAAA;AAClE,CAAC;AAEM,KAAK,sCAAuC,GAAQ,EAAE,4BAA4B,GAAG,KAAK;IAC/F,IAAI,4BAA4B,EAAE,CAAC;QACjC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACpE,IAAI,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,IAAA,eAAI,EAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,mBAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;QACvD,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,IAAA,oCAAwB,EAAC,OAAO,CAAC,CAAC,CAAA;IACrG,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,IAAI,CAAC,mDAAmD,IAAI,GAAG,CAAC,CAAA;QACvE,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/src/utils.js

@@ -18,8 +18,9 @@ exports.prune = prune;
 const mergeDefined = (...layers) => {
     const result = {};
     for (const layer of layers) {
-        if (layer)
+        if (layer) {
             Object.assign(result, (0, exports.prune)(layer));
+        }
     }
     return result;
 };

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;GAIG;AACI,MAAM,KAAK,GAAG,CAAgC,GAAM,EAAE,EAAE;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAA;IAC9E,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAM,CAAA;AACzC,CAAC,CAAA;AAHY,QAAA,KAAK,GAAL,KAAK,CAGjB;AAEM,MAAM,YAAY,GAAG,CAC1B,GAAG,MAA2C,EAC3C,EAAE;IACL,MAAM,MAAM,GAAe,EAAE,CAAA;IAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAA,QAAA,KAAK,EAAC,KAAK,CAAC,CAAC,CAAA;IAChD,CAAC;IACD,OAAO,MAAW,CAAA;AACpB,CAAC,CAAA;AARY,QAAA,YAAY,GAAZ,YAAY,CAQxB"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;GAIG;AACI,MAAM,KAAK,GAAG,CAAgC,GAAM,EAAE,EAAE;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAA;IAC9E,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAM,CAAA;AACzC,CAAC,CAAA;AAHY,QAAA,KAAK,GAAL,KAAK,CAGjB;AAEM,MAAM,YAAY,GAAG,CAC1B,GAAG,MAA2C,EAC3C,EAAE;IACL,MAAM,MAAM,GAAe,EAAE,CAAA;IAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAA,QAAA,KAAK,EAAC,KAAK,CAAC,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IACD,OAAO,MAAW,CAAA;AACpB,CAAC,CAAA;AAVY,QAAA,YAAY,GAAZ,YAAY,CAUxB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting",
-  "version": "1.10.0-beta.8.g158a2c07ad",
+  "version": "1.10.1",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   "dependencies": {
     "@azure/core-auth": "1.10.1",
     "@azure/msal-node": "5.6.0",
-    "@microsoft/agents-activity": "1.10.0-beta.8.g158a2c07ad",
-    "@microsoft/agents-telemetry": "1.10.0-beta.8.g158a2c07ad",
+    "@microsoft/agents-activity": "1.10.1",
+    "@microsoft/agents-telemetry": "1.10.1",
     "jsonwebtoken": "9.0.3",
     "jwks-rsa": "4.0.1",
     "zod": "3.25.75"

package/src/activityHandler.ts

@@ -255,9 +255,15 @@ export class ActivityHandler {
    * @throws Error if context is missing, activity is missing, or activity type is missing
    */
   async run (context: TurnContext): Promise<void> {
-    if (!context) throw ExceptionHelper.generateException(Error, Errors.MissingTurnContext)
-    if (!context.activity) throw ExceptionHelper.generateException(Error, Errors.TurnContextMissingActivity)
-    if (!context.activity.type) throw ExceptionHelper.generateException(Error, Errors.ActivityMissingType)
+    if (!context) {
+      throw ExceptionHelper.generateException(Error, Errors.MissingTurnContext)
+    }
+    if (!context.activity) {
+      throw ExceptionHelper.generateException(Error, Errors.TurnContextMissingActivity)
+    }
+    if (!context.activity.type) {
+      throw ExceptionHelper.generateException(Error, Errors.ActivityMissingType)
+    }
 
     await this.handle(context, 'Turn', async () => {
       await this.onTurnActivity(context)

package/src/agent-client/agentResponseHandler.ts

@@ -24,6 +24,13 @@ import { AGENT_RESPONSE_ROUTE_PATH, createAgentResponseHandler } from './createA
  * `post(path, handler)` method structurally matches satisfies it.
  */
 export interface WebApp {
+  /**
+   * Registers a handler for HTTP POST requests at the specified path.
+   *
+   * @param path - Route path to register.
+   * @param handler - Request handler invoked for matching requests.
+   * @returns A framework-specific registration result.
+   */
   post (
     path: string,
     handler: (req: any, res: any) => unknown | Promise<unknown>

package/src/agent-client/createAgentResponseHandler.ts

@@ -33,7 +33,9 @@ interface DelegatedConversationState {
  * the framework's URL path parser.
  */
 export interface AgentResponseHandlerParams {
+  /** ID of the conversation receiving the callback activity. */
   conversationId: string
+  /** ID to assign to the callback activity. */
   activityId: string
 }
 

package/src/app/adaptiveCards/adaptiveCardsActions.ts

@@ -13,6 +13,7 @@ import { AdaptiveCard } from '../../cards/adaptiveCard'
 import { Query } from './query'
 import { Errors } from '../../errorHelper'
 
+/** Invoke activity name used for Adaptive Card actions. */
 export const ACTION_INVOKE_NAME = 'adaptiveCard/action'
 const ACTION_EXECUTE_TYPE = 'Action.Execute'
 const DEFAULT_ACTION_SUBMIT_FILTER = 'verb'

package/src/app/attachmentDownloadHttpClient.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-telemetry'
+import { Errors } from '../errorHelper'
+import { HttpClient, HttpError, HttpResponse } from '../httpClient'
+import { OutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
+import { getHttpsUrl, hasAllowedOutboundAddresses } from '../utils/outboundUrl'
+
+const logger = debug('agents:attachmentDownloader')
+const REDIRECT_STATUSES = new Set([300, 301, 302, 303, 307, 308])
+const MAX_REDIRECTS = 50
+
+export class AttachmentDownloadHttpClient {
+  public constructor (
+    private readonly httpClient: HttpClient,
+    private readonly hostValidator: OutboundUrlPolicy
+  ) {}
+
+  public async get (url: string, headers: Record<string, string> = {}): Promise<HttpResponse<ArrayBuffer> | undefined> {
+    if (!this.hostValidator.enabled) {
+      if (!this.hostValidator.isAllowed(url)) {
+        return this.blocked(url)
+      }
+      return this.httpClient.get<ArrayBuffer>(url, { headers, responseType: 'arraybuffer' })
+    }
+
+    let currentUrl = url
+    for (let redirects = 0; ; redirects++) {
+      const parsed = getHttpsUrl(currentUrl)
+      const allowed = parsed && (this.hostValidator instanceof OutboundHostValidator
+        ? await this.hostValidator.isAllowedAsync(parsed)
+        : this.hostValidator.isAllowed(currentUrl) && await hasAllowedOutboundAddresses(parsed))
+      if (!allowed) {
+        return this.blocked(currentUrl)
+      }
+
+      const requestHeaders = new Headers(redirects === 0 ? headers : undefined)
+      const response = await fetch(currentUrl, { method: 'GET', headers: requestHeaders, redirect: 'manual' })
+      const location = response.headers.get('location')
+      if (REDIRECT_STATUSES.has(response.status) && location) {
+        await response.body?.cancel()
+        if (redirects >= MAX_REDIRECTS) {
+          throw ExceptionHelper.generateException(Error, Errors.AttachmentDownloadRedirectLimit)
+        }
+        try {
+          currentUrl = new URL(location, currentUrl).href
+        } catch {
+          throw ExceptionHelper.generateException(Error, Errors.AttachmentDownloadInvalidRedirect)
+        }
+        continue
+      }
+
+      const config = { method: 'get', url: currentUrl, responseType: 'arraybuffer' as const }
+      const result: HttpResponse<ArrayBuffer> = {
+        data: await response.arrayBuffer(),
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        config
+      }
+      if (!response.ok) {
+        throw new HttpError(`Request failed with status ${response.status}`, result, config)
+      }
+      return result
+    }
+  }
+
+  private blocked (input: string): undefined {
+    let host = '[invalid-url]'
+    try {
+      host = new URL(input).hostname
+    } catch { /* Invalid URLs have no safe host to log. */ }
+    logger.warn(`Attachment destination blocked by outbound policy or address validation. Host='${host}'`)
+    return undefined
+  }
+}

package/src/app/attachmentDownloader.ts

@@ -13,6 +13,7 @@ import { debug } from '@microsoft/agents-telemetry'
 import { loadAuthConfigFromEnv, MsalTokenProvider } from '../auth'
 import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
 import { Connections } from '../auth/connections'
+import { AttachmentDownloadHttpClient } from './attachmentDownloadHttpClient'
 
 const logger = debug('agents:attachmentDownloader')
 
@@ -24,6 +25,8 @@ const logger = debug('agents:attachmentDownloader')
  * @remarks
  * This class provides functionality to filter and download attachments from a turn context,
  * supporting various content types and handling authentication for secure URLs.
+ * Enabled outbound validation requires HTTPS and validates addresses at every redirect.
+ * Initial request credentials are not forwarded to redirects when validation is enabled.
  *
  */
 export class AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
@@ -103,18 +106,12 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       if (accessToken.length > 0) {
         headers.Authorization = `Bearer ${accessToken}`
       }
-      if (!this._hostValidator.isAllowed(attachment.contentUrl)) {
-        let host = '[invalid-url]'
-        try { host = new URL(attachment.contentUrl).hostname } catch { /* invalid */ }
-        logger.warn(`Attachment contentUrl host is not in the configured allowed hosts. Host='${host}'`)
+      const response = await new AttachmentDownloadHttpClient(this._httpClient, this._hostValidator)
+        .get(attachment.contentUrl, headers)
+      if (!response) {
         return undefined
       }
 
-      const response = await this._httpClient.get(attachment.contentUrl, {
-        headers,
-        responseType: 'arraybuffer'
-      })
-
       const content = Buffer.from(response.data as ArrayBuffer)
 
       let contentType = attachment.contentType

package/src/app/auth/authorization.ts

@@ -16,14 +16,72 @@ import { AuthorizationHandlerTokenOptions } from './types'
 
 const logger = debug('agents:authorization')
 
+/** Provides user authorization, token exchange, and sign-in lifecycle operations. */
 export interface Authorization {
+  /**
+   * Gets the user token for an authorization handler.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns The token response.
+   */
   getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>
+  /**
+   * Creates a credential backed by the current turn's user token.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns A turn-scoped token credential.
+   */
   getTokenAsTokenCredential?(context: TurnContext, authHandlerId: string): TokenCredential
+  /**
+   * Exchanges the user token for the requested scopes.
+   *
+   * @param context - Context for the current turn.
+   * @param scopes - Scopes requested for the exchanged token.
+   * @param authHandlerId - Authorization handler ID.
+   * @returns The exchanged token response.
+   * @deprecated Use the overload that accepts an authorization handler ID followed by options.
+   */
   exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>
+  /**
+   * Exchanges the user token using an authorization handler.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @param options - Optional connection and scope overrides.
+   * @returns The exchanged token response.
+   */
   exchangeToken(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>
+  /**
+   * Creates a credential that exchanges the current turn's user token.
+   *
+   * @param context - Context for the current turn.
+   * @param authHandlerId - Authorization handler ID.
+   * @param options - Optional connection and scope overrides.
+   * @returns A turn-scoped token credential.
+   */
   exchangeTokenAsTokenCredential?(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): TokenCredential
+  /**
+   * Signs out the user from one or all authorization handlers.
+   *
+   * @param context - Context for the current turn.
+   * @param state - State for the current turn.
+   * @param authHandlerId - Handler to sign out from, or `undefined` for all handlers.
+   * @returns A promise that resolves after sign-out completes.
+   */
   signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>
+  /**
+   * Registers a callback for successful sign-in.
+   *
+   * @param handler - Callback invoked after sign-in succeeds.
+   */
   onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void
+  /**
+   * Registers a callback for failed sign-in.
+   *
+   * @param handler - Callback invoked after sign-in fails.
+   */
   onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void
 }
 

package/src/app/proactive/conversation.ts

@@ -12,10 +12,15 @@ import { Errors } from '../../errorHelper'
  * `aud` (the agent's client ID) is required; all other fields are optional.
  */
 export interface ConversationClaims {
+  /** Audience identifying the agent client. */
   aud: string
+  /** Authorized-party client ID, when supplied by the token. */
   azp?: string
+  /** Calling application ID, when supplied by the token. */
   appid?: string
+  /** Microsoft Entra tenant ID, when supplied by the token. */
   tid?: string
+  /** Additional string-valued identity claims. */
   [key: string]: string | undefined
 }
 
@@ -28,11 +33,30 @@ export interface ConversationClaims {
  * `adapter.continueConversation()`.
  */
 export class Conversation {
+  /** Reference used to resume the conversation. */
   reference: ConversationReference
+  /** Identity claims used to authenticate proactive operations. */
   claims: ConversationClaims
 
+  /**
+   * Creates a conversation from the current turn.
+   *
+   * @param context - Turn context from which to capture the reference and identity.
+   */
   constructor (context: TurnContext)
+  /**
+   * Creates a conversation from explicit claims and a conversation reference.
+   *
+   * @param claims - Claims used to authenticate proactive operations.
+   * @param reference - Reference used to resume the conversation.
+   */
   constructor (claims: ConversationClaims, reference: ConversationReference)
+  /**
+   * Creates a conversation from a turn context or explicit claims and a reference.
+   *
+   * @param contextOrClaims - Turn context to capture, or authentication claims.
+   * @param reference - Reference paired with explicit claims.
+   */
   constructor (
     contextOrClaims: TurnContext | ConversationClaims,
     reference?: ConversationReference

package/src/app/proactive/conversationBuilder.ts

@@ -55,7 +55,9 @@ export class ConversationBuilder {
     requestorId?: string
   ): ConversationBuilder {
     const claims: ConversationClaims = { aud: agentClientId }
-    if (requestorId) claims.appid = requestorId
+    if (requestorId) {
+      claims.appid = requestorId
+    }
     return new ConversationBuilder(agentClientId, channelId, serviceUrl ?? '', claims, ConversationReferenceBuilder.create(agentClientId, channelId, serviceUrl).build())
   }
 

package/src/app/proactive/conversationReferenceBuilder.ts

@@ -71,8 +71,12 @@ export class ConversationReferenceBuilder {
    * `https://{channelId}.botframework.com/` pattern (matching C# behavior).
    */
   static serviceUrlForChannel (channelId: string): string {
-    if (!channelId) return ''
-    if (channelId === Channels.Msteams) return TeamsServiceEndpoints.publicGlobal
+    if (!channelId) {
+      return ''
+    }
+    if (channelId === Channels.Msteams) {
+      return TeamsServiceEndpoints.publicGlobal
+    }
     if (!knownChannelIds.has(channelId)) {
       logger.warn(
         `serviceUrlForChannel: unrecognized channelId '${channelId}' — constructing fallback URL ` +
@@ -141,8 +145,12 @@ export class ConversationReferenceBuilder {
       user: this._user ?? { role: RoleTypes.User },
     }
 
-    if (this._activityId !== undefined) ref.activityId = this._activityId
-    if (this._locale !== undefined) ref.locale = this._locale
+    if (this._activityId !== undefined) {
+      ref.activityId = this._activityId
+    }
+    if (this._locale !== undefined) {
+      ref.locale = this._locale
+    }
 
     return ref
   }

package/src/app/proactive/createConversationOptionsBuilder.ts

@@ -81,6 +81,8 @@ export class CreateConversationOptionsBuilder {
 
   /** Adds a member (the target user) to `parameters.members`. */
   withUser (userId: string, userName?: string): this
+
+  /** Adds a channel account as a member in `parameters.members`. */
   withUser (account: ChannelAccount): this
   withUser (userIdOrAccount: string | ChannelAccount, userName?: string): this {
     const account: ChannelAccount =
@@ -125,7 +127,9 @@ export class CreateConversationOptionsBuilder {
    * Only has effect on `msteams` channels.
    */
   withTeamsChannelId (teamsChannelId: string): this {
-    if (this._channelId !== Channels.Msteams) return this
+    if (this._channelId !== Channels.Msteams) {
+      return this
+    }
     this._parameters = { ...this._parameters, isGroup: true }
     this.withChannelData({ channel: { id: teamsChannelId } })
     return this

package/src/app/proactive/proactive.ts

@@ -49,6 +49,12 @@ export class Proactive<TState extends TurnState> {
   private readonly _options: ProactiveOptions
   private readonly _storage?: StorageV2
 
+  /**
+   * Creates a proactive conversation manager.
+   *
+   * @param app - Application that owns the proactive operations.
+   * @param options - Proactive messaging configuration.
+   */
   constructor (app: AgentApplication<TState>, options: ProactiveOptions) {
     this._app = app
     this._options = options
@@ -113,6 +119,12 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   storeConversation (conversation: Conversation): Promise<string>
+  /**
+   * Stores a conversation captured from a turn context or supplied explicitly.
+   *
+   * @param contextOrConversation - Turn context or conversation to store.
+   * @returns The stored conversation ID.
+   */
   async storeConversation (contextOrConversation: TurnContext | Conversation): Promise<string> {
     return trace(ProactiveTraceDefinitions.storeConversation, async ({ record, actions }) => {
       const conv =
@@ -243,6 +255,14 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   sendActivity (adapter: BaseAdapter, conversation: Conversation, activity: Partial<Activity>): Promise<ResourceResponse>
+  /**
+   * Sends an activity to a stored or explicitly supplied conversation.
+   *
+   * @param adapter - Channel adapter used to continue the conversation.
+   * @param conversationOrId - Conversation or stored conversation ID.
+   * @param activity - Activity fields to send.
+   * @returns The channel resource response.
+   */
   async sendActivity (
     adapter: BaseAdapter,
     conversationOrId: Conversation | string,
@@ -285,7 +305,9 @@ export class Proactive<TState extends TurnState> {
         logger.warn('sendActivity: failed for conversation=%s: %s', id, caughtError)
         throw caughtError
       }
-      if (response === undefined) throw ExceptionHelper.generateException(Error, Errors.ProactiveSendActivityNoResponse)
+      if (response === undefined) {
+        throw ExceptionHelper.generateException(Error, Errors.ProactiveSendActivityNoResponse)
+      }
       logger.debug('sendActivity: sent activity id=%s', response.id)
       return response
     })
@@ -359,6 +381,16 @@ export class Proactive<TState extends TurnState> {
    * ```
    */
   continueConversation (adapter: BaseAdapter, conversation: Conversation, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>
+  /**
+   * Continues a stored or explicitly supplied conversation.
+   *
+   * @param adapter - Channel adapter used to continue the conversation.
+   * @param conversationOrId - Conversation or stored conversation ID.
+   * @param handler - Handler to execute in the continued turn.
+   * @param autoSignInHandlers - Connections for which tokens are acquired before the handler runs.
+   * @param continuationActivity - Activity fields merged into the continuation activity.
+   * @returns A promise that resolves after the continued turn completes.
+   */
   async continueConversation (
     adapter: BaseAdapter,
     conversationOrId: Conversation | string,

package/src/app/routeList.ts

@@ -9,9 +9,25 @@ import { RouteRank } from './routeRank'
 import { RouteSelector } from './routeSelector'
 import { TurnState } from './turnState'
 
+/**
+ * Maintains application routes in dispatch priority order.
+ *
+ * @typeParam TState - Turn state supplied to route handlers.
+ */
 export class RouteList<TState extends TurnState> {
   private _routes: Array<AppRoute<TState>> = []
 
+  /**
+   * Adds a route and orders it by route kind and rank.
+   *
+   * @param selector - Selector that determines whether the route matches.
+   * @param handler - Handler invoked for a matching route.
+   * @param isInvokeRoute - Whether the route handles invoke activities.
+   * @param rank - Rank used to order routes of the same kind.
+   * @param authHandlers - Authentication handlers required by the route.
+   * @param isAgenticRoute - Whether the route handles agentic requests.
+   * @returns This route list.
+   */
   public addRoute (
     selector: RouteSelector,
     handler: RouteHandler<TState>,
@@ -30,9 +46,15 @@ export class RouteList<TState extends TurnState> {
     // Then by Rank
     this._routes.sort((a, b) => {
       const getPriority = (route: AppRoute<TState>) => {
-        if (route.isAgenticRoute && route.isInvokeRoute) return 0
-        if (route.isInvokeRoute) return 1
-        if (route.isAgenticRoute) return 2
+        if (route.isAgenticRoute && route.isInvokeRoute) {
+          return 0
+        }
+        if (route.isInvokeRoute) {
+          return 1
+        }
+        if (route.isAgenticRoute) {
+          return 2
+        }
         return 3
       }
 
@@ -50,6 +72,11 @@ export class RouteList<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Iterates over routes in dispatch priority order.
+   *
+   * @returns An iterator over the registered routes.
+   */
   public [Symbol.iterator] (): Iterator<AppRoute<TState>> {
     return this._routes[Symbol.iterator]()
   }