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

package/dist/src/auth/sidecar/sidecarAuthProvider.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SidecarAuthProvider = void 0;
+const agents_telemetry_1 = require("@microsoft/agents-telemetry");
+const agents_activity_1 = require("@microsoft/agents-activity");
+const errorHelper_1 = require("../../errorHelper");
+const sidecarHttpClient_1 = require("./sidecarHttpClient");
+const sidecarTokenExpiry_1 = require("./sidecarTokenExpiry");
+const sidecarModels_1 = require("./sidecarModels");
+const logger = (0, agents_telemetry_1.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;
+/**
+ * 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.
+ */
+class SidecarAuthProvider {
+    /**
+     * Creates a new {@link SidecarAuthProvider}.
+     * @param connectionSettings The connection authentication configuration.
+     */
+    constructor(connectionSettings) {
+        this._tokenCache = new Map();
+        this.connectionSettings = connectionSettings;
+        this._settings = (0, sidecarModels_1.toSidecarConnectionSettings)(connectionSettings);
+        const resolvedUrl = sidecarHttpClient_1.SidecarHttpClient.resolveBaseUrl(this._settings.sidecarBaseUrl);
+        sidecarHttpClient_1.SidecarHttpClient.validateBaseUrl(resolvedUrl, this._settings.bypassLocalNetworkRestriction);
+        this._httpClient = new sidecarHttpClient_1.SidecarHttpClient(resolvedUrl, this._settings.requestTimeout, this._settings.retryCount);
+        logger.debug('SidecarAuthProvider initialized serviceName=%s blueprintServiceName=%s', this._settings.serviceName, this._settings.blueprintServiceName);
+    }
+    async getAccessToken(authConfigOrScope, scope) {
+        const actualScope = typeof authConfigOrScope === 'string' ? authConfigOrScope : scope;
+        const options = {
+            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, agentAppInstanceId) {
+        this.ensureConnectionSettings();
+        const options = {
+            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, agentAppInstanceId) {
+        this.ensureConnectionSettings();
+        const options = {
+            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, agentAppInstanceId, upn, scopes) {
+        this.ensureConnectionSettings();
+        const isObjectId = GUID_REGEX.test(upn !== null && upn !== void 0 ? upn : '');
+        const options = {
+            agentIdentity: agentAppInstanceId,
+            agentUsername: isObjectId ? undefined : upn,
+            agentUserId: isObjectId ? upn : undefined,
+            tenant: tenantId,
+            scopes: scopes !== null && scopes !== void 0 ? scopes : this._settings.scopes
+        };
+        return this.getCachedToken(this._settings.serviceName, options);
+    }
+    async acquireTokenOnBehalfOf(_authConfigOrScopes, _scopesOrOboAssertion, _oboAssertion) {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.OnBehalfOfNotSupportedBySidecar);
+    }
+    /**
+     * Checks sidecar availability via the `/healthz` endpoint.
+     * @returns `true` when the sidecar is reachable and healthy.
+     */
+    async isHealthy() {
+        return this._httpClient.isHealthy();
+    }
+    ensureConnectionSettings() {
+        if (!this.connectionSettings) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.SidecarConnectionSettingsRequired);
+        }
+    }
+    async getCachedToken(serviceName, options) {
+        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 agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.SidecarUnsupportedAuthScheme, undefined, { scheme: result.scheme });
+        }
+        this.cacheSet(cacheKey, { token: result.token, expiresOn: (0, sidecarTokenExpiry_1.resolveTokenExpiry)(result.token) });
+        return result.token;
+    }
+    cacheGet(cacheKey, forceRefresh) {
+        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;
+    }
+    cacheSet(cacheKey, token) {
+        this._tokenCache.set(cacheKey, token);
+        if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+            this.pruneExpiredEntries();
+            if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+                this.evictNearestExpiry();
+            }
+        }
+    }
+    pruneExpiredEntries() {
+        const now = Date.now();
+        for (const [key, value] of this._tokenCache) {
+            if (value.expiresOn <= now) {
+                this._tokenCache.delete(key);
+            }
+        }
+    }
+    evictNearestExpiry() {
+        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]);
+        }
+    }
+    static buildCacheKey(serviceName, options) {
+        var _a, _b, _c, _d;
+        const scopes = options.scopes
+            ? [...new Set(options.scopes.filter((s) => s && s.trim()))].sort().join(' ')
+            : '';
+        return [
+            serviceName,
+            (_a = options.agentIdentity) !== null && _a !== void 0 ? _a : '',
+            (_b = options.agentUsername) !== null && _b !== void 0 ? _b : '',
+            (_c = options.agentUserId) !== null && _c !== void 0 ? _c : '',
+            (_d = options.tenant) !== null && _d !== void 0 ? _d : '',
+            options.requestAppToken === true ? 'app' : 'user',
+            scopes
+        ].join('|');
+    }
+}
+exports.SidecarAuthProvider = SidecarAuthProvider;
+//# sourceMappingURL=sidecarAuthProvider.js.map

package/dist/src/auth/sidecar/sidecarAuthProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecarAuthProvider.js","sourceRoot":"","sources":["../../../../src/auth/sidecar/sidecarAuthProvider.ts"],"names":[],"mappings":"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"}

package/dist/src/auth/sidecar/sidecarConnectionSettings.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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;
+}

package/dist/src/auth/sidecar/sidecarConnectionSettings.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sidecarConnectionSettings.js.map

package/dist/src/auth/sidecar/sidecarConnectionSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecarConnectionSettings.js","sourceRoot":"","sources":["../../../../src/auth/sidecar/sidecarConnectionSettings.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/src/auth/sidecar/sidecarHttpClient.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { SidecarRequestOptions, SidecarTokenResult } from './sidecarModels';
+/**
+ * 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 declare class SidecarHttpClient {
+    /** Default per-attempt request timeout (milliseconds). */
+    static readonly DEFAULT_TIMEOUT_MS = 30000;
+    /** Default number of retry attempts for transient failures. */
+    static readonly DEFAULT_RETRY_COUNT = 3;
+    private readonly _baseUrl;
+    private readonly _timeoutMs;
+    private readonly _retryCount;
+    private readonly _retryBackoffBaseMs;
+    /**
+     * 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, retryCount?: number, retryBackoffBaseMs?: number);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    private static isLoopbackOrPrivateHost;
+    private static isPrivateOrLoopbackIPv4;
+    private static isPrivateOrLoopbackIPv6;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    getAuthorizationHeaderUnauthenticated(serviceName: string, options?: SidecarRequestOptions, signal?: AbortSignal): Promise<SidecarTokenResult>;
+    /**
+     * Checks sidecar health via `GET /healthz`.
+     * @returns `true` when the sidecar responds with a success status, `false` otherwise.
+     */
+    isHealthy(): Promise<boolean>;
+    private buildUrl;
+    private withTimeout;
+    private fetchWithTimeout;
+    /**
+     * 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 fetchAndReadText;
+    private sendAndParse;
+    private delayBeforeRetry;
+    private static isTransientStatus;
+    private static parseTokenResponse;
+    private static isKnownAuthScheme;
+    private static tryParseProblemDetails;
+}