fix(auth): address PR review findings

- Add TokenManager.destroy() to prevent EmbeddedTokenManager listener leak
- Restore global.document in afterEach to fix runtime.test.ts isolation
- Move UIP.* protocol types to src/core/auth/uip-embedded-protocol.ts
  (were incorrectly placed in Action Center models domain)
- Remove unused UipEmbeddedRefreshTokenPayload type
- Add @param JSDoc to EmbeddedTokenManager constructor

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

Author: NishankSiddharth

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

@@ -1,4 +1,4 @@
-import { UipEmbeddedEventNames, UipEmbeddedInitPayload, UipEmbeddedTokenRefreshedPayload } from '../../models/action-center/tasks.internal-types';
+import { UipEmbeddedEventNames, UipEmbeddedInitPayload, UipEmbeddedTokenRefreshedPayload } from './uip-embedded-protocol';
 import { TokenInfo } from './types';
 import { AuthenticationError, HttpStatus } from '../errors';
 import { HostTokenResponse, isTokenExpired, requestHostToken } from './host-token-request';
@@ -49,6 +49,10 @@ export class EmbeddedTokenManager {
   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);

src/core/auth/token-manager.ts

@@ -237,6 +237,14 @@ export class TokenManager {
     return true;
   }
 
+  /**
+   * Releases resources held by this instance.
+   * Must be called when the TokenManager is no longer needed to prevent listener leaks.
+   */
+  destroy(): void {
+    this.embeddedTokenManager?.destroy();
+  }
+
   /**
    * Clears the current token
    */

src/core/auth/uip-embedded-protocol.ts

@@ -0,0 +1,35 @@
+/**
+ * Event names and payload types for the UIP.* postMessage protocol used
+ * when a coded app is embedded inside a first-party UiPath host.
+ *
+ * Flow:
+ *  Host → App: UIP.init       (delivers initial access token)
+ *  App → Host: UIP.refreshToken (requests a new token on expiry)
+ *  Host → App: UIP.tokenRefreshed (delivers refreshed access token)
+ */
+
+export enum UipEmbeddedEventNames {
+  INIT            = 'UIP.init',
+  REFRESH_TOKEN   = 'UIP.refreshToken',
+  TOKEN_REFRESHED = 'UIP.tokenRefreshed',
+}
+
+export type UipEmbeddedInitPayload = {
+  eventType: UipEmbeddedEventNames.INIT,
+  content: {
+    token: {
+      accessToken: string,
+      expiresAt: string, // ISO 8601
+    },
+  },
+};
+
+export type UipEmbeddedTokenRefreshedPayload = {
+  eventType: UipEmbeddedEventNames.TOKEN_REFRESHED,
+  content: {
+    token: {
+      accessToken: string,
+      expiresAt: string, // ISO 8601
+    },
+  },
+};

src/models/action-center/tasks.internal-types.ts

@@ -30,36 +30,6 @@ export type ActionCenterEventResponsePayload = {
   content: ActionCenterTokenData,
 }
 
-export enum UipEmbeddedEventNames {
-  INIT            = 'UIP.init',
-  REFRESH_TOKEN   = 'UIP.refreshToken',
-  TOKEN_REFRESHED = 'UIP.tokenRefreshed',
-}
-
-export type UipEmbeddedInitPayload = {
-  eventType: UipEmbeddedEventNames.INIT,
-  content: {
-    token: {
-      accessToken: string,
-      expiresAt: string, // ISO 8601
-    },
-  },
-};
-
-export type UipEmbeddedTokenRefreshedPayload = {
-  eventType: UipEmbeddedEventNames.TOKEN_REFRESHED,
-  content: {
-    token: {
-      accessToken: string,
-      expiresAt: string, // ISO 8601
-    },
-  },
-};
-
-export type UipEmbeddedRefreshTokenPayload = {
-  eventType: UipEmbeddedEventNames.REFRESH_TOKEN,
-};
-
 export interface TasksAssignOptions {
     taskAssignments: TaskAssignmentOptions[];
 }

tests/unit/core/auth/embedded-token-manager.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { EmbeddedTokenManager } from '../../../../src/core/auth/embedded-token-manager';
-import { UipEmbeddedEventNames } from '../../../../src/models/action-center/tasks.internal-types';
+import { UipEmbeddedEventNames } from '../../../../src/core/auth/uip-embedded-protocol';
 import { AuthenticationError } from '../../../../src/core/errors';
 import type { TokenInfo } from '../../../../src/core/auth/types';
 

tests/unit/core/auth/token-manager-embedded.test.ts

@@ -133,4 +133,30 @@ describe('TokenManager — EmbeddedTokenManager wiring', () => {
     expect(result).toBe('my-secret');
     expect(mockEmbeddedRefresh).not.toHaveBeenCalled();
   });
+
+  // ---- destroy ----
+
+  it('destroy() delegates to EmbeddedTokenManager', () => {
+    vi.mocked(platform).isBrowser = true;
+    vi.mocked(platform).isInActionCenter = false;
+    const mockDestroy = vi.fn();
+    vi.mocked(EmbeddedTokenManager).mockImplementationOnce(() => ({
+      isActive: mockEmbeddedIsActive,
+      refreshAccessToken: mockEmbeddedRefresh,
+      destroy: mockDestroy,
+    }));
+
+    const manager = makeManager(true);
+    manager.destroy();
+
+    expect(mockDestroy).toHaveBeenCalledOnce();
+  });
+
+  it('destroy() is a no-op when EmbeddedTokenManager was not instantiated', () => {
+    vi.mocked(platform).isBrowser = false;
+    vi.mocked(platform).isInActionCenter = false;
+    const manager = makeManager();
+
+    expect(() => manager.destroy()).not.toThrow();
+  });
 });

tests/unit/core/config/runtime.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 // Must mock platform before importing runtime
 vi.mock('../../../../src/utils/platform', () => ({ isBrowser: true }));
@@ -27,6 +27,10 @@ beforeEach(() => {
   global.document = { querySelector: mockQuerySelector } as unknown as Document;
 });
 
+afterEach(() => {
+  delete (global as unknown as Record<string, unknown>).document;
+});
+
 // ---------------------------------------------------------------------------
 // platformHosted meta tag tests
 // ---------------------------------------------------------------------------