@azure/msal-node-extensions 1.0.0-alpha.1 → 1.0.0-alpha.13

package/src/persistence/PersistenceCachePlugin.ts

@@ -1,96 +1,106 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { IPersistence } from "../persistence/IPersistence";
-import { CrossPlatformLock } from "../lock/CrossPlatformLock";
-import { CrossPlatformLockOptions } from "../lock/CrossPlatformLockOptions";
-import { pid } from "process";
-import { Logger } from "@azure/msal-common";
-
-/**
- * MSAL cache plugin which enables callers to write the MSAL cache to disk on Windows,
- * macOs, and Linux.
- *
- * - Persistence can be one of:
- * - FilePersistence: Writes and reads from an unencrypted file. Can be used on Windows,
- * macOs, or Linux.
- * - FilePersistenceWithDataProtection: Used on Windows, writes and reads from file encrypted
- * with windows dpapi-addon.
- * - KeychainPersistence: Used on macOs, writes and reads from keychain.
- * - LibSecretPersistence: Used on linux, writes and reads from secret service API. Requires
- * libsecret be installed.
- */
-export class PersistenceCachePlugin {
-
-    public persistence: IPersistence;
-    public lastSync: number;
-    public currentCache: string;
-    public lockFilePath: string;
-
-    private crossPlatformLock: CrossPlatformLock;
-
-    private logger: Logger;
-
-    constructor(persistence: IPersistence, lockOptions?: CrossPlatformLockOptions) {
-        this.persistence = persistence;
-
-        // initialize logger
-        this.logger = persistence.getLogger();
-
-        // create file lock
-        this.lockFilePath = `${this.persistence.getFilePath()}.lockfile`;
-        this.crossPlatformLock = new CrossPlatformLock(this.lockFilePath, this.logger, lockOptions);
-
-        // initialize default values
-        this.lastSync = 0;
-        this.currentCache = null;
-    }
-
-    /**
-     * Reads from storage and avoids saves an in memory copy. If persistence has not been updated
-     * since last time data was read, in memory copy is used.
-     */
-    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}`);
-                await this.crossPlatformLock.lock();
-
-                this.currentCache = await this.persistence.load();
-                this.lastSync = new Date().getTime();
-                this.logger.info(`Last sync time updated to: ${this.lastSync}`);
-            } finally {
-                await this.crossPlatformLock.unlock();
-                this.logger.info(`Pid ${pid} Released 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.
-     */
-    public async writeToStorage(callback: (diskState: string) => string): Promise<void> {
-        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}`);
-            }
-
-            this.currentCache = await callback(this.currentCache);
-            await this.persistence.save(this.currentCache);
-        } finally {
-            await this.crossPlatformLock.unlock();
-            this.logger.info(`Pid ${pid} Released lock`);
-        }
-    }
-}
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IPersistence } from "./IPersistence";
+import { CrossPlatformLock } from "../lock/CrossPlatformLock";
+import { CrossPlatformLockOptions } from "../lock/CrossPlatformLockOptions";
+import { pid } from "process";
+import { TokenCacheContext, ICachePlugin, Logger } from "@azure/msal-common";
+
+/**
+ * MSAL cache plugin which enables callers to write the MSAL cache to disk on Windows,
+ * macOs, and Linux.
+ *
+ * - Persistence can be one of:
+ * - FilePersistence: Writes and reads from an unencrypted file. Can be used on Windows,
+ * macOs, or Linux.
+ * - FilePersistenceWithDataProtection: Used on Windows, writes and reads from file encrypted
+ * with windows dpapi-addon.
+ * - KeychainPersistence: Used on macOs, writes and reads from keychain.
+ * - LibSecretPersistence: Used on linux, writes and reads from secret service API. Requires
+ * libsecret be installed.
+ */
+export class PersistenceCachePlugin implements ICachePlugin {
+
+    public persistence: IPersistence;
+    public lastSync: number;
+    public currentCache: string;
+    public lockFilePath: string;
+
+    private crossPlatformLock: CrossPlatformLock;
+
+    private logger: Logger;
+
+    constructor(persistence: IPersistence, lockOptions?: CrossPlatformLockOptions) {
+        this.persistence = persistence;
+
+        // initialize logger
+        this.logger = persistence.getLogger();
+
+        // create file lock
+        this.lockFilePath = `${this.persistence.getFilePath()}.lockfile`;
+        this.crossPlatformLock = new CrossPlatformLock(this.lockFilePath, this.logger, lockOptions);
+
+        // initialize default values
+        this.lastSync = 0;
+        this.currentCache = null;
+    }
+
+    /**
+     * 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 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.logger.info(`Last sync time updated to: ${this.lastSync}`);
+        } finally {
+            if (!cacheContext.cacheHasChanged) {
+                await this.crossPlatformLock.unlock();
+                this.logger.info(`Pid ${pid} released lock`);
+            } else {
+                this.logger.info(`Pid ${pid} beforeCacheAccess did not release lock`);
+            }
+        }
+    }
+
+    /**
+     * Writes to storage if MSAL in memory copy of cache has been changed.
+     */
+    public async afterCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
+        this.logger.info("Executing after cache access");
+        try {
+            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");
+            }
+        } finally {
+            await this.crossPlatformLock.unlock();
+            this.logger.info(`Pid ${pid} afterCacheAccess released lock`);
+        }
+    }
+}

package/src/persistence/PersistenceCreator.ts

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FilePersistenceWithDataProtection } from "../persistence/FilePersistenceWithDataProtection";
+import { LibSecretPersistence } from "../persistence/LibSecretPersistence";
+import { KeychainPersistence } from "../persistence/KeychainPersistence";
+import { DataProtectionScope } from "../persistence/DataProtectionScope";
+import { Environment } from "../utils/Environment";
+import { IPersistence } from "./IPersistence";
+import { FilePersistence } from "./FilePersistence";
+import { PersistenceError } from "../error/PersistenceError";
+import { IPersistenceConfiguration } from "../persistence/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);
+        }
+
+        // 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);
+        }
+
+        // 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);
+        }
+
+        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);
+
+                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,24 +1,62 @@
-/*
- * 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",
-
-    /**
-     * 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"
+};

package/src/utils/Environment.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import path from "path";
+import { Constants, Platform } from "./Constants";
+import { PersistenceError } from "../error/PersistenceError";
+import { StringUtils } from "@azure/msal-common";
+
+export class Environment {
+    static get homeEnvVar() {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.HOME);
+    }
+    
+    static get lognameEnvVar() {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.LOGNAME);
+    }
+
+    static get userEnvVar() {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.USER);
+    }
+
+    static get lnameEnvVar() {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.LNAME);
+    }
+
+    static get usernameEnvVar() {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.USERNAME);
+    }
+
+    static getEnvironmentVariable(name: string): string {
+        return process.env[name];
+    }
+
+    static getEnvironmentPlatform(): string {
+        return process.platform;
+    }
+
+    static isWindowsPlatform(): boolean {
+        return this.getEnvironmentPlatform() === Platform.WINDOWS;
+    }
+
+    static isLinuxPlatform(): boolean {
+        return this.getEnvironmentPlatform() === Platform.LINUX;
+    }
+
+    static isMacPlatform(): boolean {
+        return this.getEnvironmentPlatform() === Platform.MACOS;
+    }
+
+    static isLinuxRootUser(): boolean {
+        return process.getuid() == Constants.LINUX_ROOT_USER_GUID;
+    }
+
+    static getUserRootDirectory(): string {
+        return !this.isWindowsPlatform ?
+            this.getUserHomeDirOnUnix() :
+            this.getUserHomeDirOnWindows()
+    }
+
+    static getUserHomeDirOnWindows(): string {
+        return this.getEnvironmentVariable(Constants.ENVIRONMENT.LOCAL_APPLICATION_DATA);
+    }
+
+    static getUserHomeDirOnUnix(): string | null {
+        if (this.isWindowsPlatform()) {
+            throw PersistenceError.createNotSupportedError("Getting the user home directory for unix is not supported in windows")
+        }
+
+        if (!StringUtils.isEmpty(this.homeEnvVar)) {
+            return this.homeEnvVar;
+        }
+
+        let username = null;
+        if (!StringUtils.isEmpty(this.lognameEnvVar)) {
+            username = this.lognameEnvVar;
+        } else if (!StringUtils.isEmpty(this.userEnvVar)) {
+            username = this.userEnvVar;
+        } else if (!StringUtils.isEmpty(this.lnameEnvVar)) {
+            username = this.lnameEnvVar;
+        } else if (!StringUtils.isEmpty(this.usernameEnvVar)) {
+            username = this.usernameEnvVar;
+        }
+
+        if (this.isMacPlatform()) {
+            return !StringUtils.isEmpty(username) ? path.join("/Users", username) : null;
+        } else if (this.isLinuxPlatform()) {
+            if (this.isLinuxRootUser()) {
+                return "/root";
+            } else {
+                return !StringUtils.isEmpty(username) ? path.join("/home", username) : null;
+            }
+        } else {
+            throw PersistenceError.createNotSupportedError("Getting the user home directory for unix is not supported in windows")
+        }
+
+    }
+}

package/changelog.md

@@ -1,8 +0,0 @@
-# 1.0.0-alpha.0
-
-- Extensions 1: Sets directory structure, adds Windows DPAPI Node addon (#1830)
-- Extensions 2: Add cross process lock (#1831)
-- Extensions 3: Add cache persistence plugin, persistence on Windows, Linux, and Mac (#1832)
-- Extensions 4: Add sample (#1834)
-- Extensions 5: Add documentation, add logger (#1835)
-- Extensions 6: Add tests (#1849)