verdicttank/ops-portal/CONTRACT.md

# VerdictTank Staff Dashboard — Build Contract (2026-08-18)

Pinned contract for the `ops.verdicttank.com` staff dashboard. Three teams build
against this. Do NOT invent fields; every field below exists in the live data or is
explicitly new here.

## Goal

Staff (IT Pro Partner internal) can sign in and view ALL VerdictTank submissions and
their full results. Customers stay on `my.verdicttank.com` (product JWT). Staff use
auth2 (Stack Auth / Hexclave). Owner-email fallback guarantees the two owners can
always sign in.

## Topology (unchanged)

- API: Core, `/opt/verdicttank/api.py`, `127.0.0.1:8201`, systemd `verdicttank-api.service`.
- Submissions: one JSON file per review in `/opt/verdicttank/data/*.json`.
- auth2: app3, `auth2-api.itpropartner.com` (API) / `auth2.itpropartner.com` (dashboard).
- Python: `/root/docker/super-search/venv/bin/python3`. PyJWT imported as `import jwt as pyjwt`.

## auth2 (Stack Auth) constants

- Sign-in: `POST https://auth2-api.itpropartner.com/api/v1/auth/password/sign-in`
  body `{"email": ..., "password": ...}`.
  Headers: `x-hexclave-publishable-client-key: zZhcrUZXs8EqihvXzl7vqvasrRlj7kWn6+eENpX+6Eo=`,
  `x-hexclave-access-type: client`, `x-hexclave-project-id: internal`, `Content-Type: application/json`.
  Success returns `{access_token, refresh_token, user_id}`. `access_token` is OPAQUE (not a JWT).
- Current user: `GET https://auth2-api.itpropartner.com/api/latest/users/me`
  headers `x-hexclave-access-token: <access_token>`, `x-hexclave-access-type: client`,
  `x-hexclave-project-id: internal`. Returns `{id, display_name, primary_email}`.
- Team gate: `GET https://auth2-api.itpropartner.com/api/latest/teams?user_id=me&query=verdicttank-it-staff`
  (same access-token headers). Membership enforced server-side: `items.length > 0` == member.
- Publishable key above is the `internal` project's key (client-visible, not a secret).
- Owner emails (hardcoded fallback, always admitted): `g@germainebrown.com`, `info@itpropartner.com`, `shonuff@germainebrown.com`.
  All three exist as auth2 ProjectUsers (usedForAuth=TRUE): g@ = seed admin, info@ = "IT Pro Partner Info", shonuff@ = "Sho'Nuff".

## New admin endpoints (all prefixed `/api/verdicttank/admin/`)

### POST /api/verdicttank/admin/login
Body `{email, password}`.
1. Call auth2 sign-in (above). 200 -> parse `access_token`. Non-200 -> 401 `{"detail":"Invalid credentials"}`.
2. `users/me` -> `display_name`, `primary_email`.
3. Staff check: `primary_email` (or `email`) in OWNER_EMAILS, OR team gate returns `items.length > 0`.
4. If staff: issue admin JWT (below), return `{token, user:{email, name}}`.
5. If not staff: 403 `{"detail":"Not authorized"}`.

### GET /api/verdicttank/admin/submissions  (admin JWT)
Query: `status` (optional), `q` (optional: case-insensitive match on name/email/proposal_name),
`limit` (default 100, max 500), `offset` (default 0).
Returns `{submissions:[...], total:N}`.
Each item: `review_id, proposal_name, name, email, tier, tier_label, status, verdict,
proposal_strength, investor_readiness, composite, submitted_at, completed_at`.
Use the same pattern as the existing `/reviews` handler: `for path in sorted(DATA_DIR.glob("*.json"), reverse=True)`.

### GET /api/verdicttank/admin/submissions/{review_id}  (admin JWT)
Full detail — every field in `/results/{id}` PLUS the staff-only fields:
`review_id, status, proposal_name, name, email, user_id, tier, tier_label, submitted_at,
completed_at, verdict, verdict_rationale, executive_summary, proposal_strength,
investor_readiness, composite, divergence, dimensions, fatal_flaws, action_plan,
kill_criteria, consensus, panel_audit, report_url, receipt_url, error`.
`report_url` = `/api/verdicttank/report/{id}` (only when status == complete, else null).
`receipt_url` = `/api/receipt/{id}` (only when receipt_path exists).

### GET /api/verdicttank/admin/stats  (admin JWT)
Returns `{total, completed, failed, queued, processing, by_tier:{tier:count,...}, by_status:{...}}`.
Compute from all `*.json` in DATA_DIR.

## Admin JWT (separate from customer JWT)

- Secret: `VERDICTTANK_ADMIN_JWT_SECRET` env, else persist `secrets.token_urlsafe(48)` to
  `/opt/verdicttank/.admin_jwt_secret` (mode 0600). DO NOT reuse the customer `.jwt_secret`.
- Algo HS256, TTL 12 hours.
- Claims: `{sub: email, role: "staff", name: name, exp, iat}`.
- Dependency `require_staff(authorization: str = Header(None))`: decode with the admin
  secret, require `role == "staff"`, else 401. Reuse the existing `import jwt as pyjwt`.

## Submission JSON fields (already in data files)

`review_id, status(queued|processing|complete|failed), proposal_name, name, email, tier,
submitted_at, completed_at, verdict, verdict_rationale, executive_summary,
proposal_strength, investor_readiness, composite, divergence, dimensions(list of
{key,label,score}), fatal_flaws, action_plan, kill_criteria, consensus,
panel_audit(list), report_path, receipt_path, progress, error, user_id(optional)`.

Existing helpers in api.py: `load_submission(review_id)`, `save_submission(review_id, sub)`,
`DATA_DIR`, `TIERS`, `tier_label(tier)`, `current_user(authorization)`.

## Staff frontend (ops.verdicttank.com) — single-file SPA

Served from Core Caddy (see infra). The SPA calls the API SAME-ORIGIN via the
`/api/*` reverse proxy, so base = `""` (relative), e.g. `fetch('/api/verdicttank/admin/login', ...)`.
No CORS, no cross-origin auth2 calls from the browser — all auth2 interaction is
server-side in the API.

- Login screen: email + password -> `POST /api/verdicttank/admin/login` -> store
  `{token, user}` in localStorage. Send `Authorization: Bearer <token>` on all admin calls.
- 401/403 -> show access-denied / re-show login.
- Dashboard: stats bar from `/api/verdicttank/admin/stats`; submissions table from
  `/api/verdicttank/admin/submissions`; search box (`q`), status filter (`status`), pagination.
- Row click -> `/api/verdicttank/admin/submissions/{id}` -> detail view: two 0-100 scores,
  10 dimensions (0-10 bars), verdict + rationale, executive summary, fatal flaws, action plan,
  kill criteria, consensus, panel audit (collapsible), links to report_url and receipt_url.
- Download links: prepend `window.location.origin` to `report_url` / `receipt_url`.

Brand rules (non-negotiable): crimson `#dc2626`, Inter font (Google Fonts ok), dark/light
toggle, NO vendor/model names anywhere, NO em/en dashes (use hyphens), no fabricated
numbers (render real values only), footer "VerdictTank, a product of IT Pro Partner".
Single-file HTML/CSS/JS, vanilla, no frameworks, no CDNs beyond Google Fonts.

## Infra (Core + DNS + auth2)

1. DNS: `ops.verdicttank.com` A record -> `152.53.192.33`.
2. Caddy (Core `/etc/caddy/Caddyfile`) — add block:
   `ops.verdicttank.com { root * /var/www/verdicttank-ops; file_server; handle /api/* { reverse_proxy 127.0.0.1:8201 } header Cache-Control "no-cache" }`
   and in the existing `verdicttank.com` block add `handle /api/receipt/* { reverse_proxy 127.0.0.1:8201 }`
   (fixes the receipt 404 for the customer portal).
3. auth2 team `verdicttank-it-staff` + add `g@germainebrown.com` as member (non-blocking:
   owner fallback already admits the two owners).
4. Write `HEXCLAVE_PUBLISHABLE_KEY=zZhcrUZXs8EqihvXzl7vqvasrRlj7kWn6+eENpX+6Eo=` and
   `HEXCLAVE_PROJECT_ID=internal` to `/etc/verdicttank.env` (API reads via os.getenv).

## Deploy order (conductor enforces)

Backend module -> `py_compile` -> `systemctl restart verdicttank-api` -> Caddy reload ->
DNS propagate -> frontend deployed to `/var/www/verdicttank-ops/index.html` -> e2e test.