AES-GCM encryption implementation

📋 Product Requirements Document

PRD: AES-GCM encryption implementation

Issue: #144
Milestone: Phase 4: Security
Labels: secrets-encryption, hacktoberfest

---

PRD: AES-GCM Encryption Implementation

Overview

The AES-GCM encryption implementation is a critical feature for the MeshHook project, directly contributing to our goal of offering a secure, multi-tenant workflow engine. As part of Phase 4: Security, this task focuses on enhancing the security of stored secrets by adopting AES-GCM, an authenticated encryption algorithm that provides both data confidentiality and integrity. This aligns with our commitment to multi-tenant RLS security and secrets encryption, ensuring that sensitive data is protected at rest.

Functional Requirements

1. Encryption Mechanism: Implement AES-GCM encryption for all secrets stored by MeshHook. This includes, but is not limited to, webhook secrets, access tokens, and any user-defined secrets within workflows.
2. Key Management: Implement a Key Encryption Key (KEK) management system, allowing for regular rotation of KEKs without losing access to data encrypted with previous keys.
3. API for Encryption and Decryption: Provide internal API methods for encrypting and decrypting data, ensuring these methods can be easily utilized wherever secrets management is required in the MeshHook codebase.
4. Migration Path: Develop a secure migration path for existing secrets to be encrypted with AES-GCM, ensuring zero data loss and minimal service interruption.
5. Utility Functions: Include utility functions for generating secure nonces for AES-GCM, as this is crucial for maintaining the security guarantees of AES-GCM.

Non-Functional Requirements

• Performance: The encryption and decryption operations must be optimized for performance, ensuring minimal impact on request processing times.
• Security: Adhere to best practices in cryptographic implementations, avoiding common pitfalls such as insecure nonce usage or key management flaws.
• Reliability: Ensure that the encryption system is robust, with fail-safes in place to prevent data loss or corruption.
• Maintainability: Write clear, well-documented code with an emphasis on maintainability and ease of understanding, following the project's established coding standards.

Technical Specifications

Architecture Context

MeshHook leverages a combination of SvelteKit for front-end interactions, Supabase for backend services including Postgres for data storage, and a distributed system of workers for task execution. The AES-GCM encryption feature will primarily interact with the components responsible for secrets management and storage within the Supabase Postgres database.

Implementation Approach

1. Analysis: Review the current secrets storage mechanism to identify all areas where encryption needs to be integrated.
2. Design:
   • Define a schema for storing encrypted secrets along with their nonces and associated KEK identifiers.
   • Design the KEK management system, including database schema for KEK storage and rotation logic.
3. Implementation:
   • Develop the encryption/decryption API, incorporating AES-GCM and KEK management.
   • Implement utility functions for nonce generation and secure storage of encryption metadata.
   • Integrate the encryption API into existing secrets management workflows.
   • Create a migration tool/script for encrypting existing secrets.
4. Testing: Perform thorough testing, including unit, integration, and end-to-end tests, to ensure the encryption system functions correctly across all scenarios.
5. Documentation: Update internal documentation to reflect the new encryption mechanism and provide guidelines for developers on using the encryption API.
6. Review & Deployment: Conduct a code review with the team and prepare for deployment, including planning any required downtime for secret migration.

Data Model Changes

• encrypted_secrets table:

  • id SERIAL PRIMARY KEY
  • project_id INT REFERENCES projects(id)
  • encrypted_data BYTEA
  • nonce BYTEA
  • kek_id INT REFERENCES kek(id)

• kek table:

  • id SERIAL PRIMARY KEY
  • key BYTEA
  • created_at TIMESTAMP

API Endpoints

• No new external API endpoints required for this task.
• Internal APIs for encrypt/decrypt operations will be added to the project's service layer.

Acceptance Criteria

• AES-GCM encryption implemented for all new and existing secrets.
• KEK management system operational with the ability to rotate keys without data loss.
• Migration tool/scripts developed and tested for encrypting existing secrets.
• Encryption and decryption operations meet performance benchmarks.
• All unit and integration tests pass, ensuring encryption system reliability.
• Documentation updated to include details on the encryption implementation and usage.
• Security audit completed with no major issues found.

Dependencies

• Access to the current MeshHook codebase and database schema.
• Supabase Postgres for database changes.
• Security libraries supporting AES-GCM (e.g., Node.js crypto module).

Implementation Notes

Development Guidelines

• Use Node.js' built-in crypto module for AES-GCM operations to avoid additional dependencies.
• Follow TDD principles by writing tests before implementing the encryption logic.
• Ensure that all encryption operations are asynchronous to avoid blocking the event loop.

Testing Strategy

• Implement unit tests for all new utility functions and API methods.
• Integration tests should cover the encryption and decryption workflow, including key rotation.
• Performance tests to measure the impact of encryption on processing times.

Security Considerations

• Ensure secure generation and storage of nonces for AES-GCM to prevent reuse.
• Follow best practices for key management, including secure storage and regular rotation of KEKs.
• Conduct a thorough security review of the implementation to identify potential vulnerabilities.

Monitoring & Observability

• Monitor the performance of encryption and decryption operations to identify potential bottlenecks.
• Log key rotation events and any encryption-related errors for auditability.

By adhering to this PRD, the MeshHook project will enhance its security posture through the secure management of secrets, aligning with our goal of providing a reliable, secure, and user-friendly workflow engine.

---

This PRD was AI-generated using gpt-4-turbo-preview from GitHub issue #144
Generated: 2025-10-10

📎 Generated Documentation

• 📄 PRD Document: 144-aes-gcm-encryption-implementation.md
• 🎨 PlantUML Diagram: 144-aes-gcm-encryption-implementation.puml
• 🖼️ Diagram Image: 144-aes-gcm-encryption-implementation.png

---

This issue body was auto-generated from the PRD. Original issue content is preserved in the PRD document.
Last updated: 2025-10-10

No implementation file or test is named. Start by reviewing the current secrets storage mechanism and database schema, then map the required encryption, KEK rotation, migration, and testing work to the existing service layer. Done means the acceptance criteria are met, including documentation and security review.