Cache Rollback/Upgrade support (#7957)

Updates caching layer to version entries and allow caches from multiple
versions to co-exist for a short period of time. This is done to better
support rolling back to an older version

---------

Co-authored-by: Thomas Norling <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

change/@azure-msal-browser-b2a9f217-64a8-4970-b493-270ba68f2a69.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Cache upgrade & rollback support",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-f88c7928-ff1f-4139-abaf-97096f64fb73.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Cache upgrade & rollback support",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-3f484263-5e39-46ea-8c0c-e0c3a88cf8da.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Update internal cache key generation",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/apiReview/msal-browser.api.md

@@ -636,6 +636,7 @@ export type CacheLookupPolicy = (typeof CacheLookupPolicy)[keyof typeof CacheLoo
 // @public
 export type CacheOptions = {
     cacheLocation?: BrowserCacheLocation | string;
+    cacheRetentionDays?: number;
     temporaryCacheLocation?: BrowserCacheLocation | string;
     storeAuthStateInCookie?: boolean;
     secureCookies?: boolean;
@@ -1172,6 +1173,10 @@ export interface ITokenCache {
 export interface IWindowStorage<T> {
     // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
     containsKey(key: string): boolean;
+    // Warning: (ae-forgotten-export) The symbol "EncryptedData" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    decryptData(key: string, data: EncryptedData, correlationId: string): Promise<object | null>;
     // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
     getItem(key: string): T | null;
     getKeys(): string[];
@@ -1205,6 +1210,8 @@ export class LocalStorage implements IWindowStorage<string> {
     // (undocumented)
     containsKey(key: string): boolean;
     // (undocumented)
+    decryptData(key: string, data: EncryptedData, correlationId: string): Promise<object | null>;
+    // (undocumented)
     getItem(key: string): string | null;
     // (undocumented)
     getKeys(): string[];
@@ -1234,6 +1241,8 @@ export class MemoryStorage<T> implements IWindowStorage<T> {
     // (undocumented)
     containsKey(key: string): boolean;
     // (undocumented)
+    decryptData(): Promise<object | null>;
+    // (undocumented)
     getItem(key: string): T | null;
     // (undocumented)
     getKeys(): string[];
@@ -1642,6 +1651,8 @@ export class SessionStorage implements IWindowStorage<string> {
     // (undocumented)
     containsKey(key: string): boolean;
     // (undocumented)
+    decryptData(): Promise<object | null>;
+    // (undocumented)
     getItem(key: string): string | null;
     // (undocumented)
     getKeys(): string[];
@@ -1806,10 +1817,10 @@ export type WrapperSKU = (typeof WrapperSKU)[keyof typeof WrapperSKU];
 // src/app/PublicClientNext.ts:85:79 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
 // src/app/PublicClientNext.ts:88:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/app/PublicClientNext.ts:89:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/cache/LocalStorage.ts:299:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/cache/LocalStorage.ts:357:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/cache/LocalStorage.ts:388:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/config/Configuration.ts:256:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
+// src/cache/LocalStorage.ts:355:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
+// src/cache/LocalStorage.ts:413:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
+// src/cache/LocalStorage.ts:444:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
+// src/config/Configuration.ts:260:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
 // src/event/EventHandler.ts:113:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/event/EventHandler.ts:139:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/index.ts:8:12 - (tsdoc-characters-after-block-tag) The token "@azure" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"

lib/msal-browser/docs/caching.md

@@ -80,6 +80,31 @@ When using MSAL.js with the default configuration in a scenario where the user i
 
 To handle this scenario, you can configure MSAL to use `localStorage` as the cache location by overriding the `temporaryCacheLocation` configuration property. This allows the code verifier and challenge to be stored in the browser's `localStorage,` which is persistent across multiple tabs and windows.
 
+## Cache persistence during MSAL.js upgrades and rollbacks
+
+Occasionally MSAL.js needs to make changes to the shape of the cached artifacts to support new requirements, features or bug fixes. As often as possible these changes will be made in a backwards compatible way so as to ensure that when an application upgrades to a new version or rolls back to an older one the cache present in a user's browser can still be used. However, this is not always possible and you may end up in a state where multiple copies of the cache exist concurrently, one used by the current version of MSAL.js running and another that was written by the version used prior to the upgrade. This is done to allow applications to gracefully rollback, if needed. In the vast majority of upgrades, MSAL.js will migrate any existing cache into the new format for a seamless upgrade experience. In rare cases, such as the upgrade from v3 to v4, this may not be possible due to security or privacy requirements and this will always result in a major version bump. 
+
+When a breaking cache change is made the older cache will be kept for 5 days, by default, to allow for a rollback if needed. The length of time old cache is kept can be configured using the `cacheRetentionDays` cache configuration on `PublicClientApplication`. If the cache has not been actively used within that time it will be cleared the next time MSAL.js is initialized. Additionally, if you do not anticipate needing to rollback you may set this value to `0` to indicate that old cache should always be removed immediately upon upgrading to a new version of MSAL.js. Conversely, if you have a longer rollout window for upgrades you may choose to set this to a longer value.
+
+> [!NOTE]
+> Access and Refresh tokens will be removed once they have expired, even if the configured `cacheRetentionDays` has not yet been reached.
+> Valid access tokens may also be removed at any time if browser storage reaches its storage quota. When storage quotas are reached access tokens will be removed on a First In First Out basis, starting with entries written by a previous version of MSAL.js and then moving on to entries written by the current version of MSAL.js.
+
+```javascript
+const config = {
+    auth: {
+        clientId: "<your-client-id>"
+    },
+    cache: {
+        cacheLocation: "localStorage",
+        cacheRetentionDays: 0 // Set this to the number of days you want old cache to be preserved in the event a rollback is needed (Default 5 days)
+    }
+}
+
+const pca = new PublicClientApplication(config);
+await pca.initialize();
+```
+
 ## Remarks
 
 - We do not recommend apps having business logic dependent on direct use of entities in the cache. Instead, use the appropriate MSAL API when you need to acquire tokens or retrieve accounts.

lib/msal-browser/src/broker/nativeBroker/PlatformAuthProvider.ts

@@ -19,10 +19,8 @@ import { PlatformAuthExtensionHandler } from "./PlatformAuthExtensionHandler.js"
 import { IPlatformAuthHandler } from "./IPlatformAuthHandler.js";
 import { PlatformAuthDOMHandler } from "./PlatformAuthDOMHandler.js";
 import { createNewGuid } from "../../crypto/BrowserCrypto.js";
-import {
-    BrowserCacheLocation,
-    PLATFORM_AUTH_DOM_SUPPORT,
-} from "../../utils/BrowserConstants.js";
+import { BrowserCacheLocation } from "../../utils/BrowserConstants.js";
+import { PLATFORM_AUTH_DOM_SUPPORT } from "../../cache/CacheKeys.js";
 
 /**
  * Checks if the platform broker is available in the current environment.