@azure/msal-common 14.0.1 → 14.0.3

package/src/index.ts

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * @packageDocumentation
+ * @module @azure/msal-common
+ */
+
+export { AuthorizationCodeClient } from "./client/AuthorizationCodeClient";
+export { RefreshTokenClient } from "./client/RefreshTokenClient";
+export { SilentFlowClient } from "./client/SilentFlowClient";
+export { BaseClient } from "./client/BaseClient";
+export {
+    AuthOptions,
+    SystemOptions,
+    LoggerOptions,
+    CacheOptions,
+    DEFAULT_SYSTEM_OPTIONS,
+    AzureCloudOptions,
+    ApplicationTelemetry,
+} from "./config/ClientConfiguration";
+export {
+    IAppTokenProvider,
+    AppTokenProviderParameters,
+    AppTokenProviderResult,
+} from "./config/AppTokenProvider";
+export { ClientConfiguration } from "./config/ClientConfiguration";
+// Account
+export { AccountInfo, ActiveAccountFilters } from "./account/AccountInfo";
+export * as AuthToken from "./account/AuthToken";
+export { TokenClaims } from "./account/TokenClaims";
+export { TokenClaims as IdTokenClaims } from "./account/TokenClaims";
+export { CcsCredential, CcsCredentialType } from "./account/CcsCredential";
+export {
+    ClientInfo,
+    buildClientInfo,
+    buildClientInfoFromHomeAccountId,
+} from "./account/ClientInfo";
+// Authority
+export { Authority } from "./authority/Authority";
+export {
+    AuthorityOptions,
+    AzureCloudInstance,
+} from "./authority/AuthorityOptions";
+export { AuthorityFactory } from "./authority/AuthorityFactory";
+export { AuthorityType } from "./authority/AuthorityType";
+export { ProtocolMode } from "./authority/ProtocolMode";
+export { OIDCOptions } from "./authority/OIDCOptions";
+// Broker
+export { INativeBrokerPlugin } from "./broker/nativeBroker/INativeBrokerPlugin";
+// Cache
+export { CacheManager, DefaultStorageClass } from "./cache/CacheManager";
+export {
+    AccountCache,
+    AccessTokenCache,
+    IdTokenCache,
+    RefreshTokenCache,
+    AppMetadataCache,
+    CredentialFilter,
+    ValidCacheType,
+    ValidCredentialType,
+    TokenKeys,
+} from "./cache/utils/CacheTypes";
+export { CacheRecord } from "./cache/entities/CacheRecord";
+export { CredentialEntity } from "./cache/entities/CredentialEntity";
+export { AppMetadataEntity } from "./cache/entities/AppMetadataEntity";
+export { AccountEntity } from "./cache/entities/AccountEntity";
+export { IdTokenEntity } from "./cache/entities/IdTokenEntity";
+export { AccessTokenEntity } from "./cache/entities/AccessTokenEntity";
+export { RefreshTokenEntity } from "./cache/entities/RefreshTokenEntity";
+export { ServerTelemetryEntity } from "./cache/entities/ServerTelemetryEntity";
+export { AuthorityMetadataEntity } from "./cache/entities/AuthorityMetadataEntity";
+export { ThrottlingEntity } from "./cache/entities/ThrottlingEntity";
+export { ICachePlugin } from "./cache/interface/ICachePlugin";
+export { TokenCacheContext } from "./cache/persistence/TokenCacheContext";
+export { ISerializableTokenCache } from "./cache/interface/ISerializableTokenCache";
+// Network Interface
+export {
+    INetworkModule,
+    NetworkRequestOptions,
+    StubbedNetworkModule,
+} from "./network/INetworkModule";
+export {
+    NetworkManager,
+    NetworkResponse,
+    UrlToHttpRequestOptions,
+} from "./network/NetworkManager";
+export { ThrottlingUtils } from "./network/ThrottlingUtils";
+export { RequestThumbprint } from "./network/RequestThumbprint";
+export { IUri } from "./url/IUri";
+export { UrlString } from "./url/UrlString";
+// Crypto Interface
+export {
+    ICrypto,
+    PkceCodes,
+    DEFAULT_CRYPTO_IMPLEMENTATION,
+    SignedHttpRequestParameters,
+} from "./crypto/ICrypto";
+export { SignedHttpRequest } from "./crypto/SignedHttpRequest";
+export { IGuidGenerator } from "./crypto/IGuidGenerator";
+export { JoseHeader } from "./crypto/JoseHeader";
+// Request
+export { BaseAuthRequest } from "./request/BaseAuthRequest";
+export { CommonAuthorizationUrlRequest } from "./request/CommonAuthorizationUrlRequest";
+export { CommonAuthorizationCodeRequest } from "./request/CommonAuthorizationCodeRequest";
+export { CommonRefreshTokenRequest } from "./request/CommonRefreshTokenRequest";
+export { CommonClientCredentialRequest } from "./request/CommonClientCredentialRequest";
+export { CommonOnBehalfOfRequest } from "./request/CommonOnBehalfOfRequest";
+export { CommonSilentFlowRequest } from "./request/CommonSilentFlowRequest";
+export { CommonDeviceCodeRequest } from "./request/CommonDeviceCodeRequest";
+export { CommonEndSessionRequest } from "./request/CommonEndSessionRequest";
+export { CommonUsernamePasswordRequest } from "./request/CommonUsernamePasswordRequest";
+export { NativeRequest } from "./request/NativeRequest";
+export { NativeSignOutRequest } from "./request/NativeSignOutRequest";
+export { RequestParameterBuilder } from "./request/RequestParameterBuilder";
+export { StoreInCache } from "./request/StoreInCache";
+export { ClientAssertion } from "./account/ClientCredentials";
+// Response
+export { AzureRegion } from "./authority/AzureRegion";
+export { AzureRegionConfiguration } from "./authority/AzureRegionConfiguration";
+export { AuthenticationResult } from "./response/AuthenticationResult";
+export { AuthorizationCodePayload } from "./response/AuthorizationCodePayload";
+export { ServerAuthorizationCodeResponse } from "./response/ServerAuthorizationCodeResponse";
+export { ServerAuthorizationTokenResponse } from "./response/ServerAuthorizationTokenResponse";
+export { ExternalTokenResponse } from "./response/ExternalTokenResponse";
+export {
+    DeviceCodeResponse,
+    ServerDeviceCodeResponse,
+} from "./response/DeviceCodeResponse";
+export { ResponseHandler } from "./response/ResponseHandler";
+export { ScopeSet } from "./request/ScopeSet";
+export { AuthenticationHeaderParser } from "./request/AuthenticationHeaderParser";
+// Logger Callback
+export { ILoggerCallback, LogLevel, Logger } from "./logger/Logger";
+// Errors
+export {
+    InteractionRequiredAuthError,
+    InteractionRequiredAuthErrorMessage,
+} from "./error/InteractionRequiredAuthError";
+export { AuthError, AuthErrorMessage } from "./error/AuthError";
+export { ServerError } from "./error/ServerError";
+export {
+    ClientAuthError,
+    ClientAuthErrorMessage,
+} from "./error/ClientAuthError";
+export {
+    ClientConfigurationError,
+    ClientConfigurationErrorMessage,
+} from "./error/ClientConfigurationError";
+// Constants and Utils
+export {
+    Constants,
+    OIDC_DEFAULT_SCOPES,
+    PromptValue,
+    PersistentCacheKeys,
+    ServerResponseType,
+    ResponseMode,
+    CacheOutcome,
+    CredentialType,
+    CacheType,
+    CacheAccountType,
+    AuthenticationScheme,
+    CodeChallengeMethodValues,
+    SSOTypes,
+    PasswordGrantConstants,
+    ThrottlingConstants,
+    ClaimsRequestKeys,
+    HeaderNames,
+    AADServerParamKeys,
+    Errors,
+    THE_FAMILY_ID,
+    ONE_DAY_IN_MS,
+    GrantType,
+    AADAuthorityConstants,
+    HttpStatus,
+} from "./utils/Constants";
+export { StringUtils } from "./utils/StringUtils";
+export { StringDict } from "./utils/MsalTypes";
+export {
+    ProtocolUtils,
+    RequestStateObject,
+    LibraryStateObject,
+} from "./utils/ProtocolUtils";
+export { TimeUtils } from "./utils/TimeUtils";
+export * from "./utils/FunctionWrappers";
+// Server Telemetry
+export { ServerTelemetryManager } from "./telemetry/server/ServerTelemetryManager";
+export { ServerTelemetryRequest } from "./telemetry/server/ServerTelemetryRequest";
+
+// Performance Telemetry
+export {
+    IPerformanceClient,
+    PerformanceCallbackFunction,
+    InProgressPerformanceEvent,
+    QueueMeasurement,
+} from "./telemetry/performance/IPerformanceClient";
+export {
+    IntFields,
+    PerformanceEvent,
+    PerformanceEvents,
+    PerformanceEventStatus,
+    SubMeasurement,
+} from "./telemetry/performance/PerformanceEvent";
+export { IPerformanceMeasurement } from "./telemetry/performance/IPerformanceMeasurement";
+export {
+    PerformanceClient,
+    PreQueueEvent,
+} from "./telemetry/performance/PerformanceClient";
+export { StubPerformanceClient } from "./telemetry/performance/StubPerformanceClient";
+
+export { PopTokenGenerator } from "./crypto/PopTokenGenerator";
+
+export { version } from "./packageMetadata";

package/src/logger/Logger.ts

@@ -0,0 +1,272 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { LoggerOptions } from "../config/ClientConfiguration";
+import { Constants } from "../utils/Constants";
+
+/**
+ * Options for logger messages.
+ */
+export type LoggerMessageOptions = {
+    logLevel: LogLevel;
+    containsPii?: boolean;
+    context?: string;
+    correlationId?: string;
+};
+
+/**
+ * Log message level.
+ */
+export enum LogLevel {
+    Error,
+    Warning,
+    Info,
+    Verbose,
+    Trace,
+}
+
+/**
+ * Callback to send the messages to.
+ */
+export interface ILoggerCallback {
+    (level: LogLevel, message: string, containsPii: boolean): void;
+}
+
+/**
+ * Class which facilitates logging of messages to a specific place.
+ */
+export class Logger {
+    // Correlation ID for request, usually set by user.
+    private correlationId: string;
+
+    // Current log level, defaults to info.
+    private level: LogLevel = LogLevel.Info;
+
+    // Boolean describing whether PII logging is allowed.
+    private piiLoggingEnabled: boolean;
+
+    // Callback to send messages to.
+    private localCallback: ILoggerCallback;
+
+    // Package name implementing this logger
+    private packageName: string;
+
+    // Package version implementing this logger
+    private packageVersion: string;
+
+    constructor(
+        loggerOptions: LoggerOptions,
+        packageName?: string,
+        packageVersion?: string
+    ) {
+        const defaultLoggerCallback = () => {
+            return;
+        };
+        const setLoggerOptions =
+            loggerOptions || Logger.createDefaultLoggerOptions();
+        this.localCallback =
+            setLoggerOptions.loggerCallback || defaultLoggerCallback;
+        this.piiLoggingEnabled = setLoggerOptions.piiLoggingEnabled || false;
+        this.level =
+            typeof setLoggerOptions.logLevel === "number"
+                ? setLoggerOptions.logLevel
+                : LogLevel.Info;
+        this.correlationId =
+            setLoggerOptions.correlationId || Constants.EMPTY_STRING;
+        this.packageName = packageName || Constants.EMPTY_STRING;
+        this.packageVersion = packageVersion || Constants.EMPTY_STRING;
+    }
+
+    private static createDefaultLoggerOptions(): LoggerOptions {
+        return {
+            loggerCallback: () => {
+                // allow users to not set loggerCallback
+            },
+            piiLoggingEnabled: false,
+            logLevel: LogLevel.Info,
+        };
+    }
+
+    /**
+     * Create new Logger with existing configurations.
+     */
+    public clone(
+        packageName: string,
+        packageVersion: string,
+        correlationId?: string
+    ): Logger {
+        return new Logger(
+            {
+                loggerCallback: this.localCallback,
+                piiLoggingEnabled: this.piiLoggingEnabled,
+                logLevel: this.level,
+                correlationId: correlationId || this.correlationId,
+            },
+            packageName,
+            packageVersion
+        );
+    }
+
+    /**
+     * Log message with required options.
+     */
+    private logMessage(
+        logMessage: string,
+        options: LoggerMessageOptions
+    ): void {
+        if (
+            options.logLevel > this.level ||
+            (!this.piiLoggingEnabled && options.containsPii)
+        ) {
+            return;
+        }
+        const timestamp = new Date().toUTCString();
+
+        // Add correlationId to logs if set, correlationId provided on log messages take precedence
+        const logHeader = `[${timestamp}] : [${
+            options.correlationId || this.correlationId || ""
+        }]`;
+
+        const log = `${logHeader} : ${this.packageName}@${
+            this.packageVersion
+        } : ${LogLevel[options.logLevel]} - ${logMessage}`;
+        // debug(`msal:${LogLevel[options.logLevel]}${options.containsPii ? "-Pii": Constants.EMPTY_STRING}${options.context ? `:${options.context}` : Constants.EMPTY_STRING}`)(logMessage);
+        this.executeCallback(
+            options.logLevel,
+            log,
+            options.containsPii || false
+        );
+    }
+
+    /**
+     * Execute callback with message.
+     */
+    executeCallback(
+        level: LogLevel,
+        message: string,
+        containsPii: boolean
+    ): void {
+        if (this.localCallback) {
+            this.localCallback(level, message, containsPii);
+        }
+    }
+
+    /**
+     * Logs error messages.
+     */
+    error(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Error,
+            containsPii: false,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs error messages with PII.
+     */
+    errorPii(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Error,
+            containsPii: true,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs warning messages.
+     */
+    warning(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Warning,
+            containsPii: false,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs warning messages with PII.
+     */
+    warningPii(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Warning,
+            containsPii: true,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs info messages.
+     */
+    info(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Info,
+            containsPii: false,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs info messages with PII.
+     */
+    infoPii(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Info,
+            containsPii: true,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs verbose messages.
+     */
+    verbose(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Verbose,
+            containsPii: false,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs verbose messages with PII.
+     */
+    verbosePii(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Verbose,
+            containsPii: true,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs trace messages.
+     */
+    trace(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Trace,
+            containsPii: false,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Logs trace messages with PII.
+     */
+    tracePii(message: string, correlationId?: string): void {
+        this.logMessage(message, {
+            logLevel: LogLevel.Trace,
+            containsPii: true,
+            correlationId: correlationId || Constants.EMPTY_STRING,
+        });
+    }
+
+    /**
+     * Returns whether PII Logging is enabled or not.
+     */
+    isPiiLoggingEnabled(): boolean {
+        return this.piiLoggingEnabled || false;
+    }
+}

package/src/network/INetworkModule.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthError } from "../error/AuthError";
+import { NetworkResponse } from "./NetworkManager";
+
+/**
+ * Options allowed by network request APIs.
+ */
+export type NetworkRequestOptions = {
+    headers?: Record<string, string>;
+    body?: string;
+};
+
+/**
+ * Client network interface to send backend requests.
+ * @interface
+ */
+export interface INetworkModule {
+    /**
+     * Interface function for async network "GET" requests. Based on the Fetch standard: https://fetch.spec.whatwg.org/
+     * @param url
+     * @param requestParams
+     * @param enableCaching
+     */
+    sendGetRequestAsync<T>(
+        url: string,
+        options?: NetworkRequestOptions,
+        cancellationToken?: number
+    ): Promise<NetworkResponse<T>>;
+
+    /**
+     * Interface function for async network "POST" requests. Based on the Fetch standard: https://fetch.spec.whatwg.org/
+     * @param url
+     * @param requestParams
+     * @param enableCaching
+     */
+    sendPostRequestAsync<T>(
+        url: string,
+        options?: NetworkRequestOptions
+    ): Promise<NetworkResponse<T>>;
+}
+
+export const StubbedNetworkModule: INetworkModule = {
+    sendGetRequestAsync: () => {
+        const notImplErr =
+            "Network interface - sendGetRequestAsync() has not been implemented for the Network interface.";
+        return Promise.reject(AuthError.createUnexpectedError(notImplErr));
+    },
+    sendPostRequestAsync: () => {
+        const notImplErr =
+            "Network interface - sendPostRequestAsync() has not been implemented for the Network interface.";
+        return Promise.reject(AuthError.createUnexpectedError(notImplErr));
+    },
+};

package/src/network/NetworkManager.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { INetworkModule, NetworkRequestOptions } from "./INetworkModule";
+import { RequestThumbprint } from "./RequestThumbprint";
+import { ThrottlingUtils } from "./ThrottlingUtils";
+import { CacheManager } from "../cache/CacheManager";
+import { AuthError } from "../error/AuthError";
+import { ClientAuthError } from "../error/ClientAuthError";
+import { ServerAuthorizationTokenResponse } from "../response/ServerAuthorizationTokenResponse";
+
+export type NetworkResponse<T> = {
+    headers: Record<string, string>;
+    body: T;
+    status: number;
+};
+
+export type UrlToHttpRequestOptions = {
+    protocol: string;
+    hostname: string;
+    hash: string;
+    search: string;
+    pathname: string;
+    path: string;
+    href: string;
+    port?: number;
+    auth?: string;
+};
+
+/** @internal */
+export class NetworkManager {
+    private networkClient: INetworkModule;
+    private cacheManager: CacheManager;
+
+    constructor(networkClient: INetworkModule, cacheManager: CacheManager) {
+        this.networkClient = networkClient;
+        this.cacheManager = cacheManager;
+    }
+
+    /**
+     * Wraps sendPostRequestAsync with necessary preflight and postflight logic
+     * @param thumbprint
+     * @param tokenEndpoint
+     * @param options
+     */
+    async sendPostRequest<T extends ServerAuthorizationTokenResponse>(
+        thumbprint: RequestThumbprint,
+        tokenEndpoint: string,
+        options: NetworkRequestOptions
+    ): Promise<NetworkResponse<T>> {
+        ThrottlingUtils.preProcess(this.cacheManager, thumbprint);
+
+        let response;
+        try {
+            response = await this.networkClient.sendPostRequestAsync<T>(
+                tokenEndpoint,
+                options
+            );
+        } catch (e) {
+            if (e instanceof AuthError) {
+                throw e;
+            } else {
+                throw ClientAuthError.createNetworkError(
+                    tokenEndpoint,
+                    e as string
+                );
+            }
+        }
+
+        ThrottlingUtils.postProcess(this.cacheManager, thumbprint, response);
+
+        return response;
+    }
+}

package/src/network/RequestThumbprint.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthenticationScheme } from "../utils/Constants";
+
+/**
+ * Type representing a unique request thumbprint.
+ */
+export type RequestThumbprint = {
+    clientId: string;
+    authority: string;
+    scopes: Array<string>;
+    homeAccountIdentifier?: string;
+    claims?: string;
+    authenticationScheme?: AuthenticationScheme;
+    resourceRequestMethod?: string;
+    resourceRequestUri?: string;
+    shrClaims?: string;
+    sshKid?: string;
+};