# FortyMail — FM-01 Rebrand + Central Mailbox Authentication

## What this patch does

FM-01 converts the supplied MailTrixy codebase into the first FortyMail baseline for FortyHives Innovations Ltd.

### Product identity
- Rebrands application defaults, UI copy, PWA labels, demo/help content, internal command names, exports, and installer defaults from MailTrixy to **FortyMail**.
- Uses `https://mail.fortyhives.com` as the default FortyMail URL in `.env.example`.
- Uses `support@fortyhives.com` / `noreply@fortyhives.com` as safe FortyHives defaults.
- Keeps the existing configurable branding/theme system; no permanent logo/color assumption is hard-coded.

### Mailbox-first login
- Normal users sign in at `/login` with:
  - their full mailbox email address
  - their real mailbox password
- FortyMail verifies credentials against the centrally configured IMAP server.
- A successful first login automatically provisions:
  - the local FortyMail user record
  - a private workspace
  - the connected `EmailAccount`
  - encrypted IMAP and SMTP credentials
- Users do **not** create a separate FortyMail password.
- If a mailbox password is changed on cPanel/WHM, the next successful FortyMail login refreshes the encrypted IMAP/SMTP credentials.
- Local administrator login remains independent of IMAP, so a mail-server outage does not lock administrators out.

### Central server configuration
Admin → System Settings → **Mail Server** now has a FortyMail Mailbox Server section with:
- Enable Mailbox Login
- Auto-provision on First Login
- IMAP host / port / encryption
- TLS certificate validation
- IMAP timeout
- SMTP host / port / encryption
- optional allowed-domain list
- Test Mailbox Login

The original MailTrixy SMTP settings remain as **System / Transactional SMTP** for app-generated notifications. They are intentionally separate from user mailbox SMTP.

### User mailbox settings lock
When central mailbox mode is enabled:
- users cannot add a different mail server
- users cannot edit IMAP/SMTP hosts
- users cannot disconnect/delete their centrally managed mailbox
- these restrictions are enforced in Livewire server-side handlers, not only hidden in the UI

AI auto-reply and other mailbox-level features can still operate on the provisioned account.

## Existing installation deployment

1. Back up the application files and database.
2. Extract this patch over the existing MailTrixy/previous FortyMail application root.
3. Review `.env` and, if desired, add:

```env
APP_NAME=FortyMail
APP_URL=https://mail.fortyhives.com

FORTYMAIL_MAILBOX_LOGIN=true
FORTYMAIL_AUTO_PROVISION=true
FORTYMAIL_ALLOW_LOCAL_REGISTRATION=false

FORTYMAIL_ALLOWED_DOMAINS=

FORTYMAIL_IMAP_HOST=mail.fortyhives.com
FORTYMAIL_IMAP_PORT=993
FORTYMAIL_IMAP_ENCRYPTION=ssl
FORTYMAIL_IMAP_VALIDATE_CERT=true
FORTYMAIL_IMAP_TIMEOUT=30

FORTYMAIL_SMTP_HOST=mail.fortyhives.com
FORTYMAIL_SMTP_PORT=465
FORTYMAIL_SMTP_ENCRYPTION=ssl
```

The administrator can instead set/override the IMAP/SMTP values from the FortyMail admin UI.

4. Run the migration and clear caches.

cPanel PHP 8.3 example:

```bash
cd /path/to/fortymail
PHP=/opt/cpanel/ea-php83/root/usr/bin/php

$PHP artisan migrate --force
$PHP artisan optimize:clear
```

Generic PHP example:

```bash
php artisan migrate --force
php artisan optimize:clear
```

5. Sign in to the admin panel and open:

**System Settings → Mail Server**

Save the real cPanel/WHM IMAP and SMTP host details, then use **Test Mailbox Login** with one real mailbox.

6. Test a normal user:
- ensure the mailbox already exists on the mail server
- open `/login`
- enter the full email address and mailbox password
- FortyMail should authenticate and open the dashboard without a separate registration/onboarding flow

## Upgrade migration behavior

`2026_09_04_173900_rebrand_mailtrixy_to_fortymail.php` is intentionally conservative:
- it replaces only known legacy/default MailTrixy branding values
- it does not overwrite already-customized branding
- it inserts mailbox server settings only when they do not already exist
- it converts seeded help article references from MailTrixy to FortyMail
- its `down()` method is deliberately non-destructive

## Security notes

- Mailbox passwords are not logged.
- IMAP authentication failures return a generic message to the public login flow.
- Mailbox credentials are stored using the existing encrypted Eloquent casts on `EmailAccount`.
- A random local password is generated for mailbox-authenticated users so a stale mailbox password cannot become an unintended local-auth fallback.
- Suspended/banned users remain blocked even if their mailbox credentials are valid.
- Administrators continue to authenticate locally.

## Validation completed

- PHP syntax lint passed on all modified non-Blade PHP files.
- Modified JSON language/resources parse successfully.
- The three materially changed Blade views (login, admin mail settings, user email-account settings) were compiled in a standalone Blade syntax pass after neutralizing component tags.
- A full `artisan view:cache` boot was not possible in the analysis environment because the PHP runtime does not have the `ZipArchive` extension required by the bundled backup package; this is an environment limitation, not an application syntax failure.