Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

docs(extensions): Phases 4-5 boundary audits (Email + WordPress)

Juan Denis81d070b1d89c
diff --git a/docs/EXTRACTION_EMAIL_AUDIT.md b/docs/EXTRACTION_EMAIL_AUDIT.md
new file mode 100644
index 00000000..1fb72fc2
--- /dev/null
+++ b/docs/EXTRACTION_EMAIL_AUDIT.md
@@ -0,0 +1,89 @@
+# Email extraction — boundary audit (Phase 4, #31)
+
+**Status:** Audit complete — extraction (#32–#35) is the follow-up.
+**Verdict:** the mail-**server** stack is cleanly extractable. Two shared assets
+must stay core; one core→email boot hook must be guarded. Notifications SMTP is
+already independent and keeps working without the extension.
+
+This is the hard gate the plan requires before moving any code (#32). It maps
+every touchpoint so the move is mechanical.
+
+---
+
+## Cut list — moves into `builtin-extensions/serverkit-email/`
+
+### Backend services (move as a unit — no external importers)
+| File | ~Lines | Notes |
+|---|---|---|
+| `app/api/email.py` | 466 | blueprint `email_bp`; keep `/api/v1/email` prefix (D9) |
+| `app/services/email_service.py` | 546 | orchestrator |
+| `app/services/postfix_service.py` | 429 | MTA |
+| `app/services/dovecot_service.py` | 351 | IMAP/POP |
+| `app/services/dkim_service.py` | 270 | OpenDKIM |
+| `app/services/spamassassin_service.py` | 253 | |
+| `app/services/roundcube_service.py` | 213 | webmail |
+
+Grep confirms **zero non-email backend files import** postfix/dovecot/roundcube/
+spamassassin/dkim/email_service — the server stack is isolated.
+
+### Models that move
+- `EmailDomain`, `EmailAccount`, `EmailAlias`, `EmailForwardingRule`, and the
+ legacy `EmailRelayConfig` from `app/models/email.py`.
+
+### Frontend that moves
+- `pages/Email.jsx` + `styles/pages/_email.scss`; remove its route/title/nav/
+ palette entries (App.jsx `/email` + `ModuleRoute`, sidebarItems `email` item,
+ CommandPalette). Pre-bundle per D5.
+
+---
+
+## STAYS CORE — do not move
+
+| Asset | Why |
+|---|---|
+| `app/models/email_provider.py` (`EmailProviderConnection`) | Owned by **Notifications** (`notifications/providers.py`, `channels/email.py`). Outbound notification SMTP must work without the mail server. |
+| `app/services/email_relay_service.py` | A shim over the notifications provider model, not the MTA. Legacy `EmailRelayConfig` is migrated into `EmailProviderConnection` at boot. Keep with notifications/connections. |
+| `DNSProviderConfig` (currently in `app/models/email.py:138`) | A **general DNS-provider** model that the core DNS stack imports (`dns_provider_service.py`, `dns_zone_service`, `services/dns/cloudflare.py`, `cloudflare_service`). **Pre-req: relocate it to a neutral module** (e.g. `models/dns_provider.py`) *before* moving `models/email.py`, or the DNS stack breaks. |
+| `pages/DeliveryLog.jsx` (`/admin/notifications`) + `components/EmailProviders.jsx` | Notifications delivery log, not the mail server. |
+| `Fail2ban`, firewall, backups, monitoring | grep: no coupling to email services. |
+
+---
+
+## Couplings to invert / guard before the move
+
+1. **Boot migration hook** — `app/__init__.py:487` calls
+ `EmailRelayService.migrate_legacy_config()`. This is the *only* core→email
+ touch. Since `email_relay_service` stays core (it's notifications-side), this
+ is actually fine to keep — confirm it doesn't import the MTA services at import
+ time (it imports `postfix_service` at `email_relay_service.py:23`; **that import
+ must be made lazy/removed** so core boot doesn't pull the MTA stack).
+2. **`DNSProviderConfig` relocation** (above) — the single blocking pre-req.
+3. **`email_service` → DNS** (`api/email.py:6,106` → `DNSProviderService.deploy_email_records`)
+ is email→core (correct direction): becomes an SDK call from the extension. The
+ email-specific method `deploy_email_records` may stay in core DNS or move with
+ the extension and call generic record-creation — decide during #32.
+
+---
+
+## Extraction steps (#32–#35), in order
+
+1. **Pre-req:** relocate `DNSProviderConfig` out of `models/email.py`; make
+ `email_relay_service`'s `postfix_service` import lazy.
+2. **#32 backend move:** create `builtin-extensions/serverkit-email/backend/`;
+ move the 7 services + `email_bp` (keep `url_prefix=/api/v1/email`); migrate the
+ email models via the #24 `models` entry point (or keep as core tables during a
+ two-speed step — the server stack has no external model importers, so either
+ works). Remove `email_service` from any eager import path.
+3. **#33 frontend move:** `Email.jsx` + SCSS → extension `frontend/`, manifest
+ nav/route/title; delete the core entries; pre-bundle.
+4. **#34 upgrade auto-install:** add `serverkit-email` to
+ `extension_migration.CONVERTED_BUILTIN_SLUGS`, but gate on *actual* mail usage
+ — the module toggle (`module_email_enabled`) or presence of postfix state — so
+ only boxes that ran mail get it auto-installed; others see it in the Marketplace.
+5. **#35 prove it:** assert a fresh panel without the extension loads no email
+ blueprint (`/api/v1/docs` route dump has no `/api/v1/email`); install reaches
+ parity (the existing email tests run against the extension); uninstall --purge
+ leaves no `ext_serverkit-email_*` tables.
+
+**Risk:** LOW. Isolated stack; the only real pre-req is the `DNSProviderConfig`
+relocation. Email goes first (before WordPress) precisely because it's this clean.
diff --git a/docs/EXTRACTION_WORDPRESS_AUDIT.md b/docs/EXTRACTION_WORDPRESS_AUDIT.md
new file mode 100644
index 00000000..d7b8042f
--- /dev/null
+++ b/docs/EXTRACTION_WORDPRESS_AUDIT.md
@@ -0,0 +1,90 @@
+# WordPress extraction — boundary audit (Phase 5, #37)
+
+**Status:** Audit complete — extraction (#38) is the follow-up, and is the largest
+single move in the plan. Do it only **after** Email (#32) proves the machinery.
+**Verdict:** extractable, but WordPress has **real core hooks** that must be
+inverted/guarded first. WordPress ships as a bundled, default-installed,
+uninstallable extension (D4) — never a marketplace hunt.
+
+---
+
+## Cut list — moves into `builtin-extensions/serverkit-wordpress/`
+
+### Backend (move together — WP-internal chain is self-contained)
+| File | ~Lines |
+|---|---|
+| `app/api/wordpress.py` | 1634 |
+| `app/api/wordpress_sites.py` | 528 |
+| `app/api/environment_pipeline.py` (registered under the `wordpress` guard) | — |
+| `app/services/wordpress_service.py` | 2676 |
+| `app/services/git_wordpress_service.py` | 651 |
+| `app/services/wordpress_env_service.py` | 530 |
+| `app/services/wordpress_plugin_library_service.py` | 508 |
+| `app/services/wp_analytics_service.py` | 262 |
+| `app/services/wp_reports_service.py` | 363 |
+| `app/services/wp_security_service.py` | 201 |
+| `app/services/wp_update_service.py` | 251 |
+| `app/services/wp_vulnerability_service.py` | 318 |
+
+Blueprints keep their `/api/v1/wordpress*` prefixes (D9).
+
+### Models
+- `WordPressSite`, `WordPressVulnerability`, `WordPressUpdateRun`, `WordPressReport`
+ (`models/wordpress_site.py`), `WordPressCustomPlugin` (`models/wordpress_custom_plugin.py`).
+
+### Frontend
+- Pages `WordPress.jsx`, `WordPressDetail.jsx`, `WordPressProjects.jsx`,
+ `WordPressProject.jsx`, `WordPressPluginLibrary.jsx`; the whole
+ `components/wordpress/` dir; SCSS `_wordpress*.scss`. Remove route/title/nav/
+ palette entries (they're already `ModuleRoute`-guarded, which eases the swap).
+
+---
+
+## STAYS CORE — do not move
+
+| Asset | Why |
+|---|---|
+| **Backup/protection engine** (`backup_policy_service.py`, `models/backup_policy.py`) | Engine stays core; it keeps a WP hook (see below). Only the WP *panels* move. |
+| **Fail2ban jail engine** (`fail2ban_jail_service.py`) | Generic jail management is core. Only the WP-specific bits move (below). |
+| **`DatabaseSnapshot` + `SyncJob`** (currently colocated in `models/wordpress_site.py`) | Generic snapshot/sync models — `db_sync_service.py:941` imports `DatabaseSnapshot`. **Pre-req: relocate to a neutral models module** before the move. |
+| **Event catalog** (`event_service.py:51-59,73-74`) | Core catalog hardcodes `wordpress.*` event types — decouple the catalog entries (extension registers its own event types via SDK). |
+
+---
+
+## Couplings to invert / guard BEFORE extraction (the hard gate)
+
+1. **Eager import** — `app/services/__init__.py:8` eagerly imports `WordPressService`.
+ Must become lazy or removed, or core boot always pulls the WP stack.
+2. **Backup engine WP branch** — `backup_policy_service.py:341,719` +
+ `models/backup_policy.py` reference `target_type == 'wordpress_site'`. Invert to
+ a registered backup-target hook the WP extension provides (keep the engine core).
+3. **Fail2ban WP specifics** — `fail2ban_jail_service.py:53-57` (`FILTER_CONTENT` WP
+ login/xmlrpc regex) + `enable_wp_jail()` (line 185). Refactor the core service to
+ a generic `enable_jail(filter=...)` and let the WP extension supply the filter,
+ OR move `enable_wp_jail` + filter into the extension.
+4. **Lazy cross-imports** (already lazy — becomes SDK calls): `preview_service.py:319,361`,
+ `webhook_service.py:423`, `environment_pipeline_service.py:1471`, `api/apps.py:2103`,
+ `jobs/builtin_handlers.py:176-178`.
+5. **`DatabaseSnapshot`/`SyncJob` relocation** (above).
+6. **Event catalog decoupling** (above).
+7. **`status_page_service.py:141`** references `wordpress_site_id` — a data ref;
+ confirm it degrades gracefully when WP is uninstalled.
+
+---
+
+## Extraction steps (#38), in order
+
+1. Land all pre-reqs (1–7 above) as small, individually-tested core refactors that
+ keep the app working WITH WordPress still core (invert couplings first).
+2. Move backend services + blueprints into the extension (keep prefixes, D9);
+ models via #24 (or two-speed as core tables initially).
+3. Move frontend + manifest; pre-bundle (D5).
+4. Ship it as **bundled + default-installed + uninstallable** (D4): seed-install on
+ every panel (fresh and upgrade), unlike niche verticals.
+5. Prove parity: existing WP test suites run against the extension unchanged; a
+ panel with WordPress uninstalled loads no `wordpress*` blueprint and backups/
+ fail2ban/events still function.
+
+**Risk:** HIGH (largest move; 7 couplings to invert). This is why Email (#32) goes
+first — it validates the model/jobs/socket/purge machinery on an isolated stack
+before WordPress's coupled one.