@azure/msal-browser 4.12.0 → 4.13.0

package/src/broker/nativeBroker/{NativeMessageHandler.ts → PlatformAuthExtensionHandler.ts}

@@ -4,7 +4,7 @@
  */
 
 import {
-    NativeConstants,
+    PlatformAuthConstants,
     NativeExtensionMethod,
 } from "../../utils/BrowserConstants.js";
 import {
@@ -12,7 +12,6 @@ import {
     AuthError,
     createAuthError,
     AuthErrorCodes,
-    AuthenticationScheme,
     InProgressPerformanceEvent,
     PerformanceEvents,
     IPerformanceClient,
@@ -20,14 +19,16 @@ import {
 import {
     NativeExtensionRequest,
     NativeExtensionRequestBody,
-} from "./NativeRequest.js";
+    PlatformAuthRequest,
+} from "./PlatformAuthRequest.js";
 import { createNativeAuthError } from "../../error/NativeAuthError.js";
 import {
     createBrowserAuthError,
     BrowserAuthErrorCodes,
 } from "../../error/BrowserAuthError.js";
-import { BrowserConfiguration } from "../../config/Configuration.js";
 import { createNewGuid } from "../../crypto/BrowserCrypto.js";
+import { PlatformAuthResponse } from "./PlatformAuthResponse.js";
+import { IPlatformAuthHandler } from "./IPlatformAuthHandler.js";
 
 type ResponseResolvers<T> = {
     resolve: (value: T | PromiseLike<T>) => void;
@@ -36,7 +37,7 @@ type ResponseResolvers<T> = {
     ) => void;
 };
 
-export class NativeMessageHandler {
+export class PlatformAuthExtensionHandler implements IPlatformAuthHandler {
     private extensionId: string | undefined;
     private extensionVersion: string | undefined;
     private logger: Logger;
@@ -48,6 +49,7 @@ export class NativeMessageHandler {
     private readonly windowListener: (event: MessageEvent) => void;
     private readonly performanceClient: IPerformanceClient;
     private readonly handshakeEvent: InProgressPerformanceEvent;
+    platformAuthType: string;
 
     constructor(
         logger: Logger,
@@ -66,34 +68,51 @@ export class NativeMessageHandler {
         this.handshakeEvent = performanceClient.startMeasurement(
             PerformanceEvents.NativeMessageHandlerHandshake
         );
+        this.platformAuthType =
+            PlatformAuthConstants.PLATFORM_EXTENSION_PROVIDER;
     }
 
     /**
      * Sends a given message to the extension and resolves with the extension response
-     * @param body
+     * @param request
      */
-    async sendMessage(body: NativeExtensionRequestBody): Promise<object> {
-        this.logger.trace("NativeMessageHandler - sendMessage called.");
+    async sendMessage(
+        request: PlatformAuthRequest
+    ): Promise<PlatformAuthResponse> {
+        this.logger.trace(this.platformAuthType + " - sendMessage called.");
+
+        // fall back to native calls
+        const messageBody: NativeExtensionRequestBody = {
+            method: NativeExtensionMethod.GetToken,
+            request: request,
+        };
+
         const req: NativeExtensionRequest = {
-            channel: NativeConstants.CHANNEL_ID,
+            channel: PlatformAuthConstants.CHANNEL_ID,
             extensionId: this.extensionId,
             responseId: createNewGuid(),
-            body: body,
+            body: messageBody,
         };
 
         this.logger.trace(
-            "NativeMessageHandler - Sending request to browser extension"
+            this.platformAuthType + " - Sending request to browser extension"
         );
         this.logger.tracePii(
-            `NativeMessageHandler - Sending request to browser extension: ${JSON.stringify(
-                req
-            )}`
+            this.platformAuthType +
+                ` - Sending request to browser extension: ${JSON.stringify(
+                    req
+                )}`
         );
         this.messageChannel.port1.postMessage(req);
 
-        return new Promise((resolve, reject) => {
+        const response: object = await new Promise((resolve, reject) => {
             this.resolvers.set(req.responseId, { resolve, reject });
         });
+
+        const validatedResponse: PlatformAuthResponse =
+            this.validatePlatformBrokerResponse(response);
+
+        return validatedResponse;
     }
 
     /**
@@ -107,20 +126,21 @@ export class NativeMessageHandler {
         logger: Logger,
         handshakeTimeoutMs: number,
         performanceClient: IPerformanceClient
-    ): Promise<NativeMessageHandler> {
-        logger.trace("NativeMessageHandler - createProvider called.");
+    ): Promise<PlatformAuthExtensionHandler> {
+        logger.trace("PlatformAuthExtensionHandler - createProvider called.");
+
         try {
-            const preferredProvider = new NativeMessageHandler(
+            const preferredProvider = new PlatformAuthExtensionHandler(
                 logger,
                 handshakeTimeoutMs,
                 performanceClient,
-                NativeConstants.PREFERRED_EXTENSION_ID
+                PlatformAuthConstants.PREFERRED_EXTENSION_ID
             );
             await preferredProvider.sendHandshakeRequest();
             return preferredProvider;
         } catch (e) {
             // If preferred extension fails for whatever reason, fallback to using any installed extension
-            const backupProvider = new NativeMessageHandler(
+            const backupProvider = new PlatformAuthExtensionHandler(
                 logger,
                 handshakeTimeoutMs,
                 performanceClient
@@ -135,13 +155,13 @@ export class NativeMessageHandler {
      */
     private async sendHandshakeRequest(): Promise<void> {
         this.logger.trace(
-            "NativeMessageHandler - sendHandshakeRequest called."
+            this.platformAuthType + " - sendHandshakeRequest called."
         );
         // Register this event listener before sending handshake
         window.addEventListener("message", this.windowListener, false); // false is important, because content script message processing should work first
 
         const req: NativeExtensionRequest = {
-            channel: NativeConstants.CHANNEL_ID,
+            channel: PlatformAuthConstants.CHANNEL_ID,
             extensionId: this.extensionId,
             responseId: createNewGuid(),
             body: {
@@ -192,7 +212,7 @@ export class NativeMessageHandler {
      * @param event
      */
     private onWindowMessage(event: MessageEvent): void {
-        this.logger.trace("NativeMessageHandler - onWindowMessage called");
+        this.logger.trace(this.platformAuthType + " - onWindowMessage called");
         // We only accept messages from ourselves
         if (event.source !== window) {
             return;
@@ -202,7 +222,7 @@ export class NativeMessageHandler {
 
         if (
             !request.channel ||
-            request.channel !== NativeConstants.CHANNEL_ID
+            request.channel !== PlatformAuthConstants.CHANNEL_ID
         ) {
             return;
         }
@@ -221,7 +241,8 @@ export class NativeMessageHandler {
              */
             if (!handshakeResolver) {
                 this.logger.trace(
-                    `NativeMessageHandler.onWindowMessage - resolver can't be found for request ${request.responseId}`
+                    this.platformAuthType +
+                        `.onWindowMessage - resolver can't be found for request ${request.responseId}`
                 );
                 return;
             }
@@ -253,7 +274,9 @@ export class NativeMessageHandler {
      * @param event
      */
     private onChannelMessage(event: MessageEvent): void {
-        this.logger.trace("NativeMessageHandler - onChannelMessage called.");
+        this.logger.trace(
+            this.platformAuthType + " - onChannelMessage called."
+        );
         const request = event.data;
 
         const resolver = this.resolvers.get(request.responseId);
@@ -270,12 +293,14 @@ export class NativeMessageHandler {
                 }
                 const response = request.body.response;
                 this.logger.trace(
-                    "NativeMessageHandler - Received response from browser extension"
+                    this.platformAuthType +
+                        " - Received response from browser extension"
                 );
                 this.logger.tracePii(
-                    `NativeMessageHandler - Received response from browser extension: ${JSON.stringify(
-                        response
-                    )}`
+                    this.platformAuthType +
+                        ` - Received response from browser extension: ${JSON.stringify(
+                            response
+                        )}`
                 );
                 if (response.status !== "Success") {
                     resolver.reject(
@@ -310,7 +335,8 @@ export class NativeMessageHandler {
             } else if (method === NativeExtensionMethod.HandshakeResponse) {
                 if (!handshakeResolver) {
                     this.logger.trace(
-                        `NativeMessageHandler.onChannelMessage - resolver can't be found for request ${request.responseId}`
+                        this.platformAuthType +
+                            `.onChannelMessage - resolver can't be found for request ${request.responseId}`
                     );
                     return;
                 }
@@ -323,7 +349,8 @@ export class NativeMessageHandler {
                 this.extensionId = request.extensionId;
                 this.extensionVersion = request.body.version;
                 this.logger.verbose(
-                    `NativeMessageHandler - Received HandshakeResponse from extension: ${this.extensionId}`
+                    this.platformAuthType +
+                        ` - Received HandshakeResponse from extension: ${this.extensionId}`
                 );
                 this.handshakeEvent.end({
                     extensionInstalled: true,
@@ -349,6 +376,30 @@ export class NativeMessageHandler {
         }
     }
 
+    /**
+     * Validates native platform response before processing
+     * @param response
+     */
+    private validatePlatformBrokerResponse(
+        response: object
+    ): PlatformAuthResponse {
+        if (
+            response.hasOwnProperty("access_token") &&
+            response.hasOwnProperty("id_token") &&
+            response.hasOwnProperty("client_info") &&
+            response.hasOwnProperty("account") &&
+            response.hasOwnProperty("scope") &&
+            response.hasOwnProperty("expires_in")
+        ) {
+            return response as PlatformAuthResponse;
+        } else {
+            throw createAuthError(
+                AuthErrorCodes.unexpectedError,
+                "Response missing expected properties."
+            );
+        }
+    }
+
     /**
      * Returns the Id for the browser extension this handler is communicating with
      * @returns
@@ -365,52 +416,12 @@ export class NativeMessageHandler {
         return this.extensionVersion;
     }
 
-    /**
-     * Returns boolean indicating whether or not the request should attempt to use native broker
-     * @param logger
-     * @param config
-     * @param nativeExtensionProvider
-     * @param authenticationScheme
-     */
-    static isPlatformBrokerAvailable(
-        config: BrowserConfiguration,
-        logger: Logger,
-        nativeExtensionProvider?: NativeMessageHandler,
-        authenticationScheme?: AuthenticationScheme
-    ): boolean {
-        logger.trace("isPlatformBrokerAvailable called");
-        if (!config.system.allowPlatformBroker) {
-            logger.trace(
-                "isPlatformBrokerAvailable: allowPlatformBroker is not enabled, returning false"
-            );
-            // Developer disabled WAM
-            return false;
-        }
-
-        if (!nativeExtensionProvider) {
-            logger.trace(
-                "isPlatformBrokerAvailable: Platform extension provider is not initialized, returning false"
-            );
-            // Extension is not available
-            return false;
-        }
-
-        if (authenticationScheme) {
-            switch (authenticationScheme) {
-                case AuthenticationScheme.BEARER:
-                case AuthenticationScheme.POP:
-                    logger.trace(
-                        "isPlatformBrokerAvailable: authenticationScheme is supported, returning true"
-                    );
-                    return true;
-                default:
-                    logger.trace(
-                        "isPlatformBrokerAvailable: authenticationScheme is not supported, returning false"
-                    );
-                    return false;
-            }
-        }
-
-        return true;
+    getExtensionName(): string | undefined {
+        return this.getExtensionId() ===
+            PlatformAuthConstants.PREFERRED_EXTENSION_ID
+            ? "chrome"
+            : this.getExtensionId()?.length
+            ? "unknown"
+            : undefined;
     }
 }

package/src/broker/nativeBroker/PlatformAuthProvider.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    LoggerOptions,
+    IPerformanceClient,
+    Logger,
+    AuthenticationScheme,
+    StubPerformanceClient,
+} from "@azure/msal-common/browser";
+import { name, version } from "../../packageMetadata.js";
+import {
+    BrowserConfiguration,
+    DEFAULT_NATIVE_BROKER_HANDSHAKE_TIMEOUT_MS,
+} from "../../config/Configuration.js";
+import { PlatformAuthExtensionHandler } from "./PlatformAuthExtensionHandler.js";
+import { IPlatformAuthHandler } from "./IPlatformAuthHandler.js";
+import { PlatformAuthDOMHandler } from "./PlatformAuthDOMHandler.js";
+import { createNewGuid } from "../../crypto/BrowserCrypto.js";
+import {
+    BrowserCacheLocation,
+    PLATFORM_AUTH_DOM_SUPPORT,
+} from "../../utils/BrowserConstants.js";
+
+/**
+ * Checks if the platform broker is available in the current environment.
+ * @param loggerOptions
+ * @param perfClient
+ * @returns
+ */
+export async function isPlatformBrokerAvailable(
+    loggerOptions?: LoggerOptions,
+    perfClient?: IPerformanceClient,
+    correlationId?: string
+): Promise<boolean> {
+    const logger = new Logger(loggerOptions || {}, name, version);
+
+    logger.trace("isPlatformBrokerAvailable called");
+
+    const performanceClient = perfClient || new StubPerformanceClient();
+
+    if (typeof window === "undefined") {
+        logger.trace("Non-browser environment detected, returning false");
+        return false;
+    }
+
+    return !!(await getPlatformAuthProvider(
+        logger,
+        performanceClient,
+        correlationId || createNewGuid()
+    ));
+}
+
+export async function getPlatformAuthProvider(
+    logger: Logger,
+    performanceClient: IPerformanceClient,
+    correlationId: string,
+    nativeBrokerHandshakeTimeout?: number
+): Promise<IPlatformAuthHandler | undefined> {
+    logger.trace("getPlatformAuthProvider called", correlationId);
+
+    const enablePlatformBrokerDOMSupport = isDomEnabledForPlatformAuth();
+
+    logger.trace(
+        "Has client allowed platform auth via DOM API: " +
+            enablePlatformBrokerDOMSupport
+    );
+    let platformAuthProvider: IPlatformAuthHandler | undefined;
+    try {
+        if (enablePlatformBrokerDOMSupport) {
+            // Check if DOM platform API is supported first
+            platformAuthProvider = await PlatformAuthDOMHandler.createProvider(
+                logger,
+                performanceClient,
+                correlationId
+            );
+        }
+        if (!platformAuthProvider) {
+            logger.trace(
+                "Platform auth via DOM API not available, checking for extension"
+            );
+            /*
+             * If DOM APIs are not available, check if browser extension is available.
+             * Platform authentication via DOM APIs is preferred over extension APIs.
+             */
+            platformAuthProvider =
+                await PlatformAuthExtensionHandler.createProvider(
+                    logger,
+                    nativeBrokerHandshakeTimeout ||
+                        DEFAULT_NATIVE_BROKER_HANDSHAKE_TIMEOUT_MS,
+                    performanceClient
+                );
+        }
+    } catch (e) {
+        logger.trace("Platform auth not available", e as string);
+    }
+    return platformAuthProvider;
+}
+
+/**
+ * Returns true if the DOM API support for platform auth is enabled in session storage
+ * @returns boolean
+ * @deprecated
+ */
+export function isDomEnabledForPlatformAuth(): boolean {
+    let sessionStorage: Storage | undefined;
+    try {
+        sessionStorage = window[BrowserCacheLocation.SessionStorage];
+        // Mute errors if it's a non-browser environment or cookies are blocked.
+        return sessionStorage?.getItem(PLATFORM_AUTH_DOM_SUPPORT) === "true";
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * Returns boolean indicating whether or not the request should attempt to use native broker
+ * @param logger
+ * @param config
+ * @param platformAuthProvider
+ * @param authenticationScheme
+ */
+export function isPlatformAuthAllowed(
+    config: BrowserConfiguration,
+    logger: Logger,
+    platformAuthProvider?: IPlatformAuthHandler,
+    authenticationScheme?: AuthenticationScheme
+): boolean {
+    logger.trace("isBrokerAvailable called");
+    if (!config.system.allowPlatformBroker) {
+        logger.trace(
+            "isBrokerAvailable: allowPlatformBroker is not enabled, returning false"
+        );
+        // Developer disabled WAM
+        return false;
+    }
+
+    if (!platformAuthProvider) {
+        logger.trace(
+            "isBrokerAvailable: Platform auth provider is not initialized, returning false"
+        );
+        // Platform broker auth providers are not available
+        return false;
+    }
+
+    if (authenticationScheme) {
+        switch (authenticationScheme) {
+            case AuthenticationScheme.BEARER:
+            case AuthenticationScheme.POP:
+                logger.trace(
+                    "isBrokerAvailable: authenticationScheme is supported, returning true"
+                );
+                return true;
+            default:
+                logger.trace(
+                    "isBrokerAvailable: authenticationScheme is not supported, returning false"
+                );
+                return false;
+        }
+    }
+    return true;
+}

package/src/broker/nativeBroker/{NativeRequest.ts → PlatformAuthRequest.ts}

@@ -9,7 +9,7 @@ import { StoreInCache, StringDict } from "@azure/msal-common/browser";
 /**
  * Token request which native broker will use to acquire tokens
  */
-export type NativeTokenRequest = {
+export type PlatformAuthRequest = {
     accountId: string; // WAM specific account id used for identification of WAM account. This can be any broker-id eventually
     clientId: string;
     authority: string;
@@ -40,7 +40,7 @@ export type NativeTokenRequest = {
  */
 export type NativeExtensionRequestBody = {
     method: NativeExtensionMethod;
-    request?: NativeTokenRequest;
+    request?: PlatformAuthRequest;
 };
 
 /**
@@ -52,3 +52,42 @@ export type NativeExtensionRequest = {
     extensionId?: string;
     body: NativeExtensionRequestBody;
 };
+
+export type PlatformDOMTokenRequest = {
+    brokerId: string;
+    accountId?: string;
+    clientId: string;
+    authority: string;
+    scope: string;
+    redirectUri: string;
+    correlationId: string;
+    isSecurityTokenService: boolean;
+    state?: string;
+    /*
+     * Known optional parameters will go into extraQueryParameters.
+     * List of known parameters is:
+     * "prompt", "nonce", "claims", "loginHint", "instanceAware", "windowTitleSubstring", "extendedExpiryToken", "storeInCache",
+     * ProofOfPossessionParams: "reqCnf", "keyId", "tokenType", "shrClaims", "shrNonce", "resourceRequestMethod", "resourceRequestUri", "signPopToken"
+     */
+    extraParameters?: DOMExtraParameters;
+    embeddedClientId?: string;
+    storeInCache?: StoreInCache; // Object of booleans indicating whether to store tokens in the cache or not (default is true)
+};
+
+export type DOMExtraParameters = StringDict & {
+    prompt?: string;
+    nonce?: string;
+    claims?: string;
+    loginHint?: string;
+    instanceAware?: string;
+    windowTitleSubstring?: string;
+    extendedExpiryToken?: string;
+    reqCnf?: string;
+    keyId?: string;
+    tokenType?: string;
+    shrClaims?: string;
+    shrNonce?: string;
+    resourceRequestMethod?: string;
+    resourceRequestUri?: string;
+    signPopToken?: string; // Set to true only if token request deos not contain a PoP keyId
+};

package/src/broker/nativeBroker/{NativeResponse.ts → PlatformAuthResponse.ts}

@@ -15,7 +15,7 @@ export type NativeAccountInfo = {
 /**
  * Token response returned by Native Platform
  */
-export type NativeResponse = {
+export type PlatformAuthResponse = {
     access_token: string;
     account: NativeAccountInfo;
     client_info: string;
@@ -54,3 +54,27 @@ export type MATS = {
     http_status?: number;
     http_event_count?: number;
 };
+
+export type PlatformDOMTokenResponse = {
+    isSuccess: boolean;
+    state?: string;
+    accessToken: string;
+    expiresIn: number;
+    account: NativeAccountInfo;
+    clientInfo: string;
+    idToken: string;
+    scopes: string;
+    proofOfPossessionPayload?: string;
+    extendedLifetimeToken?: boolean;
+    error: ErrorResult;
+    properties?: Record<string, string>;
+};
+
+export type ErrorResult = {
+    code: string;
+    description?: string;
+    errorCode: string;
+    protocolError?: string;
+    status: string;
+    properties?: object;
+};

package/src/cache/BrowserCacheManager.ts

@@ -53,7 +53,7 @@ import { LocalStorage } from "./LocalStorage.js";
 import { SessionStorage } from "./SessionStorage.js";
 import { MemoryStorage } from "./MemoryStorage.js";
 import { IWindowStorage } from "./IWindowStorage.js";
-import { NativeTokenRequest } from "../broker/nativeBroker/NativeRequest.js";
+import { PlatformAuthRequest } from "../broker/nativeBroker/PlatformAuthRequest.js";
 import { AuthenticationResult } from "../response/AuthenticationResult.js";
 import { SilentRequest } from "../request/SilentRequest.js";
 import { SsoSilentRequest } from "../request/SsoSilentRequest.js";
@@ -66,6 +66,7 @@ import { getAccountKeys, getTokenKeys } from "./CacheHelpers.js";
 import { EventType } from "../event/EventType.js";
 import { EventHandler } from "../event/EventHandler.js";
 import { clearHash } from "../utils/BrowserUtils.js";
+import { version } from "../packageMetadata.js";
 
 /**
  * This class implements the cache storage interface for MSAL through browser local or session storage.
@@ -123,6 +124,29 @@ export class BrowserCacheManager extends CacheManager {
 
     async initialize(correlationId: string): Promise<void> {
         await this.browserStorage.initialize(correlationId);
+        this.trackVersionChanges(correlationId);
+    }
+
+    /**
+     * Tracks upgrades and downgrades for telemetry and debugging purposes
+     */
+    private trackVersionChanges(correlationId: string): void {
+        const previousVersion = this.browserStorage.getItem(
+            StaticCacheKeys.VERSION
+        );
+        if (previousVersion) {
+            this.logger.info(
+                `MSAL.js was last initialized by version: ${previousVersion}`
+            );
+            this.performanceClient.addFields(
+                { previousLibraryVersion: previousVersion },
+                correlationId
+            );
+        }
+
+        if (previousVersion !== version) {
+            this.browserStorage.setItem(StaticCacheKeys.VERSION, version);
+        }
     }
 
     /**
@@ -1162,7 +1186,7 @@ export class BrowserCacheManager extends CacheManager {
     /**
      * Gets cached native request for redirect flows
      */
-    getCachedNativeRequest(): NativeTokenRequest | null {
+    getCachedNativeRequest(): PlatformAuthRequest | null {
         this.logger.trace("BrowserCacheManager.getCachedNativeRequest called");
         const cachedRequest = this.getTemporaryCache(
             TemporaryCacheKeys.NATIVE_REQUEST,
@@ -1177,7 +1201,7 @@ export class BrowserCacheManager extends CacheManager {
 
         const parsedRequest = this.validateAndParseJson(
             cachedRequest
-        ) as NativeTokenRequest;
+        ) as PlatformAuthRequest;
         if (!parsedRequest) {
             this.logger.error(
                 "BrowserCacheManager.getCachedNativeRequest: Unable to parse native request"