@sudoplatform/sudo-secure-communications 0.0.1 → 5.0.1

package/types/public/modules/securityModule.d.ts

@@ -0,0 +1,291 @@
+import { VerificationRequest } from 'matrix-js-sdk/lib/crypto-api';
+import { SessionManager } from '../../private/data/session/sessionManager';
+import { HandleId } from '../typings';
+/**
+ * The state of the encrypted server backup of client keys.
+ *
+ * @property noBackup there is no backup currently stored on the server
+ * @property backupOnServer there is a backup stored on the server
+ */
+export declare enum BackupState {
+    noBackup = 0,
+    backupOnServer = 1
+}
+/**
+ * Input for `SecurityModule.isVerified` method.
+ *
+ * @interface IsVerifiedInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface IsVerifiedInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.onSessionVerificationChanged` method.
+ *
+ * @interface OnSessionVerificationChangedInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ * @property {function} handler the handler to call when the session verification status changes
+ */
+export interface OnSessionVerificationChangedInput {
+    handleId: HandleId;
+    handler: (status: boolean) => void;
+}
+/**
+ * Input for `SecurityModule.getBackupState` method.
+ *
+ * @interface GetBackupStateInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface GetBackupStateInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.createBackup` method.
+ *
+ * @interface CreateBackupInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface CreateBackupInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.recover` method.
+ *
+ * @interface RecoverInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ * @property {string} backupKey the backup key to decrypt the server backup
+ */
+export interface RecoverInput {
+    handleId: HandleId;
+    backupKey: string;
+}
+/**
+ * Input for `SecurityModule.rotateBackupKey` method.
+ *
+ * @interface RotateBackupKeyInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface RotateBackupKeyInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.resetBackup` method.
+ *
+ * @interface ResetBackupInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface ResetBackupKeyInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.onVerificationRequestReceived` method.
+ *
+ * @interface OnVerificationRequestReceivedInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ * @property {function} handler the handler to call when a verification request is received
+ */
+export interface OnVerificationRequestReceivedInput {
+    handleId: HandleId;
+    handler: (verificationRequest: VerificationRequest) => void;
+}
+/**
+ * Input for `SecurityModule.requestVerification` method.
+ *
+ * @interface RequestVerificationInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface RequestVerificationInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.acceptVerificationRequest` method.
+ *
+ * @interface AcceptVerificationRequestInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ * @property {HandleId} senderId the handle ID of the sender
+ * @property {string} flowId the flow ID of the verification request
+ */
+export interface AcceptVerificationRequestInput {
+    handleId: HandleId;
+    senderId: HandleId;
+    flowId: string;
+}
+/**
+ * Input for `SecurityModule.startSasVerification` method.
+ *
+ * @interface StartSasVerificationInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface StartVerificationInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.approveVerification` method.
+ *
+ * @interface ApproveVerificationInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface ApproveVerificationInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.declineVerification` method.
+ *
+ * @interface DeclineVerificationInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface DeclineVerificationInput {
+    handleId: HandleId;
+}
+/**
+ * Input for `SecurityModule.cancelVerification` method.
+ *
+ * @interface CancelVerificationInput
+ * @property {HandleId} handleId the handle ID owned by this client
+ */
+export interface CancelVerificationInput {
+    handleId: HandleId;
+}
+/**
+ * Key backup, restore and interactive device verification services.
+ *
+ * In the secure communications offering, each device stores their own keys.
+ * To seamlessly continue conversations across multiple devices,
+ * the keys must be replicated across those devices.
+ * Verified devices automatically remain in sync with each others keys, so it's
+ * important to design apps that encourage users to keep their devices verified.
+ *
+ * Client can verify devices with two mechanisms:
+ *
+ * 1) Key backup and restore. In this method, client keys are encrypted with a
+ *  "backup key" and uploaded to the server. The keys can later be "recovered"
+ *  on other devices using the same backup key. This backup gives the device
+ *  access to other previous session keys.
+ *
+ * 2) Interactive verification. In this method, two devices can verify their keys
+ *  out of band using emoji matching. In the case tha verification is happening between
+ *  the same handle of two different devices, the unverified device becomes verified
+ *  and will then gain access to session keys from their other devices.
+ */
+export interface SecurityModule {
+    /**
+     * Convenience method to check if the current session is verified.
+     *
+     * @param {IsVerifiedInput} input the input for the isVerified method
+     * @return {Promise<boolean>} true if the current session is verified, false otherwise
+     */
+    isVerified(input: IsVerifiedInput): Promise<boolean>;
+    /**
+     * Get notified when the state of the session verification changes.
+     *
+     * @param {OnSessionVerificationChangedInput} input the input for the onSessionVerificationChanged method
+     */
+    onSessionVerificationChanged(input: OnSessionVerificationChangedInput): void;
+    /**
+     * Get the current state of the encrypted server backup.
+     *
+     * @param {GetBackupStateInput} input the input for the get backup state method
+     * @return {Promise<BackupState>} the current backup state
+     */
+    getBackupState(input: GetBackupStateInput): Promise<BackupState>;
+    /**
+     * Create a server-side, encrypted backup of client keys for the user.
+     * After creation, keys are automatically uploaded to the backup so this
+     * only has to be called once.
+     *
+     * @param {CreateBackupInput} input the input for the create backup method
+     * @return {Promise<string>} a backup key, to be used with the [recover] method to recover keys from the server backup.
+     */
+    createBackup(input: CreateBackupInput): Promise<string>;
+    /**
+     * Recover client keys from a server-side backup.
+     *
+     * @param {RecoverInput} input the input for the recover method
+     */
+    recover(input: RecoverInput): Promise<void>;
+    /**
+     * Rotate backup keys. The previous backup key is invalidated and replaced with a new one.
+     * Only verified sessions can execute this command.
+     *
+     * @param {RotateBackupKeyInput} input the input for the rotate backup key method
+     * @return {string} a new backup key, to be used with the [recover] method to recover
+     *  keys from the server backup.
+     */
+    rotateBackupKey(input: RotateBackupKeyInput): Promise<string>;
+    /**
+     * Resets the backup. This replaces the server side backup with current keys known to
+     * this device. This will result in data loss of previous messages encrypted with keys
+     * from the previous backup not known to this device. All other devices associated
+     * with this user will become unverified.
+     *
+     * @param {ResetBackupKeyInput} input the input for the reset backup method
+     * @return {string} a new backup key, to be used with the [recover] method to recover
+     *  keys from the server backup.
+     */
+    resetBackupKey(input: ResetBackupKeyInput): Promise<string>;
+    /**
+     * Register a callback to be notified when a verification request is received.
+     *
+     * @param {OnVerificationRequestReceivedInput} input the input for the on verification request received method
+     */
+    onVerificationRequestReceived(input: OnVerificationRequestReceivedInput): void;
+    /**
+     * Begin an interactive verification flow by requesting verification to
+     * another verified, online device.
+     *
+     * @param {RequestVerificationInput} input the input for the request verification method
+     */
+    requestVerification(input: RequestVerificationInput): Promise<void>;
+    /**
+     * Accept a verification request from another device.
+     *
+     * @param {AcceptVerificationRequestInput} input the input for the accept verification request method
+     */
+    acceptVerificationRequest(input: AcceptVerificationRequestInput): Promise<void>;
+    /**
+     * Start interactive verification. This can only occur after the other device
+     * has accepted the verification request. Either device can start the verification.
+     *
+     * @param {StartVerificationInput} input the input for the start verification method
+     */
+    startVerification(input: StartVerificationInput): Promise<void>;
+    /**
+     * Cancel the current verification at any time.
+     *
+     * @param {CancelVerificationInput} input the input for the cancel verification method
+     */
+    cancelVerification(input: CancelVerificationInput): Promise<void>;
+    /**
+     * Approve a verification request. Users must check the contents of the [InteractiveVerificationState.ReceivedVerificationData]
+     * to ensure the emojis match before approving.
+     *
+     * @param {ApproveVerificationInput} input the input for the approve verification method
+     */
+    approveVerification(input: ApproveVerificationInput): Promise<void>;
+    /**
+     * Decline a verification request.
+     *
+     * @param {DeclineVerificationInput} input the input for the decline verification method
+     */
+    declineVerification(input: DeclineVerificationInput): Promise<void>;
+}
+export declare class DefaultSecurityModule implements SecurityModule {
+    private readonly sessionManager;
+    private readonly log;
+    constructor(sessionManager: SessionManager);
+    isVerified(input: IsVerifiedInput): Promise<boolean>;
+    onSessionVerificationChanged(input: OnSessionVerificationChangedInput): Promise<void>;
+    getBackupState(input: GetBackupStateInput): Promise<BackupState>;
+    createBackup(input: CreateBackupInput): Promise<string>;
+    recover(input: RecoverInput): Promise<void>;
+    rotateBackupKey(input: RotateBackupKeyInput): Promise<string>;
+    resetBackupKey(input: ResetBackupKeyInput): Promise<string>;
+    onVerificationRequestReceived(input: OnVerificationRequestReceivedInput): Promise<void>;
+    requestVerification(input: RequestVerificationInput): Promise<void>;
+    acceptVerificationRequest(input: AcceptVerificationRequestInput): Promise<void>;
+    startVerification(input: StartVerificationInput): Promise<void>;
+    approveVerification(input: ApproveVerificationInput): Promise<void>;
+    declineVerification(input: DeclineVerificationInput): Promise<void>;
+    cancelVerification(input: CancelVerificationInput): Promise<void>;
+}

package/types/public/modules/storageModule.d.ts

@@ -0,0 +1,164 @@
+import { IStore } from 'matrix-js-sdk/lib/store';
+/**
+ * SessionAPIs is a collection of APIs for session storage.
+ *
+ * @interface SessionAPIs - used by secure comms SDK
+ */
+export interface SessionAPIs {
+    getAccessToken(): Promise<string | undefined>;
+    saveAccessToken(accessToken: string): Promise<void>;
+    deleteAccessToken(): Promise<void>;
+}
+/**
+ * A secure comms store is a collection of stores for a handle.
+ *
+ * @interface SecureCommsStore
+ * @property {SessionAPIs} sessionAPIs - used by secure comms SDK
+ */
+export interface SecureCommsStore {
+    /**
+     * Close the storage
+     */
+    closeStorage(): Promise<void>;
+    /**
+     * Destroy the storage and purge data
+     */
+    destroyStorage(): Promise<void>;
+    /**
+     * Session APIs
+     */
+    sessionAPIs: SessionAPIs;
+}
+/**
+ * A handle storage is a collection of stores for a given handle.
+ *
+ * @interface HandleStorage
+ * @property {IStore} matrixStore - used by the matrix client
+ * @property {SecureCommsStore} secureCommsStore - used by secure comms SDK
+ */
+export interface HandleStorage {
+    /**
+     * `matrixStore` should be compatible with `matrix-js-sdk:IStore`
+     *   and should be used as `store` for initializing the matrix client
+     */
+    matrixStore: IStore;
+    /**
+     * `secureCommsStore` can be used for storing other SecureComms SDK data
+     */
+    secureCommsStore: SecureCommsStore;
+}
+export declare class IndexedDBStorageProviderFactory implements StorageProviderFactory {
+    private readonly log;
+    constructor();
+    useStorageProvider(handleId: string, storePassphrase?: string): Promise<StorageProvider>;
+}
+export interface StorageProviderFactory {
+    useStorageProvider(handleId: string, storePassphrase?: string): Promise<StorageProvider>;
+}
+export interface StorageProvider {
+    /**
+     * `matrixStore` should be compatible with `matrix-js-sdk:IStore`
+     *   and should be used as `store` for initializing the matrix client
+     */
+    matrixStore: IStore;
+    /**
+     * Open the database.
+     */
+    openDB(): Promise<void>;
+    /**
+     * Close the database.
+     */
+    closeDB(): Promise<void>;
+    /**
+     * Destroy the database.
+     */
+    destroyDB(): Promise<void>;
+    /**
+     * Create an item in the database.
+     * @param store - The store to create the item in.
+     * @param key - The key of the item to create.
+     * @param value - The value of the item to create.
+     */
+    createItem(store: string, key: string, value: any): Promise<void>;
+    /**
+     * Get an item from the database.
+     *
+     * Should be used when the value is expected to be a single item.
+     * @param store - The store to get the item from.
+     * @param key - The key of the item to get.
+     * @returns The item from the database.
+     */
+    getItem<T>(store: string, key: string): Promise<T | undefined>;
+    /**
+     * Get items from the database.
+     *
+     * Should be used when the value is expected to be an array.
+     * @param store - The store to get the items from.
+     * @param key - The key of the item to get.
+     * @param limit - (optional) Number of items to get.
+     * @param offset - (optional) Start index of the items to get.
+     * @returns The items from the database.
+     */
+    getItems<T>(store: string, key: string, limit?: number, offset?: number): Promise<T[]>;
+    /**
+     * Update an item in the database.
+     * @param store - The store to update the item in.
+     * @param key - The key of the item to update.
+     * @param value - The value of the item to update.
+     */
+    updateItem(store: string, key: string, value: any): Promise<void>;
+    /**
+     * Delete an item from the database.
+     * @param store - The store to delete the item from.
+     * @param key - The key of the item to delete.
+     */
+    deleteItem(store: string, key: string): Promise<void>;
+}
+/**
+ * The `StorageModule` is capable of managing multiple user sessions, ensuring data isolation across different handles (sessions).
+ *
+ * It should be storage-backend-agnostic to allow using the SDK in browser, Node.js or other environments with different storage requirements and capabilities.
+ */
+export interface StorageModule {
+    /**
+     * `useHandleStorage` is responsible for opening (creating new storage or constructing object for existing storage), caching and returning HandleStorage objects for each handleId.
+     *
+     *  Each handle gets their dedicated HandleStorage object, which helps segmenting data from different sessions.
+     * @param {string} handleId - The handleId of the handle to get a storage for.
+     * @param {string} storePassphrase - (optional) The passphrase to use for the storage.
+     * @returns {HandleStorage | undefined} - The HandleStorage object for the handleId. If the storage provider is not available, `undefined` is returned.
+     *
+     * ---
+     *
+     * ***⚠️ WARNING ⚠️***
+     *
+     * If `storePassphrase` is **not** provided when the storage handle is **first created**, the local storage will be **UNENCRYPTED**.
+     *
+     * To enable encryption, `storePassphrase` **must** be passed on the **very first call** to this function — i.e., the first time this handle is initialized on a device.
+     *
+     * ⚠️ Once the storage has been initialized **without encryption**, it **CANNOT** be encrypted later by simply providing `storePassphrase`. Doing so will lead to **storage malfunction**. If this happens, you **must delete** the existing storage and **recreate** it with `storePassphrase` provided from the start.
+     */
+    useHandleStorage(handleId: string, storePassphrase?: string): Promise<HandleStorage | undefined>;
+    /**
+     * `closeHandleStorage` when called, the associated HandleStorage object is removed from the cache, but data is not purged from storage.
+     *
+     * @param {string} handleId - The handleId of the handle to close a storage for.
+     */
+    closeHandleStorage(handleId: string): Promise<void>;
+    /**
+     * `deleteHandleStorage` when called, the associated HandleStorage object is removed from the cache, and any data is purged from storage.
+     *
+     *  Used for clearing data from storage when signing out.
+     * @param {string} handleId - The handleId of the handle to delete a storage for.
+     */
+    deleteHandleStorage(handleId: string): Promise<void>;
+}
+export declare class DefaultStorageModule implements StorageModule {
+    private readonly log;
+    private readonly storageProviderFactory;
+    private handleStorageCache;
+    constructor(storageProviderFactory: StorageProviderFactory | undefined);
+    useHandleStorage(handleId: string, storePassphrase?: string): Promise<HandleStorage | undefined>;
+    closeHandleStorage(handleId: string): Promise<void>;
+    deleteHandleStorage(handleId: string): Promise<void>;
+}

package/types/public/secureCommsClient.d.ts

@@ -0,0 +1,142 @@
+import { SudoCryptoProvider, SudoKeyManager } from '@sudoplatform/sudo-common';
+import { SudoUserClient } from '@sudoplatform/sudo-user';
+import { GroupsModule, MessagingModule, NotificationsModule, SecurityModule, StorageModule, StorageProviderFactory } from './modules';
+import { ChannelsModule } from './modules/channelsModule';
+import { DirectChatsModule } from './modules/directChatsModule';
+import { HandlesModule } from './modules/handlesModule';
+import { MediaModule } from './modules/mediaModule';
+import { HandleId } from './typings';
+/**
+ * Pagination interface designed to be extended for list interfaces.
+ *
+ * @interface Pagination
+ * @property {number} limit Number of items to return. Will be defaulted if omitted.
+ * @property {string} nextToken A token generated by a previous call.
+ */
+export interface Pagination {
+    limit?: number;
+    nextToken?: string;
+}
+/**
+ * Wrapper for input fields to indicate that they are being modified (as opposed to not modified).
+ *
+ * @interface Input
+ * @property {T} value
+ */
+export interface Input<T> {
+    value: T;
+}
+/**
+ * Properties required to upload an avatar.
+ *
+ * @interface AvatarInput
+ * @property {ArrayBuffer} file The media file to upload as an avatar.
+ * @property {string} fileName The name of the media file.
+ * @property {string} fileType The MIME type of the media file.
+ */
+export interface AvatarInput {
+    file: ArrayBuffer;
+    fileName: string;
+    fileType: string;
+}
+export interface SecureCommsClient {
+    /**
+     * Accessor for the Handles sub-module.
+     */
+    handles: HandlesModule;
+    /**
+     * Accessor for the Direct Chats sub-module.
+     */
+    directChats: DirectChatsModule;
+    /**
+     * Accessor for the Groups sub-module.
+     */
+    groups: GroupsModule;
+    /**
+     * Accessor for the Channels sub-module.
+     */
+    channels: ChannelsModule;
+    /**
+     * Accessor for the Messaging sub-module.
+     */
+    messaging: MessagingModule;
+    /**
+     * Accessor for the Media sub-module.
+     */
+    media: MediaModule;
+    /**
+     * Accessor for the Security sub-module.
+     */
+    security: SecurityModule;
+    /**
+     * Accessor for the Notifications sub-module.
+     */
+    notifications: NotificationsModule;
+    /**
+     * Accessor for the Storage sub-module.
+     */
+    storage: StorageModule;
+    /**
+     * Start syncing in the background for data updates.
+     *
+     * Can only be called after sign-in creation of a handle.
+     *
+     * @param {HandleId} handleId Identifier of the handle owned by this client.
+     */
+    startSyncing(handleId: HandleId): Promise<void>;
+    /**
+     * Check if the client has finished the initial sync and is ready for use.
+     *
+     * @param {HandleId} handleId Identifier of the handle owned by this client.
+     * @returns {boolean} True if the client is ready for use, false if not.
+     */
+    isReady(handleId: HandleId): Promise<boolean>;
+    /**
+     * Stop syncing.
+     *
+     * @param {HandleId} handleId Identifier of the handle owned by this client.
+     */
+    stopSyncing(handleId: HandleId): Promise<void>;
+    /**
+     * Removes any cached data maintained by this client.
+     */
+    reset(): Promise<void>;
+}
+export type SecureCommsClientOptions = {
+    /** Sudo User client to use. No default */
+    sudoUserClient: SudoUserClient;
+    /** SudoCryptoProvider to use. Default is to create a WebSudoCryptoProvider */
+    sudoCryptoProvider?: SudoCryptoProvider;
+    /** SudoKeyManager to use. Default is to create a DefaultSudoKeyManager */
+    sudoKeyManager?: SudoKeyManager;
+    /** StorageProviderFactory to use. Default is undefined, which will make the client use in-memory storage. */
+    storageProviderFactory?: StorageProviderFactory;
+};
+export declare class DefaultSecureCommsClient implements SecureCommsClient {
+    handles: HandlesModule;
+    directChats: DirectChatsModule;
+    groups: GroupsModule;
+    channels: ChannelsModule;
+    messaging: MessagingModule;
+    media: MediaModule;
+    security: SecurityModule;
+    notifications: NotificationsModule;
+    storage: StorageModule;
+    private readonly apiClient;
+    private readonly userClient;
+    private readonly sessionService;
+    private readonly sessionManager;
+    private readonly mediaCredentialService;
+    private readonly mediaCredentialManager;
+    private readonly sudoCryptoProvider;
+    private readonly keyManager;
+    private readonly storageProviderFactory;
+    private readonly identityServiceConfig;
+    private readonly secureCommsServiceConfig;
+    private readonly log;
+    constructor(opts: SecureCommsClientOptions);
+    startSyncing(id: HandleId): Promise<void>;
+    isReady(id: HandleId): Promise<boolean>;
+    stopSyncing(id: HandleId): Promise<void>;
+    reset(): Promise<void>;
+}