feat: Prepare Zemailnator for Dokploy deployment
- Add highly optimized Dockerfile with Nginx and PHP-FPM 8.4 - Add docker-compose.yml configured with Redis and MariaDB 10.11 - Implement entrypoint.sh and supervisord.conf for background workers - Refactor legacy IMAP scripts into scheduled Artisan Commands - Secure app by removing old routes with hardcoded basic auth credentials - Configure email attachments to use Laravel Storage instead of insecure public/tmp
This commit is contained in:
idevakk
76
Project.md
Normal file
76
Project.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
description: Zemailnator - AI-First Project Documentation
|
||||
---
|
||||
|
||||
# Zemailnator Project Documentation
|
||||
|
||||
> **AI INSTRUCTION**: This `Project.md` file contains critical context for the Zemailnator (Disposable Email Generator) application. When interacting with this project, ALWAYS load and review this file as part of your system instructions. Treat these guidelines, architectural details, and known security flaws as your primary working context.
|
||||
|
||||
## 1. Project Overview & Architecture
|
||||
Zemailnator is a scalable disposable temporary email service (like Mailinator or 10 Minute Mail) built on the Laravel framework. It provides users with instant, disposable email addresses to prevent spam, with premium tiers offering custom domains, 10-minute validity enhancements, and bulk generation capabilities.
|
||||
|
||||
**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.
|
||||
|
||||
## 2. Technology Stack
|
||||
- **Framework:** Laravel 12.x
|
||||
- **PHP Version:** >= 8.2
|
||||
- **Frontend / UI:** Livewire v3, Flux UI Free, Tailwind CSS v4, Vite
|
||||
- **Admin Panel:** Filament v4
|
||||
- **Billing:** Laravel Cashier (Stripe) v15, alongside a custom Unified Payment System (OxaPay, etc.)
|
||||
- **Testing:** Pest v3
|
||||
- **Email Parsing:** PHP `ext-imap`, `ddeboer/imap`
|
||||
|
||||
## 3. Key Features
|
||||
- **Disposable Email Generation:** Quick generation of random or temporary emails via Livewire components (e.g., `/mailbox`, `/gmailnator`).
|
||||
- **Premium Subscriptions:** Tiered access (Stripe/Crypto) unlocking features like Premium Domains, 10-Minute Emails, and Bulk Email generation.
|
||||
- **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:
|
||||
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`).
|
||||
|
||||
## 5. Pros & Cons
|
||||
**Pros:**
|
||||
- **Modern Stack:** Utilizes bleeding-edge tools (Laravel 12, 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.
|
||||
|
||||
**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.
|
||||
|
||||
## 6. Development Guide & Setup Best Practices
|
||||
1. Ensure both `ext-imap` and `ext-curl` are enabled in your `php.ini`.
|
||||
2. Run `npm run dev` in tandem with `php artisan serve` if working on Frontend/FluxUI adjustments.
|
||||
3. To test email fetching locally without an active IMAP server, consider writing Pest tests mocking the `ConnectionInterface`.
|
||||
4. Always use `php artisan test` before committing. The project uses Pest. Make sure datasets and mocking are used properly per the `CLAUDE.md` guidelines.
|
||||
|
||||
## 7. Examples / Workflows
|
||||
|
||||
**Example: Fetching Emails**
|
||||
The `Email` model has a primary function `fetchProcessStoreEmail()`:
|
||||
```php
|
||||
// Call this to manually pull emails
|
||||
App\Models\Email::fetchProcessStoreEmail();
|
||||
```
|
||||
|
||||
**Example: Reading Emails (Livewire)**
|
||||
The `Mailbox` component fetches emails for the active user session or session ID, parsing them via:
|
||||
```php
|
||||
$emails = App\Models\Email::parseEmail($currentUserEmailAddress, $deletedArray);
|
||||
```
|
||||
|
||||
## 8. AI Auto-Load Instruction
|
||||
**For AI Agents:** Whenever you receive a new chat prompt within this workspace, your implicit first step must be to cross-reference the user's request against this `Project.md` document. Pay special attention to the Laravel 12 / Livewire 3 structures and strictly avoid executing basic auth routes or standard PHP scripts directly if Laravel-native alternatives exist. Use Pest for all tests. ALWAYS rely on the `CLAUDE.md` guidelines as your secondary set of standard rules.
|
||||
Reference in New Issue
Block a user