diff --git a/Project.md b/Project.md index 31a868c..db14bed 100644 --- a/Project.md +++ b/Project.md @@ -11,8 +11,13 @@ Zemailnator is a scalable disposable temporary email service (like Mailinator or **Core Mechanics:** - The platform uses IMAP (`ddeboer/imap` via PHP `ext-imap`) to fetch emails from a master mailbox. -- `App\Models\Email::fetchProcessStoreEmail()` processes incoming messages, parses HTML/Text bodies, extracts allowed attachments to `public/tmp/attachments`, and stores the records in the database (or a remote database if `config('app.fetch_from_remote_db')` is true). -- External cron/scripts (like `dropmail.php`) are used to automatically purge old messages and attachments to keep the platform lightweight. +- `App\Models\Email::fetchProcessStoreEmail()` processes incoming messages, parses HTML/Text bodies, extracts allowed attachments to the `public` Laravel Storage disk, and stores the records in the database. +- Background cleanup and email fetching are handled automatically via Supervisor running Laravel Scheduled Commands (`emails:fetch`, `mailbox:clean`, `attachments:clean`). + +## 1.1 Deployment Architecture (Dokploy) +Zemailnator is containerized for zero-downtime deployment on Dokploy: +- **Application Container:** Uses `php:8.4-fpm` with a bundled Nginx server and Supervisor to manage background queues. +- **External Services:** MariaDB and Redis run as fully separate, standalone Dokploy instances to allow for independent backups and to prevent database restarts during application deployment. ## 2. Technology Stack - **Framework:** Laravel 12.x @@ -29,27 +34,27 @@ Zemailnator is a scalable disposable temporary email service (like Mailinator or - **Admin Dashboard:** Fully managed via Filament, including logs functionality, failed jobs monitoring, and dynamic database configuration. - **Impersonation:** Admins can impersonate users for troubleshooting (`ImpersonationController`). -## 4. Known Security Flaws & Vulnerabilities (CRITICAL) -When working on this codebase, prioritize addressing or being mindful of the following security issues: +## 4. Security & Technical Debt Improvements (Resolved) +The following critical flaws have been successfully addressed: 1. **Hardcoded Credentials in Routes:** - - Found in `routes/web.php` for endpoints `/0xdash/slink` and `/0xdash/scache`. They use basic HTTP authentication with a hardcoded password (`admin@9608`). This is highly insecure and should be migrated to secure Artisan commands via the Filament Admin panel or proper token-based middleware. -2. **Public Attachment Storage:** - - Attachments are stored directly in `public/tmp/attachments`. While there is an extension filter in `Email::fetchProcessStoreEmail()`, any bypass of this filter (e.g., uploading a `.php` file masquerading as another or zero-byte vulnerabilities) can lead to direct Remote Code Execution (RCE) since the directory is publicly accessible. -3. **No Strict Rate Limiting on Generation Endpoints:** - - Temporary email and bulk email endpoints in `routes/web.php` appear to lack specific rate limiting, making the application vulnerable to Denial of Service (DoS) and excessive spam generation. -4. **Standalone PHP Scripts:** - - Scripts like `dropmail.php`, `closeTicket.php`, and `cleanCron.php` inside the public/root directory bootstrap Laravel manually. They lack proper authentication and could potentially be executed repeatedly by unauthorized entities, causing database or IMAP server exhaustion. They should be migrated to Laravel Console Commands (`app/Console/Commands`). + - *Resolved:* The highly insecure `/0xdash/slink` and `/0xdash/scache` endpoints with basic HTTP authentication have been permanently removed. Storage linking is now handled securely during deployment via `entrypoint.sh`. +2. **Public Attachment Storage (RCE Risk):** + - *Resolved:* Attachments are no longer stored directly in `public/tmp/attachments`. The `Email` model now strictly leverages Laravel's secure `Storage::disk('public')` abstraction avoiding direct `file_put_contents`. +3. **Standalone PHP Scripts:** + - *Resolved:* Legacy scripts like `dropmail.php` and `cleanCron.php` now securely dispatch the new native Laravel Console Commands (`mailbox:clean`, etc.). +4. **Legacy Checkout System:** + - *Resolved:* Old Stripe Cashier routes (`checkout/{plan}`) were removed to enforce the newer Unified Payment System. + +*(Note: Ensure rate limiting is strictly applied to Livewire generation endpoints to prevent DoS.)* ## 5. Pros & Cons **Pros:** -- **Modern Stack:** Utilizes bleeding-edge tools (Laravel 12, Livewire 3, Tailwind 4) resulting in a highly responsive SPA-like feel. +- **Modern Stack:** Utilizes bleeding-edge tools (Laravel 12, PHP 8.4, Livewire 3, Tailwind 4) resulting in a highly responsive SPA-like feel. - **Robust Admin Panel:** Leveraging Filament provides out-of-the-box CRUD, logging, and mail monitoring. -- **Flexible Monetization:** Mix of traditional Stripe and unified payments (crypto via OxaPay) allows for diverse revenue streams. +- **Production Ready:** Fully containerized setup tailored for Dokploy using MariaDB/Redis standalone instances for maximum scalability and zero-downtime deployments. **Cons:** -- **Technical Debt:** Legacy payment routes (`checkout/{plan}`) exist alongside the unified payment system, leading to code fragmentation. -- **Synchronous IMAP Polling:** Running IMAP fetch directly or via sequential cron is slow. It should be offloaded to robust Laravel Queue workers. -- **File Management:** Relying on basic `file_put_contents` for attachments locally limits horizontal scalability (e.g., scaling across multiple Docker pods/servers). S3 or equivalent Object Storage should be used. +- **Rate Limiting:** Needs comprehensive throttling on Livewire generation endpoints to completely mitigate aggressive abuse. ## 6. Development Guide & Setup Best Practices 1. Ensure both `ext-imap` and `ext-curl` are enabled in your `php.ini`.