@azure/msal-common 14.0.2 → 14.1.0-alpha.0

package/src/telemetry/server/ServerTelemetryManager.ts

@@ -0,0 +1,274 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    SERVER_TELEM_CONSTANTS,
+    Separators,
+    CacheOutcome,
+    Constants,
+    RegionDiscoverySources,
+    RegionDiscoveryOutcomes,
+} from "../../utils/Constants";
+import { CacheManager } from "../../cache/CacheManager";
+import { AuthError } from "../../error/AuthError";
+import { ServerTelemetryRequest } from "./ServerTelemetryRequest";
+import { ServerTelemetryEntity } from "../../cache/entities/ServerTelemetryEntity";
+import { RegionDiscoveryMetadata } from "../../authority/RegionDiscoveryMetadata";
+
+/** @internal */
+export class ServerTelemetryManager {
+    private cacheManager: CacheManager;
+    private apiId: number;
+    private correlationId: string;
+    private telemetryCacheKey: string;
+    private wrapperSKU: String;
+    private wrapperVer: String;
+    private regionUsed: string | undefined;
+    private regionSource: RegionDiscoverySources | undefined;
+    private regionOutcome: RegionDiscoveryOutcomes | undefined;
+    private cacheOutcome: CacheOutcome = CacheOutcome.NOT_APPLICABLE;
+
+    constructor(
+        telemetryRequest: ServerTelemetryRequest,
+        cacheManager: CacheManager
+    ) {
+        this.cacheManager = cacheManager;
+        this.apiId = telemetryRequest.apiId;
+        this.correlationId = telemetryRequest.correlationId;
+        this.wrapperSKU = telemetryRequest.wrapperSKU || Constants.EMPTY_STRING;
+        this.wrapperVer = telemetryRequest.wrapperVer || Constants.EMPTY_STRING;
+
+        this.telemetryCacheKey =
+            SERVER_TELEM_CONSTANTS.CACHE_KEY +
+            Separators.CACHE_KEY_SEPARATOR +
+            telemetryRequest.clientId;
+    }
+
+    /**
+     * API to add MSER Telemetry to request
+     */
+    generateCurrentRequestHeaderValue(): string {
+        const request = `${this.apiId}${SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR}${this.cacheOutcome}`;
+        const platformFields = [this.wrapperSKU, this.wrapperVer].join(
+            SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR
+        );
+        const regionDiscoveryFields = this.getRegionDiscoveryFields();
+        const requestWithRegionDiscoveryFields = [
+            request,
+            regionDiscoveryFields,
+        ].join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
+
+        return [
+            SERVER_TELEM_CONSTANTS.SCHEMA_VERSION,
+            requestWithRegionDiscoveryFields,
+            platformFields,
+        ].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
+    }
+
+    /**
+     * API to add MSER Telemetry for the last failed request
+     */
+    generateLastRequestHeaderValue(): string {
+        const lastRequests = this.getLastRequests();
+
+        const maxErrors = ServerTelemetryManager.maxErrorsToSend(lastRequests);
+        const failedRequests = lastRequests.failedRequests
+            .slice(0, 2 * maxErrors)
+            .join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
+        const errors = lastRequests.errors
+            .slice(0, maxErrors)
+            .join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
+        const errorCount = lastRequests.errors.length;
+
+        // Indicate whether this header contains all data or partial data
+        const overflow =
+            maxErrors < errorCount
+                ? SERVER_TELEM_CONSTANTS.OVERFLOW_TRUE
+                : SERVER_TELEM_CONSTANTS.OVERFLOW_FALSE;
+        const platformFields = [errorCount, overflow].join(
+            SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR
+        );
+
+        return [
+            SERVER_TELEM_CONSTANTS.SCHEMA_VERSION,
+            lastRequests.cacheHits,
+            failedRequests,
+            errors,
+            platformFields,
+        ].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
+    }
+
+    /**
+     * API to cache token failures for MSER data capture
+     * @param error
+     */
+    cacheFailedRequest(error: unknown): void {
+        const lastRequests = this.getLastRequests();
+        if (
+            lastRequests.errors.length >=
+            SERVER_TELEM_CONSTANTS.MAX_CACHED_ERRORS
+        ) {
+            // Remove a cached error to make room, first in first out
+            lastRequests.failedRequests.shift(); // apiId
+            lastRequests.failedRequests.shift(); // correlationId
+            lastRequests.errors.shift();
+        }
+
+        lastRequests.failedRequests.push(this.apiId, this.correlationId);
+
+        if (error instanceof Error && !!error && error.toString()) {
+            if (error instanceof AuthError) {
+                if (error.subError) {
+                    lastRequests.errors.push(error.subError);
+                } else if (error.errorCode) {
+                    lastRequests.errors.push(error.errorCode);
+                } else {
+                    lastRequests.errors.push(error.toString());
+                }
+            } else {
+                lastRequests.errors.push(error.toString());
+            }
+        } else {
+            lastRequests.errors.push(SERVER_TELEM_CONSTANTS.UNKNOWN_ERROR);
+        }
+
+        this.cacheManager.setServerTelemetry(
+            this.telemetryCacheKey,
+            lastRequests
+        );
+
+        return;
+    }
+
+    /**
+     * Update server telemetry cache entry by incrementing cache hit counter
+     */
+    incrementCacheHits(): number {
+        const lastRequests = this.getLastRequests();
+        lastRequests.cacheHits += 1;
+
+        this.cacheManager.setServerTelemetry(
+            this.telemetryCacheKey,
+            lastRequests
+        );
+        return lastRequests.cacheHits;
+    }
+
+    /**
+     * Get the server telemetry entity from cache or initialize a new one
+     */
+    getLastRequests(): ServerTelemetryEntity {
+        const initialValue: ServerTelemetryEntity = new ServerTelemetryEntity();
+        const lastRequests = this.cacheManager.getServerTelemetry(
+            this.telemetryCacheKey
+        ) as ServerTelemetryEntity;
+
+        return lastRequests || initialValue;
+    }
+
+    /**
+     * Remove server telemetry cache entry
+     */
+    clearTelemetryCache(): void {
+        const lastRequests = this.getLastRequests();
+        const numErrorsFlushed =
+            ServerTelemetryManager.maxErrorsToSend(lastRequests);
+        const errorCount = lastRequests.errors.length;
+        if (numErrorsFlushed === errorCount) {
+            // All errors were sent on last request, clear Telemetry cache
+            this.cacheManager.removeItem(this.telemetryCacheKey);
+        } else {
+            // Partial data was flushed to server, construct a new telemetry cache item with errors that were not flushed
+            const serverTelemEntity = new ServerTelemetryEntity();
+            serverTelemEntity.failedRequests =
+                lastRequests.failedRequests.slice(numErrorsFlushed * 2); // failedRequests contains 2 items for each error
+            serverTelemEntity.errors =
+                lastRequests.errors.slice(numErrorsFlushed);
+
+            this.cacheManager.setServerTelemetry(
+                this.telemetryCacheKey,
+                serverTelemEntity
+            );
+        }
+    }
+
+    /**
+     * Returns the maximum number of errors that can be flushed to the server in the next network request
+     * @param serverTelemetryEntity
+     */
+    static maxErrorsToSend(
+        serverTelemetryEntity: ServerTelemetryEntity
+    ): number {
+        let i;
+        let maxErrors = 0;
+        let dataSize = 0;
+        const errorCount = serverTelemetryEntity.errors.length;
+        for (i = 0; i < errorCount; i++) {
+            // failedRequests parameter contains pairs of apiId and correlationId, multiply index by 2 to preserve pairs
+            const apiId =
+                serverTelemetryEntity.failedRequests[2 * i] ||
+                Constants.EMPTY_STRING;
+            const correlationId =
+                serverTelemetryEntity.failedRequests[2 * i + 1] ||
+                Constants.EMPTY_STRING;
+            const errorCode =
+                serverTelemetryEntity.errors[i] || Constants.EMPTY_STRING;
+
+            // Count number of characters that would be added to header, each character is 1 byte. Add 3 at the end to account for separators
+            dataSize +=
+                apiId.toString().length +
+                correlationId.toString().length +
+                errorCode.length +
+                3;
+
+            if (dataSize < SERVER_TELEM_CONSTANTS.MAX_LAST_HEADER_BYTES) {
+                // Adding this entry to the header would still keep header size below the limit
+                maxErrors += 1;
+            } else {
+                break;
+            }
+        }
+
+        return maxErrors;
+    }
+
+    /**
+     * Get the region discovery fields
+     *
+     * @returns string
+     */
+    getRegionDiscoveryFields(): string {
+        const regionDiscoveryFields: string[] = [];
+
+        regionDiscoveryFields.push(this.regionUsed || Constants.EMPTY_STRING);
+        regionDiscoveryFields.push(this.regionSource || Constants.EMPTY_STRING);
+        regionDiscoveryFields.push(
+            this.regionOutcome || Constants.EMPTY_STRING
+        );
+
+        return regionDiscoveryFields.join(",");
+    }
+
+    /**
+     * Update the region discovery metadata
+     *
+     * @param regionDiscoveryMetadata
+     * @returns void
+     */
+    updateRegionDiscoveryMetadata(
+        regionDiscoveryMetadata: RegionDiscoveryMetadata
+    ): void {
+        this.regionUsed = regionDiscoveryMetadata.region_used;
+        this.regionSource = regionDiscoveryMetadata.region_source;
+        this.regionOutcome = regionDiscoveryMetadata.region_outcome;
+    }
+
+    /**
+     * Set cache outcome
+     */
+    setCacheOutcome(cacheOutcome: CacheOutcome): void {
+        this.cacheOutcome = cacheOutcome;
+    }
+}

package/src/telemetry/server/ServerTelemetryRequest.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type ServerTelemetryRequest = {
+    clientId: string;
+    apiId: number;
+    correlationId: string;
+    forceRefresh?: boolean;
+    wrapperSKU?: string;
+    wrapperVer?: string;
+};

package/src/url/IUri.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface which describes URI components.
+ */
+export interface IUri {
+    Protocol: string;
+    HostNameAndPort: string;
+    AbsolutePath: string;
+    Search: string;
+    Hash: string;
+    PathSegments: string[];
+    QueryString: string;
+}

package/src/url/UrlString.ts

@@ -0,0 +1,373 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ServerAuthorizationCodeResponse } from "../response/ServerAuthorizationCodeResponse";
+import {
+    createClientConfigurationError,
+    ClientConfigurationErrorCodes,
+} from "../error/ClientConfigurationError";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError";
+import { StringUtils } from "../utils/StringUtils";
+import { IUri } from "./IUri";
+import {
+    AADAuthorityConstants,
+    Constants,
+    ServerResponseType,
+} from "../utils/Constants";
+
+/**
+ * Url object class which can perform various transformations on url strings.
+ */
+export class UrlString {
+    // internal url string field
+    private _urlString: string;
+    public get urlString(): string {
+        return this._urlString;
+    }
+
+    constructor(url: string) {
+        this._urlString = url;
+        if (!this._urlString) {
+            // Throws error if url is empty
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.urlEmptyError
+            );
+        }
+
+        if (!this.getHash()) {
+            this._urlString = UrlString.canonicalizeUri(url);
+        }
+    }
+
+    /**
+     * Ensure urls are lower case and end with a / character.
+     * @param url
+     */
+    static canonicalizeUri(url: string): string {
+        if (url) {
+            let lowerCaseUrl = url.toLowerCase();
+
+            if (StringUtils.endsWith(lowerCaseUrl, "?")) {
+                lowerCaseUrl = lowerCaseUrl.slice(0, -1);
+            } else if (StringUtils.endsWith(lowerCaseUrl, "?/")) {
+                lowerCaseUrl = lowerCaseUrl.slice(0, -2);
+            }
+
+            if (!StringUtils.endsWith(lowerCaseUrl, "/")) {
+                lowerCaseUrl += "/";
+            }
+
+            return lowerCaseUrl;
+        }
+
+        return url;
+    }
+
+    /**
+     * Throws if urlString passed is not a valid authority URI string.
+     */
+    validateAsUri(): void {
+        // Attempts to parse url for uri components
+        let components;
+        try {
+            components = this.getUrlComponents();
+        } catch (e) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.urlParseError
+            );
+        }
+
+        // Throw error if URI or path segments are not parseable.
+        if (!components.HostNameAndPort || !components.PathSegments) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.urlParseError
+            );
+        }
+
+        // Throw error if uri is insecure.
+        if (
+            !components.Protocol ||
+            components.Protocol.toLowerCase() !== "https:"
+        ) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.authorityUriInsecure
+            );
+        }
+    }
+
+    /**
+     * Given a url and a query string return the url with provided query string appended
+     * @param url
+     * @param queryString
+     */
+    static appendQueryString(url: string, queryString: string): string {
+        if (!queryString) {
+            return url;
+        }
+
+        return url.indexOf("?") < 0
+            ? `${url}?${queryString}`
+            : `${url}&${queryString}`;
+    }
+
+    /**
+     * Returns a url with the hash removed
+     * @param url
+     */
+    static removeHashFromUrl(url: string): string {
+        return UrlString.canonicalizeUri(url.split("#")[0]);
+    }
+
+    /**
+     * Given a url like https://a:b/common/d?e=f#g, and a tenantId, returns https://a:b/tenantId/d
+     * @param href The url
+     * @param tenantId The tenant id to replace
+     */
+    replaceTenantPath(tenantId: string): UrlString {
+        const urlObject = this.getUrlComponents();
+        const pathArray = urlObject.PathSegments;
+        if (
+            tenantId &&
+            pathArray.length !== 0 &&
+            (pathArray[0] === AADAuthorityConstants.COMMON ||
+                pathArray[0] === AADAuthorityConstants.ORGANIZATIONS)
+        ) {
+            pathArray[0] = tenantId;
+        }
+        return UrlString.constructAuthorityUriFromObject(urlObject);
+    }
+
+    /**
+     * Returns the anchor part(#) of the URL
+     */
+    getHash(): string {
+        return UrlString.parseHash(this.urlString);
+    }
+
+    /**
+     * Parses out the components from a url string.
+     * @returns An object with the various components. Please cache this value insted of calling this multiple times on the same url.
+     */
+    getUrlComponents(): IUri {
+        // https://gist.github.com/curtisz/11139b2cfcaef4a261e0
+        const regEx = RegExp(
+            "^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\\?([^#]*))?(#(.*))?"
+        );
+
+        // If url string does not match regEx, we throw an error
+        const match = this.urlString.match(regEx);
+        if (!match) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.urlParseError
+            );
+        }
+
+        // Url component object
+        const urlComponents = {
+            Protocol: match[1],
+            HostNameAndPort: match[4],
+            AbsolutePath: match[5],
+            QueryString: match[7],
+        } as IUri;
+
+        let pathSegments = urlComponents.AbsolutePath.split("/");
+        pathSegments = pathSegments.filter((val) => val && val.length > 0); // remove empty elements
+        urlComponents.PathSegments = pathSegments;
+
+        if (
+            urlComponents.QueryString &&
+            urlComponents.QueryString.endsWith("/")
+        ) {
+            urlComponents.QueryString = urlComponents.QueryString.substring(
+                0,
+                urlComponents.QueryString.length - 1
+            );
+        }
+        return urlComponents;
+    }
+
+    static getDomainFromUrl(url: string): string {
+        const regEx = RegExp("^([^:/?#]+://)?([^/?#]*)");
+
+        const match = url.match(regEx);
+
+        if (!match) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.urlParseError
+            );
+        }
+
+        return match[2];
+    }
+
+    static getAbsoluteUrl(relativeUrl: string, baseUrl: string): string {
+        if (relativeUrl[0] === Constants.FORWARD_SLASH) {
+            const url = new UrlString(baseUrl);
+            const baseComponents = url.getUrlComponents();
+
+            return (
+                baseComponents.Protocol +
+                "//" +
+                baseComponents.HostNameAndPort +
+                relativeUrl
+            );
+        }
+
+        return relativeUrl;
+    }
+
+    /**
+     * Parses hash string from given string. Returns empty string if no hash symbol is found.
+     * @param hashString
+     */
+    static parseHash(hashString: string): string {
+        const hashIndex1 = hashString.indexOf("#");
+        const hashIndex2 = hashString.indexOf("#/");
+        if (hashIndex2 > -1) {
+            return hashString.substring(hashIndex2 + 2);
+        } else if (hashIndex1 > -1) {
+            return hashString.substring(hashIndex1 + 1);
+        }
+        return Constants.EMPTY_STRING;
+    }
+
+    /**
+     * Parses query string from given string. Returns empty string if no query symbol is found.
+     * @param queryString
+     */
+    static parseQueryString(queryString: string): string {
+        const queryIndex1 = queryString.indexOf("?");
+        const queryIndex2 = queryString.indexOf("/?");
+        if (queryIndex2 > -1) {
+            return queryString.substring(queryIndex2 + 2);
+        } else if (queryIndex1 > -1) {
+            return queryString.substring(queryIndex1 + 1);
+        }
+        return Constants.EMPTY_STRING;
+    }
+
+    /**
+     * Parses query server response string from given string.
+     * Extract hash between '?code=' and '#' if trailing '# is present.
+     * Returns empty string if no query symbol is found.
+     * @param queryString
+     */
+    static parseQueryServerResponse(queryString: string): string {
+        const queryIndex1 = queryString.indexOf("?code");
+        const queryIndex2 = queryString.indexOf("/?code");
+        const hashIndex = queryString.indexOf("#");
+        if (queryIndex2 > -1 && hashIndex > -1) {
+            return queryString.substring(queryIndex2 + 2, hashIndex);
+        } else if (queryIndex2 > -1) {
+            return queryString.substring(queryIndex2 + 2);
+        } else if (queryIndex1 > -1 && hashIndex > -1) {
+            return queryString.substring(queryIndex1 + 1, hashIndex);
+        } else if (queryIndex1 > -1) {
+            return queryString.substring(queryIndex1 + 1);
+        }
+        return Constants.EMPTY_STRING;
+    }
+
+    static constructAuthorityUriFromObject(urlObject: IUri): UrlString {
+        return new UrlString(
+            urlObject.Protocol +
+                "//" +
+                urlObject.HostNameAndPort +
+                "/" +
+                urlObject.PathSegments.join("/")
+        );
+    }
+
+    /**
+     * Returns URL hash as server auth code response object.
+     */
+    static getDeserializedHash(hash: string): ServerAuthorizationCodeResponse {
+        // Check if given hash is empty
+        if (!hash) {
+            return {};
+        }
+        // Strip the # symbol if present
+        const parsedHash = UrlString.parseHash(hash);
+        // If # symbol was not present, above will return empty string, so give original hash value
+        const deserializedHash: ServerAuthorizationCodeResponse =
+            StringUtils.queryStringToObject<ServerAuthorizationCodeResponse>(
+                parsedHash || hash
+            );
+        // Check if deserialization didn't work
+        if (!deserializedHash) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.hashNotDeserialized
+            );
+        }
+        return deserializedHash;
+    }
+
+    /**
+     * Returns URL query string as server auth code response object.
+     */
+    static getDeserializedQueryString(
+        query: string
+    ): ServerAuthorizationCodeResponse {
+        // Check if given query is empty
+        if (!query) {
+            return {};
+        }
+        // Strip the ? symbol if present
+        const parsedQueryString = UrlString.parseQueryString(query);
+        // If ? symbol was not present, above will return empty string, so give original query value
+        const deserializedQueryString: ServerAuthorizationCodeResponse =
+            StringUtils.queryStringToObject<ServerAuthorizationCodeResponse>(
+                parsedQueryString || query
+            );
+        // Check if deserialization didn't work
+        if (!deserializedQueryString) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.hashNotDeserialized
+            );
+        }
+        return deserializedQueryString;
+    }
+    /**
+     * Returns either deserialized query string or deserialized hash, depending on the serverResponseType
+     * as a server auth code response object.
+     */
+    static getDeserializedCodeResponse(
+        serverResponseType: ServerResponseType | undefined,
+        hashFragment: string
+    ): ServerAuthorizationCodeResponse {
+        const hashUrlString = new UrlString(hashFragment);
+        let serverParams: ServerAuthorizationCodeResponse;
+        if (serverResponseType === ServerResponseType.QUERY) {
+            serverParams = UrlString.getDeserializedQueryString(hashFragment);
+        } else {
+            serverParams = UrlString.getDeserializedHash(
+                hashUrlString.getHash()
+            );
+        }
+        return serverParams;
+    }
+
+    /**
+     * Check if the hash of the URL string contains known properties
+     */
+    static hashContainsKnownProperties(hash: string): boolean {
+        if (!hash || hash.indexOf("=") < 0) {
+            // Hash doesn't contain key/value pairs
+            return false;
+        }
+
+        const parameters: ServerAuthorizationCodeResponse =
+            UrlString.getDeserializedHash(hash);
+        return !!(
+            parameters.code ||
+            parameters.error_description ||
+            parameters.error ||
+            parameters.state
+        );
+    }
+}