feat(auth): generalised postMessage auth protocol for coded app embedding

Adds a generic UIP.* postMessage token-delegation protocol so any
first-party UiPath host (Insights UI, Governance Portal, etc.) can
embed a coded app and pass the user's active session without the
existing requirement to fake ?source=ActionCenter.

Changes:
- Add UipEmbeddedEventNames enum and payload types in
  src/core/auth/uip-embedded-protocol.ts (auth domain, not AC models)
- Add uipath:platform-hosted meta tag constant to UiPathMetaTags
- Thread platformHosted flag through SDK config chain: BaseConfig →
  ConfigSchema → UiPathConfig → loadFromMetaTags (only 'true' activates)
- Add EmbeddedTokenManager: passive window.message listener activated
  by UIP.init from a validated *.uipath.com/localhost origin; handles
  token refresh via UIP.refreshToken / UIP.tokenRefreshed
- Add host-token-request.ts: shared requestHostToken() helper used by
  both EmbeddedTokenManager and ActionCenterTokenManager, built on
  AbortController for clean timeout and cancellation handling
- Wire EmbeddedTokenManager into TokenManager via
  isBrowser && config.platformHosted === true — mutually exclusive with
  ActionCenterTokenManager; AC behaviour fully unchanged
- Add TokenManager.destroy() to release the EmbeddedTokenManager
  window listener; fix global.window and global.document test isolation
- 29 unit tests: origin validation, pinning, refresh flow, 8s timeout,
  concurrent deduplication, destroy cancellation, meta tag parsing,
  TokenManager routing and destroy delegation

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NishankSiddharth

src/core/auth/action-center-token-manager.ts

@@ -2,8 +2,7 @@ import { ActionCenterEventNames, ActionCenterEventResponsePayload } from '../../
 import { TokenInfo } from './types';
 import { AuthenticationError, HttpStatus } from '../errors';
 import { Config } from '../config/config';
-
-const AUTHENTICATION_TIMEOUT = 8000;
+import { HostTokenResponse, isTokenExpired, isValidHostOrigin, requestHostToken } from './host-token-request';
 
 export class ActionCenterTokenManager {
   private readonly parentOrigin = new URLSearchParams(window.location.search).get('basedomain');
@@ -15,96 +14,54 @@ export class ActionCenterTokenManager {
   ) {}
 
   async refreshAccessToken(tokenInfo: TokenInfo): Promise<string> {
-    if (!this.isTokenExpired(tokenInfo)) {
+    if (!isTokenExpired(tokenInfo)) {
       return tokenInfo.token;
     }
 
     if (this.refreshPromise) {
       return this.refreshPromise;
     }
 
-    this.refreshPromise = new Promise<string>((resolve, reject) => {
-      const content = {
-        clientId: this.config.clientId,
-        scope: this.config.scope,
-      }
-      this.sendMessageToParent(ActionCenterEventNames.REFRESHTOKEN, content);
-
-      const messageListener = (event: MessageEvent<ActionCenterEventResponsePayload>) => {
-        if (event.origin !== this.parentOrigin) return;
-        if (event.data?.eventType !== ActionCenterEventNames.TOKENREFRESHED) return;
-
-        clearTimeout(timer);
-
-        if (event.data?.content?.token) {
-          const { accessToken, expiresAt } = event.data.content.token;
-          this.onTokenRefreshed({ token: accessToken, type: 'secret', expiresAt });
-          resolve(accessToken);
-        } else {
-          reject(new AuthenticationError({
-            message: 'Failed to fetch access token',
-            statusCode: HttpStatus.UNAUTHORIZED,
-          }));
-        }
-
-        this.refreshPromise = null;
-        this.cleanup(messageListener);
-      };
-
-      const timer = setTimeout(() => {
-        reject(new AuthenticationError({
-          message: 'Failed to fetch access token',
+    const parentOrigin = this.parentOrigin;
+    if (!parentOrigin) {
+      return Promise.reject(
+        new AuthenticationError({
+          message: 'Cannot refresh token: basedomain query parameter is missing',
           statusCode: HttpStatus.UNAUTHORIZED,
-        }));
-
-        this.refreshPromise = null;
-        this.cleanup(messageListener);
-      }, AUTHENTICATION_TIMEOUT);
+        })
+      );
+    }
 
-      window.addEventListener('message', messageListener);
+    const { promise } = requestHostToken({
+      pinnedOrigin: parentOrigin,
+      sendRequest: () => this.sendMessageToParent(ActionCenterEventNames.REFRESHTOKEN, {
+        clientId: this.config.clientId,
+        scope: this.config.scope,
+      }),
+      responseEventType: ActionCenterEventNames.TOKENREFRESHED,
+      extractToken: (data): HostTokenResponse | undefined => {
+        const token = (data as ActionCenterEventResponsePayload)?.content?.token;
+        if (!token?.accessToken) return undefined;
+        return { accessToken: token.accessToken, expiresAt: token.expiresAt };
+      },
+      onTokenRefreshed: this.onTokenRefreshed,
     });
 
-    return this.refreshPromise;
-  }
-
-  private isTokenExpired(tokenInfo: TokenInfo): boolean {
-    if (!tokenInfo?.expiresAt) {
-      return true;
+    this.refreshPromise = promise;
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
     }
-
-    return new Date() >= tokenInfo.expiresAt;
   }
 
   private sendMessageToParent(eventType: string, content?: unknown): void {
-    if (window.parent && this.isValidOrigin(this.parentOrigin)) {
+    if (window.parent && isValidHostOrigin(this.parentOrigin)) {
       try {
         window.parent.postMessage({ eventType, content }, this.parentOrigin!);
       } catch (error) {
-        console.warn('Failed to send message to Action Center', JSON.stringify(error));
+        console.warn('ActionCenterTokenManager: postMessage to host failed', JSON.stringify(error));
       }
     }
   }
-
-  private cleanup(messageListener: (event: MessageEvent<ActionCenterEventResponsePayload>) => void): void {
-    window.removeEventListener('message', messageListener);
-  }
-
-  private isValidOrigin(origin: string | null): boolean {
-    const ALLOWED_ORIGINS = ['https://alpha.uipath.com', 'https://staging.uipath.com', 'https://cloud.uipath.com'];
-
-    if (!origin) {
-      return false;
-    }
-
-    if (ALLOWED_ORIGINS.includes(origin)) {
-      return true;
-    }
-
-    try {
-      const url = new URL(origin);
-      return url.hostname === 'localhost';
-    } catch {
-      return false;
-    }
-  }
 }

src/core/auth/embedded-token-manager.ts

@@ -0,0 +1,123 @@
+import { UipEmbeddedEventNames, UipEmbeddedInitPayload, UipEmbeddedTokenRefreshedPayload } from './uip-embedded-protocol';
+import { TokenInfo } from './types';
+import { AuthenticationError, HttpStatus } from '../errors';
+import { HostTokenResponse, isTokenExpired, isValidHostOrigin, requestHostToken } from './host-token-request';
+
+function parseExpiresAt(raw: string): Date {
+  const d = new Date(raw);
+  // Malformed date → treat as already expired (safe default)
+  return isNaN(d.getTime()) ? new Date(0) : d;
+}
+
+function extractToken(data: unknown): HostTokenResponse | undefined {
+  const token = (data as UipEmbeddedTokenRefreshedPayload)?.content?.token;
+  if (!token?.accessToken) return undefined;
+  return { accessToken: token.accessToken, expiresAt: parseExpiresAt(token.expiresAt) };
+}
+
+/**
+ * Handles token delegation for coded apps embedded inside a first-party
+ * UiPath host (e.g. Governance Portal, Insights UI).
+ *
+ * Lifecycle:
+ *  1. Constructed passively — registers a window message listener.
+ *  2. Activated — when the host sends UIP.init with a valid UiPath origin.
+ *  3. On token expiry — sends UIP.refreshToken to the host and awaits UIP.tokenRefreshed.
+ *  4. Destroyed — removes all listeners and cancels any in-flight refresh.
+ */
+export class EmbeddedTokenManager {
+  /**
+   * Null until a valid UIP.init is received.
+   * Once set it is the host origin we accept all subsequent messages from.
+   */
+  private pinnedOrigin: string | null = null;
+
+  private refreshPromise: Promise<string> | null = null;
+  private cancelRefresh: (() => void) | null = null;
+  private readonly initListener: (event: MessageEvent) => void;
+
+  /**
+   * @param onTokenRefreshed Called whenever a token is received or refreshed,
+   *   allowing the caller to persist the new token in the execution context.
+   */
+  constructor(private readonly onTokenRefreshed: (tokenInfo: TokenInfo) => void) {
+    this.initListener = this.handleInit.bind(this);
+    window.addEventListener('message', this.initListener);
+  }
+
+  isActive(): boolean {
+    return this.pinnedOrigin !== null;
+  }
+
+  async refreshAccessToken(tokenInfo: TokenInfo): Promise<string> {
+    if (!isTokenExpired(tokenInfo)) {
+      return tokenInfo.token;
+    }
+
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+
+    this.refreshPromise = this.requestRefresh();
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+      this.cancelRefresh = null;
+    }
+  }
+
+  destroy(): void {
+    window.removeEventListener('message', this.initListener);
+    this.cancelRefresh?.();
+  }
+
+  private requestRefresh(): Promise<string> {
+    const pinnedOrigin = this.pinnedOrigin;
+    if (!pinnedOrigin) {
+      return Promise.reject(
+        new AuthenticationError({
+          message: 'Cannot refresh token: embedded manager has not received a UIP.init from the host',
+          statusCode: HttpStatus.UNAUTHORIZED,
+        })
+      );
+    }
+
+    const { promise, cancel } = requestHostToken({
+      pinnedOrigin,
+      sendRequest: () => {
+        try {
+          window.parent.postMessage(
+            { eventType: UipEmbeddedEventNames.REFRESH_TOKEN },
+            pinnedOrigin
+          );
+        } catch (error) {
+          console.warn('EmbeddedTokenManager: postMessage to host failed', error);
+        }
+      },
+      responseEventType: UipEmbeddedEventNames.TOKEN_REFRESHED,
+      extractToken,
+      onTokenRefreshed: this.onTokenRefreshed,
+    });
+
+    this.cancelRefresh = cancel;
+    return promise;
+  }
+
+  private handleInit(event: MessageEvent<UipEmbeddedInitPayload>): void {
+    if (event.data?.eventType !== UipEmbeddedEventNames.INIT) return;
+    if (this.pinnedOrigin !== null) return; // already activated — ignore subsequent inits
+    if (!isValidHostOrigin(event.origin)) return;
+
+    const tokenData = event.data?.content?.token;
+    if (!tokenData?.accessToken) return;
+
+    this.pinnedOrigin = event.origin;
+
+    this.onTokenRefreshed({
+      token: tokenData.accessToken,
+      type: 'secret',
+      expiresAt: parseExpiresAt(tokenData.expiresAt),
+    });
+  }
+}

src/core/auth/host-token-request.ts

@@ -0,0 +1,138 @@
+import { TokenInfo } from './types';
+import { AuthenticationError, HttpStatus } from '../errors';
+
+export const AUTHENTICATION_TIMEOUT = 8000;
+
+const ALLOWED_HOST_ORIGINS = new Set([
+  'https://alpha.uipath.com',
+  'https://staging.uipath.com',
+  'https://cloud.uipath.com',
+]);
+
+/**
+ * Returns true if the origin is a trusted UiPath host that may initiate
+ * token delegation. Mirrors the same allowlist used by ActionCenterTokenManager.
+ */
+export function isValidHostOrigin(origin: string | null): boolean {
+  if (!origin) return false;
+  if (ALLOWED_HOST_ORIGINS.has(origin)) return true;
+  try {
+    return new URL(origin).hostname === 'localhost';
+  } catch {
+    return false;
+  }
+}
+
+export function isTokenExpired(tokenInfo: TokenInfo): boolean {
+  if (!tokenInfo.expiresAt) return true;
+  return new Date() >= tokenInfo.expiresAt;
+}
+
+export interface HostTokenResponse {
+  accessToken: string;
+  expiresAt: Date;
+}
+
+export interface HostTokenRequestOptions {
+  /** Origin the request is sent to and responses accepted from. */
+  pinnedOrigin: string;
+  /** Sends the refresh request to the parent frame. */
+  sendRequest: () => void;
+  /** Event type string the host sends back with the refreshed token. */
+  responseEventType: string;
+  /** Extracts the token from the host response message. Returns undefined if the payload is malformed. */
+  extractToken: (data: unknown) => HostTokenResponse | undefined;
+  /** Called with the refreshed TokenInfo before the promise resolves. */
+  onTokenRefreshed: (tokenInfo: TokenInfo) => void;
+}
+
+export interface HostTokenRequest {
+  readonly promise: Promise<string>;
+  /** Immediately rejects the promise and removes the response listener. */
+  readonly cancel: () => void;
+}
+
+/**
+ * Waits for the next window message that satisfies `filter`.
+ * Rejects if the AbortSignal fires before a matching message arrives.
+ */
+function waitForMessage(
+  filter: (event: MessageEvent) => boolean,
+  signal: AbortSignal
+): Promise<MessageEvent> {
+  return new Promise((resolve, reject) => {
+    const handler = (event: MessageEvent): void => {
+      if (!filter(event)) return;
+      window.removeEventListener('message', handler);
+      resolve(event);
+    };
+
+    signal.addEventListener('abort', () => {
+      window.removeEventListener('message', handler);
+      reject(signal.reason);
+    }, { once: true });
+
+    window.addEventListener('message', handler);
+  });
+}
+
+/**
+ * Sends a token-refresh request to a parent host frame and waits for the
+ * response. Handles timeout, origin filtering, and listener cleanup.
+ *
+ * Both ActionCenterTokenManager and EmbeddedTokenManager delegate to this
+ * function; they differ only in the event names and message shape they use.
+ */
+export function requestHostToken(options: HostTokenRequestOptions): HostTokenRequest {
+  const { pinnedOrigin, sendRequest, responseEventType, extractToken, onTokenRefreshed } = options;
+
+  const controller = new AbortController();
+
+  const cancel = (): void =>
+    controller.abort(
+      new AuthenticationError({
+        message: 'Token refresh cancelled',
+        statusCode: HttpStatus.UNAUTHORIZED,
+      })
+    );
+
+  const promise = (async (): Promise<string> => {
+    const timer = setTimeout(
+      () =>
+        controller.abort(
+          new AuthenticationError({
+            message: `Token refresh timed out after ${AUTHENTICATION_TIMEOUT}ms waiting for host response`,
+            statusCode: HttpStatus.UNAUTHORIZED,
+          })
+        ),
+      AUTHENTICATION_TIMEOUT
+    );
+
+    try {
+      // Register listener before sending — avoids any race between send and response
+      const responsePromise = waitForMessage(
+        event => event.origin === pinnedOrigin && event.data?.eventType === responseEventType,
+        controller.signal
+      );
+
+      sendRequest();
+
+      const event = await responsePromise;
+
+      const token = extractToken(event.data);
+      if (!token) {
+        throw new AuthenticationError({
+          message: 'Host responded but did not include a valid access token',
+          statusCode: HttpStatus.UNAUTHORIZED,
+        });
+      }
+
+      onTokenRefreshed({ token: token.accessToken, type: 'secret', expiresAt: token.expiresAt });
+      return token.accessToken;
+    } finally {
+      clearTimeout(timer);
+    }
+  })();
+
+  return { promise, cancel };
+}