fix(ci): align forensic inventory with tracked release docs

Author: victorsteele

.gitignore

@@ -47,7 +47,7 @@ staticfiles/
 *.backup
 build/
 dist/
-release/
+/release/
 artifacts/
 SOURCE_MANIFEST.sha256
 

docs/FORENSIC_FILE_INVENTORY.json

@@ -88,8 +88,8 @@
       "kind": "text",
       "lines": 58,
       "path": ".gitignore",
-      "sha256": "f096ae46d0d84b4d4e6c3b6e98697a3dbe417be71dcd4ca00d2bdd70a29ba75a",
-      "size_bytes": 583
+      "sha256": "23dacac931d01bfabb329b5775c029c09b5937484ebb6928cb6c3363cb661b3e",
+      "size_bytes": 584
     },
     {
       "kind": "text",
@@ -4517,7 +4517,7 @@
     "shell_files": 13,
     "shell_functions": 30,
     "text_files": 347,
-    "total_bytes": 873490,
+    "total_bytes": 873491,
     "total_text_lines": 20775
   }
 }

mailbox-app/docs/release/V1_2_1_DEPLOYMENT_VERIFICATION_REPORT.md

@@ -0,0 +1,39 @@
+# MailStack v1.2.1 Deployment Verification Report
+
+## Baseline matched
+
+The release preserves the verified production contract:
+
+- `app.vibmail.my` and `mail.vibmail.my`
+- MariaDB 10.11-compatible dual-schema design
+- `/opt/vibmail/app`, `/opt/vibmail/venv`, `/var/vmail`, `/var/lib/vibmail/attachments`, and `/var/lib/vibmail/static`
+- `vmail` least-privilege runtime
+- Gunicorn, ingestion, Nginx, Postfix, Dovecot, and MariaDB services
+- Existing certificate paths and receive-only mail flow
+- Live Nginx proxy-header, listener, ACME, redirect, and dotfile hotfixes
+
+## Security-hotfix release assets
+
+- `scripts/audit_dependencies_v1_2_1.sh`
+- `scripts/preflight_v1_2_1.sh`
+- `scripts/upgrade_v1_2_1.sh`
+- `scripts/verify_v1_2_1.sh`
+- `scripts/verify_release_manifest.py`
+
+## Exact dependency contract
+
+- Django 5.2.15
+- Bleach 6.4.0
+- python-dotenv 1.2.2
+
+Preflight validates source pins. Deployment and post-deployment verification validate installed distributions.
+
+## Rollback model
+
+The upgrade captures current source, Nginx, systemd, and logrotate state before cutover. On failure it restores source/configuration/static state and restarts services. Additive database migrations remain forward-compatible to avoid loss of messages received during deployment. The complete backup/restore workflow remains available for coordinated database restoration.
+
+## Status
+
+- Release-side test and deployment-asset validation: PASS
+- Full live VPS installation: NOT YET EXECUTED
+- Final production acceptance requires supervised hash verification, dependency audit, preflight, backup, install, real inbound test, user-isolation test, and log audit.

mailbox-app/docs/release/V1_2_1_FORENSIC_AUDIT_REPORT.md

@@ -0,0 +1,33 @@
+# MailStack v1.2.1 Forensic Audit Report
+
+## Release status
+
+**PASS — security-hotfix release package ready for server-side dependency audit and controlled acceptance**
+
+## Defects found and closed
+
+1. v1.2.0 dependency audit found Bleach 6.3.0 sanitizer vulnerabilities.
+2. v1.2.0 dependency audit found python-dotenv 1.2.1 symlink-handling vulnerability.
+3. Bleach email-linkification advisory scope was previously implicit; v1.2.1 explicitly sets `parse_email=False`.
+4. Dependency audit now validates the exact Linker AST before allowing the narrowly scoped advisory exception.
+5. Preflight previously checked only Django; it now also checks Bleach and python-dotenv pins.
+6. Deployment and post-deployment verification now confirm all three exact installed versions.
+7. Operational scripts, reports, documentation, release identity, manifest, and hashes were rebuilt as v1.2.1.
+
+All v1.2.0 feature-set fixes remain preserved, including authorization, mailbox memberships, IDOR prevention, concurrency locking, live inbox, notification deduplication, auto-read, mark-unread correction, click-to-copy, Nginx hotfixes, rollback hardening, and production-settings enforcement.
+
+## Verification summary
+
+- 187 automated tests: PASS
+- 94.99% application coverage: PASS
+- Ruff: PASS
+- Bandit: PASS
+- Django check: PASS
+- Migration drift: PASS
+- Python compilation: PASS
+- JavaScript syntax: PASS
+- Shell syntax: PASS
+
+## Data-preservation conclusion
+
+The hotfix changes application dependencies, release enforcement, tests, and documentation. Existing mailbox rows, Maildir paths, messages, attachments, Postfix/Dovecot schema, and receive-only flow remain unchanged.

mailbox-app/docs/release/V1_2_1_KNOWN_ISSUES.md

@@ -0,0 +1,22 @@
+# MailStack v1.2.1 Known Issues and Acceptance Limitations
+
+## Known application defects
+
+None identified after the v1.2.1 security-hotfix regression and forensic audit cycle.
+
+## Accepted dependency scope decision
+
+Bleach 6.4.0 is the current security-fix release. `GHSA-g75f-g53v-794x` concerns email linkification only when `parse_email=True`. MailStack explicitly sets `parse_email=False`; the online audit script verifies that invariant through AST inspection before applying the scoped exception.
+
+## Live acceptance still required
+
+These are deployment gates, not known application defects:
+
+1. Run the online dependency audit on the VPS.
+2. Verify the v1.2.1 manifest and ZIP hash after upload.
+3. Execute read-only preflight.
+4. Create and verify the complete production backup.
+5. Perform the supervised upgrade and post-deployment verification.
+6. Repeat real inbound-email, live notification, copy, user-isolation, auto-read, delete-permission, and rollback-readiness tests.
+
+Final live status remains pending until every item in `V1_2_1_ACCEPTANCE_CHECKLIST.md` passes.

mailbox-app/docs/release/V1_2_1_PERFORMANCE_AUDIT_REPORT.md

@@ -0,0 +1,25 @@
+# MailStack v1.2.1 Performance Audit Report
+
+## Result
+
+**PASS for the release architecture and local acceptance workload**
+
+## Verified design
+
+- Existing Gunicorn threaded worker model preserved
+- Mail ingestion remains independent of browser activity
+- Polling defaults to approximately five seconds and reduces while the tab is hidden
+- Overlapping live requests are prevented
+- Live requests have a 12-second abort timeout and exponential backoff up to 60 seconds
+- New-message responses and mailbox-counter responses are bounded
+- Visible mailbox UUIDs are supplied so paginated rows beyond the global counter limit still update
+- Message bodies and attachments are excluded from live payloads
+- Dashboard, inbox, mailbox list, and user list use bounded pagination
+- Authorization querysets use related-object selection and indexed membership lookups
+- Query-count tests remain bounded with increasing mailbox/user fixture counts
+- Counter updates use transactions and row locks
+- Browser acceptance showed no UI overflow or runtime error
+
+## Production observation required
+
+After installation, observe Gunicorn response times, MariaDB slow-query logging, ingestion cycle duration, and process memory under the real mailbox volume before increasing polling frequency or worker counts.

mailbox-app/docs/release/V1_2_1_SECURITY_AUDIT_REPORT.md

@@ -0,0 +1,49 @@
+# MailStack v1.2.1 Security Audit Report
+
+## Result
+
+**Static/application security review: PASS**  
+**Live production security acceptance: pending controlled installation**
+
+## Dependency remediation
+
+- Rejected release v1.2.0 pinned vulnerable Bleach 6.3.0 and python-dotenv 1.2.1.
+- v1.2.1 pins Bleach 6.4.0 and python-dotenv 1.2.2.
+- Bleach email linkification is explicitly disabled with `parse_email=False`.
+- `scripts/audit_dependencies_v1_2_1.sh` uses an AST check to guarantee exactly one `Linker` call and a literal `parse_email=False` before applying the narrow `GHSA-g75f-g53v-794x` exception.
+- Any additional Linker call or any change enabling email parsing fails the audit.
+- Deployment and post-deployment verification require exact Django, Bleach, and python-dotenv versions.
+
+## Application controls verified
+
+- Central object-level authorization for mailbox, message, safe HTML, attachment, dashboard, and live-update access
+- Administrator-only user management
+- Ordinary-user mailbox isolation
+- Separate message-delete and mailbox-delete permissions
+- CSRF-protected POST destructive actions with confirmation
+- Soft deletion preserves Maildir evidence and blocks re-ingestion/reuse
+- No user password-change or public password-reset route
+- Case-insensitive username and mailbox uniqueness
+- Inter-process mailbox provisioning lock
+- Parameterized cross-schema SQL
+- Confined paths and symlink rejection
+- Sanitized HTML in a sandboxed iframe
+- Authorized attachment delivery as `application/octet-stream`
+- Authenticated, scoped, bounded, body-free live-update payloads
+- Safe DOM insertion using `textContent`
+- Nginx duplicate Host-header defect remains closed
+- ACME, dotfile denial, TLS, protected attachments, and security headers preserved
+- Release source cannot be the live application tree
+
+## Tool results
+
+- 187 automated tests: PASS
+- Ruff: PASS
+- Bandit: PASS
+- Django checks: PASS
+- Migration drift: PASS
+- Local online vulnerability query: unavailable because the build container cannot resolve public PyPI
+
+## Mandatory server gate
+
+Run `scripts/audit_dependencies_v1_2_1.sh` on the network-enabled VPS. Installation is prohibited unless it reports `Online dependency vulnerability audit: PASS`.

mailbox-app/docs/release/V1_2_1_TEST_REPORT.md

@@ -0,0 +1,28 @@
+# MailStack v1.2.1 Test Report
+
+## Result
+
+**Security-hotfix release verification: PASS**
+
+- Automated tests: **187 passed**
+- Application coverage: **94.99%**
+- Exact local audit runtime: Python 3.13, Django 5.2.15, Bleach 6.4.0, python-dotenv 1.2.2
+- Django system check: PASS
+- Migration drift: PASS (`No changes detected`)
+- Python compilation: PASS
+- Ruff: PASS
+- Bandit: PASS
+- JavaScript syntax (`node --check`): PASS
+- Shell syntax for all release scripts: PASS
+
+## Added security-hotfix regression coverage
+
+- Ordinary URLs remain linkified after sanitization.
+- Email addresses are not converted into `mailto:` links.
+- The only Bleach `Linker` call explicitly sets `parse_email=False`.
+- Dependency lock files require Bleach 6.4.0 and python-dotenv 1.2.2.
+- Preflight, deployment, and post-deployment scripts enforce exact security-sensitive versions.
+
+## Production acceptance
+
+The production host uses Python 3.12. The package retains the strict `>=3.12,<3.13` runtime contract. Final acceptance requires the online dependency audit and the controlled VPS preflight before installation.