@azure/msal-browser 3.0.1 → 3.1.0

package/src/broker/nativeBroker/NativeMessageHandler.ts

@@ -0,0 +1,419 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    NativeConstants,
+    NativeExtensionMethod,
+} from "../../utils/BrowserConstants";
+import {
+    Logger,
+    AuthError,
+    AuthenticationScheme,
+    InProgressPerformanceEvent,
+    PerformanceEvents,
+    IPerformanceClient,
+    ICrypto,
+} from "@azure/msal-common";
+import {
+    NativeExtensionRequest,
+    NativeExtensionRequestBody,
+} from "./NativeRequest";
+import { NativeAuthError } from "../../error/NativeAuthError";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../../error/BrowserAuthError";
+import { BrowserConfiguration } from "../../config/Configuration";
+
+type ResponseResolvers<T> = {
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (
+        value: AuthError | Error | PromiseLike<Error> | PromiseLike<AuthError>
+    ) => void;
+};
+
+export class NativeMessageHandler {
+    private extensionId: string | undefined;
+    private extensionVersion: string | undefined;
+    private logger: Logger;
+    private crypto: ICrypto;
+    private readonly handshakeTimeoutMs: number;
+    private timeoutId: number | undefined;
+    private resolvers: Map<string, ResponseResolvers<object>>;
+    private handshakeResolvers: Map<string, ResponseResolvers<void>>;
+    private messageChannel: MessageChannel;
+    private readonly windowListener: (event: MessageEvent) => void;
+    private readonly performanceClient: IPerformanceClient;
+    private readonly handshakeEvent: InProgressPerformanceEvent;
+
+    constructor(
+        logger: Logger,
+        handshakeTimeoutMs: number,
+        performanceClient: IPerformanceClient,
+        crypto: ICrypto,
+        extensionId?: string
+    ) {
+        this.logger = logger;
+        this.handshakeTimeoutMs = handshakeTimeoutMs;
+        this.extensionId = extensionId;
+        this.resolvers = new Map(); // Used for non-handshake messages
+        this.handshakeResolvers = new Map(); // Used for handshake messages
+        this.messageChannel = new MessageChannel();
+        this.windowListener = this.onWindowMessage.bind(this); // Window event callback doesn't have access to 'this' unless it's bound
+        this.performanceClient = performanceClient;
+        this.handshakeEvent = performanceClient.startMeasurement(
+            PerformanceEvents.NativeMessageHandlerHandshake
+        );
+        this.crypto = crypto;
+    }
+
+    /**
+     * Sends a given message to the extension and resolves with the extension response
+     * @param body
+     */
+    async sendMessage(body: NativeExtensionRequestBody): Promise<object> {
+        this.logger.trace("NativeMessageHandler - sendMessage called.");
+        const req: NativeExtensionRequest = {
+            channel: NativeConstants.CHANNEL_ID,
+            extensionId: this.extensionId,
+            responseId: this.crypto.createNewGuid(),
+            body: body,
+        };
+
+        this.logger.trace(
+            "NativeMessageHandler - Sending request to browser extension"
+        );
+        this.logger.tracePii(
+            `NativeMessageHandler - Sending request to browser extension: ${JSON.stringify(
+                req
+            )}`
+        );
+        this.messageChannel.port1.postMessage(req);
+
+        return new Promise((resolve, reject) => {
+            this.resolvers.set(req.responseId, { resolve, reject });
+        });
+    }
+
+    /**
+     * Returns an instance of the MessageHandler that has successfully established a connection with an extension
+     * @param {Logger} logger
+     * @param {number} handshakeTimeoutMs
+     * @param {IPerformanceClient} performanceClient
+     * @param {ICrypto} crypto
+     */
+    static async createProvider(
+        logger: Logger,
+        handshakeTimeoutMs: number,
+        performanceClient: IPerformanceClient,
+        crypto: ICrypto
+    ): Promise<NativeMessageHandler> {
+        logger.trace("NativeMessageHandler - createProvider called.");
+        try {
+            const preferredProvider = new NativeMessageHandler(
+                logger,
+                handshakeTimeoutMs,
+                performanceClient,
+                crypto,
+                NativeConstants.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(
+                logger,
+                handshakeTimeoutMs,
+                performanceClient,
+                crypto
+            );
+            await backupProvider.sendHandshakeRequest();
+            return backupProvider;
+        }
+    }
+
+    /**
+     * Send handshake request helper.
+     */
+    private async sendHandshakeRequest(): Promise<void> {
+        this.logger.trace(
+            "NativeMessageHandler - 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,
+            extensionId: this.extensionId,
+            responseId: this.crypto.createNewGuid(),
+            body: {
+                method: NativeExtensionMethod.HandshakeRequest,
+            },
+        };
+        this.handshakeEvent.add({
+            extensionId: this.extensionId,
+            extensionHandshakeTimeoutMs: this.handshakeTimeoutMs,
+        });
+
+        this.messageChannel.port1.onmessage = (event) => {
+            this.onChannelMessage(event);
+        };
+
+        window.postMessage(req, window.origin, [this.messageChannel.port2]);
+
+        return new Promise((resolve, reject) => {
+            this.handshakeResolvers.set(req.responseId, { resolve, reject });
+            this.timeoutId = window.setTimeout(() => {
+                /*
+                 * Throw an error if neither HandshakeResponse nor original Handshake request are received in a reasonable timeframe.
+                 * This typically suggests an event handler stopped propagation of the Handshake request but did not respond to it on the MessageChannel port
+                 */
+                window.removeEventListener(
+                    "message",
+                    this.windowListener,
+                    false
+                );
+                this.messageChannel.port1.close();
+                this.messageChannel.port2.close();
+                this.handshakeEvent.end({
+                    extensionHandshakeTimedOut: true,
+                    success: false,
+                });
+                reject(
+                    createBrowserAuthError(
+                        BrowserAuthErrorCodes.nativeHandshakeTimeout
+                    )
+                );
+                this.handshakeResolvers.delete(req.responseId);
+            }, this.handshakeTimeoutMs); // Use a reasonable timeout in milliseconds here
+        });
+    }
+
+    /**
+     * Invoked when a message is posted to the window. If a handshake request is received it means the extension is not installed.
+     * @param event
+     */
+    private onWindowMessage(event: MessageEvent): void {
+        this.logger.trace("NativeMessageHandler - onWindowMessage called");
+        // We only accept messages from ourselves
+        if (event.source !== window) {
+            return;
+        }
+
+        const request = event.data;
+
+        if (
+            !request.channel ||
+            request.channel !== NativeConstants.CHANNEL_ID
+        ) {
+            return;
+        }
+
+        if (request.extensionId && request.extensionId !== this.extensionId) {
+            return;
+        }
+
+        if (request.body.method === NativeExtensionMethod.HandshakeRequest) {
+            const handshakeResolver = this.handshakeResolvers.get(
+                request.responseId
+            );
+            /*
+             * Filter out responses with no matched resolvers sooner to keep channel ports open while waiting for
+             * the proper response.
+             */
+            if (!handshakeResolver) {
+                this.logger.trace(
+                    `NativeMessageHandler.onWindowMessage - resolver can't be found for request ${request.responseId}`
+                );
+                return;
+            }
+
+            // If we receive this message back it means no extension intercepted the request, meaning no extension supporting handshake protocol is installed
+            this.logger.verbose(
+                request.extensionId
+                    ? `Extension with id: ${request.extensionId} not installed`
+                    : "No extension installed"
+            );
+            clearTimeout(this.timeoutId);
+            this.messageChannel.port1.close();
+            this.messageChannel.port2.close();
+            window.removeEventListener("message", this.windowListener, false);
+            this.handshakeEvent.end({
+                success: false,
+                extensionInstalled: false,
+            });
+            handshakeResolver.reject(
+                createBrowserAuthError(
+                    BrowserAuthErrorCodes.nativeExtensionNotInstalled
+                )
+            );
+        }
+    }
+
+    /**
+     * Invoked when a message is received from the extension on the MessageChannel port
+     * @param event
+     */
+    private onChannelMessage(event: MessageEvent): void {
+        this.logger.trace("NativeMessageHandler - onChannelMessage called.");
+        const request = event.data;
+
+        const resolver = this.resolvers.get(request.responseId);
+        const handshakeResolver = this.handshakeResolvers.get(
+            request.responseId
+        );
+
+        try {
+            const method = request.body.method;
+
+            if (method === NativeExtensionMethod.Response) {
+                if (!resolver) {
+                    return;
+                }
+                const response = request.body.response;
+                this.logger.trace(
+                    "NativeMessageHandler - Received response from browser extension"
+                );
+                this.logger.tracePii(
+                    `NativeMessageHandler - Received response from browser extension: ${JSON.stringify(
+                        response
+                    )}`
+                );
+                if (response.status !== "Success") {
+                    resolver.reject(
+                        NativeAuthError.createError(
+                            response.code,
+                            response.description,
+                            response.ext
+                        )
+                    );
+                } else if (response.result) {
+                    if (
+                        response.result["code"] &&
+                        response.result["description"]
+                    ) {
+                        resolver.reject(
+                            NativeAuthError.createError(
+                                response.result["code"],
+                                response.result["description"],
+                                response.result["ext"]
+                            )
+                        );
+                    } else {
+                        resolver.resolve(response.result);
+                    }
+                } else {
+                    throw AuthError.createUnexpectedError(
+                        "Event does not contain result."
+                    );
+                }
+                this.resolvers.delete(request.responseId);
+            } else if (method === NativeExtensionMethod.HandshakeResponse) {
+                if (!handshakeResolver) {
+                    this.logger.trace(
+                        `NativeMessageHandler.onChannelMessage - resolver can't be found for request ${request.responseId}`
+                    );
+                    return;
+                }
+                clearTimeout(this.timeoutId); // Clear setTimeout
+                window.removeEventListener(
+                    "message",
+                    this.windowListener,
+                    false
+                ); // Remove 'No extension' listener
+                this.extensionId = request.extensionId;
+                this.extensionVersion = request.body.version;
+                this.logger.verbose(
+                    `NativeMessageHandler - Received HandshakeResponse from extension: ${this.extensionId}`
+                );
+                this.handshakeEvent.end({
+                    extensionInstalled: true,
+                    success: true,
+                });
+
+                handshakeResolver.resolve();
+                this.handshakeResolvers.delete(request.responseId);
+            }
+            // Do nothing if method is not Response or HandshakeResponse
+        } catch (err) {
+            this.logger.error("Error parsing response from WAM Extension");
+            this.logger.errorPii(
+                `Error parsing response from WAM Extension: ${err as string}`
+            );
+            this.logger.errorPii(`Unable to parse ${event}`);
+
+            if (resolver) {
+                resolver.reject(err as AuthError);
+            } else if (handshakeResolver) {
+                handshakeResolver.reject(err as AuthError);
+            }
+        }
+    }
+
+    /**
+     * Returns the Id for the browser extension this handler is communicating with
+     * @returns
+     */
+    getExtensionId(): string | undefined {
+        return this.extensionId;
+    }
+
+    /**
+     * Returns the version for the browser extension this handler is communicating with
+     * @returns
+     */
+    getExtensionVersion(): string | undefined {
+        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 isNativeAvailable(
+        config: BrowserConfiguration,
+        logger: Logger,
+        nativeExtensionProvider?: NativeMessageHandler,
+        authenticationScheme?: AuthenticationScheme
+    ): boolean {
+        logger.trace("isNativeAvailable called");
+        if (!config.system.allowNativeBroker) {
+            logger.trace(
+                "isNativeAvailable: allowNativeBroker is not enabled, returning false"
+            );
+            // Developer disabled WAM
+            return false;
+        }
+
+        if (!nativeExtensionProvider) {
+            logger.trace(
+                "isNativeAvailable: WAM 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(
+                        "isNativeAvailable: authenticationScheme is supported, returning true"
+                    );
+                    return true;
+                default:
+                    logger.trace(
+                        "isNativeAvailable: authenticationScheme is not supported, returning false"
+                    );
+                    return false;
+            }
+        }
+
+        return true;
+    }
+}

package/src/broker/nativeBroker/NativeRequest.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { NativeExtensionMethod } from "../../utils/BrowserConstants";
+import { StoreInCache, StringDict } from "@azure/msal-common";
+
+/**
+ * Token request which native broker will use to acquire tokens
+ */
+export type NativeTokenRequest = {
+    accountId: string; // WAM specific account id used for identification of WAM account. This can be any broker-id eventually
+    clientId: string;
+    authority: string;
+    redirectUri: string;
+    scope: string;
+    correlationId: string;
+    windowTitleSubstring: string; // The name of the document title. This helps the native prompt properly "parent" to the window making the request
+    prompt?: string;
+    nonce?: string;
+    claims?: string;
+    state?: string;
+    reqCnf?: string;
+    keyId?: string;
+    tokenType?: string;
+    shrClaims?: string;
+    shrNonce?: string;
+    resourceRequestMethod?: string;
+    resourceRequestUri?: string;
+    extendedExpiryToken?: boolean;
+    extraParameters?: StringDict;
+    storeInCache?: StoreInCache; // Object of booleans indicating whether to store tokens in the cache or not (default is true)
+};
+
+/**
+ * Request which will be forwarded to native broker by the browser extension
+ */
+export type NativeExtensionRequestBody = {
+    method: NativeExtensionMethod;
+    request?: NativeTokenRequest;
+};
+
+/**
+ * Browser extension request
+ */
+export type NativeExtensionRequest = {
+    channel: string;
+    responseId: string;
+    extensionId?: string;
+    body: NativeExtensionRequestBody;
+};

package/src/broker/nativeBroker/NativeResponse.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Account properties returned by Native Platform e.g. WAM
+ */
+export type NativeAccountInfo = {
+    id: string;
+    properties: object;
+    userName: string;
+};
+
+/**
+ * Token response returned by Native Platform e.g. WAM
+ */
+export type NativeResponse = {
+    access_token: string;
+    account: NativeAccountInfo;
+    client_info: string;
+    expires_in: number;
+    id_token: string;
+    properties: NativeResponseProperties;
+    scope: string;
+    state: string;
+    shr?: string;
+    extendedLifetimeToken?: boolean;
+};
+
+/**
+ * Properties returned under "properties" of the NativeResponse
+ */
+export type NativeResponseProperties = {
+    MATS?: string;
+};
+
+/**
+ * The native token broker can optionally include additional information about operations it performs. If that data is returned, MSAL.js will include the following properties in the telemetry it collects.
+ */
+export type MATS = {
+    is_cached?: number;
+    broker_version?: string;
+    account_join_on_start?: string;
+    account_join_on_end?: string;
+    device_join?: string;
+    prompt_behavior?: string;
+    api_error_code?: number;
+    ui_visible?: boolean;
+    silent_code?: number;
+    silent_bi_sub_code?: number;
+    silent_message?: string;
+    silent_status?: number;
+    http_status?: number;
+    http_event_count?: number;
+};

package/src/cache/AsyncMemoryStorage.ts

@@ -0,0 +1,158 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Logger } from "@azure/msal-common";
+import {
+    BrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import { DatabaseStorage } from "./DatabaseStorage";
+import { IAsyncStorage } from "./IAsyncMemoryStorage";
+import { MemoryStorage } from "./MemoryStorage";
+
+/**
+ * This class allows MSAL to store artifacts asynchronously using the DatabaseStorage IndexedDB wrapper,
+ * backed up with the more volatile MemoryStorage object for cases in which IndexedDB may be unavailable.
+ */
+export class AsyncMemoryStorage<T> implements IAsyncStorage<T> {
+    private inMemoryCache: MemoryStorage<T>;
+    private indexedDBCache: DatabaseStorage<T>;
+    private logger: Logger;
+    private storeName: string;
+
+    constructor(logger: Logger, storeName: string) {
+        this.inMemoryCache = new MemoryStorage<T>();
+        this.indexedDBCache = new DatabaseStorage<T>();
+        this.logger = logger;
+        this.storeName = storeName;
+    }
+
+    private handleDatabaseAccessError(error: unknown): void {
+        if (
+            error instanceof BrowserAuthError &&
+            error.errorCode === BrowserAuthErrorCodes.databaseUnavailable
+        ) {
+            this.logger.error(
+                "Could not access persistent storage. This may be caused by browser privacy features which block persistent storage in third-party contexts."
+            );
+        } else {
+            throw error;
+        }
+    }
+    /**
+     * Get the item matching the given key. Tries in-memory cache first, then in the asynchronous
+     * storage object if item isn't found in-memory.
+     * @param key
+     */
+    async getItem(key: string): Promise<T | null> {
+        const item = this.inMemoryCache.getItem(key);
+        if (!item) {
+            try {
+                this.logger.verbose(
+                    "Queried item not found in in-memory cache, now querying persistent storage."
+                );
+                return await this.indexedDBCache.getItem(key);
+            } catch (e) {
+                this.handleDatabaseAccessError(e);
+            }
+        }
+        return item;
+    }
+
+    /**
+     * Sets the item in the in-memory cache and then tries to set it in the asynchronous
+     * storage object with the given key.
+     * @param key
+     * @param value
+     */
+    async setItem(key: string, value: T): Promise<void> {
+        this.inMemoryCache.setItem(key, value);
+        try {
+            await this.indexedDBCache.setItem(key, value);
+        } catch (e) {
+            this.handleDatabaseAccessError(e);
+        }
+    }
+
+    /**
+     * Removes the item matching the key from the in-memory cache, then tries to remove it from the asynchronous storage object.
+     * @param key
+     */
+    async removeItem(key: string): Promise<void> {
+        this.inMemoryCache.removeItem(key);
+        try {
+            await this.indexedDBCache.removeItem(key);
+        } catch (e) {
+            this.handleDatabaseAccessError(e);
+        }
+    }
+
+    /**
+     * Get all the keys from the in-memory cache as an iterable array of strings. If no keys are found, query the keys in the
+     * asynchronous storage object.
+     */
+    async getKeys(): Promise<string[]> {
+        const cacheKeys = this.inMemoryCache.getKeys();
+        if (cacheKeys.length === 0) {
+            try {
+                this.logger.verbose(
+                    "In-memory cache is empty, now querying persistent storage."
+                );
+                return await this.indexedDBCache.getKeys();
+            } catch (e) {
+                this.handleDatabaseAccessError(e);
+            }
+        }
+        return cacheKeys;
+    }
+
+    /**
+     * Returns true or false if the given key is present in the cache.
+     * @param key
+     */
+    async containsKey(key: string): Promise<boolean> {
+        const containsKey = this.inMemoryCache.containsKey(key);
+        if (!containsKey) {
+            try {
+                this.logger.verbose(
+                    "Key not found in in-memory cache, now querying persistent storage."
+                );
+                return await this.indexedDBCache.containsKey(key);
+            } catch (e) {
+                this.handleDatabaseAccessError(e);
+            }
+        }
+        return containsKey;
+    }
+
+    /**
+     * Clears in-memory Map
+     */
+    clearInMemory(): void {
+        // InMemory cache is a Map instance, clear is straightforward
+        this.logger.verbose(`Deleting in-memory keystore ${this.storeName}`);
+        this.inMemoryCache.clear();
+        this.logger.verbose(`In-memory keystore ${this.storeName} deleted`);
+    }
+
+    /**
+     * Tries to delete the IndexedDB database
+     * @returns
+     */
+    async clearPersistent(): Promise<boolean> {
+        try {
+            this.logger.verbose("Deleting persistent keystore");
+            const dbDeleted = await this.indexedDBCache.deleteDatabase();
+            if (dbDeleted) {
+                this.logger.verbose("Persistent keystore deleted");
+            }
+
+            return dbDeleted;
+        } catch (e) {
+            this.handleDatabaseAccessError(e);
+            return false;
+        }
+    }
+}