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

package/src/auth/sidecar/sidecarHttpClient.ts

@@ -0,0 +1,443 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { isIP } from 'node:net'
+import { debug } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
+import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_RETRY_COUNT,
+  DEFAULT_SIDECAR_BASE_URL,
+  SidecarProblemDetails,
+  SidecarRequestOptions,
+  SidecarTokenResult
+} from './sidecarModels'
+
+const logger = debug('agents:sidecar')
+
+const DEFAULT_RETRY_BACKOFF_BASE_MS = 2000
+
+/**
+ * Reusable HTTP client for communicating with the Microsoft Entra Agent ID sidecar (agent container).
+ * Handles URL construction, query parameter building, response parsing, retry, and SSRF-safe base
+ * URL validation. Uses the native `fetch` API (Node.js 20+).
+ */
+export class SidecarHttpClient {
+  /** Default per-attempt request timeout (milliseconds). */
+  static readonly DEFAULT_TIMEOUT_MS = DEFAULT_REQUEST_TIMEOUT_MS
+
+  /** Default number of retry attempts for transient failures. */
+  static readonly DEFAULT_RETRY_COUNT = DEFAULT_RETRY_COUNT
+
+  private readonly _baseUrl: string
+  private readonly _timeoutMs: number
+  private readonly _retryCount: number
+  private readonly _retryBackoffBaseMs: number
+
+  /**
+   * Creates a new {@link SidecarHttpClient}.
+   * @param baseUrl The resolved (and validated) sidecar base URL.
+   * @param timeoutMs Per-attempt request timeout in milliseconds.
+   * @param retryCount Number of retry attempts for transient failures (0 disables retries).
+   * @param retryBackoffBaseMs Base delay for exponential backoff; primarily a test seam.
+   */
+  constructor (
+    baseUrl: string,
+    timeoutMs: number = SidecarHttpClient.DEFAULT_TIMEOUT_MS,
+    retryCount: number = SidecarHttpClient.DEFAULT_RETRY_COUNT,
+    retryBackoffBaseMs: number = DEFAULT_RETRY_BACKOFF_BASE_MS
+  ) {
+    this._baseUrl = SidecarHttpClient.stripTrailingSlashes(baseUrl ?? SidecarHttpClient.resolveBaseUrl())
+    this._timeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : SidecarHttpClient.DEFAULT_TIMEOUT_MS
+    this._retryCount = Number.isFinite(retryCount) ? Math.max(0, Math.floor(retryCount)) : SidecarHttpClient.DEFAULT_RETRY_COUNT
+    this._retryBackoffBaseMs = Number.isFinite(retryBackoffBaseMs) && retryBackoffBaseMs >= 0 ? retryBackoffBaseMs : DEFAULT_RETRY_BACKOFF_BASE_MS
+  }
+
+  /**
+   * Removes any trailing `/` characters from `value` using a linear scan. Avoids a regular
+   * expression so untrusted input with many `/` characters cannot trigger super-linear
+   * backtracking (ReDoS).
+   * @param value The string to trim.
+   * @returns `value` without trailing slashes.
+   */
+  private static stripTrailingSlashes (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)
+  }
+
+  /**
+   * Resolves the sidecar base URL. Resolution order: `SIDECAR_URL` environment variable >
+   * `configuredUrl` > {@link DEFAULT_SIDECAR_BASE_URL}. Empty/whitespace values are treated as unset.
+   * @param configuredUrl The optional base URL from configuration.
+   * @returns The resolved base URL.
+   */
+  static resolveBaseUrl (configuredUrl?: string): string {
+    const envUrl = process.env.SIDECAR_URL
+    if (envUrl && envUrl.trim()) {
+      return envUrl.trim()
+    }
+    return configuredUrl && configuredUrl.trim() ? configuredUrl.trim() : DEFAULT_SIDECAR_BASE_URL
+  }
+
+  /**
+   * Returns a copy of `raw` with any userinfo (credentials) removed, safe to include in logs and
+   * error messages. Falls back to a regex strip when `raw` is not a parseable URL.
+   */
+  private static redactUrl (raw: string): string {
+    try {
+      const u = new URL(raw)
+      if (u.username || u.password) {
+        u.username = ''
+        u.password = ''
+      }
+      return u.toString()
+    } catch {
+      return raw.replace(/\/\/[^/@]*@/, '//')
+    }
+  }
+
+  /**
+   * Validates that the resolved sidecar base URL is safe to call. The URL must be a well-formed
+   * absolute http/https URL without userinfo. Unless `bypassLocalNetworkRestriction` is set, the host
+   * must also be a loopback address or a private network address (RFC 1918 / RFC 4193 / link-local) to
+   * avoid sending agent credentials off-box (SSRF safety).
+   * @param resolvedUrl The resolved sidecar base URL.
+   * @param bypassLocalNetworkRestriction Skip the loopback/private-address check (UNSAFE).
+   * @throws When the URL is malformed or points to a disallowed address.
+   */
+  static validateBaseUrl (resolvedUrl: string, bypassLocalNetworkRestriction: boolean): void {
+    let uri: URL
+    try {
+      uri = new URL(resolvedUrl)
+    } catch {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarBaseUrlInvalid, undefined, { url: SidecarHttpClient.redactUrl(resolvedUrl) })
+    }
+
+    if (uri.protocol !== 'http:' && uri.protocol !== 'https:') {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarBaseUrlInsecureScheme, undefined, { url: SidecarHttpClient.redactUrl(resolvedUrl) })
+    }
+
+    if (uri.username || uri.password) {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarBaseUrlUserInfo, undefined, { url: SidecarHttpClient.redactUrl(resolvedUrl) })
+    }
+
+    if (bypassLocalNetworkRestriction) {
+      return
+    }
+
+    if (SidecarHttpClient.isLoopbackOrPrivateHost(uri.hostname)) {
+      return
+    }
+
+    throw ExceptionHelper.generateException(Error, Errors.SidecarBaseUrlNotLocal, undefined, { url: SidecarHttpClient.redactUrl(resolvedUrl) })
+  }
+
+  private static isLoopbackOrPrivateHost (host: string): boolean {
+    // URL.hostname wraps IPv6 literals in brackets (e.g. "[::1]"); strip them before classification.
+    const normalized = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+    const ipVersion = isIP(normalized)
+    if (ipVersion === 0) {
+      // DNS host: only "localhost" (and subdomains) is treated as safe.
+      const lower = normalized.toLowerCase()
+      return lower === 'localhost' || lower.endsWith('.localhost')
+    }
+    if (ipVersion === 4) {
+      return SidecarHttpClient.isPrivateOrLoopbackIPv4(normalized)
+    }
+    return SidecarHttpClient.isPrivateOrLoopbackIPv6(normalized)
+  }
+
+  private static isPrivateOrLoopbackIPv4 (host: string): boolean {
+    const b = host.split('.').map((p) => parseInt(p, 10))
+    if (b.length !== 4 || b.some((n) => Number.isNaN(n) || n < 0 || n > 255)) {
+      return false
+    }
+    if (b[0] === 127) return true // 127.0.0.0/8 loopback
+    if (b[0] === 10) return true // 10.0.0.0/8
+    if (b[0] === 172 && b[1] >= 16 && b[1] <= 31) return true // 172.16.0.0/12
+    if (b[0] === 192 && b[1] === 168) return true // 192.168.0.0/16
+    if (b[0] === 169 && b[1] === 254) return true // 169.254.0.0/16 link-local
+    return false
+  }
+
+  private static isPrivateOrLoopbackIPv6 (host: string): boolean {
+    const lower = host.toLowerCase()
+    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true // loopback (`::` is the unspecified address, not loopback)
+    // IPv4-mapped/-translated addresses in either dotted (::ffff:127.0.0.1)
+    // or hex-compressed (::ffff:7f00:1) form.
+    const mappedIPv4 = SidecarHttpClient.extractMappedIPv4(lower)
+    if (mappedIPv4) {
+      return SidecarHttpClient.isPrivateOrLoopbackIPv4(mappedIPv4)
+    }
+    const firstHextet = parseInt(lower.split(':')[0], 16)
+    if (!Number.isNaN(firstHextet)) {
+      if ((firstHextet & 0xfe00) === 0xfc00) return true // fc00::/7 unique local
+      if ((firstHextet & 0xffc0) === 0xfe80) return true // fe80::/10 link-local
+      if ((firstHextet & 0xffc0) === 0xfec0) return true // fec0::/10 site-local (deprecated)
+    }
+    return false
+  }
+
+  /**
+   * Extracts the embedded IPv4 address from an IPv4-mapped/-translated IPv6 literal, returning it
+   * in dotted-quad form, or `undefined` if `host` is not such an address. Handles both the dotted
+   * form (`::ffff:127.0.0.1`) and the hex-compressed form Node emits (`::ffff:7f00:1`).
+   */
+  private static extractMappedIPv4 (host: string): string | undefined {
+    const dotted = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
+    if (dotted) {
+      return dotted[1]
+    }
+    const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
+    if (hex) {
+      const high = parseInt(hex[1], 16)
+      const low = parseInt(hex[2], 16)
+      return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
+    }
+    return undefined
+  }
+
+  /**
+   * Calls `GET /AuthorizationHeaderUnauthenticated/{serviceName}` with the specified options.
+   * @param serviceName The sidecar downstream API name.
+   * @param options The request options used to build the query string.
+   * @param signal Optional abort signal supplied by the caller.
+   * @returns The parsed token result.
+   */
+  async getAuthorizationHeaderUnauthenticated (
+    serviceName: string,
+    options?: SidecarRequestOptions,
+    signal?: AbortSignal
+  ): Promise<SidecarTokenResult> {
+    const url = this.buildUrl(`/AuthorizationHeaderUnauthenticated/${encodeURIComponent(serviceName)}`, options)
+    return this.sendAndParse(url, signal)
+  }
+
+  /**
+   * Checks sidecar health via `GET /healthz`.
+   * @returns `true` when the sidecar responds with a success status, `false` otherwise.
+   */
+  async isHealthy (): Promise<boolean> {
+    try {
+      const response = await this.fetchWithTimeout(`${this._baseUrl}/healthz`)
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+
+  private buildUrl (path: string, options?: SidecarRequestOptions): string {
+    const url = `${this._baseUrl}${path}`
+    if (!options) {
+      return url
+    }
+
+    // AgentUsername (UPN) and AgentUserId (object id) are mutually exclusive per the sidecar contract.
+    if (options.agentUsername && options.agentUserId) {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarUserIdentityMutuallyExclusive)
+    }
+
+    const params = new URLSearchParams()
+    if (options.agentIdentity) {
+      params.append('AgentIdentity', options.agentIdentity)
+    }
+    if (options.agentUsername) {
+      params.append('AgentUsername', options.agentUsername)
+    }
+    if (options.agentUserId) {
+      params.append('AgentUserId', options.agentUserId)
+    }
+    if (options.scopes) {
+      for (const scope of options.scopes) {
+        if (scope && scope.trim()) {
+          params.append('optionsOverride.Scopes', scope)
+        }
+      }
+    }
+    if (options.requestAppToken === true) {
+      params.append('optionsOverride.RequestAppToken', 'true')
+    }
+    if (options.tenant) {
+      params.append('optionsOverride.AcquireTokenOptions.Tenant', options.tenant)
+    }
+    if (options.forceRefresh === true) {
+      params.append('optionsOverride.AcquireTokenOptions.ForceRefresh', 'true')
+    }
+
+    const query = params.toString()
+    return query ? `${url}?${query}` : url
+  }
+
+  private async withTimeout<T> (signal: AbortSignal | undefined, op: (innerSignal: AbortSignal) => Promise<T>): Promise<T> {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), this._timeoutMs)
+    const onAbort = () => controller.abort()
+    if (signal) {
+      if (signal.aborted) {
+        controller.abort()
+      } else {
+        signal.addEventListener('abort', onAbort, { once: true })
+      }
+    }
+    try {
+      return await op(controller.signal)
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+  }
+
+  private async fetchWithTimeout (url: string, signal?: AbortSignal): Promise<Response> {
+    return this.withTimeout(signal, (innerSignal) => fetch(url, { method: 'GET', signal: innerSignal }))
+  }
+
+  /**
+   * Performs the request and reads the full response body within a single timeout window, so a
+   * sidecar that streams response headers and then stalls the body cannot hang token acquisition
+   * beyond `requestTimeout`.
+   */
+  private async fetchAndReadText (url: string, signal?: AbortSignal): Promise<{ response: Response, body: string }> {
+    return this.withTimeout(signal, async (innerSignal) => {
+      const response = await fetch(url, { method: 'GET', signal: innerSignal })
+      const body = await response.text().catch(() => '')
+      return { response, body }
+    })
+  }
+
+  private async sendAndParse (url: string, signal?: AbortSignal): Promise<SidecarTokenResult> {
+    const maxAttempts = this._retryCount + 1
+    // Log only the request path, never the query string, which can carry PII (UPN, object id, tenant).
+    const requestPath = url.split('?')[0]
+
+    for (let attempt = 1; ; attempt++) {
+      logger.debug('Sidecar request (attempt %d/%d): GET %s', attempt, maxAttempts, requestPath)
+
+      let response: Response
+      let body: string
+      try {
+        ({ response, body } = await this.fetchAndReadText(url, signal))
+      } catch (err) {
+        // A caller-requested cancellation is not transient — propagate it.
+        if (signal?.aborted) {
+          throw err
+        }
+        if (attempt >= maxAttempts) {
+          logger.error('Sidecar request to %s failed after %d attempt(s).', requestPath, attempt)
+          throw ExceptionHelper.generateException(Error, Errors.SidecarRequestFailed, err as Error, {
+            attempts: String(attempt),
+            message: (err as Error)?.message ?? 'network error'
+          })
+        }
+        logger.warn('Sidecar request to %s failed (attempt %d/%d); retrying.', requestPath, attempt, maxAttempts)
+        await this.delayBeforeRetry(attempt, signal)
+        continue
+      }
+
+      if (!response.ok) {
+        if (SidecarHttpClient.isTransientStatus(response.status) && attempt < maxAttempts) {
+          logger.warn('Sidecar returned transient status %d from %s (attempt %d/%d); retrying.', response.status, requestPath, attempt, maxAttempts)
+          await this.delayBeforeRetry(attempt, signal)
+          continue
+        }
+
+        const problem = SidecarHttpClient.tryParseProblemDetails(body)
+        // Never surface problem.detail: the sidecar can echo request parameters (UPN, object id,
+        // tenant) into it. Use only the non-sensitive title/status in logs and the thrown error.
+        const message = problem?.title ?? `Sidecar returned ${response.status}`
+        logger.error('Sidecar returned error. Status: %d, URL: %s, Title: %s', response.status, requestPath, problem?.title ?? '(none)')
+        throw ExceptionHelper.generateException(Error, Errors.SidecarErrorResponse, undefined, {
+          status: String(response.status),
+          message
+        })
+      }
+
+      const result = SidecarHttpClient.parseTokenResponse(body)
+      logger.debug('Sidecar token acquired from %s. Scheme: %s, TokenLength: %d', requestPath, result.scheme, result.token.length)
+      return result
+    }
+  }
+
+  private async delayBeforeRetry (attempt: number, signal?: AbortSignal): Promise<void> {
+    const multiplier = Math.pow(2, attempt - 1)
+    const delay = this._retryBackoffBaseMs * multiplier
+    if (delay <= 0) {
+      return
+    }
+    // Resolve after the backoff delay, but reject immediately if the caller aborts so a pending
+    // retry wait does not keep the caller blocked for the full (potentially several second) delay.
+    await new Promise<void>((resolve, reject) => {
+      let onAbort: (() => void) | undefined
+      const timer = setTimeout(() => {
+        if (signal && onAbort) {
+          signal.removeEventListener('abort', onAbort)
+        }
+        resolve()
+      }, delay)
+      if (signal) {
+        onAbort = () => {
+          clearTimeout(timer)
+          reject(signal.reason ?? new Error('Aborted'))
+        }
+        if (signal.aborted) {
+          onAbort()
+          return
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+      }
+    })
+  }
+
+  private static isTransientStatus (status: number): boolean {
+    return status === 408 || status === 429 || status >= 500
+  }
+
+  private static parseTokenResponse (responseContent: string): SidecarTokenResult {
+    let body: { authorizationHeader?: unknown }
+    try {
+      body = JSON.parse(responseContent)
+    } catch (err) {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarResponseUnparsable, err as Error)
+    }
+
+    const headerValue = typeof body.authorizationHeader === 'string' ? body.authorizationHeader.trim() : ''
+    if (headerValue) {
+      const spaceIndex = headerValue.indexOf(' ')
+      if (spaceIndex > 0) {
+        // "{scheme} {token}" form: the token after the separator must be non-empty.
+        const token = headerValue.substring(spaceIndex + 1).trim()
+        if (token.length > 0) {
+          return { scheme: headerValue.substring(0, spaceIndex), token }
+        }
+      } else if (!SidecarHttpClient.isKnownAuthScheme(headerValue)) {
+        // No separator: treat the whole value as a raw token and default the scheme to
+        // Bearer. A lone scheme name (e.g. "Bearer") is not a valid token and falls
+        // through to the error below.
+        return { scheme: 'Bearer', token: headerValue }
+      }
+    }
+
+    throw ExceptionHelper.generateException(Error, Errors.SidecarResponseMissingAuthorizationHeader)
+  }
+
+  private static isKnownAuthScheme (value: string): boolean {
+    const lower = value.toLowerCase()
+    return lower === 'bearer' || lower === 'pop'
+  }
+
+  private static tryParseProblemDetails (content: string): SidecarProblemDetails | undefined {
+    if (!content) {
+      return undefined
+    }
+    try {
+      return JSON.parse(content) as SidecarProblemDetails
+    } catch {
+      return undefined
+    }
+  }
+}

package/src/auth/sidecar/sidecarModels.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthConfiguration } from '../authConfiguration'
+
+/**
+ * Default sidecar downstream API name used for app-only and autonomous agent token acquisition.
+ */
+const DEFAULT_SERVICE_NAME = 'default'
+
+/**
+ * Default sidecar downstream API name used to acquire the Blueprint (agent application) token.
+ */
+const DEFAULT_BLUEPRINT_SERVICE_NAME = 'agenticblueprint'
+
+/**
+ * Default base URL of the Entra Agent ID sidecar (agent container).
+ */
+export const DEFAULT_SIDECAR_BASE_URL = 'http://localhost:5178'
+
+/**
+ * Default per-attempt HTTP request timeout (in milliseconds) for sidecar calls.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000
+
+/**
+ * Default number of retry attempts for transient sidecar failures.
+ */
+export const DEFAULT_RETRY_COUNT = 3
+
+/**
+ * Resolved (normalized) connection settings for the sidecar-based token provider, derived from a
+ * connection's {@link AuthConfiguration} with all sidecar defaults applied. Distinct from the
+ * configuration-level {@link SidecarConnectionSettings} (which has optional properties): this is the
+ * runtime shape consumed by the provider after normalization via {@link toSidecarConnectionSettings}.
+ */
+export interface ResolvedSidecarConnectionSettings {
+  /**
+   * The configured downstream API service name in the sidecar's DownstreamApis configuration.
+   * Defaults to `'default'`.
+   */
+  serviceName: string
+
+  /**
+   * The sidecar downstream API name used to acquire the Blueprint (agent application) token for the
+   * agentic FIC chain. Defaults to `'agenticblueprint'`.
+   */
+  blueprintServiceName: string
+
+  /**
+   * Optional base URL of the Entra Agent ID sidecar (agent container). Resolution order:
+   * `SIDECAR_URL` environment variable > this setting > {@link DEFAULT_SIDECAR_BASE_URL}.
+   */
+  sidecarBaseUrl?: string
+
+  /**
+   * When `true`, disables the loopback/private-address safety check on the resolved sidecar base
+   * URL. UNSAFE; leave `false` in all normal deployments.
+   */
+  bypassLocalNetworkRestriction: boolean
+
+  /**
+   * Per-attempt HTTP request timeout (in milliseconds) for sidecar calls. Defaults to 30000.
+   */
+  requestTimeout: number
+
+  /**
+   * Number of retry attempts for transient sidecar failures. Defaults to 3.
+   */
+  retryCount: number
+
+  /**
+   * The OAuth scopes to request, used to override the sidecar's configured downstream API scopes.
+   */
+  scopes?: string[]
+}
+
+/**
+ * Builds a {@link ResolvedSidecarConnectionSettings} from a connection's {@link AuthConfiguration},
+ * applying the documented defaults.
+ * @param config The connection authentication configuration.
+ * @returns The resolved sidecar connection settings.
+ */
+export function toSidecarConnectionSettings (config?: AuthConfiguration): ResolvedSidecarConnectionSettings {
+  const scopes = config?.scopes ?? (config?.scope ? [config.scope] : undefined)
+  return {
+    serviceName: config?.serviceName?.trim() ? config.serviceName : DEFAULT_SERVICE_NAME,
+    blueprintServiceName: config?.blueprintServiceName?.trim() ? config.blueprintServiceName : DEFAULT_BLUEPRINT_SERVICE_NAME,
+    sidecarBaseUrl: config?.sidecarBaseUrl,
+    bypassLocalNetworkRestriction: config?.bypassLocalNetworkRestriction ?? false,
+    requestTimeout: config?.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    retryCount: config?.retryCount ?? DEFAULT_RETRY_COUNT,
+    scopes
+  }
+}
+
+/**
+ * Options used to build the query string for a sidecar token request. Mirrors the C#
+ * `SidecarRequestOptions` shape.
+ */
+export interface SidecarRequestOptions {
+  /** Agent app (client) ID for agent identity flows. Maps to `AgentIdentity`. */
+  agentIdentity?: string
+
+  /** Agentic user principal name for delegated agent flows. Maps to `AgentUsername`. */
+  agentUsername?: string
+
+  /** Agentic user object ID for delegated agent flows. Maps to `AgentUserId`. */
+  agentUserId?: string
+
+  /** Override the configured downstream API scopes. Maps to `optionsOverride.Scopes`. */
+  scopes?: string[]
+
+  /**
+   * Request an app-only token instead of a user (delegated) token. Maps to
+   * `optionsOverride.RequestAppToken=true`.
+   */
+  requestAppToken?: boolean
+
+  /** Override the tenant ID. Maps to `optionsOverride.AcquireTokenOptions.Tenant`. */
+  tenant?: string
+
+  /**
+   * Force a fresh token acquisition, bypassing the sidecar cache. Maps to
+   * `optionsOverride.AcquireTokenOptions.ForceRefresh=true`.
+   */
+  forceRefresh?: boolean
+}
+
+/**
+ * Result of a successful sidecar token acquisition. Mirrors the C# `SidecarTokenResult` shape.
+ */
+export interface SidecarTokenResult {
+  /** The authorization scheme (e.g., `'Bearer'` or `'PoP'`). */
+  scheme: string
+
+  /** The raw access token. */
+  token: string
+}
+
+/**
+ * RFC 7807 problem details returned by the sidecar on error. Mirrors the C# `SidecarProblemDetails`
+ * shape.
+ */
+export interface SidecarProblemDetails {
+  type?: string
+  title?: string
+  status?: number
+  detail?: string
+  instance?: string
+}

package/src/auth/sidecar/sidecarTokenExpiry.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import jwt from 'jsonwebtoken'
+
+/**
+ * Conservative lifetime (in milliseconds) applied when the token is opaque or carries no readable
+ * JWT `exp` claim.
+ */
+const FALLBACK_LIFETIME_MS = 5 * 60 * 1000
+
+/**
+ * Resolves the absolute expiry (epoch milliseconds) of a sidecar-issued token. Prefers the token's
+ * own JWT `exp` claim; falls back to {@link FALLBACK_LIFETIME_MS} from now when the token is opaque
+ * or carries no readable expiry.
+ * @param token The raw access token returned by the sidecar.
+ * @param now The current time in epoch milliseconds (defaults to `Date.now()`); primarily a test seam.
+ * @returns The absolute UTC expiry of the token, in epoch milliseconds.
+ */
+export function resolveTokenExpiry (token: string, now: number = Date.now()): number {
+  if (token) {
+    try {
+      const decoded = jwt.decode(token) as jwt.JwtPayload | null
+      if (decoded && typeof decoded.exp === 'number' && decoded.exp > 0) {
+        return decoded.exp * 1000
+      }
+    } catch {
+      // Opaque / non-JWT token — fall back below.
+    }
+  }
+
+  return now + FALLBACK_LIFETIME_MS
+}