@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.7.0-beta.1.g8bcd4f11a7

package/src/auth/settings.ts

@@ -0,0 +1,378 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
+import type { MsalConnectionSettings } from './msal/msalConnectionSettings'
+import type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSettings'
+
+export type { MsalConnectionSettings } from './msal/msalConnectionSettings'
+export type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSettings'
+
+const logger = debug('agents:authConfiguration')
+
+const DEFAULT_CONNECTION = 'serviceConnection'
+const AUTHORITY_DEFAULT = 'https://login.microsoftonline.com'
+
+/**
+ * A single entry in the connections map used to route an inbound activity
+ * (matched by audience and/or serviceUrl) to a named connection.
+ */
+export interface ConnectionMapItem {
+  serviceUrl: string
+  audience?: string
+  connection: string
+}
+
+export const DEFAULT_CONNECTION_MAP: ConnectionMapItem = { serviceUrl: '*', connection: DEFAULT_CONNECTION }
+
+export type ConnectionKeys = keyof Omit<AuthConfiguration, 'connections' | 'connectionsMap'>
+export type ConnectionMapKeys = keyof ConnectionMapItem
+
+export interface LoadEnv {
+  [upperKey: string]: { key: string, value: any }
+}
+
+export function loadEnvSettings (callback: (key: string, value: string) => void) {
+  const env: LoadEnv = {}
+  for (const [envKey, envValue] of Object.entries(process.env)) {
+    if (!envValue?.trim()) {
+      continue
+    }
+
+    env[envKey.toUpperCase()] = { key: envKey, value: envValue }
+
+    callback(envKey, envValue)
+  }
+
+  return env
+}
+
+export function applyDefaultSettings (config: AuthConfiguration) {
+  const settings = { ...config }
+  settings.authorityEndpoint ??= settings.authority ?? AUTHORITY_DEFAULT
+  settings.issuers ??= getDefaultIssuers(settings.tenantId ?? '', settings.authorityEndpoint)
+
+  // For backward compatibility
+  if (settings.federatedClientId) {
+    settings.FICClientId = settings.federatedClientId
+  }
+
+  if (settings.scopes?.length) {
+    settings.scope = settings.scopes?.[0]
+  }
+
+  if (settings.authorityEndpoint) {
+    settings.authority = settings.authorityEndpoint
+  }
+
+  // .NET parity alias: keep altBlueprintConnectionName and alternateBlueprintConnectionName in sync.
+  settings.altBlueprintConnectionName ??= settings.alternateBlueprintConnectionName
+  if (settings.altBlueprintConnectionName) {
+    settings.alternateBlueprintConnectionName = settings.altBlueprintConnectionName
+  }
+
+  if (!settings.clientId && process.env.NODE_ENV?.toLowerCase() === 'production') {
+    throw ExceptionHelper.generateException(Error, Errors.ClientIdRequiredInProduction)
+  }
+
+  const defaultConnections = settings.connections?.size
+    ? settings.connections
+    : new Map([[DEFAULT_CONNECTION, { ...settings }]])
+  const defaultConnectionsMap = settings.connectionsMap?.length
+    ? settings.connectionsMap
+    : [DEFAULT_CONNECTION_MAP]
+
+  settings.connections = defaultConnections
+  settings.connectionsMap = defaultConnectionsMap
+  return settings
+}
+
+/**
+ * A type representing a parser settings object.
+ */
+type ParserSettings<K extends string> = {
+  [key in K]: (value: string) => { key?: string, value?: any } | undefined
+}
+
+/**
+ * Creates an environment variable parser that maps the variable keys to parsing functions.
+ * @param settings An object where each key is an environment variable name and the value is a function
+ * that takes the variable value as input and returns an object with optional `key` and `value` properties.
+ * @remarks
+ * The `key` property in the returned object can be used to rename the environment variable key,
+ * while the `value` property contains the parsed value.
+ * @returns An object with a `parse` method that takes an environment variable key and value,
+ * and returns the parsed result.
+ */
+export function envParser<K extends string> (settings: ParserSettings<K> & ThisType<ParserSettings<K>>) {
+  const keys = Object.keys(settings) as K[]
+  const upperKeys = keys.reduce((acc, key) => {
+    acc[key.toUpperCase()] = key
+    return acc
+  }, {} as Record<string, K>)
+  return {
+    keys,
+    /**
+     * Parses the given environment variable key and value using the provided settings.
+     * @param key The environment variable key.
+     * @param value The environment variable value.
+     * @returns The parsed result with optional renamed key and parsed value.
+     */
+    parse (key: K, value: string) {
+      const match = upperKeys[key.toUpperCase()]
+      if (!match) {
+        return {}
+      }
+
+      const result = settings[match](value)
+      return { key: result?.key ?? match, value: result?.value }
+    }
+  }
+}
+
+/**
+ * Utility functions for environment variable parsers.
+ */
+export const envParserUtils = {
+  /**
+   * Bypass parser that returns the value as is.
+   * @param value The environment variable value.
+   * @returns An object with the original value.
+   */
+  bypass: (value: string) => ({ value }),
+  /**
+   * Redirects the parsing to another parser for a specific key.
+   * @param parser The target parser to redirect to.
+   * @param key The key to use in the target parser.
+   * @returns A function that takes the environment variable value and returns the parsed result from the target parser.
+   */
+  redirect: <Parser extends ReturnType<typeof envParser>>(parser: Parser, key: Parameters<Parser['parse']>[0]) => (value: string) => parser.parse(key, value)
+}
+
+/**
+ * Resolves the full authority URL including the tenant ID.
+ * Supports both patterns:
+ *   - Tenant embedded in authority: https://login.microsoftonline.com/my-tenant
+ *   - Authority + separate tenantId: https://login.microsoftonline.com + tenantId
+ * Also handles trailing slashes on authority.
+ */
+export function resolveAuthority (authority?: string, tenantId?: string): string {
+  const base = trimTrailingSlashes(authority ?? AUTHORITY_DEFAULT)
+  const url = new URL(base)
+  const hasPathSegment = url.pathname !== '/'
+  if (hasPathSegment) {
+    return base
+  }
+  return `${base}/${tenantId ?? 'botframework.com'}`
+}
+
+function trimTrailingSlashes (value: string): string {
+  let end = value.length
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end--
+  }
+
+  return end === value.length ? value : value.slice(0, end)
+}
+
+function getDefaultIssuers (tenantId: string, authority: string) : string[] {
+  // Convert empty string to undefined so resolveAuthority applies its 'botframework.com' default
+  const t = tenantId || undefined
+  if (!t) {
+    logger.warn('tenantId is not configured, defaulting to botframework.com')
+  }
+  return [
+    'https://api.botframework.com',
+    `${resolveAuthority('https://sts.windows.net', t)}/`,
+    `${resolveAuthority(authority, t)}/v2.0`
+  ]
+}
+
+/**
+ * Connection-level settings common to every authentication provider.
+ *
+ * @remarks
+ * Mirrors the .NET `Microsoft.Agents.Authentication.ConnectionSettingsBase` abstract class: these are
+ * the credential-agnostic properties shared by all connection types. Provider-specific settings
+ * extend this base (see {@link MsalConnectionSettings} for MSAL and {@link SidecarConnectionSettings}
+ * for the Entra sidecar). The active provider for a connection is selected
+ * by {@link ConnectionSettingsBase.authType | authType}; see `AuthProviderFactory`.
+ */
+export interface ConnectionSettingsBase {
+  /**
+   * The tenant ID for the authentication configuration.
+   */
+  tenantId?: string
+
+  /**
+   * The client ID for the authentication configuration. Required in production.
+   */
+  clientId?: string
+
+  /**
+   * The authentication type for the connection.
+   */
+  authType?: AuthType | string
+
+  /**
+   * A list of valid issuers for the authentication configuration.
+   */
+  issuers?: string[]
+
+  /**
+   * The connection name for the authentication configuration.
+   */
+  connectionName?: string
+
+  /**
+   * @deprecated Use authorityEndpoint instead.
+   *
+   * Entra Authentication Endpoint to use.
+   *
+   * @remarks
+   * If not populated the Entra Public Cloud endpoint is assumed.
+   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
+   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   */
+  authority?: string
+
+  /**
+   * Entra Authentication Endpoint to use.
+   *
+   * @remarks
+   * If not populated the Entra Public Cloud endpoint is assumed.
+   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
+   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   */
+  authorityEndpoint?: string
+
+  /**
+   * @deprecated Use scopes instead.
+   */
+  scope?: string
+
+  /**
+   * The scopes for the authentication configuration.
+   */
+  scopes?: string[]
+
+  /**
+   * An optional alternative blueprint Connection name used when constructing a connector client.
+   *
+   * @remarks
+   * Equivalent to the .NET `AlternateBlueprintConnectionName` connection setting. {@link alternateBlueprintConnectionName}
+   * is an alias of this property that matches the .NET name exactly; when both are provided this property takes precedence.
+   */
+  altBlueprintConnectionName?: string
+
+  /**
+   * Alias of {@link altBlueprintConnectionName} named to match the .NET `AlternateBlueprintConnectionName`
+   * connection setting exactly.
+   *
+   * @remarks
+   * Provided for stricter .NET parity. The two properties are kept in sync during configuration normalization;
+   * {@link altBlueprintConnectionName} takes precedence when both are set.
+   */
+  alternateBlueprintConnectionName?: string
+}
+
+/**
+ * The complete settings for a single connection, across every provider.
+ *
+ * @remarks
+ * This is the per-connection unit that an `AuthProvider` consumes: it combines the common base
+ * ({@link ConnectionSettingsBase}) with the MSAL settings ({@link MsalConnectionSettings}) and the
+ * Entra sidecar settings ({@link SidecarConnectionSettings}). The active provider for a connection is
+ * selected by `authType`, so only the subset of these properties relevant to that provider is used.
+ *
+ * Conceptually this is the consumer-facing counterpart to the {@link AuthConfiguration} *container*:
+ * each value in {@link AuthConfiguration.connections} is the settings for one connection. It parallels
+ * the .NET `IConnectionSettings` (a single connection's settings) as distinct from the connection
+ * registry. {@link AuthConfiguration} extends this type for backward compatibility (it doubles as the
+ * settings for the legacy single connection).
+ */
+export interface ConnectionSettings extends MsalConnectionSettings, SidecarConnectionSettings {}
+
+/**
+ * Represents the authentication configuration.
+ *
+ * @remarks
+ * The agent-level authentication container. It owns the connection registry
+ * (`connections`/`connectionsMap`) and, for backward compatibility, also extends
+ * {@link ConnectionSettings} so the legacy single-connection shape (a flat config with `clientId`,
+ * `clientSecret`, etc.) keeps working — in that mode the top-level object *is* the one connection's
+ * settings. The active provider for each connection is dispatched by `authType` via
+ * `AuthProviderFactory`, so a single connection only uses the subset of these properties relevant to
+ * its provider.
+ */
+export interface AuthConfiguration extends ConnectionSettings {
+  /**
+   * The connection registry: a map of connection name to that connection's settings.
+   *
+   * @remarks
+   * Each value is the {@link ConnectionSettings} for one connection (typed as {@link AuthConfiguration}
+   * for backward compatibility; only the connection-settings subset is consumed). An `AuthProvider` is
+   * created per entry by `AuthProviderFactory`, dispatched by `authType`.
+   */
+  connections?: Map<string, AuthConfiguration>
+
+  /**
+   * A list of connection map items to map service URLs to connection names.
+   */
+  connectionsMap?: ConnectionMapItem[]
+}
+
+/**
+ * Supported authentication types for agent connections.
+ */
+export enum AuthType {
+  Certificate = 'Certificate',
+  CertificateSubjectName = 'CertificateSubjectName',
+  ClientSecret = 'ClientSecret',
+  UserManagedIdentity = 'UserManagedIdentity',
+  SystemManagedIdentity = 'SystemManagedIdentity',
+  FederatedCredentials = 'FederatedCredentials',
+  WorkloadIdentity = 'WorkloadIdentity',
+  IdentityProxyManager = 'IdentityProxyManager',
+  EntraAuthSideCar = 'EntraAuthSideCar'
+}
+
+/**
+ * Resolves the authentication type for a given authentication configuration.
+ * @remarks
+ * The function checks various properties of the `authConfig` object to determine the appropriate authentication type.
+ * It returns a string representing the resolved authentication type or 'unknown' if it cannot be determined.
+ * @param authConfig The authentication configuration object.
+ * @returns The resolved authentication type as a string or 'unknown' if it cannot be determined.
+ */
+export function resolveAuthType (authConfig?: AuthConfiguration): AuthType | string {
+  if (!authConfig) {
+    return 'none'
+  }
+  if (authConfig.authType) {
+    return authConfig.authType
+  }
+  if (authConfig.WIDAssertionFile !== undefined) {
+    return AuthType.WorkloadIdentity
+  }
+  if (authConfig.federatedClientId !== undefined || authConfig.FICClientId !== undefined) {
+    return AuthType.FederatedCredentials
+  }
+  if (authConfig.clientSecret !== undefined) {
+    return AuthType.ClientSecret
+  }
+  if (authConfig.certPemFile !== undefined && authConfig.certKeyFile !== undefined) {
+    return AuthType.Certificate
+  }
+  if (authConfig.clientSecret === undefined && authConfig.certPemFile === undefined && authConfig.certKeyFile === undefined) {
+    return AuthType.UserManagedIdentity
+  }
+  if (authConfig.idpmResource !== undefined) {
+    return AuthType.IdentityProxyManager
+  }
+  return 'unknown'
+}

package/src/auth/sidecar/sidecarAuthProvider.ts

@@ -0,0 +1,234 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
+import { AuthConfiguration } from '../authConfiguration'
+import { AuthProvider } from '../authProvider'
+import { SidecarHttpClient } from './sidecarHttpClient'
+import { resolveTokenExpiry } from './sidecarTokenExpiry'
+import {
+  ResolvedSidecarConnectionSettings,
+  SidecarRequestOptions,
+  toSidecarConnectionSettings
+} from './sidecarModels'
+
+const logger = debug('agents:sidecar')
+
+const GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+// Refresh slightly ahead of the real expiry so callers never receive a token that expires mid-flight.
+const EXPIRY_BUFFER_MS = 30 * 1000
+
+// Hard upper bound on cached entries; protects memory when many distinct identities are served.
+const MAX_CACHE_ENTRIES = 500
+
+interface CachedToken {
+  token: string
+  expiresOn: number
+}
+
+/**
+ * Authentication provider that delegates token acquisition to the Microsoft Entra Agent ID
+ * sidecar (agent container). This replaces MSAL at the connection layer, using the sidecar's
+ * `/AuthorizationHeaderUnauthenticated/{serviceName}` endpoint for app-only and agentic identity
+ * flows. The sidecar performs the full Blueprint→Instance→User chain internally; no MSAL exchange is
+ * performed in-process.
+ */
+export class SidecarAuthProvider implements AuthProvider {
+  public readonly connectionSettings?: AuthConfiguration
+  private readonly _settings: ResolvedSidecarConnectionSettings
+  private readonly _httpClient: SidecarHttpClient
+  private readonly _tokenCache: Map<string, CachedToken> = new Map()
+
+  /**
+   * Creates a new {@link SidecarAuthProvider}.
+   * @param connectionSettings The connection authentication configuration.
+   */
+  constructor (connectionSettings?: AuthConfiguration) {
+    this.connectionSettings = connectionSettings
+    this._settings = toSidecarConnectionSettings(connectionSettings)
+
+    const resolvedUrl = SidecarHttpClient.resolveBaseUrl(this._settings.sidecarBaseUrl)
+    SidecarHttpClient.validateBaseUrl(resolvedUrl, this._settings.bypassLocalNetworkRestriction)
+    this._httpClient = new SidecarHttpClient(resolvedUrl, this._settings.requestTimeout, this._settings.retryCount)
+    logger.debug('SidecarAuthProvider initialized serviceName=%s blueprintServiceName=%s', this._settings.serviceName, this._settings.blueprintServiceName)
+  }
+
+  /**
+   * Acquires an app-only access token from the sidecar.
+   * @param scope The scope for the token.
+   */
+  async getAccessToken (scope: string): Promise<string>
+  /**
+   * Acquires an app-only access token from the sidecar.
+   * @param authConfig The authentication configuration. Ignored by the sidecar provider, which
+   * owns the credential and derives the token from its configured service name; accepted only to
+   * satisfy the {@link AuthProvider} overload.
+   * @param scope The scope for the token.
+   */
+  async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  async getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string> {
+    const actualScope = typeof authConfigOrScope === 'string' ? authConfigOrScope : scope
+    const options: SidecarRequestOptions = {
+      scopes: actualScope ? [actualScope] : this._settings.scopes,
+      requestAppToken: true
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * Acquires the Blueprint (agent application) token from the sidecar.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   */
+  async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
+    this.ensureConnectionSettings()
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      tenant: tenantId
+    }
+    return this.getCachedToken(this._settings.blueprintServiceName, options)
+  }
+
+  /**
+   * Acquires the autonomous agent (instance) token from the sidecar for the configured resource.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   */
+  async getAgenticInstanceToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
+    this.ensureConnectionSettings()
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      requestAppToken: true,
+      tenant: tenantId,
+      scopes: this._settings.scopes
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * Acquires the agentic user token from the sidecar for the configured resource.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   * @param upn The agentic user identifier. A GUID is sent as `AgentUserId`; otherwise as `AgentUsername`.
+   * @param scopes The OAuth scopes to request.
+   */
+  async getAgenticUserToken (tenantId: string, agentAppInstanceId: string, upn: string, scopes: string[]): Promise<string> {
+    this.ensureConnectionSettings()
+    const isObjectId = GUID_REGEX.test(upn ?? '')
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      agentUsername: isObjectId ? undefined : upn,
+      agentUserId: isObjectId ? upn : undefined,
+      tenant: tenantId,
+      scopes: scopes ?? this._settings.scopes
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * On-behalf-of token exchange — not supported by the sidecar provider in Phase 1.
+   */
+  async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  async acquireTokenOnBehalfOf (
+    _authConfigOrScopes: AuthConfiguration | string[],
+    _scopesOrOboAssertion?: string[] | string,
+    _oboAssertion?: string
+  ): Promise<string> {
+    throw ExceptionHelper.generateException(Error, Errors.OnBehalfOfNotSupportedBySidecar)
+  }
+
+  /**
+   * Checks sidecar availability via the `/healthz` endpoint.
+   * @returns `true` when the sidecar is reachable and healthy.
+   */
+  async isHealthy (): Promise<boolean> {
+    return this._httpClient.isHealthy()
+  }
+
+  private ensureConnectionSettings (): void {
+    if (!this.connectionSettings) {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarConnectionSettingsRequired)
+    }
+  }
+
+  private async getCachedToken (serviceName: string, options: SidecarRequestOptions): Promise<string> {
+    const forceRefresh = options.forceRefresh === true
+    const cacheKey = SidecarAuthProvider.buildCacheKey(serviceName, options)
+
+    const cached = this.cacheGet(cacheKey, forceRefresh)
+    if (cached) {
+      return cached
+    }
+
+    const result = await this._httpClient.getAuthorizationHeaderUnauthenticated(serviceName, options)
+    // The hosting stack always transmits the token as `Bearer {token}`. Reject any other scheme
+    // (e.g. PoP) rather than silently emitting an invalid Authorization header.
+    if (result.scheme && result.scheme.toLowerCase() !== 'bearer') {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarUnsupportedAuthScheme, undefined, { scheme: result.scheme })
+    }
+    this.cacheSet(cacheKey, { token: result.token, expiresOn: resolveTokenExpiry(result.token) })
+    return result.token
+  }
+
+  private cacheGet (cacheKey: string, forceRefresh: boolean): string | undefined {
+    const cached = this._tokenCache.get(cacheKey)
+    if (cached) {
+      if (!forceRefresh && cached.expiresOn >= Date.now() + EXPIRY_BUFFER_MS) {
+        return cached.token
+      }
+      this._tokenCache.delete(cacheKey)
+    }
+    return undefined
+  }
+
+  private cacheSet (cacheKey: string, token: CachedToken): void {
+    this._tokenCache.set(cacheKey, token)
+    if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+      this.pruneExpiredEntries()
+      if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+        this.evictNearestExpiry()
+      }
+    }
+  }
+
+  private pruneExpiredEntries (): void {
+    const now = Date.now()
+    for (const [key, value] of this._tokenCache) {
+      if (value.expiresOn <= now) {
+        this._tokenCache.delete(key)
+      }
+    }
+  }
+
+  private evictNearestExpiry (): void {
+    const overflow = this._tokenCache.size - MAX_CACHE_ENTRIES
+    if (overflow <= 0) {
+      return
+    }
+    const sorted = [...this._tokenCache.entries()].sort((a, b) => a[1].expiresOn - b[1].expiresOn)
+    for (let i = 0; i < overflow; i++) {
+      this._tokenCache.delete(sorted[i][0])
+    }
+  }
+
+  private static buildCacheKey (serviceName: string, options: SidecarRequestOptions): string {
+    const scopes = options.scopes
+      ? [...new Set(options.scopes.filter((s) => s && s.trim()))].sort().join(' ')
+      : ''
+    return [
+      serviceName,
+      options.agentIdentity ?? '',
+      options.agentUsername ?? '',
+      options.agentUserId ?? '',
+      options.tenant ?? '',
+      options.requestAppToken === true ? 'app' : 'user',
+      scopes
+    ].join('|')
+  }
+}

package/src/auth/sidecar/sidecarConnectionSettings.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ConnectionSettingsBase } from '../settings'
+
+/**
+ * Connection settings for the Entra Agent ID sidecar (agent container) authentication provider, used when a
+ * connection's `authType` is `'EntraAuthSideCar'`.
+ *
+ * @remarks
+ * Mirrors the .NET `Microsoft.Agents.Authentication.EntraAuthSidecar.Model.SidecarConnectionSettings`
+ * class, which likewise derives from `ConnectionSettingsBase`. These are the configuration-level
+ * properties; they are normalized (with defaults applied) before use by the sidecar token provider.
+ */
+export interface SidecarConnectionSettings extends ConnectionSettingsBase {
+  /**
+   * Optional base URL of the Entra Agent ID sidecar (agent container).
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Resolution order:
+   * `SIDECAR_URL` environment variable > this setting > `http://localhost:5178`.
+   * Regardless of how it is resolved, the host must be a loopback/private address
+   * unless `bypassLocalNetworkRestriction` is set.
+   */
+  sidecarBaseUrl?: string
+
+  /**
+   * The configured downstream API service name in the sidecar's DownstreamApis configuration.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to `'default'`.
+   */
+  serviceName?: string
+
+  /**
+   * The sidecar downstream API name used to acquire the Blueprint (agent application) token for the
+   * agentic FIC chain.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to `'agenticblueprint'`. This
+   * downstream API must be configured app-only with the `api://AzureAdTokenExchange/.default` scope.
+   */
+  blueprintServiceName?: string
+
+  /**
+   * When `true`, disables the loopback/private-address safety check on the resolved sidecar base URL.
+   *
+   * @remarks
+   * UNSAFE. Leave this `false` in all normal deployments. Only enable it for a carefully validated
+   * private-network configuration where the sidecar is reachable at a non-private address that the
+   * operator explicitly trusts. Only used when `authType` is `'EntraAuthSideCar'`.
+   */
+  bypassLocalNetworkRestriction?: boolean
+
+  /**
+   * HTTP request timeout (in milliseconds) for sidecar calls.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to 30000 (30 seconds).
+   */
+  requestTimeout?: number
+
+  /**
+   * Number of retry attempts for transient sidecar failures (5xx, 408, 429, network/timeout).
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to 3.
+   */
+  retryCount?: number
+}