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

package/src/request/ScopeSet.ts

@@ -0,0 +1,246 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    createClientConfigurationError,
+    ClientConfigurationErrorCodes,
+} from "../error/ClientConfigurationError";
+import { StringUtils } from "../utils/StringUtils";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError";
+import { Constants, OIDC_SCOPES } from "../utils/Constants";
+
+/**
+ * The ScopeSet class creates a set of scopes. Scopes are case-insensitive, unique values, so the Set object in JS makes
+ * the most sense to implement for this class. All scopes are trimmed and converted to lower case strings in intersection and union functions
+ * to ensure uniqueness of strings.
+ */
+export class ScopeSet {
+    // Scopes as a Set of strings
+    private scopes: Set<string>;
+
+    constructor(inputScopes: Array<string>) {
+        // Filter empty string and null/undefined array items
+        const scopeArr = inputScopes
+            ? StringUtils.trimArrayEntries([...inputScopes])
+            : [];
+        const filteredInput = scopeArr
+            ? StringUtils.removeEmptyStringsFromArray(scopeArr)
+            : [];
+
+        // Validate and filter scopes (validate function throws if validation fails)
+        this.validateInputScopes(filteredInput);
+
+        this.scopes = new Set<string>(); // Iterator in constructor not supported by IE11
+        filteredInput.forEach((scope) => this.scopes.add(scope));
+    }
+
+    /**
+     * Factory method to create ScopeSet from space-delimited string
+     * @param inputScopeString
+     * @param appClientId
+     * @param scopesRequired
+     */
+    static fromString(inputScopeString: string): ScopeSet {
+        const scopeString = inputScopeString || Constants.EMPTY_STRING;
+        const inputScopes: Array<string> = scopeString.split(" ");
+        return new ScopeSet(inputScopes);
+    }
+
+    /**
+     * Creates the set of scopes to search for in cache lookups
+     * @param inputScopeString
+     * @returns
+     */
+    static createSearchScopes(inputScopeString: Array<string>): ScopeSet {
+        const scopeSet = new ScopeSet(inputScopeString);
+        if (!scopeSet.containsOnlyOIDCScopes()) {
+            scopeSet.removeOIDCScopes();
+        } else {
+            scopeSet.removeScope(Constants.OFFLINE_ACCESS_SCOPE);
+        }
+
+        return scopeSet;
+    }
+
+    /**
+     * Used to validate the scopes input parameter requested  by the developer.
+     * @param {Array<string>} inputScopes - Developer requested permissions. Not all scopes are guaranteed to be included in the access token returned.
+     * @param {boolean} scopesRequired - Boolean indicating whether the scopes array is required or not
+     */
+    private validateInputScopes(inputScopes: Array<string>): void {
+        // Check if scopes are required but not given or is an empty array
+        if (!inputScopes || inputScopes.length < 1) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.emptyInputScopesError
+            );
+        }
+    }
+
+    /**
+     * Check if a given scope is present in this set of scopes.
+     * @param scope
+     */
+    containsScope(scope: string): boolean {
+        const lowerCaseScopes = this.printScopesLowerCase().split(" ");
+        const lowerCaseScopesSet = new ScopeSet(lowerCaseScopes);
+        // compare lowercase scopes
+        return scope
+            ? lowerCaseScopesSet.scopes.has(scope.toLowerCase())
+            : false;
+    }
+
+    /**
+     * Check if a set of scopes is present in this set of scopes.
+     * @param scopeSet
+     */
+    containsScopeSet(scopeSet: ScopeSet): boolean {
+        if (!scopeSet || scopeSet.scopes.size <= 0) {
+            return false;
+        }
+
+        return (
+            this.scopes.size >= scopeSet.scopes.size &&
+            scopeSet.asArray().every((scope) => this.containsScope(scope))
+        );
+    }
+
+    /**
+     * Check if set of scopes contains only the defaults
+     */
+    containsOnlyOIDCScopes(): boolean {
+        let defaultScopeCount = 0;
+        OIDC_SCOPES.forEach((defaultScope: string) => {
+            if (this.containsScope(defaultScope)) {
+                defaultScopeCount += 1;
+            }
+        });
+
+        return this.scopes.size === defaultScopeCount;
+    }
+
+    /**
+     * Appends single scope if passed
+     * @param newScope
+     */
+    appendScope(newScope: string): void {
+        if (newScope) {
+            this.scopes.add(newScope.trim());
+        }
+    }
+
+    /**
+     * Appends multiple scopes if passed
+     * @param newScopes
+     */
+    appendScopes(newScopes: Array<string>): void {
+        try {
+            newScopes.forEach((newScope) => this.appendScope(newScope));
+        } catch (e) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.cannotAppendScopeSet
+            );
+        }
+    }
+
+    /**
+     * Removes element from set of scopes.
+     * @param scope
+     */
+    removeScope(scope: string): void {
+        if (!scope) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.cannotRemoveEmptyScope
+            );
+        }
+        this.scopes.delete(scope.trim());
+    }
+
+    /**
+     * Removes default scopes from set of scopes
+     * Primarily used to prevent cache misses if the default scopes are not returned from the server
+     */
+    removeOIDCScopes(): void {
+        OIDC_SCOPES.forEach((defaultScope: string) => {
+            this.scopes.delete(defaultScope);
+        });
+    }
+
+    /**
+     * Combines an array of scopes with the current set of scopes.
+     * @param otherScopes
+     */
+    unionScopeSets(otherScopes: ScopeSet): Set<string> {
+        if (!otherScopes) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.emptyInputScopeSet
+            );
+        }
+        const unionScopes = new Set<string>(); // Iterator in constructor not supported in IE11
+        otherScopes.scopes.forEach((scope) =>
+            unionScopes.add(scope.toLowerCase())
+        );
+        this.scopes.forEach((scope) => unionScopes.add(scope.toLowerCase()));
+        return unionScopes;
+    }
+
+    /**
+     * Check if scopes intersect between this set and another.
+     * @param otherScopes
+     */
+    intersectingScopeSets(otherScopes: ScopeSet): boolean {
+        if (!otherScopes) {
+            throw createClientAuthError(
+                ClientAuthErrorCodes.emptyInputScopeSet
+            );
+        }
+
+        // Do not allow OIDC scopes to be the only intersecting scopes
+        if (!otherScopes.containsOnlyOIDCScopes()) {
+            otherScopes.removeOIDCScopes();
+        }
+        const unionScopes = this.unionScopeSets(otherScopes);
+        const sizeOtherScopes = otherScopes.getScopeCount();
+        const sizeThisScopes = this.getScopeCount();
+        const sizeUnionScopes = unionScopes.size;
+        return sizeUnionScopes < sizeThisScopes + sizeOtherScopes;
+    }
+
+    /**
+     * Returns size of set of scopes.
+     */
+    getScopeCount(): number {
+        return this.scopes.size;
+    }
+
+    /**
+     * Returns the scopes as an array of string values
+     */
+    asArray(): Array<string> {
+        const array: Array<string> = [];
+        this.scopes.forEach((val) => array.push(val));
+        return array;
+    }
+
+    /**
+     * Prints scopes into a space-delimited string
+     */
+    printScopes(): string {
+        if (this.scopes) {
+            const scopeArr = this.asArray();
+            return scopeArr.join(" ");
+        }
+        return Constants.EMPTY_STRING;
+    }
+
+    /**
+     * Prints scopes into a space-delimited lower-case string (used for caching)
+     */
+    printScopesLowerCase(): string {
+        return this.printScopes().toLowerCase();
+    }
+}

package/src/request/StoreInCache.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Controls whether tokens should be stored in the cache or not. If set to false, tokens may still be acquired and returned but will not be cached for later retrieval.
+ */
+export type StoreInCache = {
+    /* Indicates whether or not the acquired accessToken will be stored in the cache */
+    accessToken?: boolean;
+    /* Indicates whether or not the acquired idToken will be stored in the cache */
+    idToken?: boolean;
+    /* Indicates whether or not the acquired refreshToken will be stored in the cache */
+    refreshToken?: boolean;
+};

package/src/response/AuthenticationResult.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AccountInfo } from "../account/AccountInfo";
+
+/**
+ * Result returned from the authority's token endpoint.
+ * - uniqueId               - `oid` or `sub` claim from ID token
+ * - tenantId               - `tid` claim from ID token
+ * - scopes                 - Scopes that are validated for the respective token
+ * - account                - An account object representation of the currently signed-in user
+ * - idToken                - Id token received as part of the response
+ * - idTokenClaims          - MSAL-relevant ID token claims
+ * - accessToken            - Access token or SSH certificate received as part of the response
+ * - fromCache              - Boolean denoting whether token came from cache
+ * - expiresOn              - Javascript Date object representing relative expiration of access token
+ * - extExpiresOn           - Javascript Date object representing extended relative expiration of access token in case of server outage
+ * - refreshOn              - Javascript Date object representing relative time until an access token must be refreshed
+ * - state                  - Value passed in by user in request
+ * - familyId               - Family ID identifier, usually only used for refresh tokens
+ * - requestId              - Request ID returned as part of the response
+ */
+export type AuthenticationResult = {
+    authority: string;
+    uniqueId: string;
+    tenantId: string;
+    scopes: Array<string>;
+    account: AccountInfo | null;
+    idToken: string;
+    idTokenClaims: object;
+    accessToken: string;
+    fromCache: boolean;
+    expiresOn: Date | null;
+    extExpiresOn?: Date;
+    refreshOn?: Date;
+    tokenType: string;
+    correlationId: string;
+    requestId?: string;
+    state?: string;
+    familyId?: string;
+    cloudGraphHostName?: string;
+    msGraphHost?: string;
+    code?: string;
+    fromNativeBroker?: boolean;
+};

package/src/response/AuthorizationCodePayload.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Response returned after processing the code response query string or fragment.
+ */
+export type AuthorizationCodePayload = {
+    code: string;
+    cloud_instance_name?: string;
+    cloud_instance_host_name?: string;
+    cloud_graph_host_name?: string;
+    msgraph_host?: string;
+    state?: string;
+    nonce?: string;
+    client_info?: string;
+};

package/src/response/DeviceCodeResponse.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * DeviceCode returned by the security token service device code endpoint containing information necessary for device code flow.
+ * - userCode: code which user needs to provide when authenticating at the verification URI
+ * - deviceCode: code which should be included in the request for the access token
+ * - verificationUri: URI where user can authenticate
+ * - expiresIn: expiration time of the device code in seconds
+ * - interval: interval at which the STS should be polled at
+ * - message: message which should be displayed to the user
+ */
+export type DeviceCodeResponse = {
+    userCode: string;
+    deviceCode: string;
+    verificationUri: string;
+    expiresIn: number;
+    interval: number;
+    message: string;
+};
+
+export type ServerDeviceCodeResponse = {
+    user_code: string;
+    device_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+    message: string;
+};

package/src/response/ExternalTokenResponse.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ServerAuthorizationTokenResponse } from "./ServerAuthorizationTokenResponse";
+
+/**
+ * Response object used for loading external tokens to cache.
+ * - token_type: Indicates the token type value. The only type that Azure AD supports is Bearer.
+ * - scope: The scopes that the access_token is valid for.
+ * - expires_in: How long the access token is valid (in seconds).
+ * - id_token: A JSON Web Token (JWT). The app can decode the segments of this token to request information about the user who signed in.
+ * - refresh_token: An OAuth 2.0 refresh token. The app can use this token acquire additional access tokens after the current access token expires.
+ * - access_token: The requested access token. The app can use this token to authenticate to the secured resource, such as a web API.
+ * - client_info: Client info object
+ */
+export type ExternalTokenResponse = Pick<
+    ServerAuthorizationTokenResponse,
+    "token_type" | "scope" | "expires_in" | "id_token" | "refresh_token"
+> & {
+    access_token?: string;
+    client_info?: string;
+};

package/src/response/IMDSBadResponse.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type IMDSBadResponse = {
+    error: string;
+    "newest-versions": Array<string>;
+};