# Upwork Project Control

Private, single-owner dashboard for Python applications managed in this project tree. The home page discovers only direct child folders with a safe `project.json`; it never scans arbitrary scripts or offers command/path entry fields. PostgreSQL stores the owner account, server-side sessions, login throttling, and desired project state. Vendor Lookup is the first managed application and remains independently runnable on a laptop.

## Local development

Python 3.11+ (tested on Python 3.14) and PostgreSQL 15+ are required. There is no SQLite fallback.

1. Create a local virtual environment and install `requirements.txt`.
2. Set a private PostgreSQL `DATABASE_URL` and a random `APP_SECRET` of at least 32 characters in the process environment.
3. Run `python -m dashboard.admin bootstrap` with `UPWORK_ADMIN_PASSWORD` supplied securely in the deployment environment. The bootstrap command never prints the password. Use at least 14 characters including letters and digits.
4. Run `python -m dashboard.app`; the first login requires changing that password. The development server listens on port 8790. Use HTTPS when testing secure cookies.

For the complete isolated database and browser acceptance run `./verify.sh`. It reads the operator-provided `test-db.env` locally; that file is excluded from Git, build context, and ZIP exports. It never prints credentials and uses only demo lookup mode.

## Add an approved Python project

Create a direct child folder with a regular, non-symlink `project.json`, README, and Python launch file. A typical manifest is:

```json
{
  "id": "sampletool",
  "name": "Sample Tool",
  "description": "A concise description for the project card.",
  "category": "OPERATIONS",
  "runtime": "PYTHON 3.11+",
  "launch_file": "app.py",
  "args": ["--port", "8771"],
  "port": 8771,
  "proxy_path": "/apps/sampletool",
  "runtime_allowlist": ["app.py", "static/index.html", "static/app.js", "static/style.css"],
  "export_allowlist": ["app.py", "static/index.html", "README.md"]
}
```

The ID must match the folder name. The launch file and every export must remain inside that folder; symlinks, path traversal, duplicate ports, private files, database dumps, caches, keys, and `.env` files are rejected. Use only application launch arguments that are fixed and reviewed in the manifest. The server constructs `[sys.executable, launch_file, *args]` without a shell. The app should bind only to `127.0.0.1` on its declared unique port.

`proxy_path` is optional. If present, it must equal `/apps/<id>` and all browser reads and writes travel through the dashboard's fixed loopback proxy after owner authentication. Proxied HTML forms/browser code must send `X-Dashboard-CSRF` from a `<meta name="dashboard-csrf">` value on mutations and retain the app's own app-specific CSRF token. The dashboard validates the public `Origin`, checks this session-bound token, then strips the external Origin and supplies an exact loopback Host to the project. The public UI cannot select another host, port, project ID, command, or path.

`runtime_allowlist` names every exact source/static file needed to run the app and is required to include the launch file. The installer copies only those files, the manifest, and the separately reviewed export files into an immutable staging directory. This curated stage is mounted read-only into the dashboard as UID 10001; original project file permissions are not broadened. `export_allowlist` is a reviewed list of exact relative regular files, not glob patterns. Only these files are included in the authenticated project ZIP. Keep app credentials outside source; never add secrets to either allowlist. The root installer never mounts `archive/`, `admin/`, private deployment files, or a Docker socket.

## Vendor Lookup

`vendorlookup/` remains a standard-library-only portable Python app with demo mode, CSV/XLSX exports, and its original tests. For desktop use, run `python app.py` or the Windows launcher. Its default local port is 8766. The dashboard starts the same `app.py` under its manifest, then authenticates every proxied page/API/export request. App/API credentials stay server-side in the private dashboard environment and are never in client ZIPs. The safe ZIP contains only the reviewed allowlist, including the credential-free `.env.example`; it omits `.env`, caches, local databases, deployment secrets, and archives.

Vendor Lookup's `fixit.md` contains a separately queued credential-entry UI request. That change is intentionally not part of this build.

## Deployment handoff (operator only)

After development acceptance, the root/operator may run `python3 deploy/deploy.py`. It idempotently creates mode-0700/0600 deployment files, generates the initial owner password, builds the dashboard image, starts the dashboard and dedicated PostgreSQL 18 Compose services, bootstraps the one owner, and performs a local health check. Retrieve `deploy/private/initial-admin-password` once through the root-only operational channel, then change it in the browser. Do not paste it into chat, logs, tests, or source. Optional Vendor Lookup API keys belong only in `deploy/private/vendorlookup.env`.

The dashboard container runs as UID/GID 10001, has no Docker socket, has a read-only root filesystem and read-only project mounts, and publishes HTTP only at `127.0.0.1:8790`. Gunicorn intentionally uses one worker (with 16 request threads) because that worker owns the allowlisted child-process registry; its `worker_exit` hook stops child process groups before graceful exit. PostgreSQL is not host-published and uses a dedicated persistent named volume. Both services restart unless stopped. The installer does not edit Apache. `deploy/apache-upwork.conf` is a selective replacement for only the existing HTTP/HTTPS `upwork.robspace.me` vhosts; the operator must back up and replace only those two vhosts, preserve all unrelated sites and archive data, then validate Apache before reloading it. HTTP redirects to HTTPS using the existing certificate. No screener stack or volume is used.

Never run `docker compose down -v` for this deployment. To preserve boot restoration, desired-running project state is stored in PostgreSQL. Dashboard restart starts those allowlisted projects again. Daily project use (Start/Stop/Open/Download) is browser-only; terminal access is reserved for first deployment and exceptional administration.

## Verification

`./verify.sh` runs the original Vendor Lookup suite plus end-to-end tests against the operator-provisioned isolated PostgreSQL database. It verifies login/password rotation, session persistence across app recreation, authorization, Origin/CSRF, dynamic second-project discovery/lifecycle/proxy/export, manifest traversal and symlink rejection, Vendor Lookup start/overlap/stop and boot restore, authenticated demo progress/cancel and spreadsheet downloads, allowlisted ZIP contents, and a real Chromium mobile/login/open/demo flow when the supplied browser is available. No paid API is contacted. Tests reset only the dedicated `upwork_projects_test` database owner/project test records.

Runner and Windows installer contract
------------------------------------

The dashboard exposes a dedicated runner API (deployment-only secret) to support an authorized Windows build runner. The server enforces a strict state machine and artifact contract: final uploads are accepted only during UPLOADING and must include exactly the configured installer .exe plus build-evidence.json and acceptance-evidence.json. Filenames, SHA256, sizes and job/project/staging identity are validated. Runner credentials are compared in constant time and the server fails closed when the secret is not configured.
# App Manager — server-only enrollment and Linux packages

App Manager retains this project's existing URL, authentication, reviewed runtimes and client downloads. Add Project offers Create New and Attach Existing on the **Linux development server**, not on a laptop. Arbitrary directories enroll as persistent inspection-only cards; attachment never executes or overwrites source. Runtime commands are optional metadata until a reviewed manifest is explicitly provisioned. Detach preserves source/artifacts; reattach preserves identity.

The approved-root browser uses an operator-provisioned narrow Unix-socket broker, not broad host mounts. Linux packaging uses the tested LinuxInstaller CLI through a separately supervised host worker, with isolated PostgreSQL jobs and disposable package launch acceptance. AppImage is the client default; native deb/rpm are explicit server options. Source-only Python/Node is rejected without a bundled runtime. Only verified final packages can become immutable public client-download links.

Run acceptance: `bash ./verify.sh && .venv/bin/python -m unittest dashboard.tests.test_app_manager -v`. See `APP_MANAGER_RESULT.md` for exact operator deployment, restrictions, test evidence and live verification requirements. Production promotion remains coordinator-owned.
