@opengovsg/formsg-sdk 0.16.1 → 7.1.2

package/README.md

@@ -1,14 +1,13 @@
 _Please note that this is an SDK for webhooks integration, and_ **_not_** _the FormSG system._
 
-[![Coverage Status](https://coveralls.io/repos/github/opengovsg/formsg-javascript-sdk/badge.svg?branch=master)](https://coveralls.io/github/opengovsg/formsg-javascript-sdk?branch=master)
-
-# FormSG Javascript SDK
+# FormSG JavaScript SDK
 
 This SDK provides convenient utilities for verifying FormSG webhooks and decrypting submissions in JavaScript and Node.js.
 
-Not using Javascript? Check out our sister SDKs:
+This package used to live at [`opengovsg/formsg-javascript-sdk`](https://github.com/opengovsg/formsg-javascript-sdk) and is now developed in the main FormSG monorepo under [`packages/sdk`](./). It is still published to npm as [`@opengovsg/formsg-sdk`](https://www.npmjs.com/package/@opengovsg/formsg-sdk); starting with this migration the major version is bumped to `v7` to track the FormSG monorepo.
+
+Not using JavaScript? Check out our sister SDKs:
 - [formsg-python-sdk](https://github.com/opengovsg/formsg-python-sdk)
-- [formsg-ruby-sdk](https://github.com/opengovsg/formsg-ruby-sdk)
 
 ## Installation
 
@@ -114,7 +113,7 @@ the shape
 
 <pre>
 {
-  responses: <a href="./src/types.ts#L30">FormField</a>[]
+  responses: <a href="./src/types.ts">FormField</a>[]
   verified?: <a href="https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkt">Record&lt;string, any&gt;</a>
 }
 </pre>
@@ -128,7 +127,7 @@ The `decryptParams.encryptedContent` field decrypts into an array of `FormField`
 Furthermore, if `decryptParams.verifiedContent` exists, the function will
 decrypt and open the signed decrypted content with the package's own
 `signingPublicKey` in
-[`signing-keys.ts`](https://github.com/opengovsg/formsg-javascript-sdk/tree/master/src/resource/signing-keys.ts).
+[`signing-keys.ts`](./src/resource/signing-keys.ts).
 The resulting decrypted verifiedContent will be assigned to the `verified` key
 of the returned object.
 
@@ -137,7 +136,7 @@ of the returned object.
 
 Note that due to end-to-end encryption, FormSG servers are unable to verify the data format.
 
-However, the `decrypt` function exposed by this library [validates](https://github.com/opengovsg/formsg-javascript-sdk/blob/master/src/util/validate.ts) the decrypted content and will **return `null` if the
+However, the `decrypt` function exposed by this library [validates](./src/util/validate.ts) the decrypted content and will **return `null` if the
 decrypted content does not contain all of the fields displayed in the schema below.**
 
 | Key         | Type     | Description                                                                                              |
@@ -152,7 +151,7 @@ decrypted content does not contain all of the fields displayed in the schema bel
 > Additional internal fields may be included in webhooks from time to time, which will then be published as part of our official schema once it is stable for public consumption. If you are applying your own validation, you should account for this e.g. by not rejecting the webhook if there are additional fields included.
 
 The full schema can be viewed in
-[`validate.ts`](https://github.com/opengovsg/formsg-javascript-sdk/tree/master/src/util/validate.ts).
+[`validate.ts`](./src/util/validate.ts).
 
 If the decrypted content is the correct shape, then:
 

package/cjs-entry.cjs

@@ -0,0 +1,5 @@
+// CJS backward-compatibility shim.
+// TypeScript compiles `export default function` to `exports.default = fn`,
+// but CJS consumers expect `require('@opengovsg/formsg-sdk')` to return
+// the function directly (matching the old v0.15.0 behavior).
+module.exports = require('./dist/cjs/index.js').default

package/dist/{crypto-base.js → cjs/crypto-base.js}

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
@@ -79,14 +79,12 @@ var CryptoBase = /** @class */ (function () {
          * @param encrypted.nonce The nonce as a base-64 string
          * @param encrypted.blob The encrypted file as a Blob object
          */
-        this.decryptFile = function (secretKey, _a) {
-            var filePublicKey = _a.submissionPublicKey, nonce = _a.nonce, encryptedBinary = _a.binary;
-            return __awaiter(_this, void 0, void 0, function () {
-                return __generator(this, function (_b) {
-                    return [2 /*return*/, tweetnacl_1.default.box.open(encryptedBinary, (0, tweetnacl_util_1.decodeBase64)(nonce), (0, tweetnacl_util_1.decodeBase64)(filePublicKey), (0, tweetnacl_util_1.decodeBase64)(secretKey))];
-                });
+        this.decryptFile = function (secretKey_1, _a) { return __awaiter(_this, [secretKey_1, _a], void 0, function (secretKey, _b) {
+            var filePublicKey = _b.submissionPublicKey, nonce = _b.nonce, encryptedBinary = _b.binary;
+            return __generator(this, function (_c) {
+                return [2 /*return*/, tweetnacl_1.default.box.open(encryptedBinary, (0, tweetnacl_util_1.decodeBase64)(nonce), (0, tweetnacl_util_1.decodeBase64)(filePublicKey), (0, tweetnacl_util_1.decodeBase64)(secretKey))];
             });
-        };
+        }); };
     }
     return CryptoBase;
 }());

package/dist/{crypto.js → cjs/crypto.js}

@@ -24,8 +24,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/{index.d.ts → cjs/index.d.ts}

@@ -1,3 +1,4 @@
+export type { DecryptedContent, DecryptedContentV3, DecryptParams, DecryptParamsV3, EncryptedAttachmentContent, EncryptedAttachmentRecords, EncryptedContent, EncryptedContentV3, EncryptedFileContent, FieldType, FormField, FormFieldsV3, Keypair, PackageMode, VerificationOptions, } from './types';
 import Crypto from './crypto';
 import CryptoV3 from './crypto-v3';
 import { PackageInitParams } from './types';
@@ -11,10 +12,9 @@ import Webhooks from './webhooks';
  * @param {string?} [config.webhookSecretKey] Optional. base64 secret key for signing webhooks. If provided, enables generating signature and headers to authenticate webhook data.
  * @param {VerificationOptions?} [config.verificationOptions] Optional. If provided, enables the usage of the verification module.
  */
-declare const _default: (config?: PackageInitParams) => {
+export default function (config?: PackageInitParams): {
     webhooks: Webhooks;
     crypto: Crypto;
     cryptoV3: CryptoV3;
     verification: Verification;
 };
-export = _default;

package/dist/{index.js → cjs/index.js}

@@ -2,12 +2,22 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
 var publicKey_1 = require("./util/publicKey");
 var crypto_1 = __importDefault(require("./crypto"));
 var crypto_v3_1 = __importDefault(require("./crypto-v3"));
 var verification_1 = __importDefault(require("./verification"));
 var webhooks_1 = __importDefault(require("./webhooks"));
-module.exports = function (config) {
+/**
+ * Entrypoint into the FormSG SDK
+ *
+ * @param {PackageInitParams} config Package initialization config parameters
+ * @param {string?} [config.mode] Optional. Initializes public key used for verifying and decrypting in this package. If `config.signingPublicKey` is given, this param will be ignored.
+ * @param {string?} [config.webhookSecretKey] Optional. base64 secret key for signing webhooks. If provided, enables generating signature and headers to authenticate webhook data.
+ * @param {VerificationOptions?} [config.verificationOptions] Optional. If provided, enables the usage of the verification module.
+ */
+function default_1(config) {
     if (config === void 0) { config = {}; }
     var webhookSecretKey = config.webhookSecretKey, mode = config.mode, verificationOptions = config.verificationOptions;
     /**
@@ -32,4 +42,4 @@ module.exports = function (config) {
             transactionExpiry: verificationOptions === null || verificationOptions === void 0 ? void 0 : verificationOptions.transactionExpiry,
         }),
     };
-};
+}

package/dist/{util → cjs/util}/publicKey.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVerificationPublicKey = exports.getSigningPublicKey = void 0;
+exports.getSigningPublicKey = getSigningPublicKey;
+exports.getVerificationPublicKey = getVerificationPublicKey;
 var signing_keys_1 = require("../resource/signing-keys");
 var verification_keys_1 = require("../resource/verification-keys");
 var stage_1 = __importDefault(require("./stage"));
@@ -24,7 +25,6 @@ function getSigningPublicKey(mode) {
             return signing_keys_1.SIGNING_KEYS.production.publicKey;
     }
 }
-exports.getSigningPublicKey = getSigningPublicKey;
 /**
  * Retrieves the appropriate verification public key.
  * Defaults to production.
@@ -42,4 +42,3 @@ function getVerificationPublicKey(mode) {
             return verification_keys_1.VERIFICATION_KEYS.production.publicKey;
     }
 }
-exports.getVerificationPublicKey = getVerificationPublicKey;

package/dist/{util → cjs/util}/signature.js

@@ -15,15 +15,26 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verify = exports.sign = void 0;
+exports.sign = sign;
+exports.verify = verify;
 var tweetnacl = __importStar(require("tweetnacl"));
 var tweetnacl_util_1 = require("tweetnacl-util");
 /**
@@ -35,7 +46,6 @@ var tweetnacl_util_1 = require("tweetnacl-util");
 function sign(basestring, secretKey) {
     return (0, tweetnacl_util_1.encodeBase64)(tweetnacl.sign.detached((0, tweetnacl_util_1.decodeUTF8)(basestring), (0, tweetnacl_util_1.decodeBase64)(secretKey)));
 }
-exports.sign = sign;
 /**
  * Verifies a signature against a message and public key
  * @param message The message to verify
@@ -46,4 +56,3 @@ exports.sign = sign;
 function verify(message, signature, publicKey) {
     return tweetnacl.sign.detached.verify((0, tweetnacl_util_1.decodeUTF8)(message), (0, tweetnacl_util_1.decodeBase64)(signature), (0, tweetnacl_util_1.decodeBase64)(publicKey));
 }
-exports.verify = verify;

package/dist/{util → cjs/util}/validate.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.determineIsFormFieldsV3 = exports.determineIsFormFields = void 0;
+exports.determineIsFormFields = determineIsFormFields;
+exports.determineIsFormFieldsV3 = determineIsFormFieldsV3;
 function determineIsFormFields(tbd) {
     if (!Array.isArray(tbd)) {
         return false;
@@ -21,7 +22,6 @@ function determineIsFormFields(tbd) {
     });
     return filter.length === tbd.length;
 }
-exports.determineIsFormFields = determineIsFormFields;
 // TODO(MRF): This is currently very rudimentary, we should look at making this more specific where required.
 function determineIsFormFieldsV3(tbd) {
     for (var _i = 0, _a = Object.keys(tbd); _i < _a.length; _i++) {
@@ -33,4 +33,3 @@ function determineIsFormFieldsV3(tbd) {
     }
     return true;
 }
-exports.determineIsFormFieldsV3 = determineIsFormFieldsV3;

package/dist/{util → cjs/util}/webhooks.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasEpochExpired = exports.isSignatureHeaderValid = void 0;
 var url = __importStar(require("url"));

package/dist/{webhooks.js → cjs/webhooks.js}

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 var url = __importStar(require("url"));
 var parser_1 = require("./util/parser");

package/dist/esm/crypto-base.d.ts

@@ -0,0 +1,25 @@
+import { EncryptedFileContent } from './types';
+export default class CryptoBase {
+    /**
+     * Generates a new keypair for encryption.
+     * @returns The generated keypair.
+     */
+    generate: () => import("./types").Keypair;
+    /**
+     * Encrypt given binary file with a unique keypair for each submission.
+     * @param binary The file to encrypt, should be a blob that is converted to Uint8Array binary
+     * @param publicKey The base-64 encoded public key
+     * @returns Promise holding the encrypted file
+     * @throws error if any of the encrypt methods fail
+     */
+    encryptFile: (binary: Uint8Array, publicKey: string) => Promise<EncryptedFileContent>;
+    /**
+     * Decrypt the given encrypted file content.
+     * @param secretKey Secret key as a base-64 string
+     * @param encrypted Object returned from encryptFile function
+     * @param encrypted.submissionPublicKey The file's public key as a base-64 string
+     * @param encrypted.nonce The nonce as a base-64 string
+     * @param encrypted.blob The encrypted file as a Blob object
+     */
+    decryptFile: (secretKey: string, { submissionPublicKey: filePublicKey, nonce, binary: encryptedBinary, }: EncryptedFileContent) => Promise<Uint8Array | null>;
+}

package/dist/esm/crypto-base.js

@@ -0,0 +1,86 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import nacl from 'tweetnacl';
+import { decodeBase64, encodeBase64 } from 'tweetnacl-util';
+import { generateKeypair } from './util/crypto';
+var CryptoBase = /** @class */ (function () {
+    function CryptoBase() {
+        var _this = this;
+        /**
+         * Generates a new keypair for encryption.
+         * @returns The generated keypair.
+         */
+        this.generate = generateKeypair;
+        /**
+         * Encrypt given binary file with a unique keypair for each submission.
+         * @param binary The file to encrypt, should be a blob that is converted to Uint8Array binary
+         * @param publicKey The base-64 encoded public key
+         * @returns Promise holding the encrypted file
+         * @throws error if any of the encrypt methods fail
+         */
+        this.encryptFile = function (binary, publicKey) { return __awaiter(_this, void 0, void 0, function () {
+            var fileKeypair, nonce;
+            return __generator(this, function (_a) {
+                fileKeypair = this.generate();
+                nonce = nacl.randomBytes(24);
+                return [2 /*return*/, {
+                        //! NOTE: submissionPublicKey here is a misnomer as a new keypair is generated per file.
+                        // The naming is only retained for backward-compatibility purposes.
+                        submissionPublicKey: fileKeypair.publicKey,
+                        nonce: encodeBase64(nonce),
+                        binary: nacl.box(binary, nonce, decodeBase64(publicKey), decodeBase64(fileKeypair.secretKey)),
+                    }];
+            });
+        }); };
+        /**
+         * Decrypt the given encrypted file content.
+         * @param secretKey Secret key as a base-64 string
+         * @param encrypted Object returned from encryptFile function
+         * @param encrypted.submissionPublicKey The file's public key as a base-64 string
+         * @param encrypted.nonce The nonce as a base-64 string
+         * @param encrypted.blob The encrypted file as a Blob object
+         */
+        this.decryptFile = function (secretKey_1, _a) { return __awaiter(_this, [secretKey_1, _a], void 0, function (secretKey, _b) {
+            var filePublicKey = _b.submissionPublicKey, nonce = _b.nonce, encryptedBinary = _b.binary;
+            return __generator(this, function (_c) {
+                return [2 /*return*/, nacl.box.open(encryptedBinary, decodeBase64(nonce), decodeBase64(filePublicKey), decodeBase64(secretKey))];
+            });
+        }); };
+    }
+    return CryptoBase;
+}());
+export default CryptoBase;

package/dist/esm/crypto-v3.d.ts

@@ -0,0 +1,41 @@
+import CryptoBase from './crypto-base';
+import { DecryptedContentV3, DecryptParams, DecryptParamsV3, EncryptedContentV3 } from './types';
+export default class CryptoV3 extends CryptoBase {
+    signingPublicKey?: string;
+    constructor({ signingPublicKey }?: {
+        signingPublicKey?: string;
+    });
+    /**
+     * Encrypt input with a unique keypair for each submission.
+     * @param msg The message to encrypt, will be stringified.
+     * @param form The base-64 encoded form public key for encrypting.
+     * @returns The encrypted basestring.
+     */
+    encrypt: (msg: any, formPublicKey: string) => EncryptedContentV3;
+    /**
+     * Decrypts an encrypted submission and returns it.
+     * @param submissionSecretKey The base-64 encoded secret key for decrypting.
+     * @param decryptParams The params containing encrypted content and information.
+     * @param decryptParams.encryptedContent The encrypted content encoded with base-64.
+     * @param decryptParams.version The version of the payload.
+     * @returns The decrypted content if successful. Else, null will be returned.
+     */
+    decryptFromSubmissionKey: (submissionSecretKey: string, decryptParams: DecryptParams) => DecryptedContentV3 | null;
+    /**
+     * Decrypts an encrypted submission and returns it.
+     * @param formSecretKey The base-64 encoded form secret key for decrypting the submission.
+     * @param decryptParams The params containing encrypted content, encrypted submission key and information.
+     * @param decryptParams.encryptedContent The encrypted content encoded with base-64.
+     * @param decryptParams.encryptedSubmissionSecretKey The encrypted submission secret key encoded with base-64.
+     * @param decryptParams.version The version of the payload. Used to determine the decryption process to decrypt the content with.
+     * @returns The decrypted content if successful. Else, null will be returned.
+     * @throws {MissingPublicKeyError} if a public key is not provided when instantiating this class and is needed for verifying signed content.
+     */
+    decrypt: (formSecretKey: string, decryptParams: DecryptParamsV3) => DecryptedContentV3 | null;
+    /**
+     * Returns true if a pair of public & secret keys are associated with each other
+     * @param publicKey The public key to verify against.
+     * @param secretKey The private key to verify against.
+     */
+    valid: (publicKey: string, secretKey: string) => boolean;
+}

package/dist/esm/crypto-v3.js

@@ -0,0 +1,168 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { decodeBase64, decodeUTF8, encodeBase64, encodeUTF8, } from 'tweetnacl-util';
+import { decryptContent, encryptMessage, generateKeypair, verifySignedMessage, } from './util/crypto';
+import { determineIsFormFieldsV3 } from './util/validate';
+import CryptoBase from './crypto-base';
+import { MissingPublicKeyError } from './errors';
+var CryptoV3 = /** @class */ (function (_super) {
+    __extends(CryptoV3, _super);
+    function CryptoV3(_a) {
+        var _b = _a === void 0 ? {} : _a, signingPublicKey = _b.signingPublicKey;
+        var _this = _super.call(this) || this;
+        /**
+         * Encrypt input with a unique keypair for each submission.
+         * @param msg The message to encrypt, will be stringified.
+         * @param form The base-64 encoded form public key for encrypting.
+         * @returns The encrypted basestring.
+         */
+        _this.encrypt = function (msg, formPublicKey) {
+            var submissionKeypair = generateKeypair();
+            var encryptedSubmissionSecretKey = encryptMessage(decodeBase64(submissionKeypair.secretKey), formPublicKey);
+            var processedMsg = decodeUTF8(JSON.stringify(msg));
+            var encryptedContent = encryptMessage(processedMsg, submissionKeypair.publicKey);
+            return {
+                submissionPublicKey: submissionKeypair.publicKey,
+                submissionSecretKey: submissionKeypair.secretKey,
+                encryptedContent: encryptedContent,
+                encryptedSubmissionSecretKey: encryptedSubmissionSecretKey,
+            };
+        };
+        /**
+         * Decrypts an encrypted submission and returns it.
+         * @param submissionSecretKey The base-64 encoded secret key for decrypting.
+         * @param decryptParams The params containing encrypted content and information.
+         * @param decryptParams.encryptedContent The encrypted content encoded with base-64.
+         * @param decryptParams.version The version of the payload.
+         * @returns The decrypted content if successful. Else, null will be returned.
+         */
+        _this.decryptFromSubmissionKey = function (submissionSecretKey, decryptParams) {
+            try {
+                var encryptedContent = decryptParams.encryptedContent, verifiedContent = decryptParams.verifiedContent;
+                // Do not return the transformed object in `_decrypt` function as a signed
+                // object is not encoded in UTF8 and is encoded in Base-64 instead.
+                var decryptedContent = decryptContent(submissionSecretKey, encryptedContent);
+                if (!decryptedContent) {
+                    throw new Error('Failed to decrypt content');
+                }
+                var decryptedObject = JSON.parse(encodeUTF8(decryptedContent));
+                if (!determineIsFormFieldsV3(decryptedObject)) {
+                    throw new Error('Decrypted object does not fit expected shape');
+                }
+                var returnedObject = {
+                    submissionSecretKey: submissionSecretKey,
+                    responses: decryptedObject,
+                };
+                /**
+                 * Note on verifiedContent decryption for cryptoV3:
+                 * Although decryption is supported, verifiedContent encryption is not supported
+                 * in cryptoV3 encrypt.
+                 * This is to keep the encryption of verifiedContent and encryptedContent similar to storage mode - where
+                 * verifiedContent and encryptedContent are defined and encrypted separately.
+                 */
+                // decrypt verifiedContent if it exists
+                if (verifiedContent) {
+                    if (!_this.signingPublicKey) {
+                        throw new MissingPublicKeyError('Public signing key must be provided when instantiating the Crypto class in order to verify verified content');
+                    }
+                    var decryptedVerifiedContent = decryptContent(submissionSecretKey, verifiedContent);
+                    if (!decryptedVerifiedContent) {
+                        // Returns null if decrypting verified content failed.
+                        throw new Error('Failed to decrypt verified content');
+                    }
+                    var decryptedVerifiedObject = verifySignedMessage(decryptedVerifiedContent, _this.signingPublicKey);
+                    returnedObject.verified = decryptedVerifiedObject;
+                }
+                return returnedObject;
+            }
+            catch (err) {
+                // Should only throw if MissingPublicKeyError.
+                // This library should be able to be used to encrypt and decrypt content
+                // if the content does not contain verified fields.
+                if (err instanceof MissingPublicKeyError) {
+                    throw err;
+                }
+                return null;
+            }
+        };
+        /**
+         * Decrypts an encrypted submission and returns it.
+         * @param formSecretKey The base-64 encoded form secret key for decrypting the submission.
+         * @param decryptParams The params containing encrypted content, encrypted submission key and information.
+         * @param decryptParams.encryptedContent The encrypted content encoded with base-64.
+         * @param decryptParams.encryptedSubmissionSecretKey The encrypted submission secret key encoded with base-64.
+         * @param decryptParams.version The version of the payload. Used to determine the decryption process to decrypt the content with.
+         * @returns The decrypted content if successful. Else, null will be returned.
+         * @throws {MissingPublicKeyError} if a public key is not provided when instantiating this class and is needed for verifying signed content.
+         */
+        _this.decrypt = function (formSecretKey, decryptParams) {
+            try {
+                var encryptedSubmissionSecretKey = decryptParams.encryptedSubmissionSecretKey, rest = __rest(decryptParams, ["encryptedSubmissionSecretKey"]);
+                var submissionSecretKey = decryptContent(formSecretKey, encryptedSubmissionSecretKey);
+                if (submissionSecretKey === null)
+                    return null;
+                return _this.decryptFromSubmissionKey(encodeBase64(submissionSecretKey), rest);
+            }
+            catch (err) {
+                if (err instanceof MissingPublicKeyError) {
+                    // rethrow to let the caller decide how to handle missing signing key
+                    throw err;
+                }
+                return null;
+            }
+        };
+        /**
+         * Returns true if a pair of public & secret keys are associated with each other
+         * @param publicKey The public key to verify against.
+         * @param secretKey The private key to verify against.
+         */
+        _this.valid = function (publicKey, secretKey) {
+            var _a;
+            var testResponse = {};
+            var internalValidationVersion = 3;
+            var cipherResponse = _this.encrypt(testResponse, publicKey);
+            // Use toString here since the return should be an empty array.
+            return (testResponse.toString() ===
+                ((_a = _this.decrypt(secretKey, __assign(__assign({}, cipherResponse), { version: internalValidationVersion }))) === null || _a === void 0 ? void 0 : _a.responses.toString()));
+        };
+        _this.signingPublicKey = signingPublicKey;
+        return _this;
+    }
+    return CryptoV3;
+}(CryptoBase));
+export default CryptoV3;