matrix-react-sdk/lib/src/utils/tokens/tokens.d.ts

SDK for matrix.org using React

import { AESEncryptedSecretStoragePayload } from "matrix-js-sdk/src/types";
/**
 * Utility functions related to the storage and retrieval of access tokens
 */
export declare const ACCESS_TOKEN_STORAGE_KEY = "mx_access_token";
export declare const REFRESH_TOKEN_STORAGE_KEY = "mx_refresh_token";
export declare const ACCESS_TOKEN_IV = "access_token";
export declare const REFRESH_TOKEN_IV = "refresh_token";
export declare const HAS_ACCESS_TOKEN_STORAGE_KEY = "mx_has_access_token";
export declare const HAS_REFRESH_TOKEN_STORAGE_KEY = "mx_has_refresh_token";
/**
 * 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, 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.
 */
export declare function tryDecryptToken(pickleKey: string | undefined, token: AESEncryptedSecretStoragePayload | string, tokenName: string): Promise<string>;
/**
 * Persist a token in storage
 *
 * 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 declare function persistTokenInStorage(storageKey: string, tokenName: string, token: string | undefined, pickleKey: string | undefined, hasTokenStorageKey: string): Promise<void>;
/**
 * 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 declare function persistAccessTokenInStorage(token: string | undefined, pickleKey: string | undefined): Promise<void>;
/**
 * 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 declare function persistRefreshTokenInStorage(token: string | undefined, pickleKey: string | undefined): Promise<void>;