treva

📖 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

• 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();

• 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.

• 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.