@webex/plugin-encryption 3.8.0

package/src/cypher/index.ts

@@ -0,0 +1,159 @@
+import {WebexPlugin} from '@webex/webex-core';
+
+import {FileDownloadOptions, IEncryption} from './types';
+import {CYPHER} from './constants';
+import {WebexSDK} from '../types';
+
+/**
+ * @description Encryption APIs for KMS
+ * @class
+ */
+class Cypher extends WebexPlugin implements IEncryption {
+  readonly namespace = CYPHER;
+  private readonly $webex: WebexSDK;
+  registered = false;
+
+  /**
+   * Constructs an instance of the class.
+   *
+   * @param {...any[]} args - The arguments to pass to the superclass constructor.
+   *
+   * @remarks
+   * This constructor calls the superclass constructor with the provided arguments.
+   * It also assigns the `webex` property to the `$webex` property, ignoring TypeScript errors.
+   */
+  constructor(...args: any[]) {
+    super(...args);
+    this.$webex = (this as WebexPlugin).webex as WebexSDK;
+  }
+
+  /**
+   * Registers the device to WDM. This is required for metrics and other services.
+   * @returns {Promise<void>}
+   */
+  async register() {
+    if (this.registered) {
+      this.$webex.logger.info('Cypher: webex.internal.device.register already done');
+
+      return Promise.resolve();
+    }
+
+    return this.$webex.internal.device
+      .register()
+      .then(() => {
+        this.$webex.logger.info('Cypher: webex.internal.device.register successful');
+        this.registered = true;
+      })
+      .catch((error) => {
+        this.$webex.logger.error(`Error occurred during device.register() ${error}`);
+
+        throw error;
+      });
+  }
+
+  /**
+   * Deregisters the device.
+   * @returns {Promise<void>}
+   */
+  async deregister() {
+    if (!this.registered) {
+      this.$webex.logger.info('Cypher: webex.internal.device.deregister already done');
+
+      return Promise.resolve();
+    }
+
+    return this.$webex.internal.device
+      .unregister()
+      .then(() => {
+        this.$webex.logger.info('Cypher: webex.internal.device.deregister successful');
+        this.registered = false;
+      })
+      .catch((error) => {
+        this.$webex.logger.error(`Error occurred during device.deregister() ${error}`);
+
+        throw error;
+      });
+  }
+
+  /**
+   * Downloads and decrypts a file from the given URI.
+   *
+   * @param {string} fileUri - The URI of the file to be decrypted.
+   * @param {FileDownloadOptions} options - The options for file download.
+   * @returns {Promise<ArrayBuffer>} A promise that resolves to the decrypted ArrayBuffer.
+   * @throws {Error} If the file download or decryption fails.
+   *
+   * @example
+   * ```typescript
+   * const attachmentURL = 'https:/myfileurl.xyz/zzz/fileid?keyUri=somekeyuri&JWE=somejwe';
+   * const options: FileDownloadOptions = {
+   *   useFileService: false,
+   *   jwe: somejwe, // Provide the JWE here if not already present in the attachmentURL
+   *   keyUri: someKeyUri, // Provide the keyURI here if not already present in the attachmentURL
+   * };
+   * const decryptedBuf = await webex.cypher.downloadAndDecryptFile(attachmentURL, options);
+   * const file = new File([decryptedBuf], "myFileName.jpeg", {type: 'image/jpeg'});
+   * ```
+   */
+  public async downloadAndDecryptFile(
+    fileUri: string,
+    {useFileService = false, ...options}: FileDownloadOptions = {}
+  ): Promise<ArrayBuffer> {
+    // Sample fileUri: https://someserver.com/3cc29537-7f39-4cce-b204-a529960997fcab9375d8-4fd4-4788-bb12-18426674e95b.jpg?keyUri=kms://kms.wbx2.com/keys/79be16-a4dd-4195-93ef-a72604509aca&JWE=eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..EHYI5SmnFisaOJgv.6Ie3Zui7LFtAr4eWMSnxXAzfi8Cgixcy2b9jy9cImDWvBjjvJQfwik7qvZewCaq-u8lhtTbjEzsJLeVtOKhW_9RoZt3U0RQ-cKaSh2RaK3N_mvuH7_BsoXCMf5zxaqP1HD-3jXUtVSnqFYvEGdGRWxTCWK-PK9BoIUjX6v5t22CUNYbBQBuHizLWvrGAM0UkSvFNRX5n07Xd3WVJ7OnIhYi0JvOb50lbZIrBn27AQL-_CIKoOQxQLkW9zmVACsVpHxLZx9wIo9XYsBYADRTZaw_l_uTiosAd2P1QAGHgLr_Q_qf1wGUn3eGhmptpPx-YCSJikvs2DttwWOg_-vg4jI3EiIXlc0gGsDnleeNRguCLtrks0PMz5hOp5_w9Z5EW05Cx2UAztnp1hE9_nCvPP9wTzdHsG3flkK82HMbPpeVStWvWmAlzp24vTw2KzYrCemdS2AkrShWsNt6_G7_G8nB4RhUnZ11MKaduE5jYpCXNcTx84RBYwA.vqYHCx8uIn-IMQAsPvrw
+    // KeyUri: An attachment level unique ID generated by Webex KMS post encryption of an attachment. In order to
+    // decrypt an attachment, KeyUri is a required parameter.
+    // JWE: JWE can be decrypted using KMS key to obtain the SCR key.
+    // Decrypting an attachment requires the SCR key parameter.
+    // We need to download the encrypted file from the given URI and then decrypt it using the SCR key.
+    // The decrypted file is then returned.
+
+    // step 1: parse the fileUri to get the keyUri and JWE
+    // step 2: if keyUri and JWE are not present in the fileUri, use the options
+    // step 3: use the keyUri to decrypt the JWE to get the SCR
+    // step 4: download the file from the fileUri and decrypt it using the SCR
+
+    let keyUri: string | undefined;
+    let JWE: string | undefined;
+    try {
+      const url = new URL(fileUri);
+      keyUri = url.searchParams.get('keyUri') ?? undefined;
+      JWE = url.searchParams.get('JWE') ?? undefined;
+    } catch (error) {
+      this.$webex.logger.error(`Cypher: Invalid fileUri: ${(error as Error).message}`);
+      throw new Error(
+        `Failed to decrypt the JWE: ${(error as Error).message}\nStack: ${(error as Error).stack}`
+      );
+    }
+
+    // Check if the keyUri and JWE are present, else take it from options
+    if (!keyUri || !JWE) {
+      keyUri = options.keyUri;
+      JWE = options.jwe;
+    }
+
+    // Check if the keyUri and JWE are present, else throw an error
+    if (!keyUri || !JWE) {
+      throw new Error(
+        'KeyUri and JWE are required to decrypt the file. Either provide them in the fileUri or in the options.'
+      );
+    }
+
+    try {
+      // Decrypt the JWE to get the SCR
+      const scr = await this.$webex.internal.encryption.decryptScr(keyUri, JWE);
+
+      // Start the download and decryption process, returning a promise
+      return this.$webex.internal.encryption.download(fileUri, scr, {useFileService});
+    } catch (error) {
+      const enhancedError = new Error(
+        `Failed to decrypt or download the file: ${(error as Error).message}\nStack: ${
+          (error as Error).stack
+        }`
+      );
+      enhancedError.cause = error;
+      throw enhancedError;
+    }
+  }
+}
+
+export default Cypher;

package/src/cypher/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Options for downloading a file with encryption.
+ */
+interface FileDownloadOptions {
+  /**
+   * Indicates whether to use the file service for downloading.
+   * If true, the webex files service will be used.
+   * If false or undefined, the file will be downloaded directly from the URL.
+   */
+  useFileService?: boolean;
+
+  /**
+   * The JSON Web Encryption (JWE) string used for decrypting the file.
+   * This is a required parameter if the url does not contain the JWE.
+   */
+  jwe?: string;
+
+  /**
+   * The URI of the key used for decrypting the file.
+   * This is a required parameter if the url does not contain the keyUri.
+   */
+  keyUri?: string;
+}
+interface IEncryption {
+  downloadAndDecryptFile(fileUri: string, options: FileDownloadOptions): Promise<ArrayBuffer>;
+}
+
+export type {IEncryption, FileDownloadOptions};

package/src/index.ts

@@ -0,0 +1,13 @@
+/* eslint-env browser */
+import {registerPlugin} from '@webex/webex-core';
+
+import Cypher from './cypher';
+import config from './config';
+import {FileDownloadOptions, IEncryption} from './cypher/types';
+
+registerPlugin('cypher', Cypher, {
+  config,
+});
+
+export default Cypher;
+export type {FileDownloadOptions, IEncryption};

package/src/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Logging related types
+ */
+export type Logger = {
+  log: (payload: string) => void;
+  error: (payload: string) => void;
+  warn: (payload: string) => void;
+  info: (payload: string) => void;
+  trace: (payload: string) => void;
+  debug: (payload: string) => void;
+};
+
+interface IWebexInternal {
+  mercury: {
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+  };
+  device: {
+    register: () => Promise<void>;
+    unregister: () => Promise<void>;
+  };
+  encryption: {
+    decryptScr: (keyUri: string, jwe: string) => Promise<string>;
+    download: (
+      fileUri: string,
+      scr: string,
+      options: {useFileService: boolean}
+    ) => Promise<ArrayBuffer>;
+  };
+}
+
+export interface WebexSDK {
+  version: string;
+  canAuthorize: boolean;
+  credentials: {
+    getUserToken: () => Promise<string>;
+    getOrgId: () => string;
+  };
+  ready: boolean;
+  once: (event: string, callBack: () => void) => void;
+  // internal plugins
+  internal: IWebexInternal;
+  // public plugins
+  logger: Logger;
+}

package/test/unit/spec/cypher/index.ts

@@ -0,0 +1,146 @@
+import MockWebex from '@webex/test-helper-mock-webex';
+import Cypher from '../../../../src/cypher';
+
+import Encryption from '@webex/internal-plugin-encryption';
+
+describe('Cypher', () => {
+  let cypher: Cypher;
+  let webex: any;
+
+  beforeEach(() => {
+    webex = new MockWebex({
+      children: {
+        cypher: Cypher,
+        encryption: Encryption
+      },
+      logger: {
+        log: jest.fn(),
+        debug: jest.fn(),
+        error: jest.fn(),
+        info: jest.fn(),
+      },
+      credentials: {
+        getOrgId: jest.fn(() => 'mockOrgId'),
+      },
+      once: jest.fn((event, callback) => callback()),
+    });
+
+    cypher = new Cypher({parent: webex});
+    webex.cypher = cypher;
+
+    webex.internal.encryption.decryptScr = jest.fn();
+    webex.internal.encryption.download = jest.fn();
+    webex.internal.device.register = jest.fn(() => Promise.resolve());
+    webex.internal.device.unregister = jest.fn(() => Promise.resolve());
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('downloadAndDecryptFile', () => {
+    const fileUri =
+      'https://example.com/encrypted-file?JWE=eyJhbGci&keyUri=kms://example.com/keys/1234';
+    const options = {useFileService: false};
+
+    it('should throw an error if keyUri and JWE are not present in fileUri or options', async () => {
+      await expect(
+        cypher.downloadAndDecryptFile('https://example.com/encrypted-file', {})
+      ).rejects.toThrow(
+        'KeyUri and JWE are required to decrypt the file. Either provide them in the fileUri or in the options.'
+      );
+    });
+
+    it('should use keyUri and JWE from options if not present in fileUri', async () => {
+      const customOptions = {...options ,keyUri: 'kms://example.com/keys/1234', jwe: 'eyJhbGci'};
+      webex.internal.encryption.decryptScr.mockResolvedValue('scr');
+      webex.internal.encryption.download.mockResolvedValue(new ArrayBuffer(8));
+
+      const result = await cypher.downloadAndDecryptFile('https://example.com/encrypted-file', customOptions);
+
+      expect(webex.internal.encryption.decryptScr).toHaveBeenCalledWith('kms://example.com/keys/1234', 'eyJhbGci');
+      expect(webex.internal.encryption.download).toHaveBeenCalledWith('https://example.com/encrypted-file', 'scr', {useFileService: false});
+      expect(result).toBeInstanceOf(ArrayBuffer);
+    });
+
+    it('should decrypt and download the file successfully', async () => {
+      webex.internal.encryption.decryptScr.mockResolvedValue('scr');
+      webex.internal.encryption.download.mockResolvedValue(new ArrayBuffer(8));
+
+      const result = await cypher.downloadAndDecryptFile(fileUri, options);
+
+      expect(webex.internal.encryption.decryptScr).toHaveBeenCalledWith('kms://example.com/keys/1234', 'eyJhbGci');
+      expect(webex.internal.encryption.download).toHaveBeenCalledWith(fileUri, 'scr', {useFileService: false});
+      expect(result).toBeInstanceOf(ArrayBuffer);
+    });
+
+    it('should throw an error if decryption fails', async () => {
+      webex.internal.encryption.decryptScr.mockRejectedValue(new Error('Decryption failed'));
+
+      await expect(cypher.downloadAndDecryptFile(fileUri, options)).rejects.toThrow('Decryption failed');
+    });
+
+    it('should throw an error if download fails', async () => {
+      webex.internal.encryption.decryptScr.mockResolvedValue('scr');
+      webex.internal.encryption.download.mockRejectedValue(new Error('Download failed'));
+
+      await expect(cypher.downloadAndDecryptFile(fileUri, options)).rejects.toThrow('Download failed');
+    });
+  });
+
+  describe('register', () => {
+    it('should register the device and connect to Mercury', async () => {
+      await cypher.register();
+
+      expect(webex.internal.device.register).toHaveBeenCalled();
+    });
+
+    it('should log already registered message if device is already registered', async () => {
+      cypher.registered = true;
+
+      await cypher.register();
+      expect(webex.logger.info).toHaveBeenCalledWith('Cypher: webex.internal.device.register already done');
+    });
+
+    it('should log an error if device registration fails', async () => {
+      webex.internal.device.register.mockRejectedValue(new Error('Device registration failed'));
+
+      try {
+        await cypher.register();
+      } catch (error) {
+        expect(error).toEqual(new Error('Device registration failed'));
+      }
+
+      expect(webex.logger.error).toHaveBeenCalledWith('Error occurred during device.register() Error: Device registration failed');
+    });
+  });
+
+  describe('deregister', () => {
+    it('should deregister the device from WDM', async () => {
+      cypher.registered = true;
+
+      await cypher.deregister();
+
+      expect(webex.internal.device.unregister).toHaveBeenCalled();
+    });
+
+    it('should log an error if device deregistration fails', async () => {
+      cypher.registered = true;
+      webex.internal.device.unregister.mockRejectedValue(new Error('Device deregistration failed'));
+
+      try {
+        await cypher.deregister();
+      } catch (error) {
+        expect(error).toEqual(new Error('Device deregistration failed'));
+      }
+
+      expect(webex.logger.error).toHaveBeenCalledWith('Error occurred during device.deregister() Error: Device deregistration failed');
+    });
+
+    it('should not deregister if device is not registered', async () => {
+      await cypher.deregister();
+
+      expect(webex.logger.info).toHaveBeenCalledWith('Cypher: webex.internal.device.deregister already done');
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["src"],
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/index.ts"
+    ],
+    "sort": [
+      "source-order"
+    ],
+    "name": "Encryption (@webex/plugin-encryption)",
+    "disableSources": "true",
+    "entryPointStrategy": "expand",
+    "excludeExternals": "true",
+    "excludePrivate": "true",
+    "hideGenerator": "true",
+  },
+}