@azure/msal-common 14.0.2 → 14.0.3

package/src/crypto/JoseHeader.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { JoseHeaderError } from "../error/JoseHeaderError";
+import { JsonTypes } from "../utils/Constants";
+
+export type JoseHeaderOptions = {
+    typ?: JsonTypes;
+    alg?: string;
+    kid?: string;
+};
+
+/** @internal */
+export class JoseHeader {
+    public typ?: JsonTypes;
+    public alg?: string;
+    public kid?: string;
+
+    constructor(options: JoseHeaderOptions) {
+        this.typ = options.typ;
+        this.alg = options.alg;
+        this.kid = options.kid;
+    }
+
+    /**
+     * Builds SignedHttpRequest formatted JOSE Header from the
+     * JOSE Header options provided or previously set on the object and returns
+     * the stringified header object.
+     * Throws if keyId or algorithm aren't provided since they are required for Access Token Binding.
+     * @param shrHeaderOptions
+     * @returns
+     */
+    static getShrHeaderString(shrHeaderOptions: JoseHeaderOptions): string {
+        // KeyID is required on the SHR header
+        if (!shrHeaderOptions.kid) {
+            throw JoseHeaderError.createMissingKidError();
+        }
+
+        // Alg is required on the SHR header
+        if (!shrHeaderOptions.alg) {
+            throw JoseHeaderError.createMissingAlgError();
+        }
+
+        const shrHeader = new JoseHeader({
+            // Access Token PoP headers must have type pop, but the type header can be overriden for special cases
+            typ: shrHeaderOptions.typ || JsonTypes.Pop,
+            kid: shrHeaderOptions.kid,
+            alg: shrHeaderOptions.alg,
+        });
+
+        return JSON.stringify(shrHeader);
+    }
+}

package/src/crypto/PopTokenGenerator.ts

@@ -0,0 +1,155 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ICrypto, SignedHttpRequestParameters } from "./ICrypto";
+import { TimeUtils } from "../utils/TimeUtils";
+import { UrlString } from "../url/UrlString";
+import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient";
+import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent";
+
+/**
+ * See eSTS docs for more info.
+ * - A kid element, with the value containing an RFC 7638-compliant JWK thumbprint that is base64 encoded.
+ * -  xms_ksl element, representing the storage location of the key's secret component on the client device. One of two values:
+ *      - sw: software storage
+ *      - uhw: hardware storage
+ */
+type ReqCnf = {
+    kid: string;
+    xms_ksl: KeyLocation;
+};
+
+export type ReqCnfData = {
+    kid: string;
+    reqCnfString: string;
+    reqCnfHash: string;
+};
+
+const KeyLocation = {
+    SW: "sw",
+    UHW: "uhw",
+} as const;
+export type KeyLocation = (typeof KeyLocation)[keyof typeof KeyLocation];
+
+/** @internal */
+export class PopTokenGenerator {
+    private cryptoUtils: ICrypto;
+    private performanceClient?: IPerformanceClient;
+
+    constructor(cryptoUtils: ICrypto, performanceClient?: IPerformanceClient) {
+        this.cryptoUtils = cryptoUtils;
+        this.performanceClient = performanceClient;
+    }
+
+    /**
+     * Generates the req_cnf validated at the RP in the POP protocol for SHR parameters
+     * and returns an object containing the keyid, the full req_cnf string and the req_cnf string hash
+     * @param request
+     * @returns
+     */
+    async generateCnf(
+        request: SignedHttpRequestParameters
+    ): Promise<ReqCnfData> {
+        this.performanceClient?.addQueueMeasurement(
+            PerformanceEvents.PopTokenGenerateCnf,
+            request.correlationId
+        );
+
+        this.performanceClient?.setPreQueueTime(
+            PerformanceEvents.PopTokenGenerateKid,
+            request.correlationId
+        );
+        const reqCnf = await this.generateKid(request);
+        const reqCnfString: string = this.cryptoUtils.base64Encode(
+            JSON.stringify(reqCnf)
+        );
+
+        return {
+            kid: reqCnf.kid,
+            reqCnfString,
+            reqCnfHash: await this.cryptoUtils.hashString(reqCnfString),
+        };
+    }
+
+    /**
+     * Generates key_id for a SHR token request
+     * @param request
+     * @returns
+     */
+    async generateKid(request: SignedHttpRequestParameters): Promise<ReqCnf> {
+        this.performanceClient?.addQueueMeasurement(
+            PerformanceEvents.PopTokenGenerateKid,
+            request.correlationId
+        );
+
+        const kidThumbprint = await this.cryptoUtils.getPublicKeyThumbprint(
+            request
+        );
+
+        return {
+            kid: kidThumbprint,
+            xms_ksl: KeyLocation.SW,
+        };
+    }
+
+    /**
+     * Signs the POP access_token with the local generated key-pair
+     * @param accessToken
+     * @param request
+     * @returns
+     */
+    async signPopToken(
+        accessToken: string,
+        keyId: string,
+        request: SignedHttpRequestParameters
+    ): Promise<string> {
+        return this.signPayload(accessToken, keyId, request);
+    }
+
+    /**
+     * Utility function to generate the signed JWT for an access_token
+     * @param payload
+     * @param kid
+     * @param request
+     * @param claims
+     * @returns
+     */
+    async signPayload(
+        payload: string,
+        keyId: string,
+        request: SignedHttpRequestParameters,
+        claims?: object
+    ): Promise<string> {
+        // Deconstruct request to extract SHR parameters
+        const {
+            resourceRequestMethod,
+            resourceRequestUri,
+            shrClaims,
+            shrNonce,
+        } = request;
+
+        const resourceUrlString = resourceRequestUri
+            ? new UrlString(resourceRequestUri)
+            : undefined;
+        const resourceUrlComponents = resourceUrlString?.getUrlComponents();
+        return await this.cryptoUtils.signJwt(
+            {
+                at: payload,
+                ts: TimeUtils.nowSeconds(),
+                m: resourceRequestMethod?.toUpperCase(),
+                u: resourceUrlComponents?.HostNameAndPort,
+                nonce: shrNonce || this.cryptoUtils.createNewGuid(),
+                p: resourceUrlComponents?.AbsolutePath,
+                q: resourceUrlComponents?.QueryString
+                    ? [[], resourceUrlComponents.QueryString]
+                    : undefined,
+                client_claims: shrClaims || undefined,
+                ...claims,
+            },
+            keyId,
+            request.correlationId
+        );
+    }
+}

package/src/crypto/SignedHttpRequest.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type SignedHttpRequest = {
+    at?: string;
+    cnf?: object;
+    m?: string;
+    u?: string;
+    p?: string;
+    q?: [Array<string>, string];
+    ts?: number;
+    nonce?: string;
+    client_claims?: string;
+};

package/src/error/AuthError.ts

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Constants } from "../utils/Constants";
+
+/**
+ * AuthErrorMessage class containing string constants used by error codes and messages.
+ */
+export const AuthErrorMessage = {
+    unexpectedError: {
+        code: "unexpected_error",
+        desc: "Unexpected error in authentication.",
+    },
+    postRequestFailed: {
+        code: "post_request_failed",
+        desc: "Post request failed from the network, could be a 4xx/5xx or a network unavailability. Please check the exact error code for details.",
+    },
+};
+
+/**
+ * General error class thrown by the MSAL.js library.
+ */
+export class AuthError extends Error {
+    /**
+     * Short string denoting error
+     */
+    errorCode: string;
+
+    /**
+     * Detailed description of error
+     */
+    errorMessage: string;
+
+    /**
+     * Describes the subclass of an error
+     */
+    subError: string;
+
+    /**
+     * CorrelationId associated with the error
+     */
+    correlationId: string;
+
+    constructor(errorCode?: string, errorMessage?: string, suberror?: string) {
+        const errorString = errorMessage
+            ? `${errorCode}: ${errorMessage}`
+            : errorCode;
+        super(errorString);
+        Object.setPrototypeOf(this, AuthError.prototype);
+
+        this.errorCode = errorCode || Constants.EMPTY_STRING;
+        this.errorMessage = errorMessage || Constants.EMPTY_STRING;
+        this.subError = suberror || Constants.EMPTY_STRING;
+        this.name = "AuthError";
+    }
+
+    setCorrelationId(correlationId: string): void {
+        this.correlationId = correlationId;
+    }
+
+    /**
+     * Creates an error that is thrown when something unexpected happens in the library.
+     * @param errDesc
+     */
+    static createUnexpectedError(errDesc: string): AuthError {
+        return new AuthError(
+            AuthErrorMessage.unexpectedError.code,
+            `${AuthErrorMessage.unexpectedError.desc}: ${errDesc}`
+        );
+    }
+
+    /**
+     * Creates an error for post request failures.
+     * @param errDesc
+     * @returns
+     */
+    static createPostRequestFailed(errDesc: string): AuthError {
+        return new AuthError(
+            AuthErrorMessage.postRequestFailed.code,
+            `${AuthErrorMessage.postRequestFailed.desc}: ${errDesc}`
+        );
+    }
+}