@webex/plugin-encryption 3.8.0

package/dist/cypher/index.js.map

@@ -0,0 +1 @@
+null

package/dist/cypher/types.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=types.js.map

package/dist/cypher/types.js.map

@@ -0,0 +1 @@
+null

package/dist/encryption/constants.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ENCRYPTION = exports.DECRYPTION_SUCCESS = exports.DECRYPTION_IN_PROGRESS = exports.DECRYPTION_FAILED = exports.DECRYPTION = void 0;
+const ENCRYPTION = exports.ENCRYPTION = 'cypher';
+const DECRYPTION = exports.DECRYPTION = 'decryption';
+const DECRYPTION_FAILED = exports.DECRYPTION_FAILED = 'decryptionFailed';
+const DECRYPTION_IN_PROGRESS = exports.DECRYPTION_IN_PROGRESS = 'decryptionInProgress';
+const DECRYPTION_SUCCESS = exports.DECRYPTION_SUCCESS = 'decryptionSuccess';
+//# sourceMappingURL=constants.js.map

package/dist/encryption/constants.js.map

@@ -0,0 +1 @@
+null

package/dist/encryption/encryption.types.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=encryption.types.js.map

package/dist/encryption/encryption.types.js.map

@@ -0,0 +1 @@
+null

package/dist/encryption/index.js

@@ -0,0 +1,84 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _webexCore = require("@webex/webex-core");
+var _constants = require("./constants");
+/* eslint-disable no-unused-expressions */
+
+/**
+ * @description Encryption APIs for KMS
+ * @class
+ */
+class Cypher extends _webexCore.WebexPlugin {
+  namespace = _constants.ENCRYPTION;
+  constructor(...args) {
+    super(...args);
+    // @ts-ignore
+    this.$webex = this.webex;
+  }
+
+  /**
+   * 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 decryptedBuf = await webex.cypher.downloadAndDecryptFile('https://example.com/encrypted-file?JWE=eyJhbGci&keyUri=kms://example.com/keys/1234', {useFileService: false});
+   * const file = new File([decryptedBuf], "myFileName.jpeg", {type: 'image/jpeg'});
+   * ```
+   */
+  async downloadAndDecryptFile(fileUri, {
+    useFileService = false,
+    ...options
+  } = {}) {
+    // 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
+
+    // Parse the fileUri & JWE to get the keyUri using urlSearchParams
+    const url = new URL(fileUri);
+    let keyUri = url.searchParams.get('keyUri');
+    let JWE = url.searchParams.get('JWE');
+
+    // 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) {
+      throw new Error(`Failed to decrypt the JWE: ${error.message}`);
+    }
+  }
+}
+var _default = exports.default = Cypher;
+//# sourceMappingURL=index.js.map

package/dist/encryption/index.js.map

@@ -0,0 +1 @@
+null

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _webexCore = require("@webex/webex-core");
+var _cypher = _interopRequireDefault(require("./cypher"));
+var _config = _interopRequireDefault(require("./config"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/* eslint-env browser */
+
+(0, _webexCore.registerPlugin)('cypher', _cypher.default, {
+  config: _config.default
+});
+var _default = exports.default = _cypher.default;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+null

package/dist/types/config.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    cypher: {};
+};
+export default _default;

package/dist/types/constants.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cypher/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const CYPHER = "cypher";
+export declare const DECRYPTION = "decryption";
+export declare const DECRYPTION_FAILED = "decryptionFailed";
+export declare const DECRYPTION_IN_PROGRESS = "decryptionInProgress";
+export declare const DECRYPTION_SUCCESS = "decryptionSuccess";

package/dist/types/cypher/cypher.types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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/dist/types/cypher/index.d.ts

@@ -0,0 +1,53 @@
+import { WebexPlugin } from '@webex/webex-core';
+import { FileDownloadOptions, IEncryption } from './types';
+/**
+ * @description Encryption APIs for KMS
+ * @class
+ */
+declare class Cypher extends WebexPlugin implements IEncryption {
+    readonly namespace = "cypher";
+    private readonly $webex;
+    registered: boolean;
+    /**
+     * 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[]);
+    /**
+     * Registers the device to WDM. This is required for metrics and other services.
+     * @returns {Promise<void>}
+     */
+    register(): Promise<void>;
+    /**
+     * Deregisters the device.
+     * @returns {Promise<void>}
+     */
+    deregister(): Promise<void>;
+    /**
+     * 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'});
+     * ```
+     */
+    downloadAndDecryptFile(fileUri: string, { useFileService, ...options }?: FileDownloadOptions): Promise<ArrayBuffer>;
+}
+export default Cypher;

package/dist/types/cypher/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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/dist/types/encryption/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const ENCRYPTION = "cypher";
+export declare const DECRYPTION = "decryption";
+export declare const DECRYPTION_FAILED = "decryptionFailed";
+export declare const DECRYPTION_IN_PROGRESS = "decryptionInProgress";
+export declare const DECRYPTION_SUCCESS = "decryptionSuccess";

package/dist/types/encryption/encryption.types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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/dist/types/encryption/index.d.ts

@@ -0,0 +1,27 @@
+import { WebexPlugin } from '@webex/webex-core';
+import { FileDownloadOptions, IEncryption } from './encryption.types';
+/**
+ * @description Encryption APIs for KMS
+ * @class
+ */
+declare class Cypher extends WebexPlugin implements IEncryption {
+    readonly namespace = "cypher";
+    private readonly $webex;
+    constructor(...args: any[]);
+    /**
+     * 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 decryptedBuf = await webex.cypher.downloadAndDecryptFile('https://example.com/encrypted-file?JWE=eyJhbGci&keyUri=kms://example.com/keys/1234', {useFileService: false});
+     * const file = new File([decryptedBuf], "myFileName.jpeg", {type: 'image/jpeg'});
+     * ```
+     */
+    downloadAndDecryptFile(fileUri: string, { useFileService, ...options }?: FileDownloadOptions): Promise<ArrayBuffer>;
+}
+export default Cypher;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+import Cypher from './cypher';
+import { FileDownloadOptions, IEncryption } from './cypher/types';
+export default Cypher;
+export type { FileDownloadOptions, IEncryption };

package/dist/types/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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: IWebexInternal;
+    logger: Logger;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+null

package/jest.config.js

@@ -0,0 +1,44 @@
+const config = require('@webex/jest-config-legacy');
+
+const jestConfig = {
+  rootDir: './',
+  transformIgnorePatterns: [],
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  testResultsProcessor: 'jest-junit',
+  // Clear mocks in between tests by default
+  clearMocks: true,
+  collectCoverage: true,
+  coverageThreshold: {
+    global: {
+      lines: 85,
+      functions: 85,
+      branches: 85,
+      statements: 85,
+    },
+  },
+  coverageDirectory: 'coverage',
+  coverageReporters: ['clover', 'json', 'lcov'],
+  reporters: [
+    'default',
+    [
+      'jest-junit',
+      {
+        outputDirectory: 'coverage/junit',
+        outputName: 'coverage-junit.xml',
+        classNameTemplate: '{classname}',
+        titleTemplate: '{title}',
+      },
+    ],
+    [
+      'jest-html-reporters',
+      {
+        publicPath: './coverage',
+        filename: 'jest-report.html',
+        openReport: false,
+      },
+    ],
+  ],
+};
+
+module.exports = {...config, ...jestConfig};
+

package/junit.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="jest tests" tests="11" failures="0" errors="0" time="2.132">
+  <testsuite name="Cypher" errors="0" failures="0" skipped="0" timestamp="2025-05-06T09:39:24" time="1.83" tests="11">
+    <testcase classname="Cypher downloadAndDecryptFile should throw an error if keyUri and JWE are not present in fileUri or options" name="Cypher downloadAndDecryptFile should throw an error if keyUri and JWE are not present in fileUri or options" time="0.015">
+    </testcase>
+    <testcase classname="Cypher downloadAndDecryptFile should use keyUri and JWE from options if not present in fileUri" name="Cypher downloadAndDecryptFile should use keyUri and JWE from options if not present in fileUri" time="0.003">
+    </testcase>
+    <testcase classname="Cypher downloadAndDecryptFile should decrypt and download the file successfully" name="Cypher downloadAndDecryptFile should decrypt and download the file successfully" time="0.003">
+    </testcase>
+    <testcase classname="Cypher downloadAndDecryptFile should throw an error if decryption fails" name="Cypher downloadAndDecryptFile should throw an error if decryption fails" time="0.002">
+    </testcase>
+    <testcase classname="Cypher downloadAndDecryptFile should throw an error if download fails" name="Cypher downloadAndDecryptFile should throw an error if download fails" time="0.002">
+    </testcase>
+    <testcase classname="Cypher register should register the device and connect to Mercury" name="Cypher register should register the device and connect to Mercury" time="0.003">
+    </testcase>
+    <testcase classname="Cypher register should log already registered message if device is already registered" name="Cypher register should log already registered message if device is already registered" time="0.002">
+    </testcase>
+    <testcase classname="Cypher register should log an error if device registration fails" name="Cypher register should log an error if device registration fails" time="0.004">
+    </testcase>
+    <testcase classname="Cypher deregister should deregister the device from WDM" name="Cypher deregister should deregister the device from WDM" time="0.002">
+    </testcase>
+    <testcase classname="Cypher deregister should log an error if device deregistration fails" name="Cypher deregister should log an error if device deregistration fails" time="0.002">
+    </testcase>
+    <testcase classname="Cypher deregister should not deregister if device is not registered" name="Cypher deregister should not deregister if device is not registered" time="0.004">
+    </testcase>
+  </testsuite>
+</testsuites>

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@webex/plugin-encryption",
+  "description": "Encryption plugin for the Cisco Webex JS SDK",
+  "version": "3.8.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webex/webex-js-sdk.git",
+    "directory": "packages/@webex/plugin-encryption"
+  },
+  "license": "https://github.com/webex/webex-js-sdk/blob/next/LICENSE.md",
+  "contributors": [
+    "Bharath Balan <bhabalan@cisco.com>"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn run -T tsc --declaration true --declarationDir ./dist/types",
+    "build:docs": "typedoc --out ../../../docs/plugin-encrption",
+    "build:src": "webex-legacy-tools build -dest \"./dist\" -src \"./src\" -js -ts -maps && yarn build",
+    "deploy:npm": "yarn npm publish",
+    "test:browser": "webex-legacy-tools test --integration --runner karma",
+    "test:style": "eslint ./src/**/*.*",
+    "test:unit": "webex-legacy-tools test --unit --runner jest"
+  },
+  "browserify": {
+    "transform": [
+      "babelify",
+      "envify"
+    ]
+  },
+  "dependencies": {
+    "@webex/internal-plugin-encryption": "0.0.0",
+    "@webex/webex-core": "0.0.0"
+  },
+  "devDependencies": {
+    "@babel/preset-typescript": "7.22.11",
+    "@types/jsdom": "^21",
+    "@webex/babel-config-legacy": "0.0.0",
+    "@webex/eslint-config-legacy": "0.0.0",
+    "@webex/jest-config-legacy": "0.0.0",
+    "@webex/legacy-tools": "0.0.0",
+    "@webex/test-helper-mock-webex": "0.0.0",
+    "eslint": "^8.24.0",
+    "jest-html-reporters": "3.0.11",
+    "jest-junit": "13.0.0",
+    "jsdom": "19.0.0",
+    "jsdom-global": "3.0.2",
+    "prettier": "^2.7.1",
+    "typed-emitter": "^2.1.0",
+    "typedoc": "0.23.26",
+    "typescript": "^4.9.5"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devMain": "src/index.js"
+}

package/process

@@ -0,0 +1 @@
+module.exports = {browser: true};

package/src/config.ts

@@ -0,0 +1,3 @@
+export default {
+  cypher: {},
+};

package/src/cypher/constants.ts

@@ -0,0 +1,5 @@
+export const CYPHER = 'cypher';
+export const DECRYPTION = 'decryption';
+export const DECRYPTION_FAILED = 'decryptionFailed';
+export const DECRYPTION_IN_PROGRESS = 'decryptionInProgress';
+export const DECRYPTION_SUCCESS = 'decryptionSuccess';