Secure Messaging

Technical documentation

Feature Overview

The objective of the Secure Messaging feature is to enable secure, auditable electronic message delivery by enforcing encryption and recipient authentication. This ensures that sensitive messages are accessible only to verified recipients, maintaining data confidentiality, integrity, and compliance with industry security standards. All data is protected both at rest and in transit using modern encryption protocols (TLS 2.0 or higher), and access is controlled via identity verification mechanisms based on email-delivered one-time use passcodes.

Feature Description

The Secure Messaging Service enables secure communication through a process that protects message content and controls recipient access:

• Data Protection: All data is encrypted at rest and in transit using TLS 2.0 or higher.

• Recipient Verification: When a message is sent, the recipient receives an email with a secure link to access the message.

• Access Control: Upon visiting the secure Web page, the recipient must generate and enter a one-time use passcode, sent to their email, to view the message.

• User Privacy: In multi-recipient scenarios, each recipient receives an individual notification and is unaware of other recipients.

• Audit Logging: Every access attempt and message transaction is recorded in a persistent audit trail within VisualVault.

• Configurability:

  • Passcode expiration time is adjustable.

  • Expired passcodes can be regenerated by the recipient.

  • The number of OTP requests per message can be limited.

  • Message expiration can be configured, after which no new OTPs can be generated and the message becomes inaccessible.

This service ensures that messages are only accessed by intended recipients, remain secure during transmission and storage, and are fully auditable to support compliance requirements.

Technical Architecture

Walkthrough

1. Clone the Github repository using Visual Studio Code

   • Prerequisites

     • VS Code

     • Node version 18 or higher installed

     • AWS VPN connection for database access

   • NPM Install in respository directory

     • From VS Code terminal or Windows termainal execute "npm install" in the project directory

   • Install the localhost certificate for local development

     • Windows 10/11: Right click on the localhost.crt file, select Install Certificate--> Local Machine-->Place all certificates in the following store-->browse to Trusted Root Certificate Authorities-->click OK.

   • Click Run and Debug Icon

     • Click the Run and Debug Icon (ctrl+Shift+D) Click Launch Program Icon (F5)

   • Open browser to https://localhost:89

     • You change the port number in the /bin/www file

2. Configuration

   • /Services/serverstrings.js file contains the VisualVault API URL and credentials Update the API Key/Secret and database connection information

Execution (with Error Handling)

1. Initiate and Send Secure Message

• Action: The Sender inputs required message details (e.g., message body, subject, recipients). Upon submission, the system validates input fields (e.g., required data, email formats). If validation succeeds, HTTP Client sends an HTTP POST /api/email to the Secure Messaging Service

• Payload: msgBody, msgSubject, emailRecipients, customerDatabaseId and a JSON web token (JWT).

• Parameter	Type	Description
  msgBody	longtext	Body
  msgSubject	longtext	Subject
  emailRecipients	comma delimited list	Recipients
  jsonwebtoken	JWT	JSON web token (JWT) authorization token provided by VV API once connected to VV API
  customerDatabaseId	char(36)	The name for the authentication database. This identifies and connect to the correct database instance where user credentials or tokens are stored.

• Error Handling:

  • If any required data is missing or invalid (e.g., incorrect email address for recipient), block the action and display an appropriate error message.

  • Only proceed with sending the HTTP POST request upon successful validation.

  • Catch HTTP errors and log them.

  • Retry mechanism (e.g., up to 3 attempts on errors like timeouts).

2. Message and Recipient Verification

• Action: Secure Messaging Portal generates messageId and recipientEmail, and saves to multi-tenant database.

  • App updates messages table. Note the messageId.

    • 

  • App updates message_recipients table. Note the email entered appears in recipientEmail.

    • 

• Error Handling:

  • If database write fails, return error to sender and stop transaction.

  • Show sender an error (e.g.,"Failed to create secure message. Please try again.")

3. Notification Email Dispatch

• Action: Secure Messaging Portal sends email to each recipient using VisualVault API.

  • The following message is sent to the recipient:

    • 

• Error Handling:

  • If email delivery fails (Microservice/API failure), log failure and mark message as "undelivered".

  • Optionally retry email delivery asynchronously.

4. One-Time Code Request

• Action: Recipient clicks link, “Click here to verify”, which triggers HTTP POST /api/code to the Secure Messaging Service.

• Payload: messageId, msgRecipId

• Error Handling:

  • Invalid or expired messageId/msgRecipId: show error "Invalid message request."

  • Log all failed code generation attempts for auditing.

5. Code Generation and Delivery

• Action: Secure Messaging Portal generates one-time code and stores in database, then emails code to recipient.

• Error Handling:

  • If database or email operation fails: log and notify user "Unable to generate access code. Please try again later."

6. Code Validation

• Action: Recipient submits code, HTTP POST /api/code/{code}/validate to the Secure Messaging Portal.

• Error Handling:

  • Expired/invalid code: show message, (e.g., "Code is invalid or expired.")

  • Lock out after 5 failed attempts.

7. Code Verification and Message Rendering

• Action: Secure Messaging Portal verifies code and renders UI.

• Error Handling:

  • If initialization fails (e.g., missing data), show message, (e.g., "Unable to load message. Contact support.")

  • Log rendering or state errors with user/session context.

8. Access the Secure Message

• Action: User reads secure message in browser.

• Error Handling:

  • If browser loses session or network, show reconnection options.

Related Resources

Additional Resources:

• Github Repository