matrix/matrix-react-sdk
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-react-sdk.git synced 2026-01-03 21:42:32 +03:00
Code Activity

tokens.ts: improve documentation

Browse Source 
Improve variable naming and documentation on the methods in `tokens.ts`.
This commit is contained in:
Richard van der Hoff
2024-09-11 13:03:54 +01:00
parent 0252c1214c
commit 642058d936
1 changed files with 44 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
src/utils/tokens/tokens.ts
View File

@@ -24,13 +24,13 @@ import * as StorageAccess from "../StorageAccess";
*/
/*
* Keys used when storing the tokens in indexeddb or localstorage
* Names used when storing the tokens in indexeddb or localstorage
*/
export const ACCESS_TOKEN_STORAGE_KEY = "mx_access_token";
export const REFRESH_TOKEN_STORAGE_KEY = "mx_refresh_token";
/*
* Used as initialization vector during encryption in persistTokenInStorage
* And decryption in restoreFromLocalStorage
* Names of the tokens. Used as part of the calculation to derive AES keys during encryption in persistTokenInStorage,
* and decryption in restoreFromLocalStorage.
*/
export const ACCESS_TOKEN_IV = "access_token";
export const REFRESH_TOKEN_IV = "refresh_token";
@@ -71,23 +71,31 @@ async function pickleKeyToAesKey(pickleKey: string): Promise<Uint8Array> {
const isEncryptedPayload = (token?: IEncryptedPayload | string | undefined): token is IEncryptedPayload => {
return !!token && typeof token !== "string";
};
/**
* Try to decrypt a token retrieved from storage
* Where token is not encrypted (plain text) returns the plain text token
* Where token is encrypted, attempts decryption. Returns successfully decrypted token, else undefined.
* @param pickleKey pickle key used during encryption of token, or undefined
* @param token
* @param tokenIv initialization vector used during encryption of token eg ACCESS_TOKEN_IV
*
* Where token is not encrypted (plain text) returns the plain text token.
*
* Where token is encrypted, attempts decryption. Returns successfully decrypted token, or throws if
* decryption failed.
*
* @param pickleKey Pickle key: used to derive the encryption key, or undefined if the token is not encrypted.
* Must be the same as provided to {@link persistTokenInStorage}.
* @param token token to be decrypted.
* @param tokenName Name of the token. Used in logging, but also used as an input when generating the actual AES key,
* so the same value must be provided to {@link persistTokenInStorage}.
*
* @returns the decrypted token, or the plain text token. Returns undefined when token cannot be decrypted
*/
export async function tryDecryptToken(
pickleKey: string | undefined,
token: IEncryptedPayload | string | undefined,
tokenIv: string,
tokenName: string,
): Promise<string | undefined> {
if (pickleKey && isEncryptedPayload(token)) {
const encrKey = await pickleKeyToAesKey(pickleKey);
const decryptedToken = await decryptAES(token, encrKey, tokenIv);
const decryptedToken = await decryptAES(token, encrKey, tokenName);
encrKey.fill(0);
return decryptedToken;
}
@@ -100,18 +108,24 @@ export async function tryDecryptToken(
/**
* Persist a token in storage
* When pickle key is present, will attempt to encrypt the token
* Stores in idb, falling back to localStorage
*
* @param storageKey key used to store the token
* @param initializationVector Initialization vector for encrypting the token. Only used when `pickleKey` is present
* @param token the token to store, when undefined any existing token at the storageKey is removed from storage
* @param pickleKey optional pickle key used to encrypt token
* @param hasTokenStorageKey Localstorage key for an item which stores whether we expect to have a token in indexeddb, eg "mx_has_access_token".
* When pickle key is present, will attempt to encrypt the token. If encryption fails (typically because
* WebCrypto is unavailable), the key will be stored unencrypted.
*
* Stores in IndexedDB, falling back to localStorage.
*
* @param storageKey key used to store the token. Note: not an encryption key; rather a localstorage or indexeddb key.
* @param tokenName Name of the token. Used in logging, but also used as an input when generating the actual AES key,
* so the same value must be provided to {@link tryDecryptToken} when decrypting.
* @param token the token to store. When undefined, any existing token at the `storageKey` is removed from storage.
* @param pickleKey Pickle key: used to derive the key used to encrypt token. If `undefined`, the token will be stored
* unencrypted.
* @param hasTokenStorageKey Localstorage key for an item which stores whether we expect to have a token in indexeddb,
* eg "mx_has_access_token".
*/
export async function persistTokenInStorage(
storageKey: string,
initializationVector: string,
tokenName: string,
token: string | undefined,
pickleKey: string | undefined,
hasTokenStorageKey: string,
@@ -130,12 +144,12 @@ export async function persistTokenInStorage(
try {
// try to encrypt the access token using the pickle key
const encrKey = await pickleKeyToAesKey(pickleKey);
encryptedToken = await encryptAES(token, encrKey, initializationVector);
encryptedToken = await encryptAES(token, encrKey, tokenName);
encrKey.fill(0);
} catch (e) {
// This is likely due to the browser not having WebCrypto or somesuch.
// Warn about it, but fall back to storing the unencrypted token.
logger.warn(`Could not encrypt token for ${storageKey}`, e);
logger.warn(`Could not encrypt token for ${tokenName}`, e);
}
}
try {
@@ -167,9 +181,11 @@ export async function persistTokenInStorage(
}
/**
* Wraps persistTokenInStorage with accessToken storage keys
* @param token the token to store, when undefined any existing accessToken is removed from storage
* @param pickleKey optional pickle key used to encrypt token
* Wraps {@link persistTokenInStorage} with accessToken storage keys
*
* @param token - The token to store. When undefined, any existing accessToken is removed from storage.
* @param pickleKey - Pickle key: used to derive the key used to encrypt token. If `undefined`, the token will be stored
* unencrypted.
*/
export async function persistAccessTokenInStorage(
token: string | undefined,
@@ -185,9 +201,11 @@ export async function persistAccessTokenInStorage(
}
/**
* Wraps persistTokenInStorage with refreshToken storage keys
* @param token the token to store, when undefined any existing refreshToken is removed from storage
* @param pickleKey optional pickle key used to encrypt token
* Wraps {@link persistTokenInStorage} with refreshToken storage keys.
*
* @param token - The token to store. When undefined, any existing refreshToken is removed from storage.
* @param pickleKey - Pickle key: used to derive the key used to encrypt token. If `undefined`, the token will be stored
* unencrypted.
*/
export async function persistRefreshTokenInStorage(
token: string | undefined,