feat: add verified content to v3 (#121)

* add verifiedContent decryption support for cryptoV3

* move decryption of verifiedContent to decryptFromSubmissionkey; use submissionKey

* remove unused variables

* bumped version to 0.14.0 to match latest

* fixed tests

* added to tests

* replace coveralls with coveralls-next

* resolved tests

* revert coveralls to use v2

* rethrow missingPublicKeyError

* add missing }

* added comment to explain v1 vs v3 decryption differences

* removed coveralls package

* updated explanataion for v1 vs v3 content

Author: scottheng96

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
       - run: npm run test-ci
         env:
           NODE_OPTIONS: '--max-old-space-size=8192'
-      - name: Submit test coverage to Coveralls
-        uses: coverallsapp/github-action@v1.1.2
+      - name: Submit coverage to Coveralls
+        uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengovsg/formsg-sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/opengovsg/formsg-javascript-sdk.git"
@@ -36,7 +36,6 @@
     "@types/node": "^18.18.9",
     "@typescript-eslint/eslint-plugin": "^4.25.0",
     "auto-changelog": "^2.4.0",
-    "coveralls": "^3.1.1",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-import": "^2.23.3",
     "eslint-plugin-jest": "^24.3.6",

package.json

@@ -4,20 +4,27 @@ import {
   ciphertext,
   formPublicKey,
   formSecretKey,
-  submissionSecretKey
+  submissionSecretKey,
+  plainVerifiedText
 } from './resources/crypto-v3-data-20231207'
 import CryptoV3 from '../src/crypto-v3'
+import Crypto from '../src/crypto'
+import { SIGNING_KEYS } from '../src/resource/signing-keys'
 
 const INTERNAL_TEST_VERSION = 3
 
 const testFileBuffer = new Uint8Array(Buffer.from('./resources/ogp.svg'))
 
+const encryptionPublicKey = SIGNING_KEYS.test.publicKey
+const signingSecretKey = SIGNING_KEYS.test.secretKey
+
 jest.mock('axios', () => mockAxios)
 
 describe('CryptoV3', function () {
   afterEach(() => mockAxios.reset())
 
-  const crypto = new CryptoV3()
+  const crypto = new CryptoV3({ signingPublicKey: encryptionPublicKey })
+  const cryptoV1 = new Crypto({ signingPublicKey: encryptionPublicKey })
 
   it('should generate a keypair', () => {
     const keypair = crypto.generate()
@@ -126,4 +133,22 @@ describe('CryptoV3', function () {
 
     expect(decrypted).toBeNull()
   })
+
+    it('should be able to encrypt and decrypt submissions with verifiedContent from 2023-12-07 end-to-end successfully from the form private key', () => {
+    // Arrange
+    const { publicKey, secretKey } = crypto.generate()
+
+    // Act
+    const ciphertext = crypto.encrypt(plaintext, publicKey)
+    const verifiedText = cryptoV1.encrypt(plainVerifiedText, ciphertext.submissionPublicKey, signingSecretKey)  
+    const decrypted = crypto.decrypt(secretKey, {
+      ...ciphertext,
+      verifiedContent: verifiedText,
+      version: INTERNAL_TEST_VERSION,
+    })
+    // Assert
+    expect(decrypted).toHaveProperty('responses', plaintext)
+    expect(decrypted).toHaveProperty('verified', plainVerifiedText)  
+      
+  })
 })

spec/crypto-v3.spec.ts

@@ -30,6 +30,8 @@ const plaintext = {
   }
 }
 
+const plainVerifiedText = { 'uinFin (Step 1)': 'S9912370B' }
+
 const ciphertext = {
   encryptedContent:
     'yUW5li4+IA9q2/n3ZS+5+wrXQ8mKGrFJ1KW9Kf/eRzc=;PgZE8+y8rBvssnqLnqjnnqHDW6PngYKK:eIEuOUQjf1YkQIulZ7bCKXIl6wByg644Ulk/LjhefmLzhkVmXbTxBJVKVG6YgV0ZMcG4JPUuQ+WOW+N1/AOyL/8DJqclX74kG6s0DNXIJixkqNZCnfZapulerR9XXKSfwBjpo1nK25KCg32F/ey2HypPcluGV19hWwgj80mlms7Ya7x1X5wcdttlGrzGEnNH2VEPXjzJZHqiV1TWoQGwxSZ753fpkHUkBeKFA1UkMHS5XYnWyYD48JpfpOAz0L2ti6RHQnQLSKUHscYVfAZt5OyUGqPFmhm2ulWdycNVp8HayQrpqeY8cdu8QsmZRdNCMfMFLahZCm6xKS+8GUrJWgJr64yaZpkxQS45uPb9zxC+G/u4FZhS/YsrjDTuIIwMGS0+qsNr4075yemFFAQHIpbhWZ9QlYrNq2TAolrVezeAw3AQ/nr4sz60dvqRahcse9x8oMxB7jA55OuxH5uk6PcCIAmEi+njr6Lgbcn2mtPMyk7kGcwjNzCL57b51RxJVi0ZqNXrS0FFepvzCK3IOEqKqrKGGK0qGqF4MFsH2wdq4RFkXjLMZk4u9ZWjIRjc',
@@ -44,6 +46,7 @@ const submissionSecretKey = 'bIyKphcx5hiuBaJ4q5cwnXaFNY9Ofe5NQBqTEzf3zYA='
 
 export {
   plaintext,
+  plainVerifiedText,
   ciphertext,
   formPublicKey,
   formSecretKey,

spec/resources/crypto-v3-data-20231207.ts

@@ -5,9 +5,15 @@ import {
   encodeUTF8,
 } from 'tweetnacl-util'
 
-import { decryptContent, encryptMessage, generateKeypair } from './util/crypto'
+import {
+  decryptContent,
+  encryptMessage,
+  generateKeypair,
+  verifySignedMessage,
+} from './util/crypto'
 import { determineIsFormFieldsV3 } from './util/validate'
 import CryptoBase from './crypto-base'
+import { MissingPublicKeyError } from './errors'
 import {
   DecryptedContentV3,
   DecryptParams,
@@ -17,8 +23,11 @@ import {
 } from './types'
 
 export default class CryptoV3 extends CryptoBase {
-  constructor() {
+  signingPublicKey?: string
+
+  constructor({ signingPublicKey }: { signingPublicKey?: string } = {}) {
     super()
+    this.signingPublicKey = signingPublicKey
   }
 
   /**
@@ -62,7 +71,7 @@ export default class CryptoV3 extends CryptoBase {
     decryptParams: DecryptParams
   ): DecryptedContentV3 | null => {
     try {
-      const { encryptedContent } = decryptParams
+      const { encryptedContent, verifiedContent } = decryptParams
 
       // 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.
@@ -85,8 +94,47 @@ export default class CryptoV3 extends CryptoBase {
         responses: decryptedObject as FormFieldsV3,
       }
 
+      /** 
+       * 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'
+          )
+        }
+
+        const decryptedVerifiedContent = decryptContent(
+          submissionSecretKey,
+          verifiedContent
+        )
+
+        if (!decryptedVerifiedContent) {
+          // Returns null if decrypting verified content failed.
+          throw new Error('Failed to decrypt verified content')
+        }
+
+        const 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
     }
   }
@@ -99,24 +147,34 @@ export default class CryptoV3 extends CryptoBase {
    * @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 => {
-    const { encryptedSubmissionSecretKey, ...rest } = decryptParams
+    try {
+      const { encryptedSubmissionSecretKey, ...rest } = decryptParams
 
-    const submissionSecretKey = decryptContent(
-      formSecretKey,
-      encryptedSubmissionSecretKey
-    )
+      const submissionSecretKey = decryptContent(
+        formSecretKey,
+        encryptedSubmissionSecretKey
+      )
 
-    if (submissionSecretKey === null) return null
+      if (submissionSecretKey === null) return null
 
-    return this.decryptFromSubmissionKey(
-      encodeBase64(submissionSecretKey),
-      rest
-    )
+      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
+    }
   }
 
   /**

src/crypto-v3.ts

@@ -31,7 +31,7 @@ export = function (config: PackageInitParams = {}) {
       secretKey: webhookSecretKey,
     }),
     crypto: new Crypto({ signingPublicKey }),
-    cryptoV3: new CryptoV3(),
+    cryptoV3: new CryptoV3({ signingPublicKey }),
     verification: new Verification({
       publicKey: verificationPublicKey,
       secretKey: verificationOptions?.secretKey,

src/index.ts

@@ -82,6 +82,7 @@ export interface DecryptParams {
 export interface DecryptParamsV3 {
   encryptedContent: EncryptedContent
   encryptedSubmissionSecretKey: EncryptedContent
+  verifiedContent?: EncryptedContent
   version: number
 }
 
@@ -93,6 +94,7 @@ export type DecryptedContent = {
 export type DecryptedContentV3 = {
   submissionSecretKey: string
   responses: FormFieldsV3
+  verified?: Record<string, any>
 }
 
 export type DecryptedFile = {