@unwanted/matrix-sdk-mini 34.12.0-1

package/lib/secret-storage.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Implementation of server-side secret storage
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#storage
+ */
+import { TypedEventEmitter } from "./models/typed-event-emitter.ts";
+import { ClientEvent, ClientEventHandlerMap } from "./client.ts";
+import { AESEncryptedSecretStoragePayload } from "./@types/AESEncryptedSecretStoragePayload.ts";
+export declare const SECRET_STORAGE_ALGORITHM_V1_AES = "m.secret_storage.v1.aes-hmac-sha2";
+/**
+ * Common base interface for Secret Storage Keys.
+ *
+ * The common properties for all encryption keys used in server-side secret storage.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#key-storage
+ */
+export interface SecretStorageKeyDescriptionCommon {
+    /** A human-readable name for this key. */
+    name: string;
+    /** The encryption algorithm used with this key. */
+    algorithm: string;
+    /** Information for deriving this key from a passphrase. */
+    passphrase: PassphraseInfo;
+}
+/**
+ * Properties for a SSSS key using the `m.secret_storage.v1.aes-hmac-sha2` algorithm.
+ *
+ * Corresponds to `AesHmacSha2KeyDescription` in the specification.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#msecret_storagev1aes-hmac-sha2
+ */
+export interface SecretStorageKeyDescriptionAesV1 extends SecretStorageKeyDescriptionCommon {
+    /** The 16-byte AES initialization vector, encoded as base64. */
+    iv: string;
+    /** The MAC of the result of encrypting 32 bytes of 0, encoded as base64. */
+    mac: string;
+}
+/**
+ * Union type for secret storage keys.
+ *
+ * For now, this is only {@link SecretStorageKeyDescriptionAesV1}, but other interfaces may be added in future.
+ */
+export type SecretStorageKeyDescription = SecretStorageKeyDescriptionAesV1;
+/**
+ * Information on how to generate the key from a passphrase.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#deriving-keys-from-passphrases
+ */
+export interface PassphraseInfo {
+    /** The algorithm to be used to derive the key. */
+    algorithm: "m.pbkdf2";
+    /** The number of PBKDF2 iterations to use. */
+    iterations: number;
+    /** The salt to be used for PBKDF2. */
+    salt: string;
+    /** The number of bits to generate. Defaults to 256. */
+    bits?: number;
+}
+/**
+ * Options for {@link ServerSideSecretStorageImpl#addKey}.
+ */
+export interface AddSecretStorageKeyOpts {
+    /** Information for deriving the key from a passphrase if any. */
+    passphrase?: PassphraseInfo;
+    /** Optional name of the key. */
+    name?: string;
+    /** The private key. Will be used to generate the key check values in the key info; it will not be stored on the server */
+    key: Uint8Array;
+}
+/**
+ * Return type for {@link ServerSideSecretStorageImpl#getKey}.
+ */
+export type SecretStorageKeyTuple = [keyId: string, keyInfo: SecretStorageKeyDescription];
+/**
+ * Return type for {@link ServerSideSecretStorageImpl#addKey}.
+ */
+export type SecretStorageKeyObject = {
+    /** The ID of the key */
+    keyId: string;
+    /**  details about the key */
+    keyInfo: SecretStorageKeyDescription;
+};
+/** Interface for managing account data on the server.
+ *
+ * A subset of {@link MatrixClient}.
+ */
+export interface AccountDataClient extends TypedEventEmitter<ClientEvent.AccountData, ClientEventHandlerMap> {
+    /**
+     * Get account data event of given type for the current user. This variant
+     * gets account data directly from the homeserver if the local store is not
+     * ready, which can be useful very early in startup before the initial sync.
+     *
+     * @param eventType - The type of account data
+     * @returns The contents of the given account data event, or `null` if the event is not found
+     */
+    getAccountDataFromServer: <T extends Record<string, any>>(eventType: string) => Promise<T | null>;
+    /**
+     * Set account data event for the current user, with retries
+     *
+     * @param eventType - The type of account data
+     * @param content - the content object to be set
+     * @returns an empty object
+     */
+    setAccountData: (eventType: string, content: any) => Promise<{}>;
+}
+/**
+ *  Application callbacks for use with {@link SecretStorage.ServerSideSecretStorageImpl}
+ */
+export interface SecretStorageCallbacks {
+    /**
+     * Called to retrieve a secret storage encryption key
+     *
+     * Before a secret can be stored in server-side storage, it must be encrypted with one or more
+     * keys. Similarly, after it has been retrieved from storage, it must be decrypted with one of
+     * the keys it was encrypted with. These encryption keys are known as "secret storage keys".
+     *
+     * Descriptions of the secret storage keys are also stored in server-side storage, per the
+     * [matrix specification](https://spec.matrix.org/v1.6/client-server-api/#key-storage), so
+     * before a key can be used in this way, it must have been stored on the server. This is
+     * done via {@link ServerSideSecretStorage#addKey}.
+     *
+     * Obviously the keys themselves are not stored server-side, so the js-sdk calls this callback
+     * in order to retrieve a secret storage key from the application.
+     *
+     * @param keys - An options object, containing only the property `keys`.
+     *
+     * @param name - the name of the *secret* (NB: not the encryption key) being stored or retrieved.
+     *    This is the "event type" stored in account data.
+     *
+     * @returns a pair [`keyId`, `privateKey`], where `keyId` is one of the keys from the `keys` parameter,
+     *    and `privateKey` is the raw private encryption key, as appropriate for the encryption algorithm.
+     *    (For `m.secret_storage.v1.aes-hmac-sha2`, it is the input to an HKDF as defined in the
+     *    [specification](https://spec.matrix.org/v1.6/client-server-api/#msecret_storagev1aes-hmac-sha2).)
+     *
+     *    Alternatively, if none of the keys are known, may return `null` — in which case the original
+     *    storage/retrieval operation will fail with an exception.
+     */
+    getSecretStorageKey?: (keys: {
+        /**
+         * details of the secret storage keys required: a map from the key ID
+         * (excluding the `m.secret_storage.key.` prefix) to details of the key.
+         *
+         * When storing a secret, `keys` will contain exactly one entry; this method will be called
+         * once for each secret storage key to be used for encryption.
+         *
+         * For secret retrieval, `keys` may contain several entries, and the application can return
+         * any one of the requested keys.
+         */
+        keys: Record<string, SecretStorageKeyDescription>;
+    }, name: string) => Promise<[string, Uint8Array] | null>;
+}
+/**
+ * Interface provided by SecretStorage implementations
+ *
+ * Normally this will just be an {@link ServerSideSecretStorageImpl}, but for backwards
+ * compatibility some methods allow other implementations.
+ */
+export interface ServerSideSecretStorage {
+    /**
+     * Add a key for encrypting secrets.
+     *
+     * @param algorithm - the algorithm used by the key.
+     * @param opts - the options for the algorithm.  The properties used
+     *     depend on the algorithm given.
+     * @param keyId - the ID of the key.  If not given, a random
+     *     ID will be generated.
+     *
+     * @returns details about the key.
+     */
+    addKey(algorithm: string, opts: AddSecretStorageKeyOpts, keyId?: string): Promise<SecretStorageKeyObject>;
+    /**
+     * Get the key information for a given ID.
+     *
+     * @param keyId - The ID of the key to check
+     *     for. Defaults to the default key ID if not provided.
+     * @returns If the key was found, the return value is an array of
+     *     the form [keyId, keyInfo].  Otherwise, null is returned.
+     *     XXX: why is this an array when addKey returns an object?
+     */
+    getKey(keyId?: string | null): Promise<SecretStorageKeyTuple | null>;
+    /**
+     * Check whether we have a key with a given ID.
+     *
+     * @param keyId - The ID of the key to check
+     *     for. Defaults to the default key ID if not provided.
+     * @returns Whether we have the key.
+     */
+    hasKey(keyId?: string): Promise<boolean>;
+    /**
+     * Check whether a key matches what we expect based on the key info
+     *
+     * @param key - the key to check
+     * @param info - the key info
+     *
+     * @returns whether or not the key matches
+     */
+    checkKey(key: Uint8Array, info: SecretStorageKeyDescriptionAesV1): Promise<boolean>;
+    /**
+     * Store an encrypted secret on the server.
+     *
+     * Details of the encryption keys to be used must previously have been stored in account data
+     * (for example, via {@link ServerSideSecretStorage#addKey}.
+     *
+     * @param name - The name of the secret - i.e., the "event type" to be stored in the account data
+     * @param secret - The secret contents.
+     * @param keys - The IDs of the keys to use to encrypt the secret, or null/undefined to use the default key
+     *     (will throw if no default key is set).
+     */
+    store(name: string, secret: string, keys?: string[] | null): Promise<void>;
+    /**
+     * Get a secret from storage, and decrypt it.
+     *
+     * @param name - the name of the secret - i.e., the "event type" stored in the account data
+     *
+     * @returns the decrypted contents of the secret, or "undefined" if `name` is not found in
+     *    the user's account data.
+     */
+    get(name: string): Promise<string | undefined>;
+    /**
+     * Check if a secret is stored on the server.
+     *
+     * @param name - the name of the secret
+     *
+     * @returns map of key name to key info the secret is encrypted
+     *     with, or null if it is not present or not encrypted with a trusted
+     *     key
+     */
+    isStored(name: string): Promise<Record<string, SecretStorageKeyDescriptionAesV1> | null>;
+    /**
+     * Get the current default key ID for encrypting secrets.
+     *
+     * @returns The default key ID or null if no default key ID is set
+     */
+    getDefaultKeyId(): Promise<string | null>;
+    /**
+     * Set the default key ID for encrypting secrets.
+     *
+     * @param keyId - The new default key ID
+     */
+    setDefaultKeyId(keyId: string): Promise<void>;
+}
+/**
+ * Implementation of Server-side secret storage.
+ *
+ * Secret *sharing* is *not* implemented here: this class is strictly about the storage component of
+ * SSSS.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#storage
+ */
+export declare class ServerSideSecretStorageImpl implements ServerSideSecretStorage {
+    private readonly accountDataAdapter;
+    private readonly callbacks;
+    /**
+     * Construct a new `SecretStorage`.
+     *
+     * Normally, it is unnecessary to call this directly, since MatrixClient automatically constructs one.
+     * However, it may be useful to construct a new `SecretStorage`, if custom `callbacks` are required, for example.
+     *
+     * @param accountDataAdapter - interface for fetching and setting account data on the server. Normally an instance
+     *   of {@link MatrixClient}.
+     * @param callbacks - application level callbacks for retrieving secret keys
+     */
+    constructor(accountDataAdapter: AccountDataClient, callbacks: SecretStorageCallbacks);
+    /**
+     * Get the current default key ID for encrypting secrets.
+     *
+     * @returns The default key ID or null if no default key ID is set
+     */
+    getDefaultKeyId(): Promise<string | null>;
+    /**
+     * Set the default key ID for encrypting secrets.
+     *
+     * @param keyId - The new default key ID
+     */
+    setDefaultKeyId(keyId: string): Promise<void>;
+    /**
+     * Add a key for encrypting secrets.
+     *
+     * @param algorithm - the algorithm used by the key.
+     * @param opts - the options for the algorithm.  The properties used
+     *     depend on the algorithm given.
+     * @param keyId - the ID of the key.  If not given, a random
+     *     ID will be generated.
+     *
+     * @returns An object with:
+     *     keyId: the ID of the key
+     *     keyInfo: details about the key (iv, mac, passphrase)
+     */
+    addKey(algorithm: string, opts: AddSecretStorageKeyOpts, keyId?: string): Promise<SecretStorageKeyObject>;
+    /**
+     * Get the key information for a given ID.
+     *
+     * @param keyId - The ID of the key to check
+     *     for. Defaults to the default key ID if not provided.
+     * @returns If the key was found, the return value is an array of
+     *     the form [keyId, keyInfo].  Otherwise, null is returned.
+     *     XXX: why is this an array when addKey returns an object?
+     */
+    getKey(keyId?: string | null): Promise<SecretStorageKeyTuple | null>;
+    /**
+     * Check whether we have a key with a given ID.
+     *
+     * @param keyId - The ID of the key to check
+     *     for. Defaults to the default key ID if not provided.
+     * @returns Whether we have the key.
+     */
+    hasKey(keyId?: string): Promise<boolean>;
+    /**
+     * Check whether a key matches what we expect based on the key info
+     *
+     * @param key - the key to check
+     * @param info - the key info
+     *
+     * @returns whether or not the key matches
+     */
+    checkKey(key: Uint8Array, info: SecretStorageKeyDescriptionAesV1): Promise<boolean>;
+    /**
+     * Store an encrypted secret on the server.
+     *
+     * Details of the encryption keys to be used must previously have been stored in account data
+     * (for example, via {@link ServerSideSecretStorageImpl#addKey}. {@link SecretStorageCallbacks#getSecretStorageKey} will be called to obtain a secret storage
+     * key to decrypt the secret.
+     *
+     * @param name - The name of the secret - i.e., the "event type" to be stored in the account data
+     * @param secret - The secret contents.
+     * @param keys - The IDs of the keys to use to encrypt the secret, or null/undefined to use the default key.
+     */
+    store(name: string, secret: string, keys?: string[] | null): Promise<void>;
+    /**
+     * Get a secret from storage, and decrypt it.
+     *
+     * {@link SecretStorageCallbacks#getSecretStorageKey} will be called to obtain a secret storage
+     * key to decrypt the secret.
+     *
+     * @param name - the name of the secret - i.e., the "event type" stored in the account data
+     *
+     * @returns the decrypted contents of the secret, or "undefined" if `name` is not found in
+     *    the user's account data.
+     */
+    get(name: string): Promise<string | undefined>;
+    /**
+     * Check if a secret is stored on the server.
+     *
+     * @param name - the name of the secret
+     *
+     * @returns map of key name to key info the secret is encrypted
+     *     with, or null if it is not present or not encrypted with a trusted
+     *     key
+     */
+    isStored(name: string): Promise<Record<string, SecretStorageKeyDescriptionAesV1> | null>;
+    private getSecretStorageKey;
+}
+/** trim trailing instances of '=' from a string
+ *
+ * @internal
+ *
+ * @param input - input string
+ */
+export declare function trimTrailingEquals(input: string): string;
+/**
+ * Calculate the MAC for checking the key.
+ * See https://spec.matrix.org/v1.11/client-server-api/#msecret_storagev1aes-hmac-sha2, steps 3 and 4.
+ *
+ * @param key - the key to use
+ * @param iv - The initialization vector as a base64-encoded string.
+ *     If omitted, a random initialization vector will be created.
+ * @returns An object that contains, `mac` and `iv` properties.
+ */
+export declare function calculateKeyCheck(key: Uint8Array, iv?: string): Promise<AESEncryptedSecretStoragePayload>;
+//# sourceMappingURL=secret-storage.d.ts.map

package/lib/secret-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-storage.d.ts","sourceRoot":"","sources":["../src/secret-storage.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAMjE,OAAO,EAAE,gCAAgC,EAAE,MAAM,8CAA8C,CAAC;AAEhG,eAAO,MAAM,+BAA+B,sCAAsC,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,WAAW,iCAAiC;IAC9C,0CAA0C;IAE1C,IAAI,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAE3D,UAAU,EAAE,cAAc,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAiC,SAAQ,iCAAiC;IAOvF,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IAEX,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,gCAAgC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,kDAAkD;IAClD,SAAS,EAAE,UAAU,CAAC;IAEtB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IAEnB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IAEb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,iEAAiE;IACjE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0HAA0H;IAC1H,GAAG,EAAE,UAAU,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,2BAA2B,CAAC,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,OAAO,EAAE,2BAA2B,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB,CAAC,WAAW,CAAC,WAAW,EAAE,qBAAqB,CAAC;IACxG;;;;;;;OAOG;IACH,wBAAwB,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAElG;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,mBAAmB,CAAC,EAAE,CAClB,IAAI,EAAE;QACF;;;;;;;;;WASG;QACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;KACrD,EACD,IAAI,EAAE,MAAM,KACX,OAAO,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;CAC7C;AAaD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACpC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAE1G;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAErE;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,gCAAgC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpF;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/C;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzF;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,qBAAa,2BAA4B,YAAW,uBAAuB;IAYnE,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAZ9B;;;;;;;;;OASG;gBAEkB,kBAAkB,EAAE,iBAAiB,EACrC,SAAS,EAAE,sBAAsB;IAGtD;;;;OAIG;IACU,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQtD;;;;OAIG;IACI,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBpD;;;;;;;;;;;;OAYG;IACU,MAAM,CACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,uBAAuB,EAC7B,KAAK,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC;IAsClC;;;;;;;;OAQG;IACU,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAcjF;;;;;;OAMG;IACU,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrD;;;;;;;OAOG;IACU,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,gCAAgC,GAAG,OAAO,CAAC,OAAO,CAAC;IAchG;;;;;;;;;;OAUG;IACU,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCvF;;;;;;;;;;OAUG;IACU,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAuC3D;;;;;;;;OAQG;IACU,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,GAAG,IAAI,CAAC;YA0BvF,mBAAmB;CAoCpC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcxD;AAKD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAEzG"}