Phoenix Protocol

Phoenix Protocol is a Windows-first secure file sharing system built for enterprise-style document control. It encrypts files locally, stores only encrypted payloads on the backend, opens content from the Phoenix Inbox, renders plaintext in memory, and enforces policy such as PIN, expiry, geofence, network restrictions, revocation, watermarking, and controlled export.

The project is designed around a governed workflow:

• secure send inside Phoenix
• app-only viewing by default
• remote revocation and continuous session checks
• optional download approval before export
• auditability and attribution for viewer and export activity

Core Model

Phoenix is not a generic file transfer tool. It is a policy-enforced secure access system.

High-level flow:

1. Sender selects a file in Phoenix.
2. Phoenix encrypts it locally with hybrid cryptography.
3. Phoenix uploads the encrypted wrapper to the backend.
4. The sender-side temporary wrapper is destroyed after upload.
5. The receiver opens the item from Phoenix Inbox.
6. The client requests a short-lived open session from the backend.
7. The encrypted payload is fetched and decrypted in memory only.
8. The secure viewer renders the plaintext with watermarking and capture shielding on supported Windows builds.

Security Features

• Hybrid encryption using AES-256-GCM, RSA-4096, and HKDF
• PIN-gated decryption
• Time-to-live expiry
• Optional geofence restrictions
• Optional network/CIDR restrictions
• Remote attestation and revocation checks
• HomeBeacon continuous server reachability / revocation monitoring
• RAM-only viewer path for Inbox opens
• Windows WDA_EXCLUDEFROMCAPTURE integration on supported builds
• Viewer watermark with user identity, timestamp, and session token
• Controlled export with approval workflow
• Audit logging for security-relevant actions

Download Approval Workflow

Phoenix supports three export policies during send:

• View only
• Download with approval
• Download allowed

When Download with approval is selected:

1. The receiver requests export from Inbox.
2. Phoenix records the business justification.
3. The sender reviews the request in the Approvals tab.
4. If approved, the backend issues a short-lived export grant.
5. The receiver must still enter the PIN.
6. Phoenix decrypts in memory and writes a controlled exported copy only after approval.
7. Phoenix writes an adjacent export audit manifest for traceability.

This workflow governs exports inside Phoenix. It does not claim to solve every possible out-of-band organisational bypass by itself.

Repository Layout

phoenix_desktop1/
├── backend/
│   ├── local_backend.py
│   └── test_backend.py
├── config/
│   └── phoenix_config.json
├── docs/
│   └── TESTING_CHECKLIST.md
├── phoenix/
│   ├── app.py
│   ├── audit_logger.py
│   ├── crypto_engine.py
│   ├── hw_security.py
│   ├── os_integrator.py
│   └── self_destruct.py
├── build.bat
├── main.py
├── requirements.txt
├── test_backend.py
└── README.md

Main Components

Desktop Client

• phoenix/app.py Main UI, secure viewer, Inbox/Sent/Approvals flows, and audit wiring.

• phoenix/crypto_engine.py Encryption, decryption, policy parsing, and in-memory payload handling.

• phoenix/os_integrator.py Windows integration including capture protection, secure key storage helpers, geolocation, and network detection.

• phoenix/self_destruct.py Secure destruction helpers for protected wrappers.

Backend

• backend/test_backend.py Lightweight development backend for localhost and hosted demo testing.

• backend/server_backend.py Persistent hosted backend for Render or other server deployment.

It currently provides:

• registration and login
• organisation-scoped user listing
• public key upload
• encrypted payload registration
• Inbox and Sent metadata
• open-session grants
• encrypted payload retrieval
• export approval requests
• export grants and controlled export download
• revocation checks
• audit ingestion

Requirements

• Windows for the full desktop security experience
• Python 3.12+ recommended
• Reachable backend URL

Dependencies are listed in requirements.txt.

Local Development Setup

1. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Configure backend URL

Edit config/phoenix_config.json.

For localhost:

{
  "mode": "server",
  "server_backend_url": "http://localhost:5050"
}

For hosted backend:

{
  "mode": "server",
  "server_backend_url": "https://your-render-service.onrender.com"
}

3. Run backend

For localhost testing only:

python3 test_backend.py

For the persistent hosted/server backend:

python3 run_backend.py

4. Run desktop app

python3 main.py

Default Test Accounts

The test backend ships with:

• analyst@corp.com / analyst123
• reviewer@corp.com / reviewer123

Recommended Testing Plan

Phase 1: Localhost

Use the local backend but keep Phoenix in server mode.

• backend URL: http://localhost:5050
• test login, key generation, send, Inbox open, revoke, expiry
• test download approval flow end to end

Phase 2: Hosted Backend

Deploy the same backend to Render and switch the URL.

• backend URL: your hosted Render URL
• repeat send/open/revoke/export tests
• validate real HTTPS server behavior

Phase 3: Packaged App

Package the client and test with other users.

• build Phoenix.exe
• distribute to test users
• register same-domain users
• validate multi-device workflow

Packaging

The Windows build script is build.bat.

Packaging assets:

• Phoenix.spec
• installer.nsi

Build on Windows:

.\build.bat

Typical output:

• dist/Phoenix.exe
• Phoenix-Setup.exe when NSIS is installed

For release steps and distribution guidance, use docs/RELEASE_CHECKLIST.md.

GitHub Preparation

Before pushing to GitHub:

1. Keep .gitignore in place.
2. Do not commit generated RSA keys.
3. Do not commit backend payload storage.
4. Do not commit audit logs or local test data.
5. Do not commit local backend URLs that you do not want published.

Recommended first-pass repo workflow:

git init
git add .
git status
git commit -m "Initial Phoenix Protocol commit"

Check git status before committing. Make sure local secrets and generated files are not staged.

Render Hosting Notes

For Render deployment of the backend:

• deploy the backend service, not the desktop client
• use the persistent hosted backend, not test_backend.py
• use render.yaml or equivalent settings
• point server_backend_url to the Render HTTPS URL after deploy

Recommended start command:

gunicorn run_backend:app

If you later split the development backend from a production backend, keep the same API contract used by the client.

Files That Must Not Be Committed

These are local/runtime artifacts and should stay out of Git:

• private keys such as phoenix_private.pem
• public/private keypairs generated during local testing
• __pycache__/
• venv/ or .venv/
• local backend payloads under data/backend_payloads/
• audit logs such as .phoenix_audit.jsonl
• build outputs such as build/, dist/, and generated .exe

Security Boundary

Phoenix is designed to reduce persistence, tighten access control, and improve attribution. It does not claim that any desktop application can make visible plaintext physically impossible to recapture once a user is allowed to see it.

What Phoenix does well:

• governs secure access inside the application
• avoids ordinary user-managed Inbox downloads by default
• traces viewer and export activity
• supports revocation and policy-bound access

What still requires enterprise governance outside the app:

• DLP / MDM
• approved sharing channels
• device management
• organisational policy enforcement