POST /api/auth/bulk-users/resolve reads a list of usernames (first
column; comma, semicolon or tab; header skipped) and answers line by
line, the CR-005 validate-and-report pattern. A line is rejected, with
its number and reason, when it names nobody the caller can see ('User
not found', as everywhere else), an account they may not change (the
single route's own reason), their own account, or a username already
listed (duplicate of line N). An email address resolves only when
exactly one account has it. Nothing is changed by this route.
The console's 'Select from CSV' turns the accepted accounts into the
ordinary selection (filter reset so every selected row is visible) and
lists every rejected line. The action, confirm and per-row report are
the checkbox ones, through the same T12.1 routes, which re-check each
row: a CSV cannot reach an account a checkbox could not.
Usernames only, action in the toolbar (decided 2026-10-06). Files over
1 MB are refused before upload; FileReader fallback for browsers
without Blob.text().
bulk_users_check.py: 61/61. DOM harness: 40/40.
Work Package Suite API
A small Python (FastAPI) service that stores project SOPs, Work Packages,
and comments in PostgreSQL. NGINX serves the static site and proxies /api/
to this service.
browser → NGINX ──serves──> static site (index.html, …)
└─proxy /api/─> api container (:8000) → db container (postgres)
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health |
liveness check (unauthenticated) |
| GET | /api/auth/okta/login |
redirects the browser to Okta's authorize endpoint (?next= optional) |
| GET | /api/auth/okta/callback |
Okta redirects back here with the auth code; signs the person in |
| POST | /api/auth/logout |
clear the session cookie |
| GET | /api/auth/me |
the logged-in user |
| GET | /api/auth/users |
list accounts (admin) |
| POST | /api/auth/users |
pre-create an account by username (admin) |
| DELETE | /api/auth/users/{id} |
delete an account (admin) |
| POST | /api/sops |
create/update a SOP (upsert by id) |
| GET | /api/sops |
list SOP summaries |
| GET | /api/sops/latest?complete=true |
most recent (complete) SOP |
| GET | /api/sops/{id} |
full SOP document |
| DELETE | /api/sops/{id} |
delete a SOP |
| POST | /api/wps |
create/update a Work Package (upsert by id) |
| GET | /api/wps?sop_id=… |
list WPs (optionally for one SOP) |
| GET | /api/wps/{id} |
full WP document |
| DELETE | /api/wps/{id} |
delete a WP |
| POST | /api/comments (and /api/feedback) |
add a comment |
| GET | /api/comments?source=&sop_id=&wp_id=&step= |
list comments |
Interactive docs once running: /api/docs.
The full client document is stored in each row's data (JSON) column; common
fields (name, number, status, …) are promoted to columns for listing/filtering.
Sign-in (Okta)
There is no local password anywhere in this app (D15/D16) — Okta OIDC is the
only way in. login.html is a single "Sign in with Okta" button; the actual
exchange is server/okta_auth.py (the Okta client config) and the two routes
in server/app.py: okta_login() sends the browser to Okta's authorize
endpoint, okta_callback() exchanges the code, matches the ID token's identity
claim against users.username, and signs the person in.
Sign-in still ends the same way it always did: a signed JWT in an HttpOnly,
SameSite=Lax cookie (wp_session), marked Secure automatically whenever
the request arrives over HTTPS (via NGINX's X-Forwarded-Proto). There is no
server-side session store — each request is validated by checking the cookie's
signature and expiry. Okta only confirms who someone is; this app still
decides what they may do — roles, project membership, everything below stays
local and unchanged by Okta.
The real security boundary is the API: every /api/ data route is refused
with 401 unless a valid session cookie is present (see auth_gate in
app.py). The static pages additionally include auth-guard.js, which redirects
to login.html when there's no session — that's for UX, not protection.
Access gating is Okta's job, not this app's. Only accounts assigned to the app integration in Okta can complete the sign-in flow at all, so there is no required-group or claim check layered on top here. Once Okta lets someone through, this app decides their role — see below.
Roles are admin, project_super_user, project_admin, project_user
(html/users.js, enforced server-side).
Set the signing secret and the Okta app integration
Add AUTH_SECRET_KEY and the five OKTA_* variables to .env — see
.env.example for what each one is and where it comes from. AUTH_SECRET_KEY
is required in production: without it the API uses a random per-process
key, so logins reset on restart. The OKTA_* variables are not a hard-fail the
same way — the API starts without them, it just refuses every sign-in and says
so in the startup log (okta_auth.describe()).
python -c "import secrets; print(secrets.token_urlsafe(48))"
The Okta app integration itself (sign-in method OIDC, Application type Web
Application) needs its Sign-in redirect URI set to exactly
OKTA_REDIRECT_URI's value, and the people who should have access assigned to
it — that assignment IS the access control (see above).
Create the first admin
There's no create-admin command anymore — creating an account from scratch
by hand-typed username risks a second, orphaned row if it doesn't exactly match
what Okta actually sends (see OKTA_IDENTITY_CLAIM in .env.example). Instead,
have the first admin sign in through Okta once — they land as an ordinary
project_user, JIT-provisioned — then promote that existing row from a shell
(run from the project root, like uvicorn):
python -m server.manage_users promote alice --role admin
In Docker:
docker compose exec api python -m server.manage_users promote alice --role admin
Other commands: list, disable <user>, enable <user>. After the first
admin exists, they can promote others through the User Directory page (or keep
using the CLI) — no shell access needed for anyone after the first.
No break-glass path. If Okta is unreachable or misconfigured, the app is unreachable for everyone, including admins, until Okta is restored (D16) — this is a deliberate choice, the same one the abandoned LDAPS design made, not an oversight.
Local dev
cd server
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# No DATABASE_URL → uses a local sqlite file, so you can start immediately:
uvicorn server.app:app --reload --port 8000 # run from the PROJECT ROOT
Then open http://localhost:8000/api/docs.
Run uvicorn/gunicorn from the project root (the folder that contains the
server/directory), because the import path isserver.app:app.
Production — Docker Compose
This is the recommended production setup. Three containers run in an isolated
internal network; only NGINX is exposed to the outside via the external proxy
network.
[external proxy network]
│
┌────▼────┐ internal network ┌──────────┐ ┌────────┐
│ nginx │ ───────────────────> │ api │ → │ db │
└─────────┘ └──────────┘ └────────┘
1. Create the credentials file
Create .env in the project root (same directory as docker-compose.yml).
This file is never committed — add it to .gitignore.
# .env — project root
POSTGRES_DB=wpsuite
POSTGRES_USER=wpsuite
POSTGRES_PASSWORD=<strong-random-password>
# Must match POSTGRES_* above; hostname is the compose service name "db"
DATABASE_URL=postgresql+psycopg://wpsuite:<strong-random-password>@db:5432/wpsuite
Generate a strong password:
openssl rand -base64 32
2. Add the Dockerfile
Create Dockerfile in the project root:
FROM python:3.12-slim
WORKDIR /app
COPY server/requirements.txt ./server/
RUN pip install --no-cache-dir -r server/requirements.txt
COPY server/ ./server/
EXPOSE 8000
CMD ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", \
"-b", "0.0.0.0:8000", "--workers", "2", "server.app:app"]
3. Update the NGINX site config
The API is no longer at 127.0.0.1:8000 — it is the api container.
Update the /api/ proxy block in your nginx conf (e.g. nginx/conf.d/wp-suite.conf):
location /api/ {
proxy_pass http://api:8000; # ← service name, not localhost
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 5m;
}
4. docker-compose.yml
Replace your existing docker-compose.yml with:
services:
webserver:
image: nginx:alpine
container_name: nginx_webserver
volumes:
- ./html:/usr/share/nginx/html:ro
- ./nginx/conf.d:/etc/nginx/conf.d:ro
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./logs:/var/log/nginx
restart: unless-stopped
depends_on:
api:
condition: service_started
networks:
- proxy # external — reachable by your reverse proxy / traefik
- internal # needs a path to the api container
api:
build: .
container_name: wp_api
env_file: .env # loads DATABASE_URL
restart: unless-stopped
depends_on:
db:
condition: service_healthy # waits for postgres to accept connections
networks:
- internal
db:
image: postgres:16-alpine
container_name: wp_db
env_file: .env # loads POSTGRES_DB / USER / PASSWORD
volumes:
- pgdata:/var/lib/postgresql/data
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
networks:
- internal
volumes:
pgdata:
networks:
proxy:
name: proxy
external: true
internal:
internal: true # no outbound internet access from api/db
5. First-time startup
# Build the api image and start all containers
docker compose up -d --build
# Confirm all three containers are running
docker compose ps
# Tail logs (Ctrl-C to stop following)
docker compose logs -f api
Tables are created automatically on first API startup — no manual CREATE TABLE
needed.
Authentication notes
Postgres → API authentication is handled entirely through DATABASE_URL in
.env. The db container uses POSTGRES_USER / POSTGRES_PASSWORD to
initialise the database on first run; the api container uses the matching
credentials in DATABASE_URL to connect. Neither credential ever appears in the
compose file itself.
Network isolation: the db container is on the internal network only —
it has no port exposed to the host and is unreachable from outside the compose
stack. Only the api container can open a connection to it.
Changing the password: update both POSTGRES_PASSWORD and the password
in DATABASE_URL in .env, then:
# Stop api first (db must keep running to accept the ALTER USER command)
docker compose stop api
docker compose exec db psql -U wpsuite -c "ALTER USER wpsuite PASSWORD 'new-password';"
docker compose start api
Day-to-day operations
# Rebuild api after a code change
docker compose up -d --build api
# View postgres data directly
docker compose exec db psql -U wpsuite -d wpsuite
# Take a database backup
docker compose exec db pg_dump -U wpsuite wpsuite > backup-$(date +%F).sql
# Restore from backup
docker compose exec -T db psql -U wpsuite -d wpsuite < backup-2025-01-01.sql
# Stop everything (data volume is preserved)
docker compose down
# Stop everything AND delete all data
docker compose down -v
Quick test
/api/health is open; every other /api/ route needs a session cookie:
curl http://127.0.0.1:8000/api/health # {"ok":true} — no auth needed
Without a session cookie, protected routes return 401 {"detail":"Not authenticated"}.
Or via the nginx proxy (replace with your hostname):
curl https://wp-suite.company.local/api/health
There's no curl-able login anymore — Okta requires a real browser to
complete, which is what login.html's "Sign in with Okta" button is for. To
exercise a protected route from a script instead, use server/smoketest.py's
own technique (mint a session with auth.create_token() and set it as the
wp_session cookie, the same thing okta_callback() does after Okta hands
back an identity) rather than reaching for curl by hand — see that script's
own AUTHENTICATION section for the exact steps, and why it has to run
somewhere that shares the target server's AUTH_SECRET_KEY and database.