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,133 @@
+import { UipEmbeddedEventNames, UipEmbeddedInitPayload, UipEmbeddedTokenRefreshedPayload } from './uip-embedded-protocol';
+import { TokenInfo } from './types';
+import { AuthenticationError, HttpStatus } from '../errors';
+import { Config } from '../config/config';
+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 config SDK configuration — `clientId` and `scope` are forwarded to
+   *   the host in every `UIP.refreshToken` request so it knows which OAuth
+   *   client to use when issuing a new token.
+   * @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 config: Config,
+    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,
+              content: { clientId: this.config.clientId, scope: this.config.scope },
+            },
+            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),
+    });
+  }
+}