Security Overview
Relevant source files
The following files were used as context for generating this wiki page:
The portfolio project, particularly its newsletter management system, is designed with a strong emphasis on data security, user privacy, and compliance. The architecture employs a multi-layered security approach, including encryption for sensitive data at rest, a privacy-conscious subscription mechanism, and robust data management practices. The core of the security model is a file-based system that avoids external database dependencies and leverages GitHub for automation and audit trails.
Key security pillars include AES-256 encryption for all subscriber emails, a unique subscription flow using GitHub Issues to minimize direct data handling, automated cleanup of personal data, and features to support GDPR compliance. This document provides a technical overview of these security measures as implemented across the project.
Data Encryption
The system ensures that all subscriber data is protected using strong encryption, particularly for personally identifiable information (PII) like email addresses.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Encryption at Rest
All subscriber email addresses are encrypted at rest within the subscribers.encrypted.json file. This prevents unauthorized access to sensitive user data even if the file system is compromised.
- Algorithm: AES-256-CBC is used for encryption, providing a strong, industry-standard level of security.
- Key Management: The encryption key is a 32-byte key, base64 encoded, and managed via the
ENCRYPTION_KEYenvironment variable. It is never stored in the repository. - Initialization Vector (IV): A random, 16-byte IV is generated for each encryption operation, ensuring that identical emails do not result in the same encrypted output. The IV is stored alongside the encrypted data.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js:108-116
The structure of the encrypted subscriber data demonstrates how the IV is stored with the ciphertext.
{
"id": "uuid",
"encryptedEmail": {
"encrypted": "hex-string",
"iv": "hex-string",
"keyVersion": "env-v1"
},
"status": "active",
"subscribedAt": "2025-10-31T10:00:00Z",
"source": "website"
}
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Encryption Flow
The following diagram illustrates the process of encrypting a subscriber's email address before it is stored.
This diagram shows how a subscriber's email is encrypted using an environment key and a random IV before being stored.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Subscription and Data Handling
The newsletter subscription process is designed to be secure and privacy-focused by leveraging GitHub Issues as an intermediary, which minimizes direct data handling and creates a transparent audit trail.
Sources: themes/matrix-flow/README-newsletter.md, themes/matrix-flow/source/js/newsletter.js
Frontend Validation
Security begins on the client side. The subscription form includes robust validation to ensure data quality and prevent malicious submissions.
- Real-time Validation: The form validates email formats as the user types, using a regex and checking for common domain typos.
- Disposable Email Block: A basic check is in place to reject submissions from known temporary email providers.
- Consent Enforcement: The form cannot be submitted unless the user explicitly checks the consent checkbox.
- Rate Limiting: A simple 5-second cooldown is implemented to prevent rapid, repeated submissions.
Sources: themes/matrix-flow/source/js/newsletter.js:120-170, themes/matrix-flow/source/js/newsletter.js:231-235
GitHub Issue-Based Subscription Flow
Instead of a traditional backend that directly handles user data, the system redirects the user to create a pre-filled GitHub Issue. This has several security advantages:
- No Exposed API Tokens: The frontend does not need to handle API tokens for creating subscriptions.
- Audit Trail: Every subscription attempt is logged as a GitHub Issue, providing a clear and auditable history.
- Automation: GitHub Actions are triggered to process the issue, acting as a secure, isolated backend.
After processing, the GitHub Issue is automatically closed and scheduled for deletion (typically after 24 hours) to protect user privacy by not leaving personal data in the issue history.
Sources: themes/matrix-flow/README-newsletter.md, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js:200-221
The following sequence diagram illustrates the secure subscription flow.
This diagram shows the end-to-end subscription process, from form submission to secure storage and issue cleanup.
Sources: themes/matrix-flow/README-newsletter.md, themes/matrix-flow/source/js/newsletter.js:377-393, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js
Data Protection and GDPR Compliance
The system includes several features designed to comply with GDPR principles, such as data portability and the right to erasure.
| GDPR Principle | Implementation |
|---|---|
| Data Portability | A CLI command npm run export gdpr --email <email> allows for a complete export of all data associated with a specific subscriber. |
| Right to Erasure | The npm run subscribers remove --id <uuid> command securely deletes a subscriber's data. |
| Data Minimization | The system collects only necessary data for newsletter delivery and preferences. |
| Consent Management | Explicit consent is required via a checkbox during subscription, and this consent is logged in the created GitHub issue. Unsubscribe links use secure, unique tokens. |
| Data Protection by Design | Email addresses are encrypted at rest, and privacy-sensitive GitHub issues are automatically deleted. |
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Configuration and Secrets Management
Sensitive configuration, such as API keys and encryption keys, is managed securely using environment variables and GitHub Secrets, ensuring they are not hardcoded in the source code.
| Variable | Description | Storage Method |
|---|---|---|
ENCRYPTION_KEY | Base64 encoded 32-byte key for AES-256 encryption of subscriber data. | Environment Variable / GitHub Secret |
RESEND_API_KEY | API key for the Resend email service. | GitHub Secret |
DISCORD_WEBHOOK_URL | Optional webhook URL for sending notifications. | GitHub Secret |
CONTACT_EMAIL | Optional contact email for GDPR-related requests. | Environment Variable |
A new encryption key can be generated using the following Node.js command:
node -e "const crypto = require('crypto'); console.log('ENCRYPTION_KEY=' + crypto.randomBytes(32).toString('base64'));"
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md, newsletters/README.md, _config.yml:102-106
Secure Data Export
The newsletter-program provides functionality for exporting subscriber and analytics data securely. This is managed via the export-cli.js and supports GDPR data requests.
Key features include:
- Full Data Export: The
npm run export createcommand generates a complete export of all data. - Anonymization: The
--anonymizeflag can be used to create an anonymized dataset for research or analysis, stripping PII. - GDPR-Specific Export: The
npm run export gdpr --email <email>command is specifically designed to fulfill data portability requests for an individual. - Integrity Verification: The
npm run export verify --file <export-file.json>command can be used to check the integrity of an export file.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Summary
The security of the portfolio's newsletter system is built on a foundation of strong encryption, a privacy-first data handling architecture, and robust compliance features. By using a file-based encrypted storage system and a unique GitHub Issue-based subscription flow, the project minimizes its attack surface and ensures that user data is protected throughout its lifecycle. The clear separation of concerns, secure management of secrets, and built-in tools for GDPR compliance demonstrate a comprehensive approach to security and privacy.