📖 TREVA: A Secure Trace Events Activity Package

TREVA is a robust Node.js package designed for storing and managing event logs in a MongoDB database with built-in authenticated data encryption. This package simplifies the process of logging events while ensuring the confidentiality and integrity of sensitive data.

✨ Features

• Secure Data Encryption: Utilizes AES-256-GCM authenticated encryption to protect sensitive event data at rest.

• Flexible Event Logging: Allows for adding and retrieving both encrypted and unencrypted events.

• Dynamic Collection Naming: Automatically creates dedicated collections for each eventType for efficient data organization.

• Environment-Based Configuration: Securely loads critical connection and encryption keys from environment variables.

📦 Installation

To get started, install the TREVA package and its dependencies via npm.

npm install treva

⚙️ Configuration

The package relies on two crucial environment variables for secure operation. You must set these before running your application.

• MONGO_URI: The full MongoDB connection string. For example: mongodb://localhost:27017/treva.

• ENCRYPTION_KEY: A strong, randomly generated 32-byte encryption key for AES-256-GCM. It is critical to keep this key a secret.

# Example .env file content
MONGO_URI="mongodb://localhost:27017/treva"
ENCRYPTION_KEY="your-strong-random-key-here-of-32-bytes"

🚀 Usage

1. Connect to the Database

   First, you must establish a connection to your MongoDB instance. Ensure you have added MONGO_URI in your .env.

import { Database } from "treva";

async function initialize() {
  try {
    await Database.connect();
    console.log("Database connection established.");
  } catch (err) {
    console.error("Failed to connect to database:", err);
  }
}

initialize();

2. Add an Event

   The addEvent method is used to securely log a new event into your database.

Method Signature:

EventLogger.addEvent({
  eventType: string;
  eventName: string;
  data: object;
  encryption?: boolean;
  isOwn?: boolean;
});

Parameters:

• eventType: (Required) The type of event being logged (e.g., "user", "payment").

• eventName: (Required) The specific name of the event (e.g., "user_login", "credit_card_transaction").

• data: (Required) The event payload, which must be a JSON object.

• encryption: (Optional) A boolean flag to determine if the event's data should be encrypted before storage. Defaults to false.

• isOwn: (Optional) A boolean flag to control where the event is stored. Defaults to true.

Behavior:

• Collection Management: If isOwn is true, the event will be stored in a dedicated collection named <eventType>_event_logs. If isOwn is false, the event will be stored in the main master_event_logs collection.

• Data Encryption: If encryption is set to true, the data payload is encrypted using the provided ENCRYPTION_KEY before it is saved to the database. Otherwise, the data is stored as-is.

• Mandatory Fields: eventType, eventName, and data are all required parameters. If any of these are missing, the method will return an error.

3. Retrieve Events

   The getEvents method allows you to retrieve event logs with flexible filtering and pagination.

EventLogger.getEvents({
  eventType: string;
  eventName: string;
  filter?: object;
  isEncrypted?: boolean;
  page?: number;
  limit?: number;
});

Parameters:

• eventType: (Required) The type of event to retrieve (e.g., "user", "payment").

• eventName: (Required) The specific name of the event (e.g., "user_login", "credit_card_transaction").

• filter: (Optional) An object to apply additional filters on the event's data field.

• isFromMaster: (Optional) A boolean flag that, when set to true, forces the query to run on the master_event_logs collection.

• isEncrypted: (Optional) A boolean flag to filter events by their encryption status. true fetches only encrypted data which will be automatically decrypted before being returned, while false fetches only unencrypted data.

• page: (Optional) The page number for pagination. Defaults to 1.

• limit: (Optional) The maximum number of events to return per page. Defaults to 10.

🛡️ Security

The security of your data depends entirely on the ENCRYPTION_KEY.

• Do not hardcode your key. Always use a secure environment variable.

• Protect the key. Store it securely and do not commit it to version control (e.g., using .gitignore).

• Use a strong key. A randomly generated 32-byte string is recommended.

📜 License

This project is licensed under the MIT License.