@azure/msal-node-extensions 1.0.0-alpha.3 → 1.0.0-alpha.31

package/src/persistence/KeychainPersistence.ts

@@ -1,78 +1,89 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { setPassword, getPassword, deletePassword } from "keytar";
-import { FilePersistence } from "./FilePersistence";
-import { IPersistence } from "./IPersistence";
-import { PersistenceError } from "../error/PersistenceError";
-import { Logger, LoggerOptions } from "@azure/msal-common";
-
-/**
- * Uses reads and writes passwords to macOS keychain
- *
- * serviceName: Identifier used as key for whatever value is stored
- * accountName: Account under which password should be stored
- */
-export class KeychainPersistence implements IPersistence {
-
-    protected readonly serviceName;
-    protected readonly accountName;
-    private filePersistence: FilePersistence;
-
-    private constructor(serviceName: string, accountName: string) {
-        this.serviceName = serviceName;
-        this.accountName = accountName;
-    }
-
-    public static async create(
-        fileLocation: string,
-        serviceName: string,
-        accountName: string,
-        loggerOptions?: LoggerOptions): Promise<KeychainPersistence> {
-
-        const persistence = new KeychainPersistence(serviceName, accountName);
-        persistence.filePersistence = await FilePersistence.create(fileLocation, loggerOptions);
-        return persistence;
-    }
-
-    public async save(contents: string): Promise<void> {
-        try {
-            await setPassword(this.serviceName, this.accountName, contents);
-        } catch (err) {
-            throw PersistenceError.createKeychainPersistenceError(err.message);
-        }
-        // Write dummy data to update file mtime
-        await this.filePersistence.save("{}");
-    }
-
-    public async load(): Promise<string | null> {
-        try{
-            return await getPassword(this.serviceName, this.accountName);
-        } catch(err){
-            throw PersistenceError.createKeychainPersistenceError(err.message);
-        }
-    }
-
-    public async delete(): Promise<boolean> {
-        try {
-            await this.filePersistence.delete();
-            return await deletePassword(this.serviceName, this.accountName);
-        } catch (err) {
-            throw PersistenceError.createKeychainPersistenceError(err.message);
-        }
-    }
-
-    public async reloadNecessary(lastSync: number): Promise<boolean> {
-        return this.filePersistence.reloadNecessary(lastSync);
-    }
-
-    public getFilePath(): string {
-        return this.filePersistence.getFilePath();
-    }
-
-    public getLogger(): Logger {
-        return this.filePersistence.getLogger();
-    }
-}
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { setPassword, getPassword, deletePassword } from "keytar";
+import { FilePersistence } from "./FilePersistence";
+import { IPersistence } from "./IPersistence";
+import { PersistenceError } from "../error/PersistenceError";
+import { Logger, LoggerOptions } from "@azure/msal-common";
+import { dirname } from "path";
+import { BasePersistence } from "./BasePersistence";
+
+/**
+ * Uses reads and writes passwords to macOS keychain
+ *
+ * serviceName: Identifier used as key for whatever value is stored
+ * accountName: Account under which password should be stored
+ */
+export class KeychainPersistence extends BasePersistence implements IPersistence {
+
+    protected readonly serviceName;
+    protected readonly accountName;
+    private filePersistence: FilePersistence;
+
+    private constructor(serviceName: string, accountName: string) {
+        super();
+        this.serviceName = serviceName;
+        this.accountName = accountName;
+    }
+
+    public static async create(
+        fileLocation: string,
+        serviceName: string,
+        accountName: string,
+        loggerOptions?: LoggerOptions): Promise<KeychainPersistence> {
+
+        const persistence = new KeychainPersistence(serviceName, accountName);
+        persistence.filePersistence = await FilePersistence.create(fileLocation, loggerOptions);
+        return persistence;
+    }
+
+    public async save(contents: string): Promise<void> {
+        try {
+            await setPassword(this.serviceName, this.accountName, contents);
+        } catch (err) {
+            throw PersistenceError.createKeychainPersistenceError(err.message);
+        }
+        // Write dummy data to update file mtime
+        await this.filePersistence.save("{}");
+    }
+
+    public async load(): Promise<string | null> {
+        try{
+            return await getPassword(this.serviceName, this.accountName);
+        } catch(err){
+            throw PersistenceError.createKeychainPersistenceError(err.message);
+        }
+    }
+
+    public async delete(): Promise<boolean> {
+        try {
+            await this.filePersistence.delete();
+            return await deletePassword(this.serviceName, this.accountName);
+        } catch (err) {
+            throw PersistenceError.createKeychainPersistenceError(err.message);
+        }
+    }
+
+    public async reloadNecessary(lastSync: number): Promise<boolean> {
+        return this.filePersistence.reloadNecessary(lastSync);
+    }
+
+    public getFilePath(): string {
+        return this.filePersistence.getFilePath();
+    }
+
+    public getLogger(): Logger {
+        return this.filePersistence.getLogger();
+    }
+   
+    public createForPersistenceValidation(): Promise<KeychainPersistence> {
+        const testCacheFileLocation = `${dirname(this.filePersistence.getFilePath())}/test.cache`;
+        return KeychainPersistence.create(
+            testCacheFileLocation, 
+            "persistenceValidationServiceName", "persistencValidationAccountName"
+        );
+    }
+}

package/src/persistence/LibSecretPersistence.ts

@@ -1,79 +1,90 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { setPassword, getPassword, deletePassword } from "keytar";
-import { FilePersistence } from "./FilePersistence";
-import { IPersistence } from "./IPersistence";
-import { PersistenceError } from "../error/PersistenceError";
-import { Logger, LoggerOptions } from "@azure/msal-common";
-
-/**
- * Uses reads and writes passwords to Secret Service API/libsecret. Requires libsecret
- * to be installed.
- *
- * serviceName: Identifier used as key for whatever value is stored
- * accountName: Account under which password should be stored
- */
-export class LibSecretPersistence implements IPersistence {
-
-    protected readonly serviceName;
-    protected readonly accountName;
-    private filePersistence: FilePersistence;
-
-    private constructor(serviceName: string, accountName: string) {
-        this.serviceName = serviceName;
-        this.accountName = accountName;
-    }
-
-    public static async create(
-        fileLocation: string,
-        serviceName: string,
-        accountName: string,
-        loggerOptions?: LoggerOptions): Promise<LibSecretPersistence> {
-
-        const persistence = new LibSecretPersistence(serviceName, accountName);
-        persistence.filePersistence = await FilePersistence.create(fileLocation, loggerOptions);
-        return persistence;
-    }
-
-    public async save(contents: string): Promise<void> {
-        try {
-            await setPassword(this.serviceName, this.accountName, contents);
-        } catch (err) {
-            throw PersistenceError.createLibSecretError(err.message);
-        }
-        // Write dummy data to update file mtime
-        await this.filePersistence.save("{}");
-    }
-
-    public async load(): Promise<string | null> {
-        try {
-            return await getPassword(this.serviceName, this.accountName);
-        } catch (err) {
-            throw PersistenceError.createLibSecretError(err.message);
-        }
-    }
-
-    public async delete(): Promise<boolean> {
-        try {
-            await this.filePersistence.delete();
-            return await deletePassword(this.serviceName, this.accountName);
-        } catch (err) {
-            throw PersistenceError.createLibSecretError(err.message);
-        }
-    }
-
-    public async reloadNecessary(lastSync: number): Promise<boolean> {
-        return this.filePersistence.reloadNecessary(lastSync);
-    }
-
-    public getFilePath(): string {
-        return this.filePersistence.getFilePath();
-    }
-
-    public getLogger(): Logger {
-        return this.filePersistence.getLogger();
-    }
-}
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { setPassword, getPassword, deletePassword } from "keytar";
+import { FilePersistence } from "./FilePersistence";
+import { IPersistence } from "./IPersistence";
+import { PersistenceError } from "../error/PersistenceError";
+import { Logger, LoggerOptions } from "@azure/msal-common";
+import { dirname } from "path";
+import { BasePersistence } from "./BasePersistence";
+
+/**
+ * Uses reads and writes passwords to Secret Service API/libsecret. Requires libsecret
+ * to be installed.
+ *
+ * serviceName: Identifier used as key for whatever value is stored
+ * accountName: Account under which password should be stored
+ */
+export class LibSecretPersistence extends BasePersistence implements IPersistence {
+
+    protected readonly serviceName;
+    protected readonly accountName;
+    private filePersistence: FilePersistence;
+
+    private constructor(serviceName: string, accountName: string) {
+        super();
+        this.serviceName = serviceName;
+        this.accountName = accountName;
+    }
+
+    public static async create(
+        fileLocation: string,
+        serviceName: string,
+        accountName: string,
+        loggerOptions?: LoggerOptions): Promise<LibSecretPersistence> {
+
+        const persistence = new LibSecretPersistence(serviceName, accountName);
+        persistence.filePersistence = await FilePersistence.create(fileLocation, loggerOptions);
+        return persistence;
+    }
+
+    public async save(contents: string): Promise<void> {
+        try {
+            await setPassword(this.serviceName, this.accountName, contents);
+        } catch (err) {
+            throw PersistenceError.createLibSecretError(err.message);
+        }
+        // Write dummy data to update file mtime
+        await this.filePersistence.save("{}");
+    }
+
+    public async load(): Promise<string | null> {
+        try {
+            return await getPassword(this.serviceName, this.accountName);
+        } catch (err) {
+            throw PersistenceError.createLibSecretError(err.message);
+        }
+    }
+
+    public async delete(): Promise<boolean> {
+        try {
+            await this.filePersistence.delete();
+            return await deletePassword(this.serviceName, this.accountName);
+        } catch (err) {
+            throw PersistenceError.createLibSecretError(err.message);
+        }
+    }
+
+    public async reloadNecessary(lastSync: number): Promise<boolean> {
+        return this.filePersistence.reloadNecessary(lastSync);
+    }
+
+    public getFilePath(): string {
+        return this.filePersistence.getFilePath();
+    }
+
+    public getLogger(): Logger {
+        return this.filePersistence.getLogger();
+    }
+      
+    public createForPersistenceValidation(): Promise<LibSecretPersistence> {
+        const testCacheFileLocation = `${dirname(this.filePersistence.getFilePath())}/test.cache`;
+        return LibSecretPersistence.create(
+            testCacheFileLocation, 
+            "persistenceValidationServiceName", "persistencValidationAccountName"
+        );
+    }
+}

package/src/persistence/PersistenceCachePlugin.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { IPersistence } from "../persistence/IPersistence";
+import { IPersistence } from "./IPersistence";
 import { CrossPlatformLock } from "../lock/CrossPlatformLock";
 import { CrossPlatformLockOptions } from "../lock/CrossPlatformLockOptions";
 import { pid } from "process";
-import { Logger } from "@azure/msal-common";
+import { TokenCacheContext, ICachePlugin, Logger } from "@azure/msal-common";
 
 /**
  * MSAL cache plugin which enables callers to write the MSAL cache to disk on Windows,
@@ -22,7 +22,7 @@ import { Logger } from "@azure/msal-common";
  * - LibSecretPersistence: Used on linux, writes and reads from secret service API. Requires
  * libsecret be installed.
  */
-export class PersistenceCachePlugin {
+export class PersistenceCachePlugin implements ICachePlugin {
 
     public persistence: IPersistence;
     public lastSync: number;
@@ -49,48 +49,58 @@ export class PersistenceCachePlugin {
     }
 
     /**
-     * Reads from storage and avoids saves an in memory copy. If persistence has not been updated
+     * Reads from storage and saves an in-memory copy. If persistence has not been updated
      * since last time data was read, in memory copy is used.
+     *
+     * If cacheContext.cacheHasChanged === true, then file lock is created and not deleted until
+     * afterCacheAccess() is called, to prevent the cache file from changing in between
+     * beforeCacheAccess() and afterCacheAccess().
      */
-    public async readFromStorage(): Promise<string> {
-        this.logger.info("Reading from storage");
-        if (await this.persistence.reloadNecessary(this.lastSync) || this.currentCache == null) {
-            try {
-                this.logger.info(`Reload necessary. Last sync time: ${this.lastSync}`);
+    public async beforeCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
+        this.logger.info("Executing before cache access");
+        const reloadNecessary = await this.persistence.reloadNecessary(this.lastSync);
+        if (!reloadNecessary && this.currentCache !== null) {
+            if (cacheContext.cacheHasChanged) {
+                this.logger.verbose("Cache context has changed");
                 await this.crossPlatformLock.lock();
+            }
+            return;
+        }
+        try {
+            this.logger.info(`Reload necessary. Last sync time: ${this.lastSync}`);
+            await this.crossPlatformLock.lock();
+
+            this.currentCache = await this.persistence.load();
+            this.lastSync = new Date().getTime();
+            cacheContext.tokenCache.deserialize(this.currentCache);
 
-                this.currentCache = await this.persistence.load();
-                this.lastSync = new Date().getTime();
-                this.logger.info(`Last sync time updated to: ${this.lastSync}`);
-            } finally {
+            this.logger.info(`Last sync time updated to: ${this.lastSync}`);
+        } finally {
+            if (!cacheContext.cacheHasChanged) {
                 await this.crossPlatformLock.unlock();
-                this.logger.info(`Pid ${pid} Released lock`);
+                this.logger.info(`Pid ${pid} released lock`);
+            } else {
+                this.logger.info(`Pid ${pid} beforeCacheAccess did not release lock`);
             }
         }
-        return this.currentCache;
     }
 
     /**
-     * Writes to storage. If persistence has not been updated since last time data was read,
-     * reads and latest state from persistence, sends state via callback, and updates in memory copy.
+     * Writes to storage if MSAL in memory copy of cache has been changed.
      */
-    public async writeToStorage(callback: (diskState: string) => string): Promise<void> {
+    public async afterCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
+        this.logger.info("Executing after cache access");
         try {
-            this.logger.info("Writing to storage");
-            await this.crossPlatformLock.lock();
-
-            if (await this.persistence.reloadNecessary(this.lastSync)) {
-                this.logger.info(`Reload necessary. Last sync time: ${this.lastSync}`);
-                this.currentCache = await this.persistence.load();
-                this.lastSync = new Date().getTime();
-                this.logger.info(`Last sync time updated to: ${this.lastSync}`);
+            if (cacheContext.cacheHasChanged) {
+                this.logger.info("Msal in-memory cache has changed. Writing changes to persistence");
+                this.currentCache = cacheContext.tokenCache.serialize();
+                await this.persistence.save(this.currentCache);
+            } else {
+                this.logger.info("Msal in-memory cache has not changed. Did not write to persistence");
             }
-
-            this.currentCache = await callback(this.currentCache);
-            await this.persistence.save(this.currentCache);
         } finally {
             await this.crossPlatformLock.unlock();
-            this.logger.info(`Pid ${pid} Released lock`);
+            this.logger.info(`Pid ${pid} afterCacheAccess released lock`);
         }
     }
 }

package/src/persistence/PersistenceCreator.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FilePersistenceWithDataProtection } from "./FilePersistenceWithDataProtection";
+import { LibSecretPersistence } from "./LibSecretPersistence";
+import { KeychainPersistence } from "./KeychainPersistence";
+import { DataProtectionScope } from "./DataProtectionScope";
+import { Environment } from "../utils/Environment";
+import { IPersistence } from "./IPersistence";
+import { FilePersistence } from "./FilePersistence";
+import { PersistenceError } from "../error/PersistenceError";
+import { IPersistenceConfiguration } from "./IPersistenceConfiguration";
+
+export class PersistenceCreator {
+    static async createPersistence(config: IPersistenceConfiguration): Promise<IPersistence> {
+        let peristence: IPersistence;
+
+        // On Windows, uses a DPAPI encrypted file
+        if (Environment.isWindowsPlatform()) {
+            if (!config.cachePath || !config.dataProtectionScope) {
+                throw PersistenceError.createPersistenceNotValidatedError(
+                    "Cache path and/or data protection scope not provided for the FilePersistenceWithDataProtection cache plugin");
+            }
+
+            peristence = await FilePersistenceWithDataProtection.create(config.cachePath, DataProtectionScope.CurrentUser, undefined, config.loggerOptions);
+        }
+
+        // On Mac, uses keychain.
+        else if (Environment.isMacPlatform()) {
+            if (!config.cachePath || !config.serviceName || !config.accountName) {
+                throw PersistenceError.createPersistenceNotValidatedError(
+                    "Cache path, service name and/or account name not provided for the KeychainPersistence cache plugin");
+            }
+
+            peristence = await KeychainPersistence.create(config.cachePath, config.serviceName, config.accountName, config.loggerOptions);
+        }
+
+        // On Linux, uses  libsecret to store to secret service. Libsecret has to be installed.
+        else if (Environment.isLinuxPlatform()) {
+            if (!config.cachePath || !config.serviceName || !config.accountName) {
+                throw PersistenceError.createPersistenceNotValidatedError(
+                    "Cache path, service name and/or account name not provided for the LibSecretPersistence cache plugin");
+            }
+
+            peristence = await LibSecretPersistence.create(config.cachePath, config.serviceName, config.accountName, config.loggerOptions);
+        }
+
+        else {
+            throw PersistenceError.createNotSupportedError(
+                "The current environment is not supported by msal-node-extensions yet.");
+        }
+
+        // Initially suppress the error thrown during persistence verification to allow us to fallback to plain text
+        const isPersistenceVerified = await peristence.verifyPersistence().catch(() => false);
+
+        if (!isPersistenceVerified) {
+            if (Environment.isLinuxPlatform() && config.usePlaintextFileOnLinux) {
+                if (!config.cachePath) {
+                    throw PersistenceError.createPersistenceNotValidatedError(
+                        "Cache path not provided for the FilePersistence cache plugin");
+                }
+
+                peristence = await FilePersistence.create(config.cachePath, config.loggerOptions);
+
+                const isFilePersistenceVerified = await peristence.verifyPersistence();
+                if (isFilePersistenceVerified) {
+                    return peristence;
+                }
+            }
+
+            throw PersistenceError.createPersistenceNotVerifiedError("Persistence could not be verified");
+        }
+
+        return peristence;
+    }
+}

package/src/utils/Constants.ts

@@ -1,30 +1,67 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-export const Constants = {
-
-    /**
-     * An existing file was the target of an operation that required that the target not exist
-     */
-    EEXIST_ERROR: "EEXIST",
-
-    /**
-     * No such file or directory: Commonly raised by fs operations to indicate that a component
-     * of the specified pathname does not exist. No entity (file or directory) could be found
-     * by the given path
-     */
-    ENOENT_ERROR: "ENOENT",
-
-    /**
-     * Operation not permitted. An attempt was made to perform an operation that requires 
-     * elevated privileges. 
-     */
-    EPERM_ERROR: "EPERM",
-    
-    /**
-     * Default service name for using MSAL Keytar
-     */
-    DEFAULT_SERVICE_NAME: "msal-node-extensions",
-};
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export const Constants = {
+
+    /**
+     * An existing file was the target of an operation that required that the target not exist
+     */
+    EEXIST_ERROR: "EEXIST",
+
+    /**
+     * No such file or directory: Commonly raised by fs operations to indicate that a component
+     * of the specified pathname does not exist. No entity (file or directory) could be found
+     * by the given path
+     */
+    ENOENT_ERROR: "ENOENT",
+
+    /**
+     * Operation not permitted. An attempt was made to perform an operation that requires 
+     * elevated privileges. 
+     */
+    EPERM_ERROR: "EPERM",
+    
+    /**
+     * Default service name for using MSAL Keytar
+     */
+    DEFAULT_SERVICE_NAME: "msal-node-extensions",
+
+    /**
+     * Test data used to verify underlying persistence mechanism
+     */
+    PERSISTENCE_TEST_DATA: "Dummy data to verify underlying persistence mechanism",
+
+    /**
+     * This is the value of a the guid if the process is being ran by the root user
+     */
+    LINUX_ROOT_USER_GUID: 0,
+
+    /**
+     * List of environment variables
+     */
+    ENVIRONMENT: {
+        HOME: "HOME",
+        LOGNAME: "LOGNAME",
+        USER: "USER",
+        LNAME: "LNAME",
+        USERNAME: "USERNAME",
+        PLATFORM: "platform",
+        LOCAL_APPLICATION_DATA: "LOCALAPPDATA"
+    },
+
+    // Name of the default cache file
+    DEFAULT_CACHE_FILE_NAME: "cache.json"
+};
+
+export enum Platform {
+    WINDOWS = "win32",
+    LINUX = "linux",
+    MACOS = "darwin"
+}
+
+export enum ErrorCodes {
+    INTERATION_REQUIRED_ERROR_CODE = "interaction_required",
+    SERVER_UNAVAILABLE = "server_unavailable"
+}