Compare commits
24 Commits
feat/t14-1
...
feat/ldaps
| Author | SHA1 | Date | |
|---|---|---|---|
| c99666796a | |||
| 60b5b0c1f2 | |||
| c6a100405d | |||
| 25bc5bcd3f | |||
| b97ccd7ad8 | |||
| 3f4cd7ac92 | |||
| 332b74e5de | |||
| eecd724e02 | |||
| 24fff382c8 | |||
| d261024139 | |||
| 79787b3e9f | |||
| e0008670fc | |||
| c47b2ae210 | |||
| dc0cee240e | |||
| 8d49fb9248 | |||
| 495d87dd72 | |||
| c5540ce6da | |||
| 9f91e9e26b | |||
| ab7bce9f5b | |||
| 8cfb4c1008 | |||
| 0de746bc62 | |||
| 2a3c4a83fa | |||
| 0577660c86 | |||
| 3c9343dfc8 |
@@ -1,10 +0,0 @@
|
||||
# Copy to .env in the repository root for a local Docker run (T13.8).
|
||||
# .env is ignored by git. Use values that are not used anywhere else.
|
||||
POSTGRES_USER=wpsuite
|
||||
POSTGRES_PASSWORD=local-only-change-me
|
||||
POSTGRES_DB=wpsuite
|
||||
# Generate: python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||||
AUTH_SECRET_KEY=local-only-change-me-to-a-long-random-string
|
||||
# Rehearse the Okta sync first. Add OKTA_API_TOKEN and OKTA_ORG_URL only when you
|
||||
# want the local stack to call the real Okta, and keep this on until you read the log.
|
||||
OKTA_SYNC_DRY_RUN=true
|
||||
29
CLAUDE.md
@@ -70,6 +70,31 @@ Adding a raw hex value to a page stylesheet is a defect regardless of what the t
|
||||
for. Four parallel token systems is what produced S5, and the `.field-hint` comment at
|
||||
`work-package-suite-styles.css:336` is the bug that resulted. Do not recreate it.
|
||||
|
||||
## The authentication rules
|
||||
|
||||
Sign-in is an LDAPS bind against the domain (`D13`, `docs/waves/decisions-2026-08-21.md`).
|
||||
Four things about it are load-bearing and look like tidying-up if you do not know why:
|
||||
|
||||
- **The empty-password guard in `ldap_auth.verify` runs before `bind()`.** An LDAP
|
||||
simple bind with an empty password is an *anonymous* bind and it SUCCEEDS. Remove
|
||||
that check and a blank password authenticates as any username submitted. It looks
|
||||
redundant because `login()` checks too. Both stay.
|
||||
- **`validate=ssl.CERT_REQUIRED` with an explicit CA file.** Never `CERT_NONE`, never
|
||||
the system trust store (which trusts five other self-signed CAs on this estate).
|
||||
`CERT_NONE` still encrypts, so it fails silently - what it loses is the ability to
|
||||
tell a real DC from someone harvesting domain passwords.
|
||||
- **`AUTH_MAX_ATTEMPTS` is 2, and that is arithmetic, not taste.** Failures are real
|
||||
domain binds counting against the AD lockout policy (5 here), and 2 workers double
|
||||
it: 2 x 2 = 4 < 5. Raising it, or adding a worker, makes `/api/auth/login` a way to
|
||||
lock colleagues out of Windows.
|
||||
- **Connect to `prime.local`, never a DC name or an IP.** Every DC certificate carries
|
||||
the domain name in its SAN; an IP fails hostname validation, and the only way to
|
||||
force it is to disable the check above.
|
||||
|
||||
There is **no break-glass account** - a misconfiguration locks out everyone including
|
||||
admins. And roles are LOCAL: the directory supplies identity, this app supplies
|
||||
authorization. Never read a role from AD.
|
||||
|
||||
## Accessibility is in scope
|
||||
|
||||
Approved Aug 14, 2026 (C1). Any component you rebuild ships accessible or it is not done:
|
||||
@@ -90,10 +115,12 @@ A task is not done because the code is written. Every task file lists its own do
|
||||
checks. In addition, for any task touching the frontend:
|
||||
|
||||
1. Run the app locally: `uvicorn server.app:app` against a throwaway SQLite database.
|
||||
Signing in needs a domain credential now (D13) — a local run reaches `prime.local`
|
||||
from the host with no extra configuration. A container needs the `outbound` network.
|
||||
2. Exercise the affected flow at **390px** and at **1440px**. Field View at 390px is the
|
||||
gloved-hands surface and is where the worst rendering was found.
|
||||
3. Capture before and after screenshots into the PR.
|
||||
4. Run the existing smoke test. It signs in, and so does `server/seed_demo.py` (S13, fixed at T1.6 - this line said otherwise until Aug 20 2026, a stale record).
|
||||
4. Run the existing smoke test. It signs in, and so does `server/seed_demo.py` (S13, fixed at T1.6 - this line said otherwise until Aug 20 2026, a stale record). Since D13 both need a **domain** credential, and `WP_SMOKE_PASSWORD` is now a real Windows password - never put one on a command line.
|
||||
|
||||
If a done-when check cannot be verified, do not mark the task complete. Say which check
|
||||
failed and why.
|
||||
|
||||
@@ -1,103 +1,154 @@
|
||||
# Deploy: Work Package Suite — login portal update
|
||||
# Deploy: Work Package Suite — domain sign-in (D13)
|
||||
|
||||
Instructions for the **Portainer admin** to take the new secure login portal live.
|
||||
Instructions for the **Portainer admin** to take domain authentication live.
|
||||
No prior context needed.
|
||||
|
||||
**Repo:** `Project-SDE-WP-Suite` (primegit) — changes are merged to **`main`**.
|
||||
|
||||
**What changed:** the app now has a username/password login. Going live needs:
|
||||
1. one new environment variable,
|
||||
2. a **rebuild** of the stack (not just a restart), and
|
||||
3. creating the first admin account.
|
||||
> **This document replaced an earlier one.** Until Aug 24 2026 it described taking a
|
||||
> **username/password login portal** live: bcrypt hashes, an `AUTH_SECRET_KEY`, and a
|
||||
> first admin created with `manage_users create-admin <user> --password …`. All of
|
||||
> that is gone. The app no longer stores a password of any kind, `create-admin` no
|
||||
> longer exists, and following the old steps will fail at the first command. The
|
||||
> superseded design is recorded in `docs/waves/decisions-2026-08-21.md` (D13).
|
||||
|
||||
**What changed:** signing in is now an **LDAPS bind against `prime.local`**. People
|
||||
use their **Windows password**. The suite stores no credential, there is no password
|
||||
reset, and accounts create themselves on first sign-in.
|
||||
|
||||
Going live needs:
|
||||
|
||||
1. two environment variables,
|
||||
2. a **rebuild** of the stack (not just a restart),
|
||||
3. one network check, and
|
||||
4. promoting the first admin.
|
||||
|
||||
> **Why a rebuild (not a restart):** both the **nginx/webserver** and **api** images
|
||||
> bake the code in at build time (`COPY html/` and `COPY server/` in their
|
||||
> Dockerfiles). A plain restart will **not** pick up the new code — the images must
|
||||
> be **rebuilt** from the latest `main`.
|
||||
> bake the code in at build time (`COPY html/` and `COPY server/`). A plain restart
|
||||
> will **not** pick up the new code — the images must be **rebuilt** from latest `main`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Add an environment variable to the stack
|
||||
## ⚠ Read this before you start
|
||||
|
||||
In the stack's **Environment variables** section, add:
|
||||
**There is no break-glass account.** If the directory is unreachable, the CA bundle
|
||||
path is wrong, or the required group is misconfigured, **nobody can sign in —
|
||||
including you.** That was a deliberate decision, not an oversight. Recovery is to fix
|
||||
the configuration and restart; there is no local password to fall back on.
|
||||
|
||||
So: do step 3 before you tell anyone the deploy is done.
|
||||
|
||||
---
|
||||
|
||||
## 1. Add environment variables to the stack
|
||||
|
||||
In the stack's **Environment variables** section:
|
||||
|
||||
| Name | Value | Notes |
|
||||
|------|-------|-------|
|
||||
| `AUTH_SECRET_KEY` | a long random string | **Required.** Signs the login session cookies. |
|
||||
| `AUTH_SESSION_HOURS` | `8` | *Optional.* Hours a login lasts before re-auth (defaults to 8). |
|
||||
| `AUTH_SECRET_KEY` | a long random string | **Required.** Unchanged — still signs the session cookies. Keep the existing value; changing it signs everyone out. |
|
||||
| `LDAP_REQUIRED_GROUP` | `CN=Prime Employees,OU=Prime Distribution and Security Groups,DC=prime,DC=local` | AD group required to sign in. A full DN is best — it skips a directory lookup. Nested groups count. Leave empty to allow any domain account. |
|
||||
| `AUTH_SESSION_HOURS` | `12` | *Optional.* Unchanged. |
|
||||
|
||||
Generate the secret on the host with:
|
||||
You do **not** need to set `LDAP_HOST`, `LDAP_DOMAIN` or `LDAP_CA_FILE`. Their
|
||||
defaults are correct for this estate, and the CA bundle ships inside the image.
|
||||
|
||||
```bash
|
||||
openssl rand -base64 48
|
||||
```
|
||||
**Do not point `LDAP_HOST` at a domain controller's name or at an IP address.** It is
|
||||
set to `prime.local` on purpose: every DC's certificate carries that name in its SAN,
|
||||
so the domain name both validates and load-balances across all six DCs. An IP fails
|
||||
certificate validation outright, and the only way to force it through is to switch
|
||||
validation off — which would let anyone on the network intercept **domain passwords**.
|
||||
|
||||
> If `AUTH_SECRET_KEY` is **not** set, the app still starts but falls back to a random
|
||||
> per-process key — logins then reset on every restart and break across the 2 gunicorn
|
||||
> workers. It must be set to a fixed value.
|
||||
|
||||
The existing database variables (`POSTGRES_*`) are unchanged.
|
||||
`AUTH_RESET_MINUTES` and `AUTH_RESET_COOLDOWN_SECONDS` can be deleted if present.
|
||||
They configured the password-reset email, which no longer exists.
|
||||
|
||||
---
|
||||
|
||||
## 2. Pull latest `main`, rebuild, and redeploy
|
||||
|
||||
- Pull the latest commit on `main` and redeploy the stack **with image rebuild enabled**
|
||||
(e.g. "Re-pull and redeploy" / force rebuild). This rebuilds both the `webserver` and
|
||||
`api` images.
|
||||
- New Python dependencies (`bcrypt`, `PyJWT`) are in `requirements.txt` and install
|
||||
automatically during the rebuild.
|
||||
- The `users` table is created automatically on API startup — **no DB migration needed.**
|
||||
- Pull the latest commit on `main` and redeploy **with image rebuild enabled**.
|
||||
- The new Python dependency (`ldap3`) is in `requirements.txt` and installs during
|
||||
the rebuild.
|
||||
- A database migration drops the `users.password_hash` column. It runs automatically
|
||||
at container start. **Every account, role and project membership is preserved** —
|
||||
it removes one column, not any rows.
|
||||
|
||||
---
|
||||
|
||||
## 3. Verify the containers
|
||||
## 3. Verify BEFORE announcing it
|
||||
|
||||
- Confirm `wp_api` and the webserver container are both **running**.
|
||||
- If `wp_api` fails to start, check its **Logs**. (A missing `AUTH_SECRET_KEY` only logs a
|
||||
warning — it won't crash — but please confirm it's set.)
|
||||
|
||||
---
|
||||
|
||||
## 4. Create the first admin account
|
||||
|
||||
The login system needs one admin user in the production (Postgres) database. Open the
|
||||
**`wp_api`** container's **Console** (`/bin/sh`) and run:
|
||||
**a. Did the API start at all?**
|
||||
|
||||
```bash
|
||||
python -m server.manage_users create-admin <username> --name "<Full Name>"
|
||||
docker compose logs api | grep -i "LDAP auth"
|
||||
```
|
||||
|
||||
It prompts for a password (minimum 8 characters) and prints `Created admin: <username>`.
|
||||
You want:
|
||||
|
||||
Non-interactive alternative:
|
||||
```
|
||||
LDAP auth enabled — ldaps://prime.local:636, domain prime.local, CA /app/server/certs/prime-ca-chain.pem, required group: CN=Prime Employees,…
|
||||
```
|
||||
|
||||
If it says `LDAP auth DISABLED`, stop — nobody will be able to sign in. The message
|
||||
names the reason.
|
||||
|
||||
**b. Can the container actually reach a domain controller?** This opens a TLS session
|
||||
and validates the certificate **without binding**, so it touches no account and
|
||||
cannot contribute to any lockout:
|
||||
|
||||
```bash
|
||||
python -m server.manage_users create-admin <username> --name "<Full Name>" --password "<password>"
|
||||
docker compose exec api openssl s_client -connect prime.local:636 -CAfile /app/server/certs/prime-ca-chain.pem </dev/null 2>&1 | grep "Verify return"
|
||||
```
|
||||
|
||||
Other CLI commands (run the same way): `list`, `create <user> --role user`,
|
||||
`reset-password <user>`, `disable <user>`, `enable <user>`.
|
||||
Want `Verify return code: 0 (ok)`. If you get a connection error, the `api` container
|
||||
is missing the `outbound` network — `internal` has no default gateway and blocks the
|
||||
LAN as well as the internet. If you get `62 (hostname mismatch)`, something is
|
||||
pointing at an IP instead of `prime.local`.
|
||||
|
||||
**c. Sign in.** Use your own Windows username and password.
|
||||
|
||||
---
|
||||
|
||||
## 5. Confirm it works
|
||||
## 4. Promote the first admin
|
||||
|
||||
1. Load the site's normal URL — it should redirect to a **login page**.
|
||||
2. Sign in with the admin account from step 4.
|
||||
3. That admin can then add all other users from the in-app **Admin → User
|
||||
administration** page (top-right **Admin** link), so no further shell access is needed.
|
||||
Roles are stored locally and are not read from AD, so someone has to be made an admin
|
||||
once. Sign in first — that creates your account — then:
|
||||
|
||||
```bash
|
||||
docker compose exec api python -m server.manage_users promote <your-sAMAccountName>
|
||||
```
|
||||
|
||||
It asks for **your** domain username and password, binds to confirm who you are, and
|
||||
prints `<user>: project_user -> admin`.
|
||||
|
||||
Other commands: `list` (needs no credential), `demote`, `disable`, `enable`.
|
||||
`create-admin`, `create` and `reset-password` no longer exist.
|
||||
|
||||
After that, admins manage everyone else from the in-app **Admin → User
|
||||
administration** page. No further shell access needed.
|
||||
|
||||
---
|
||||
|
||||
## What people will notice
|
||||
|
||||
- They sign in with their **Windows password**, not an app password.
|
||||
- **"Forgot password?"** now goes to `https://primecontrols.okta.com/`. The app cannot
|
||||
reset a password it does not hold.
|
||||
- The **Change password** item is gone from the top-right menu.
|
||||
- Anyone in the required group can sign in **without being added first** — their
|
||||
account is created automatically. They will see **no projects** until an admin
|
||||
grants access, which is intentional. New accounts appear in the Admin console and
|
||||
each one is recorded in the audit log.
|
||||
- Two wrong passwords and the app stops trying for a while. That is deliberate: every
|
||||
failed attempt is a real domain bind and counts against the **AD lockout policy**,
|
||||
so the app stops well short of locking anyone out of Windows.
|
||||
|
||||
## Reference — what's in this release
|
||||
|
||||
- `server/auth.py` — bcrypt password hashing, JWT session cookie, the request gate.
|
||||
- `server/app.py` — `/api/auth/*` endpoints + middleware that refuses every `/api` data
|
||||
route without a valid session.
|
||||
- `server/manage_users.py` — the CLI used in step 4.
|
||||
- `html/login.html`, `html/auth-guard.js` — login page and per-page guard.
|
||||
- `html/admin.html` / `admin.js` — Admin Console gated on the admin role, with the user
|
||||
administration UI.
|
||||
- Sessions are stateless: a signed JWT in an **HttpOnly, SameSite=Lax** cookie, marked
|
||||
**Secure** automatically when served over HTTPS (via `X-Forwarded-Proto` from nginx).
|
||||
- `server/ldap_auth.py` — the LDAPS client: bind, nested-group check, certificate validation.
|
||||
- `server/app.py` — `login()` binds instead of comparing a hash; password endpoints removed.
|
||||
- `server/auth.py` — sessions and roles only; no hashing, no reset tokens.
|
||||
- `server/certs/prime-ca-chain.pem` — the CA bundle that validates the DC certificate.
|
||||
- `server/manage_users.py` — `promote` / `demote`, each requiring a domain bind.
|
||||
- `html/login.html`, `login.js` — one view; "Forgot password?" points at Okta.
|
||||
- Migration `b7e4f1a20c93` — drops `users.password_hash`.
|
||||
|
||||
@@ -1,355 +0,0 @@
|
||||
# Deploy runbook: WP Suite Okta cutover (wave 10)
|
||||
|
||||
**For:** IT / whoever administers the Docker host and Portainer
|
||||
**From:** m.mabrey@prime-controls.com
|
||||
**Revised:** 2026-09-03. First version of this runbook.
|
||||
**Expected duration:** 20-30 minutes, including the backup and the live sign-in check
|
||||
**Expected downtime:** under a minute, while containers are recreated
|
||||
|
||||
This is a separate runbook from `DEPLOY-runbook-2026-08-04.md`, not a revision of it.
|
||||
That one still applies to its own deploy. Read this one in full before starting.
|
||||
It has a step that the earlier one does not: this deploy removes the local password
|
||||
system entirely, and one part of that removal cannot be undone by the usual means.
|
||||
See "What this deploy changes" below.
|
||||
|
||||
---
|
||||
|
||||
## Fill these in before handing this over
|
||||
|
||||
| Thing | Value |
|
||||
|---|---|
|
||||
| Docker host (SSH target) | `________________` |
|
||||
| Stack name in Portainer | `________________` |
|
||||
| Site URL | `https://________________` |
|
||||
| Stack directory on the host (holds `docker-compose.yml` / `backups/`) | `________________` |
|
||||
| A real Okta account assigned to the app integration, for the live check in Step 4 | `________________` |
|
||||
|
||||
Container names are fixed by the compose file and are the same on every host:
|
||||
`nginx_webserver`, `wp_api`, `wp_db`, `wp_db_backup`.
|
||||
|
||||
---
|
||||
|
||||
## What this deploy changes
|
||||
|
||||
Sign-in changes from a local username/password to Okta OIDC, completely. Not a
|
||||
toggle, not a fallback. Three things make this more than a routine deploy:
|
||||
|
||||
1. **Five new environment variables are required**, and without them nobody can
|
||||
sign in: `OKTA_ISSUER`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`,
|
||||
`OKTA_REDIRECT_URI`, and optionally `OKTA_IDENTITY_CLAIM`. This is a genuine
|
||||
change from how deploys usually go here. Do not skip Step 1.5.
|
||||
|
||||
2. **A migration drops the `password_hash` column** (`1d60a608bb51`), and it is
|
||||
**one-way in practice.** Its `downgrade()` re-adds the column, but empty.
|
||||
The real password hashes are gone the moment this commits, and no `alembic
|
||||
downgrade` brings them back. If this deploy needs to be undone after that
|
||||
point, going back to the old local-password code does not work on its own.
|
||||
See the Rollback section, Case C. This is why Step 1's backup is not
|
||||
optional the way it sometimes reads in other runbooks.
|
||||
|
||||
3. **There is no break-glass path**, by design (recorded decision D16). If Okta
|
||||
is unreachable or misconfigured after this deploy, the app is unreachable for
|
||||
everyone, admins included, until Okta is fixed. That is expected behavior,
|
||||
not a bug to roll back from. See Rollback, Case A/B, before assuming
|
||||
something is broken.
|
||||
|
||||
The visible change for people using the app: the login page becomes "Sign in
|
||||
with Okta" instead of a username/password form. Nothing else in the app's
|
||||
day-to-day behavior changes.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Record the current state (needed for rollback)
|
||||
|
||||
SSH to the Docker host and run:
|
||||
|
||||
```bash
|
||||
docker exec wp_api alembic -c server/alembic.ini current
|
||||
docker inspect nginx_webserver --format 'nginx image: {{.Image}}'
|
||||
docker inspect wp_api --format 'api image: {{.Image}}'
|
||||
```
|
||||
|
||||
**Copy the output into your ticket.** Also note the Git commit the Portainer
|
||||
stack is currently on (Portainer, the stack, the Git reference / last-updated
|
||||
commit). Without these, rollback is guesswork.
|
||||
|
||||
Expected output of the first command before this deploy: `a1b8c6d4e2f9 (head)`.
|
||||
If it shows anything else, stop and check with me before continuing. This
|
||||
runbook assumes that starting point.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Back up the database
|
||||
|
||||
On the Docker host:
|
||||
|
||||
```bash
|
||||
docker exec wp_db_backup /scripts/db-backup.sh
|
||||
```
|
||||
|
||||
Expected output ends with a line like:
|
||||
|
||||
```
|
||||
[db-backup] wrote 1.4M /backups/wpsuite-20260903-141233Z.sql.gz.enc
|
||||
```
|
||||
|
||||
Confirm the file is on the host (substitute the stack directory):
|
||||
|
||||
```bash
|
||||
ls -lt <stack-dir>/backups | head -3
|
||||
```
|
||||
|
||||
**Record that filename.** Do not continue until you have seen the `wrote ...`
|
||||
line and the file in that listing.
|
||||
|
||||
This backup matters more than usual for this deploy. Once the migration in
|
||||
Step 3 commits, this file becomes the *only* way to get local password hashes
|
||||
back, for any reason. Treat it as the point you would restore to, not routine
|
||||
housekeeping.
|
||||
|
||||
- A `.sql.gz.enc` extension means backups are encrypted. Expected and correct.
|
||||
- A `.sql.gz` extension plus a `WARNING: BACKUP_ENC_PASSPHRASE not set` line
|
||||
means backups are unencrypted. Not a blocker for this deploy; report it back.
|
||||
- **No SSH access?** Portainer, **Containers**, `wp_db_backup`, **Console**,
|
||||
connect with `/bin/sh`, then run `/scripts/db-backup.sh`. Same result: the
|
||||
dump lands on the host, because `/backups` is a bind mount.
|
||||
|
||||
---
|
||||
|
||||
## Step 1.5: Confirm the Okta app integration is actually ready
|
||||
|
||||
Do this before redeploying, not after. Everything here is checked in Okta's own
|
||||
admin console and in the values that will go into the stack's environment
|
||||
variables. Nothing touches the WP Suite host yet.
|
||||
|
||||
1. The Okta app integration exists (Sign-in method: OIDC, Authorization Code,
|
||||
Application type: Web Application), and the account listed in the fill-in
|
||||
table above is assigned to it.
|
||||
2. `OKTA_REDIRECT_URI` matches a "Sign-in redirect URI" registered on that app
|
||||
integration **exactly**: scheme, host, and path, including whether it ends
|
||||
in `/api/auth/okta/callback`.
|
||||
3. `OKTA_ISSUER`, `OKTA_CLIENT_ID`, and `OKTA_CLIENT_SECRET` are the values from
|
||||
that same app integration, not a different one.
|
||||
4. If your Okta configuration puts the directory identity somewhere other than
|
||||
the `preferred_username` claim, `OKTA_IDENTITY_CLAIM` is set to the right
|
||||
claim name. If unsure, leave it unset; `preferred_username` is the default.
|
||||
|
||||
Add all five to the stack's **Environment variables** in Portainer now, before
|
||||
Step 2. `OKTA_CLIENT_SECRET` should be handled the same way `AUTH_SECRET_KEY`
|
||||
already is: not typed anywhere it will be logged.
|
||||
|
||||
If any of items 1-3 above are not yet confirmed, stop here and get them
|
||||
confirmed first. A wrong redirect URI or an unassigned account will not corrupt
|
||||
anything, but it does mean nobody signs in after this deploy until it is fixed.
|
||||
See Rollback, Case B, which is the ordinary way that gets fixed and does not
|
||||
involve the database at all.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Redeploy the stack in Portainer
|
||||
|
||||
1. Portainer, **Stacks**, select the stack.
|
||||
2. **Pull and redeploy**, with re-pull / re-build **enabled**.
|
||||
3. Wait for it to report success.
|
||||
|
||||
A plain "restart" or "stop/start" will not pick up new code, and will not pick
|
||||
up the environment variables added in Step 1.5 either.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Confirm the containers came up
|
||||
|
||||
```bash
|
||||
docker ps --filter name=nginx_webserver --filter name=wp_api --filter name=wp_db
|
||||
```
|
||||
|
||||
All three must be `Up`, and `wp_db` should show `(healthy)`. Then check the API
|
||||
applied its migration cleanly:
|
||||
|
||||
```bash
|
||||
docker logs wp_api --tail 40
|
||||
```
|
||||
|
||||
You are looking for an Alembic `Running upgrade a1b8c6d4e2f9 -> 1d60a608bb51`
|
||||
line followed by gunicorn starting up, and no traceback. The API refuses to
|
||||
start if a migration fails, so a restarting `wp_api` container means it failed.
|
||||
Go to Rollback, Case B, and read the "did the migration commit" note there
|
||||
before doing anything to the database.
|
||||
|
||||
Confirm the database landed on the new revision:
|
||||
|
||||
```bash
|
||||
docker exec wp_api alembic -c server/alembic.ini current
|
||||
```
|
||||
|
||||
Expected: `1d60a608bb51 (head)`. **Once you see this, you have passed the
|
||||
point of no return described above.** The backup from Step 1 is now the only
|
||||
way back to a working local-password system, if that is ever needed.
|
||||
|
||||
Then verify nginx's own view of its config:
|
||||
|
||||
```bash
|
||||
docker exec nginx_webserver nginx -t
|
||||
```
|
||||
|
||||
Expected: `syntax is ok` / `test is successful`.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Confirm Okta sign-in actually works, live
|
||||
|
||||
This is the step that matters most for this deploy. A clean container start
|
||||
does not by itself prove sign-in works, and there is currently no startup log
|
||||
line that confirms Okta config is good (logged separately as a follow-up, not
|
||||
fixed as part of this runbook). The only real proof is a live sign-in.
|
||||
|
||||
1. Open the site's normal URL in a private/incognito window. It should land on
|
||||
`login.html` with a "Sign in with Okta" button, not a username/password
|
||||
form.
|
||||
2. Click it. You should be redirected to your organization's actual Okta
|
||||
sign-in page (the real Okta domain from `OKTA_ISSUER`, not this app's own
|
||||
domain).
|
||||
3. Sign in with the account from the fill-in table. You should land back on
|
||||
the WP Suite site, signed in.
|
||||
4. If this is the account's first-ever sign-in, it is now JIT-provisioned as a
|
||||
regular user (`project_user`). To make it an admin, on the Docker host:
|
||||
|
||||
```bash
|
||||
docker exec -it wp_api python -m server.manage_users promote <username> --role admin
|
||||
```
|
||||
|
||||
This only works on an account that has already signed in once through Okta.
|
||||
It promotes an existing row; it does not create one. That is deliberate
|
||||
(recorded decision D16): there is no other admin-bootstrap path.
|
||||
|
||||
If step 2 or 3 fails (redirected to an Okta error page, redirected back to
|
||||
`login.html` with an error, or nothing happens), this is almost always a
|
||||
configuration problem from Step 1.5, not a code or database problem. Go to
|
||||
Rollback, Case B, before considering anything more drastic.
|
||||
|
||||
Also confirm the API is reachable through the proxy and the redirect itself is
|
||||
wired up:
|
||||
|
||||
```bash
|
||||
curl -s https://<site-url>/api/health # -> {"ok": true}
|
||||
curl -sI https://<site-url>/api/auth/okta/login | grep -i ^location # -> your Okta authorize URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Hard-reload once in a browser, then sanity-check
|
||||
|
||||
Press **Ctrl+Shift+R** (Cmd+Shift+R on macOS) once. The app uses a service
|
||||
worker; a normal reload can serve the previous version.
|
||||
|
||||
1. Signed in as the account from Step 4, the home page offers to select or
|
||||
create a project, same as before.
|
||||
2. Open **Admin Console** as the promoted admin account. The user table shows
|
||||
the account you just signed in with. There is no password column, no
|
||||
"reset password" action anywhere in the UI.
|
||||
3. Open a project and confirm a work package can be opened and edited
|
||||
normally. Sign-in is the only thing this deploy changes, so the rest of
|
||||
the app should look untouched.
|
||||
|
||||
**Deploy complete.** Please report back: the Step 0 output, the backup
|
||||
filename from Step 1, and confirmation that Step 4's live sign-in worked.
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
Read this before assuming a rollback is needed. Cases A and B below do **not**
|
||||
touch the database and are the far more likely outcome of something going
|
||||
wrong here. Okta configuration is fiddly and easy to get slightly wrong. Case
|
||||
C is the severe, destructive one, and should be a last resort, not a first
|
||||
reaction.
|
||||
|
||||
### Case A: nginx won't start, or containers won't come up at all
|
||||
|
||||
Same as any other deploy: the database is untouched by container start-up
|
||||
failures. In Portainer, redeploy the stack pinned to the **previous Git
|
||||
commit** recorded in Step 0, then re-run Step 3.
|
||||
|
||||
```bash
|
||||
docker logs nginx_webserver --tail 100
|
||||
docker logs wp_api --tail 100
|
||||
```
|
||||
|
||||
Send me whichever of those is relevant.
|
||||
|
||||
### Case B: containers are up, but Okta sign-in doesn't work
|
||||
|
||||
This is a configuration problem, not a data problem, and does **not** need a
|
||||
code rollback or a database restore. Check, in order:
|
||||
|
||||
1. Is `wp_api`'s log showing anything at all when a sign-in is attempted?
|
||||
`docker logs wp_api --tail 100`.
|
||||
2. Do the five `OKTA_*` values in the stack's environment variables actually
|
||||
match the Okta app integration (Step 1.5)? A copy-paste error in
|
||||
`OKTA_CLIENT_SECRET` or a redirect URI that's off by a trailing slash are
|
||||
the two most common causes.
|
||||
3. Is the account assigned to the Okta app integration? An unassigned account
|
||||
gets denied by Okta itself, before it ever reaches this app.
|
||||
4. If a specific person can't sign in but others can, check
|
||||
`OKTA_IDENTITY_CLAIM`. The claim it reads may not carry that person's
|
||||
directory identity in the format expected. Confirm with security which
|
||||
claim Okta is actually issuing.
|
||||
|
||||
Fix the environment variable(s) in Portainer, then redeploy (Pull and redeploy
|
||||
is fine; the migration already applied and does not run again). No backup
|
||||
restore, no code rollback.
|
||||
|
||||
If it's still not working after checking all four, send me the `wp_api` log
|
||||
from item 1 along with which of items 2-4 you already ruled out.
|
||||
|
||||
### Case C: the decision is made to abandon Okta and restore local-password sign-in
|
||||
|
||||
This is the case the point-of-no-return warning in "What this deploy changes"
|
||||
is about. Only reach for this if Case A and B do not apply. That is, Okta
|
||||
itself is working correctly but a decision has been made to go back to the old
|
||||
system entirely.
|
||||
|
||||
**This cannot be done with a code rollback alone.** The old code expects a
|
||||
real `password_hash` on every user row. After Step 3 commits, that column is
|
||||
either gone or (if `alembic downgrade` is run) present but empty. Either way,
|
||||
nobody's stored password survived, including admins'. The only way to get a
|
||||
working local-password system back is to restore the full database from the
|
||||
Step 1 backup, which also rolls back every other change made since that
|
||||
backup: new work packages, comments, uploaded files, everything.
|
||||
|
||||
**Do not do this without confirming with me first.** If it is confirmed, for
|
||||
an encrypted dump, on the Docker host, in the `backups` directory:
|
||||
|
||||
```bash
|
||||
export BACKUP_ENC_PASSPHRASE='<the passphrase, from the stack env vars>'
|
||||
openssl enc -d -aes-256-cbc -pbkdf2 -pass env:BACKUP_ENC_PASSPHRASE \
|
||||
-in wpsuite-<timestamp>.sql.gz.enc \
|
||||
| gunzip \
|
||||
| docker exec -i wp_db psql -U wpsuite -d wpsuite
|
||||
unset BACKUP_ENC_PASSPHRASE
|
||||
```
|
||||
|
||||
For an unencrypted dump, drop the `openssl` stage and pipe `gunzip` straight
|
||||
into `psql`. Substitute the real values if `POSTGRES_USER` / `POSTGRES_DB` are
|
||||
not `wpsuite`. After restoring, redeploy pinned to the Git commit recorded in
|
||||
Step 0, since the restored database matches the old schema, not this one.
|
||||
|
||||
Reach me at m.mabrey@prime-controls.com.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Do not run `docker compose down -v`. The `-v` flag deletes the `pgdata`
|
||||
volume and with it the entire database.
|
||||
- `docker exec <container-name>` is used throughout rather than
|
||||
`docker compose ...`, because a Portainer-managed Git stack's compose project
|
||||
lives under Portainer's own data directory and usually isn't reachable from
|
||||
an ad hoc SSH session the same way.
|
||||
- There is currently no startup log line confirming Okta config is valid
|
||||
(`okta_auth.describe()` exists but nothing calls it yet, logged as a
|
||||
follow-up). Step 4's live sign-in is the real verification until that's
|
||||
wired in.
|
||||
- Full background documentation: `DEPLOYMENT.md` and `server/README.md` in the
|
||||
repository. `docs/waves/decisions-2026-09-03.md` (D16, D17) records why
|
||||
there is no break-glass path and why this runbook exists as its own document.
|
||||
403
DEPLOYMENT.md
@@ -52,44 +52,34 @@ POSTGRES_DB=wpsuite
|
||||
POSTGRES_USER=wpsuite
|
||||
POSTGRES_PASSWORD=<strong-random-password>
|
||||
|
||||
# REQUIRED — signs login session cookies, AFTER Okta has confirmed who someone
|
||||
# is. If unset, `docker compose up` errors out and the API refuses to start.
|
||||
# Generate once and keep it stable:
|
||||
# REQUIRED — signs login session cookies. If unset, `docker compose up` errors
|
||||
# out and the API refuses to start. Generate once and keep it stable:
|
||||
# openssl rand -base64 48
|
||||
AUTH_SECRET_KEY=<strong-random-secret>
|
||||
|
||||
# REQUIRED (in spirit — see the note below) — Okta OIDC is the only sign-in
|
||||
# path (D15/D16). There is no local password anywhere in this app to fall back
|
||||
# to, so without these nobody can sign in at all. Get them from the Okta app
|
||||
# integration (sign-in method OIDC - Authorization Code, Web Application):
|
||||
#
|
||||
# OKTA_ISSUER the authorization server, e.g.
|
||||
# https://your-org.okta.com/oauth2/default
|
||||
# OKTA_CLIENT_ID \_ from the app integration
|
||||
# OKTA_CLIENT_SECRET /
|
||||
# OKTA_REDIRECT_URI must exactly match a "Sign-in redirect URI"
|
||||
# registered on the app integration, e.g.
|
||||
# https://wp-suite.company.local/api/auth/okta/callback
|
||||
#
|
||||
# Full explanation, and the optional OKTA_IDENTITY_CLAIM override, in
|
||||
# server/.env.example. Not enforced at startup the way AUTH_SECRET_KEY is —
|
||||
# the API starts without these, it just refuses every sign-in and says so in
|
||||
# `docker compose logs api` (server/okta_auth.py's describe()).
|
||||
OKTA_ISSUER=<https://your-org.okta.com/oauth2/default>
|
||||
OKTA_CLIENT_ID=<from the Okta app integration>
|
||||
OKTA_CLIENT_SECRET=<from the Okta app integration>
|
||||
OKTA_REDIRECT_URI=<https://your-hostname/api/auth/okta/callback>
|
||||
|
||||
# Encrypts database backups at rest (AES-256). Set this BEFORE the DB holds
|
||||
# customer IP. Keep the passphrase OFF this host — losing it makes dumps
|
||||
# unrecoverable: openssl rand -base64 32
|
||||
BACKUP_ENC_PASSPHRASE=<strong-random-passphrase>
|
||||
|
||||
# OPTIONAL — SMTP password for WP-assignment email. Email is OFF by default and
|
||||
# enabled from the Admin console; the host/port/from-address are configured
|
||||
# there, but the password is only ever read from this variable (never stored
|
||||
# in the DB or shown in the UI). Leave unset until you have SMTP details.
|
||||
# OPTIONAL — SMTP password for WP-assignment email + password-reset links. Email
|
||||
# is OFF by default and enabled from the Admin console; the host/port/from-address
|
||||
# are configured there, but the password is only ever read from this variable
|
||||
# (never stored in the DB or shown in the UI). Leave unset until you have SMTP
|
||||
# details.
|
||||
# SMTP_PASSWORD=<smtp-app-password>
|
||||
|
||||
# OPTIONAL — the AD group required to sign in (D13). A group NAME or a full DN;
|
||||
# nested groups count. Empty means any domain account may sign in. This is the
|
||||
# initial value; the live one is set in the Admin console.
|
||||
# LDAP_REQUIRED_GROUP=CN=Prime Employees,OU=Prime Distribution and Security Groups,DC=prime,DC=local
|
||||
#
|
||||
# OPTIONAL — the rest of the directory settings. The defaults are correct for this
|
||||
# estate and you should not normally set them. NEVER point LDAP_HOST at a DC name
|
||||
# or an IP: see § Domain authentication below.
|
||||
# LDAP_DOMAIN=prime.local
|
||||
# LDAP_HOST=prime.local
|
||||
# LDAP_CA_FILE=/app/server/certs/prime-ca-chain.pem
|
||||
```
|
||||
|
||||
The API builds its own DB connection string from the `POSTGRES_*`
|
||||
@@ -101,14 +91,34 @@ ignored whenever the three `POSTGRES_*` values are present.
|
||||
|
||||
Generate a strong password with `openssl rand -base64 32`.
|
||||
|
||||
> **Portainer note:** for a Git-based stack these go in the stack's
|
||||
> **Environment variables** section (Portainer doesn't read a local `.env`).
|
||||
> Set `POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD` / `AUTH_SECRET_KEY` /
|
||||
> `OKTA_ISSUER` / `OKTA_CLIENT_ID` / `OKTA_CLIENT_SECRET` / `OKTA_REDIRECT_URI` /
|
||||
> `BACKUP_ENC_PASSPHRASE` (and `SMTP_PASSWORD`, if you enable email) there.
|
||||
> **Portainer note:** for a Git-based stack the stack's **Environment variables**
|
||||
> section is not merely an alternative to `.env` — it is the ONLY route, because
|
||||
> Portainer does not read a local `.env` at all. Every value the compose file
|
||||
> references as `${VAR}` has to be set there or it arrives empty.
|
||||
>
|
||||
> The full list, and what an empty one costs you:
|
||||
>
|
||||
> | Variable | Required? | If unset |
|
||||
> |---|---|---|
|
||||
> | `POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD` | **yes** | the stack will not start |
|
||||
> | `AUTH_SECRET_KEY` | **yes** | compose fails fast; the API refuses to start |
|
||||
> | `LDAP_REQUIRED_GROUP` | **effectively yes** | no group gate — **every account in the domain may sign in**. Silent: sign-in works, so nothing looks wrong. |
|
||||
> | `BACKUP_ENC_PASSPHRASE` | before real data | dumps are written unencrypted |
|
||||
> | `SMTP_PASSWORD` | only with email on | notifications are recorded and never sent |
|
||||
> | `MICRON_DB_URL` | optional | the asset picker degrades to manual entry |
|
||||
>
|
||||
> Paste values raw — it is a form field, not a shell, so no surrounding quotes.
|
||||
> Quotes are not stripped and become part of the value: a quoted
|
||||
> `LDAP_REQUIRED_GROUP` will not resolve, and a quoted `MICRON_DB_URL` will not
|
||||
> parse.
|
||||
>
|
||||
> **`MICRON_DB_URL` must be URL-encoded** (`@` → `%40`, `#` → `%23`, `/` → `%2F`)
|
||||
> because it is a full connection URL. `LDAP_REQUIRED_GROUP` must NOT be encoded —
|
||||
> it is an LDAP distinguished name, and its spaces and commas are legal as they are.
|
||||
|
||||
These are the only credentials in the system, and they never appear in the
|
||||
compose file or in git.
|
||||
`POSTGRES_PASSWORD`, `AUTH_SECRET_KEY`, `BACKUP_ENC_PASSPHRASE`, `SMTP_PASSWORD` and
|
||||
the password inside `MICRON_DB_URL` are the only credentials in the system, and none
|
||||
of them appears in the compose file or in git.
|
||||
|
||||
## 3. Point your reverse proxy at the nginx container
|
||||
|
||||
@@ -169,34 +179,25 @@ project → SOP → Work Package → the AWP issue gate → status → metrics
|
||||
archive round trip → cascade cleanup → sign-out). Stdlib only — no pip/jq.
|
||||
|
||||
It **signs in first**, because every `/api/` route except `/api/health` requires a
|
||||
session — but there is no local password to sign in with (D15/D16), and Okta
|
||||
requires a real browser to complete, which this script cannot do. So instead
|
||||
of an HTTP login, it mints a session directly the same way `okta_callback()`
|
||||
does after Okta hands back an identity, which means **it has to run somewhere
|
||||
that can read the same `AUTH_SECRET_KEY` and reach the same database as the
|
||||
server under test** — inside the `api` container, or local dev against your
|
||||
own DB. It can no longer sign in to an arbitrary remote URL from an unrelated
|
||||
workstation the way the old password-based version could.
|
||||
|
||||
The account named by `WP_SMOKE_USER` must **already exist** — sign it in
|
||||
through Okta once first, or pre-create it from the User Directory — and must
|
||||
be an **admin**: the run creates a project and deletes it again, and deleting
|
||||
one takes Project Admin on it. The script checks the signed-in role up front
|
||||
and warns if it is too low rather than letting you find out in the cleanup
|
||||
step.
|
||||
session. Credentials come from the environment so a password stays out of shell
|
||||
history, and the account must be an **admin**: the run creates a project and deletes
|
||||
it again, and archiving or deleting one takes Project Admin on it. The script checks
|
||||
the signed-in role up front and warns if it is too low rather than letting you find
|
||||
out in the cleanup step.
|
||||
|
||||
```bash
|
||||
# From inside the api container — has AUTH_SECRET_KEY and DATABASE_URL, and
|
||||
# hits FastAPI directly. This is the normal way to run it in production:
|
||||
docker compose exec -e WP_SMOKE_USER api \
|
||||
export WP_SMOKE_USER=<admin-account>
|
||||
export WP_SMOKE_PASSWORD='…'
|
||||
|
||||
# Through the proxy (use --insecure for a self-signed internal cert):
|
||||
python3 server/smoketest.py https://wp-suite.company.local --insecure
|
||||
|
||||
# Or from inside the api container (hits FastAPI directly). Pass the vars through:
|
||||
docker compose exec -e WP_SMOKE_USER -e WP_SMOKE_PASSWORD api \
|
||||
python /app/server/smoketest.py http://localhost:8000
|
||||
|
||||
# Local dev, against the app you're running yourself:
|
||||
export AUTH_SECRET_KEY=... DATABASE_URL=... WP_SMOKE_USER=<admin-account>
|
||||
python3 server/smoketest.py http://localhost:8000
|
||||
|
||||
# Add --keep to leave a demo project in the DB so you can open it in the UI.
|
||||
# --user overrides $WP_SMOKE_USER if you'd rather be explicit.
|
||||
# --user / --password override the environment if you'd rather be explicit.
|
||||
```
|
||||
|
||||
Exit codes: **0** all checks passed · **1** one or more checks failed · **2** the run
|
||||
@@ -284,7 +285,7 @@ users on the same project see the same server-stored SOP and Work Packages.
|
||||
| `sops` | project SOP baselines | `project_id` → projects, `name`, `number`, `complete`, `data` (full SOP JSON) |
|
||||
| `work_packages` | individual IWPs | `project_id` → projects, `sop_id` → sops, `parent_id` (split instances), `number`, `subject`, `type`, `status`, `assignee_id` (owner), `issued_at`, `archived_at`, `data` (full WP JSON) |
|
||||
| `comments` | feedback from any page | `source`, `sop_id`, `wp_id`, `step`, `author`, `text`, `extra` |
|
||||
| `users` | login accounts | `username` (matched against Okta's identity claim — no password column; D15/D16), `role`, `full_name`, `email`, `is_active`, `auto_add_projects` + `auto_add_role` (default membership on new projects), `token_version` |
|
||||
| `users` | login accounts (no password — D13) | `username` (sAMAccountName), `role`, `full_name`, `email`, `is_active`, `auto_add_projects` + `auto_add_role` (default membership on new projects), login-lockout + `token_version` fields |
|
||||
| `project_members` | per-project access control | `user_id` → users, `project_id` → projects |
|
||||
| `audit_log` | append-only activity trail | `actor`, `action`, `entity_type`, `entity_id`, `project_id`, `summary`, `detail` |
|
||||
| `notifications` | in-app record + email outbox | `user_id`, `kind`, `wp_id`, `subject`, `status` (pending / sent / failed / skipped) |
|
||||
@@ -302,9 +303,8 @@ Work Packages `GET/POST /api/wps`, `GET/DELETE /api/wps/{id}`,
|
||||
`POST /api/wps/{id}/issue`, `POST /api/wps/{id}/status`, `POST /api/wps/{id}/archive`,
|
||||
`GET /api/wps/metrics` ·
|
||||
Comments `POST /api/comments` (and `/api/feedback`), `GET /api/comments` ·
|
||||
Auth `GET /api/auth/okta/login` / `okta/callback` (the Okta sign-in round trip),
|
||||
`POST /api/auth/logout`, `GET /api/auth/me`, admin user management under
|
||||
`/api/auth/users` (including `POST /api/auth/users/{id}/auto-add`) ·
|
||||
Auth `POST /api/auth/login` / `logout`, `GET /api/auth/me`, admin user management
|
||||
under `/api/auth/users` (including `POST /api/auth/users/{id}/auto-add`) ·
|
||||
Admin-only `GET/PUT /api/settings`,
|
||||
`POST /api/settings/test-email`, `GET /api/notifications`,
|
||||
`GET /api/projects/{id}/members`.
|
||||
@@ -324,6 +324,56 @@ docker compose up -d --build webserver # front-end change (html/) — rebuild
|
||||
docker compose up -d --build api # backend change (server/)
|
||||
```
|
||||
|
||||
## Before deploying the D13 auth change — take a backup first
|
||||
|
||||
**Timing is the whole point.** The container's start command is
|
||||
`alembic upgrade head && exec gunicorn`, so migrations run *seconds after you
|
||||
redeploy*. Migration `b7e4f1a20c93` drops `users.password_hash`. There is no window
|
||||
afterwards: back up **before** you redeploy, not after.
|
||||
|
||||
```bash
|
||||
# 1. Record what you are rolling back TO. Do this first; it is easy to forget
|
||||
# and impossible to reconstruct under pressure.
|
||||
git -C /path/to/repo rev-parse --short HEAD
|
||||
|
||||
# 2. One-shot dump, using the sidecar that is already running.
|
||||
docker compose exec backup sh /scripts/db-backup.sh
|
||||
# -> ./backups/wpsuite-<UTC timestamp>.sql.gz[.enc] on the host
|
||||
|
||||
# 3. Take it OUT of the rotation. The scheduled job prunes to the newest
|
||||
# BACKUP_KEEP (default 14) files matching wpsuite-*.sql.gz*, so on a daily
|
||||
# cadence this dump is deleted in a fortnight. A prefix that does not match
|
||||
# the glob is enough to protect it.
|
||||
docker compose exec backup sh -c 'cd /backups && cp "$(ls -1t wpsuite-*.sql.gz* | head -1)" "pre-d13-$(ls -1t wpsuite-*.sql.gz* | head -1)"'
|
||||
|
||||
# 4. Prove it is readable BEFORE you deploy. An untested dump is not a backup.
|
||||
docker compose exec backup sh -c 'openssl enc -d -aes-256-cbc -pbkdf2 -pass env:BACKUP_ENC_PASSPHRASE -in /backups/pre-d13-*.sql.gz.enc | gunzip -c | grep -c "INSERT INTO public.users"'
|
||||
# (drop the openssl stage for an unencrypted .sql.gz)
|
||||
```
|
||||
|
||||
### Two things about this particular dump
|
||||
|
||||
**It is the last copy of every password hash that will ever exist.** After the
|
||||
migration the column is gone; this file is where those bcrypt hashes live from then
|
||||
on. Make sure `BACKUP_ENC_PASSPHRASE` is set before step 2 — the script warns loudly
|
||||
if it is not, and writes plaintext — and decide deliberately how long to keep the
|
||||
file. bcrypt is not plaintext, but it is crackable offline given time and a copy.
|
||||
|
||||
**Restoring the database is not, by itself, a rollback.** The new code has no
|
||||
`password_hash` in its model and the old code requires it, so a restore without a
|
||||
matching code rollback leaves you with a schema and an application that disagree. A
|
||||
real rollback is both, in this order:
|
||||
|
||||
```bash
|
||||
# redeploy the commit from step 1 (Portainer: point the stack back and rebuild)
|
||||
docker compose exec backup sh /scripts/db-restore.sh /backups/pre-d13-wpsuite-<ts>.sql.gz.enc
|
||||
```
|
||||
|
||||
`db-restore.sh` dumps are taken with `--clean --if-exists`, so restoring **drops and
|
||||
recreates** objects before loading. It overwrites whatever is currently there.
|
||||
|
||||
---
|
||||
|
||||
## Backups & retention
|
||||
|
||||
A **`backup` sidecar** (in `docker-compose.yml`) runs `pg_dump` on a schedule and
|
||||
@@ -378,173 +428,96 @@ TLS / From address and flips the master toggle.
|
||||
package contents — so customer IP stays behind the login.
|
||||
- Use the card's **Send test email** button to confirm SMTP before enabling.
|
||||
|
||||
### Sign-in and admin bootstrap (Okta)
|
||||
### Password reset — there isn't one
|
||||
|
||||
There is no local password anywhere in this app — no "Forgot password," no
|
||||
reset link, nothing email-related to sign-in (D15/D16). `SMTP_PASSWORD` above
|
||||
is purely for WP-assignment notification emails.
|
||||
D13 removed local passwords entirely. **Turning email on no longer affects sign-in.**
|
||||
The login page's "Forgot password?" links to `https://primecontrols.okta.com/`, which
|
||||
is the only self-service route; the app cannot reset a credential it does not hold.
|
||||
|
||||
Sign-in is entirely Okta's job: `login.html` redirects to Okta, and access
|
||||
control is **who is assigned to the app integration in Okta** — see step 2's
|
||||
`OKTA_*` variables and [`server/README.md`](server/README.md#sign-in-okta) for
|
||||
the full flow. The first admin has to sign in through Okta once (landing as an
|
||||
ordinary `project_user`, auto-provisioned), then get promoted from a shell:
|
||||
Email still carries WP-assignment notifications and the critical-reopen mail.
|
||||
|
||||
---
|
||||
|
||||
## Domain authentication (D13)
|
||||
|
||||
Sign-in is an **LDAPS simple bind** as `<sAMAccountName>@prime.local`. There is no
|
||||
password in the database and **no break-glass account**. If the domain is
|
||||
unreachable, `LDAP_CA_FILE` is wrong, or the required group is misconfigured,
|
||||
**nobody can sign in, including admins.**
|
||||
|
||||
**First thing to check on any sign-in problem** — the API logs one line at startup
|
||||
saying whether LDAP is configured, and `/api/health` stays unauthenticated so the
|
||||
stack is diagnosable while nobody can log in:
|
||||
|
||||
```bash
|
||||
docker compose exec api python -m server.manage_users promote alice --role admin
|
||||
docker compose logs api | grep -i "LDAP auth"
|
||||
# LDAP auth enabled — ldaps://prime.local:636, domain prime.local, …
|
||||
# LDAP auth DISABLED — CA bundle not found at '…'. No one can sign in.
|
||||
curl https://wp-suite.company.local/api/health # → {"ok": true}
|
||||
```
|
||||
|
||||
This is deliberate, not an oversight: a hand-typed username at account-creation
|
||||
time risks a second, orphaned row if it doesn't exactly match what Okta sends,
|
||||
so the CLI promotes an existing Okta-provisioned row rather than creating one
|
||||
blind (D16). Every admin after the first can be promoted from the User
|
||||
Directory page — no shell access needed.
|
||||
|
||||
**No break-glass path.** If Okta is unreachable or misconfigured, the app is
|
||||
unreachable for everyone, including admins, until Okta is restored — the same
|
||||
posture the abandoned LDAPS design took, carried forward deliberately (D16).
|
||||
|
||||
### Accounts the Okta sync disabled (D18)
|
||||
|
||||
**Who this is for:** app admins, and project super users who manage accounts.
|
||||
|
||||
When Okta credentials are set (`OKTA_API_TOKEN`, or the service-app pair below), the `api` container asks Okta every 15 minutes
|
||||
(`OKTA_SYNC_INTERVAL_SECONDS`) who is still active. It **disables** a local
|
||||
account when the person is missing from Okta's list, or when Okta shows the
|
||||
status SUSPENDED or DEPROVISIONED. A password expiry, a lockout, or a recovery
|
||||
in progress does not disable anyone. With no token set, the sync is off and the
|
||||
startup log says `Okta sync DISABLED`.
|
||||
|
||||
**Two ways to sign in to Okta.** Set one of them.
|
||||
|
||||
- *API token (SSWS):* set `OKTA_API_TOKEN` to the token string. It has about 40
|
||||
letters, digits, hyphens and underscores, and no quote marks.
|
||||
- *Service app with a private key (`private_key_jwt`):* set `OKTA_SYNC_CLIENT_ID`
|
||||
(the app's client ID, it starts with `0oa`) and `OKTA_SYNC_PRIVATE_KEY` (the
|
||||
private key as a JWK). The key starts with `{` and has fields such as `kty`,
|
||||
`kid` and `d`. In Portainer, encode it as base64 first, because Portainer can
|
||||
change the quote marks in JSON. In Windows PowerShell, save the key to a file
|
||||
`key.json` and run:
|
||||
|
||||
[Convert]::ToBase64String([IO.File]::ReadAllBytes("key.json"))
|
||||
|
||||
Paste the one-line result as the value. Delete `key.json` afterward. The key is
|
||||
a secret: never put it in Git, a ticket, or a chat.
|
||||
|
||||
The Okta admin must set up the app as follows: the app type is API Services; the
|
||||
scope `okta.users.read` is granted on the Okta API Scopes tab; an admin role
|
||||
that can read users (for example Read-only Administrator) is assigned to the app.
|
||||
DPoP can be on or off. By default (`OKTA_SYNC_DPOP=auto`) the sync asks for a plain
|
||||
token first, and if Okta answers `invalid_dpop_proof` it uses DPoP. Set
|
||||
`OKTA_SYNC_DPOP` to `on` or `off` only to force one way. If both
|
||||
`OKTA_API_TOKEN` and the service-app pair are set, the token is used.
|
||||
|
||||
The startup line in the log says which credential is in use. A failed sign-in
|
||||
shows the HTTP status and the Okta error code, for example
|
||||
`Okta answered HTTP 400 to the token request, error invalid_scope`. Common codes:
|
||||
`invalid_client` (wrong client ID or key, or the key is not registered on the app),
|
||||
`invalid_scope` (the scope is not granted), `access_denied` (no admin role assigned), `invalid_dpop_proof` (DPoP was used and Okta
|
||||
rejected the proof: send the log lines to the developer), `use_dpop_nonce` (Okta kept
|
||||
asking for a new nonce).
|
||||
|
||||
**First deploy: use the dry run.** Set `OKTA_SYNC_DRY_RUN=true` in `.env` (or the
|
||||
Portainer stack environment) with the token, then run `docker compose up -d --build api`.
|
||||
The sync runs as normal but changes no account and writes no audit row. Read the
|
||||
result:
|
||||
|
||||
docker compose logs api | grep "Okta sync"
|
||||
|
||||
The summary line shows how many Okta users and active local accounts it checked,
|
||||
how many matched, and how many it would disable. A line `DRY RUN would disable ...`
|
||||
names each account. If the match count is close to your number of real users and
|
||||
the list holds only people who have left, remove `OKTA_SYNC_DRY_RUN` (or set it
|
||||
to `false`) and run `docker compose up -d api` again to go live. If the match
|
||||
count is low, the Okta attribute is wrong. Set `OKTA_SYNC_PROFILE_ATTRIBUTE`
|
||||
and run the dry run again.
|
||||
|
||||
The sync only ever disables. **It never re-enables an account.** A person comes
|
||||
back only when an admin enables the account by hand.
|
||||
|
||||
**How to see what the sync did**
|
||||
|
||||
1. Open the **Admin Console** (`admin.html`). Find the **Activity log** card.
|
||||
2. Click **Refresh**. Search for `okta_sync`, or set the type to **User accounts**.
|
||||
3. A row from the sync reads: Who `system:okta_sync`, Action `user deprovisioned
|
||||
by sync`, Item the username, Detail `okta_status: SUSPENDED` (or `MISSING` if
|
||||
the person was not in Okta's list at all).
|
||||
|
||||
Only app admins see these rows. They belong to no project.
|
||||
|
||||
**How to re-enable a person**
|
||||
|
||||
1. **Fix the person in Okta first.** Ask the Okta admin to make the person ACTIVE
|
||||
again (or to restore them, for a rehire). If you skip this step, the next sync
|
||||
cycle (up to 15 minutes later) disables the account again.
|
||||
2. Open the **User Directory** (`users.html`).
|
||||
3. Find the person. A disabled account shows the **Enable** button on its row.
|
||||
Click it.
|
||||
4. The person can sign in on their next attempt. The app writes a `user enabled`
|
||||
row to the Activity log under your name.
|
||||
|
||||
**Who may do step 3**
|
||||
|
||||
* An **app admin** may enable any account.
|
||||
* A **project super user** may enable an account only if every project the person
|
||||
belongs to is a project that super user administers. If the person is also on a
|
||||
project that the super user does not administer, the row is read-only and shows
|
||||
the reason. An app admin must make the change.
|
||||
* Nobody can change their own account.
|
||||
|
||||
**If no admin can sign in** (for example, a bad sync run disabled every admin),
|
||||
use the shell on the host. Replace `alice` with the username:
|
||||
Then prove the certificate path, without binding — this touches no account and so
|
||||
cannot contribute to a lockout:
|
||||
|
||||
```bash
|
||||
docker compose exec api python -m server.manage_users list
|
||||
docker compose exec api python -m server.manage_users enable alice
|
||||
docker compose exec api openssl s_client -connect prime.local:636 -CAfile /app/server/certs/prime-ca-chain.pem </dev/null 2>&1 | grep "Verify return"
|
||||
# want: Verify return code: 0 (ok)
|
||||
```
|
||||
|
||||
**If the sync disabled the wrong people**
|
||||
### Three things that are not obvious
|
||||
|
||||
1. Turn the sync off. Remove `OKTA_API_TOKEN` from `.env` and restart the api
|
||||
(`docker compose up -d api`). The sync starts only when the token is set.
|
||||
2. Find the cause before you turn it on again. The usual cause is that the Okta
|
||||
profile attribute does not match `users.username`. See
|
||||
`OKTA_SYNC_PROFILE_ATTRIBUTE` in `server/.env.example`.
|
||||
3. Enable the people who were disabled by mistake (steps above).
|
||||
4. Set the token again and restart.
|
||||
**Connect to the domain name, never a DC or an IP.** Every DC's certificate carries
|
||||
`prime.local` in its SAN, so the domain name both passes hostname validation and
|
||||
round-robins across all six DCs published in `_ldap._tcp.prime.local`. An IP gives
|
||||
`Verify return code: 62 (hostname mismatch)` because there is no IP SAN — and the
|
||||
only way to force it through is to disable validation. Do not. Domain passwords
|
||||
cross this link, and an unvalidated one can be terminated by anyone on the network
|
||||
who then harvests them.
|
||||
|
||||
If the sync cannot reach Okta, or Okta gives an answer the sync cannot trust, the
|
||||
sync changes **no** account in that cycle and writes a line to the api log:
|
||||
`docker compose logs api | grep "Okta sync"`.
|
||||
**The CA bundle is not a certificate issued to this app.** The API is the TLS
|
||||
*client*; clients verify, they do not present. `server/certs/prime-ca-chain.pem`
|
||||
contains `PRIME CONTROLS ROOT CA` (valid to 2051) and `PRIME CONTROLS ISSUING CA 1`
|
||||
(2036) — public certificates with no private key. There is nothing to request from
|
||||
IT, no CSR and no enrollment. Rebuild it from any domain-joined machine with:
|
||||
|
||||
## Run the stack on your own PC (T13.8)
|
||||
```powershell
|
||||
Get-ChildItem Cert:\LocalMachine\Root, Cert:\LocalMachine\CA |
|
||||
Where-Object { $_.Thumbprint -in
|
||||
'C371E91C430A12051029527C443B1EF683675CF3', # PRIME CONTROLS ROOT CA
|
||||
'4F7506105228C73DF64181ACA20AD9783437EC8B' } # PRIME CONTROLS ISSUING CA 1
|
||||
```
|
||||
|
||||
Use this to check a build in Docker before you deploy it. It needs Docker Desktop.
|
||||
Do not use it on the host.
|
||||
exporting each as Base-64 and concatenating them into one file.
|
||||
|
||||
1. Copy `.env.local.example` to `.env` in the repository root. Change the two
|
||||
`CHANGE` values: the database password and `AUTH_SECRET_KEY`.
|
||||
2. Run these commands in the repository root:
|
||||
**The `outbound` network is required.** `internal` has no default gateway, which
|
||||
blocks the LAN and the VPN as well as the internet, so the `api` container cannot
|
||||
reach `prime.local:636` without it. Its comment used to say it was optional if you
|
||||
were not using the Micron asset picker; detaching it now breaks every sign-in.
|
||||
|
||||
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build
|
||||
### Accounts
|
||||
|
||||
3. Open `http://localhost:8080/api/health`. The answer is `{"ok":true}`.
|
||||
4. Read the api log: `docker compose logs api`. The log shows each database
|
||||
migration, then one `Okta sync` line. With no `OKTA_API_TOKEN`, the line says
|
||||
`DISABLED`. That is correct.
|
||||
5. To stop it and keep the data, run
|
||||
`docker compose -f docker-compose.yml -f docker-compose.local.yml stop`.
|
||||
To stop it and delete the data, replace `stop` with `down -v`.
|
||||
Accounts are **created on first successful sign-in**, at `project_user` with **no
|
||||
project access** — the person signs in and sees nothing until an admin grants it.
|
||||
Roles are local and never read from AD, so an existing admin keeps admin.
|
||||
|
||||
What this proves: the images build, all migrations run on Postgres, and the app
|
||||
starts. What it does not prove: sign-in. Okta sends the browser back to the
|
||||
redirect URI that is set for the Okta app, and that is the production host name.
|
||||
To rehearse the Okta sync against your real Okta, add `OKTA_API_TOKEN` and
|
||||
`OKTA_ORG_URL` to `.env` and keep `OKTA_SYNC_DRY_RUN=true`. The local database has
|
||||
no real users, so every real Okta user shows as a non-match. Use it only to check
|
||||
that the token works and that the log lines appear.
|
||||
The first admin is bootstrapped in two steps: sign in once, then
|
||||
|
||||
The override file `docker-compose.local.yml` explains each change that it makes.
|
||||
```bash
|
||||
docker compose exec api python -m server.manage_users promote <sAMAccountName>
|
||||
```
|
||||
|
||||
which prompts for *your* domain credential. `list`, `demote`, `disable` and `enable`
|
||||
are the other commands; `create-admin` and `create` no longer exist.
|
||||
|
||||
### The lockout arithmetic
|
||||
|
||||
`AUTH_MAX_ATTEMPTS` defaults to **2**, and that is a safety limit rather than a
|
||||
preference. Failures are now domain binds, so they count against the **AD account
|
||||
lockout policy** (5 on this estate). The throttle is per-process and the API runs 2
|
||||
gunicorn workers, so a local limit of N allows up to 2N binds to reach a DC: 2 × 2 = 4,
|
||||
one under the threshold. **Raising this, or adding a worker, means redoing that
|
||||
arithmetic** — otherwise `/api/auth/login` becomes a way for anyone, unauthenticated,
|
||||
to lock a colleague out of Windows.
|
||||
|
||||
## Permissions roles
|
||||
|
||||
@@ -556,7 +529,7 @@ which no longer manages accounts.
|
||||
| Role | May do |
|
||||
|---|---|
|
||||
| `admin` | User administration everywhere, app settings, and every project |
|
||||
| `project_super_user` | Everything `project_admin` may do, **plus user administration on the projects they hold the role on**: pre-create accounts by username, set permissions, grant project access |
|
||||
| `project_super_user` | Everything `project_admin` may do, **plus user administration on the projects they hold the role on**: create accounts, reset passwords, set permissions, grant project access |
|
||||
| `project_admin` | On assigned projects: delete work packages, change a **completed** SOP, delete the project |
|
||||
| `project_user` | Create/edit work packages, author a SOP up to completion; may archive a WP but not delete one |
|
||||
|
||||
@@ -573,9 +546,9 @@ Its limits are what make it safe to hand out, and all of them are server-side
|
||||
* **Scope comes from projects, not the job title.** A super user administers the users
|
||||
of the projects they hold the role on — via their account role, or via
|
||||
`ProjectMember.role` for a super user on one job only. No projects, no authority.
|
||||
* **Account changes need EXCLUSIVE scope.** Disabling, renaming, changing
|
||||
permissions or deleting are global acts, so they are refused when the target
|
||||
is also on a project the caller does not administer. The directory shows
|
||||
* **Account changes need EXCLUSIVE scope.** Resetting a password, disabling, renaming,
|
||||
changing permissions or deleting are global acts, so they are refused when the
|
||||
target is also on a project the caller does not administer. The directory shows
|
||||
those rows read-only with the reason. An app admin has to make the change.
|
||||
* **No admin or super-user targets, and none granted.** A super user may hand out
|
||||
`project_admin` / `project_user` only, and may not touch an admin's or another
|
||||
|
||||
@@ -89,6 +89,11 @@ be built as written, or cannot be built once, until something else lands.
|
||||
| 7 | The creator | `docs/waves/wave-7.md` | `B7` `A1` `CR-015` `A2` `A6` `CR-014` `CR-007` `B6` `S1`(creator) `F6` `D1` `D2` `D3` `D4` `D5` `D8` `D9` `D10` |
|
||||
| 8 | Kitting and material | `docs/waves/wave-8.md` | `CR-009` `CR-010` `CR-011` `CR-012` `CR-013` `D6` `D10` |
|
||||
| 9 | Verification and cleanup | `docs/waves/wave-9.md` | `CR-008` `CR-017` `S6` `S7` `C1` `C2` `C4` `D7` |
|
||||
| 10 | Domain authentication over LDAPS | `docs/waves/wave-10.md` | `D13` |
|
||||
|
||||
Wave 10 was added on August 21, 2026 and is not part of the original nine-wave sequence. It
|
||||
is new scope (`docs/waves/decisions-2026-08-21.md`), not a reinterpretation of anything
|
||||
above, and it depends only on wave 9 being merged rather than on any particular item in it.
|
||||
|
||||
**Waves 1 through 4 produce almost no field-visible change.** That is deliberate and it is
|
||||
roughly the first third of the effort. It is called out here because the Micron team is
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Local override (T13.8). Use it only on your own PC, never on the host.
|
||||
#
|
||||
# docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build
|
||||
#
|
||||
# What it changes, and why:
|
||||
# 1. It publishes the web server on http://localhost:8080 (loopback only). On the
|
||||
# host a reverse proxy reaches the web server over the `proxy` network and no
|
||||
# port is published.
|
||||
# 2. It replaces the external `proxy` network with an ordinary bridge that this
|
||||
# stack owns. A `proxy` network that already exists on a PC may have no gateway
|
||||
# (internal), and Docker does not publish ports through such a network.
|
||||
# 3. It makes the web server answer for any host name, so http://localhost:8080
|
||||
# works. The shipped nginx config answers only for wp.controls.dev, and
|
||||
# without this every /api request from localhost gets a 404. The change is
|
||||
# made when the container starts: it removes the stock default.conf, which
|
||||
# answers to "localhost" first, and marks the app server as the default. The
|
||||
# shipped config file is not edited.
|
||||
# 4. It turns the backup service off. Its scripts are checked out with CRLF line
|
||||
# endings on Windows and cannot start (BL-070). To start it anyway, add
|
||||
# --profile backup.
|
||||
#
|
||||
# Sign-in needs a real Okta redirect URI, so this stack proves the build, the
|
||||
# database migrations on Postgres, and the Okta sync. It does not prove sign-in.
|
||||
services:
|
||||
webserver:
|
||||
ports:
|
||||
- "127.0.0.1:8080:80"
|
||||
command:
|
||||
- sh
|
||||
- -c
|
||||
- rm -f /etc/nginx/conf.d/default.conf && sed -i 's/listen 80;/listen 80 default_server;/' /etc/nginx/conf.d/wp-suite.conf && exec nginx -g 'daemon off;'
|
||||
backup:
|
||||
profiles: ["backup"]
|
||||
|
||||
networks:
|
||||
proxy: !override
|
||||
name: wp_local_proxy
|
||||
driver: bridge
|
||||
@@ -27,48 +27,26 @@ services:
|
||||
POSTGRES_HOST: db
|
||||
# Optional full-URL override (must be URL-encoded if used).
|
||||
DATABASE_URL: ${DATABASE_URL:-}
|
||||
# Signs login session cookies, AFTER Okta has confirmed who someone is.
|
||||
# REQUIRED — compose fails fast if it's unset, and the API refuses to
|
||||
# start in production without it (see server/auth.py).
|
||||
# Signs login session cookies. REQUIRED — compose fails fast if it's unset,
|
||||
# and the API refuses to start in production without it (see server/auth.py).
|
||||
AUTH_SECRET_KEY: ${AUTH_SECRET_KEY:?set AUTH_SECRET_KEY in .env (see server/.env.example)}
|
||||
AUTH_SESSION_HOURS: ${AUTH_SESSION_HOURS:-8}
|
||||
# Okta OIDC — the only sign-in path (D15/D16). Not marked required the
|
||||
# way AUTH_SECRET_KEY is: the API starts without these, it just refuses
|
||||
# every sign-in and says so in the startup log (server/okta_auth.py
|
||||
# describe()). See server/.env.example for what each one is and how to
|
||||
# get it from the Okta app integration.
|
||||
OKTA_ISSUER: ${OKTA_ISSUER:-}
|
||||
OKTA_CLIENT_ID: ${OKTA_CLIENT_ID:-}
|
||||
OKTA_CLIENT_SECRET: ${OKTA_CLIENT_SECRET:-}
|
||||
OKTA_REDIRECT_URI: ${OKTA_REDIRECT_URI:-}
|
||||
# NOT ${OKTA_IDENTITY_CLAIM:-} — server/okta_auth.py's own default only
|
||||
# applies when the env var is UNSET, and compose setting it to an empty
|
||||
# string here is not the same thing as leaving it unset. An empty value
|
||||
# would make the API look for a claim literally named "", which is
|
||||
# never present, so EVERY sign-in would 503. Mirror the same default
|
||||
# here instead, so an operator who leaves .env's copy commented out gets
|
||||
# the real default, not a broken one.
|
||||
OKTA_IDENTITY_CLAIM: ${OKTA_IDENTITY_CLAIM:-preferred_username}
|
||||
# Okta deprovisioning sync (D18, wave 13). OFF until OKTA_API_TOKEN is set; the
|
||||
# startup log says which. The token is a read-only Okta API token, NOT the OIDC
|
||||
# client secret above. Empty values here mean "unset" to the code, so the
|
||||
# ${VAR:-} form is safe for all four (unlike OKTA_IDENTITY_CLAIM above, whose
|
||||
# code default only applies when the variable is absent).
|
||||
# Reaching Okta needs outbound https. The `outbound` network the api service
|
||||
# already joins is an ordinary bridge with a gateway, so no new network is
|
||||
# needed; the host firewall must allow https to the Okta org.
|
||||
OKTA_API_TOKEN: ${OKTA_API_TOKEN:-}
|
||||
OKTA_ORG_URL: ${OKTA_ORG_URL:-}
|
||||
OKTA_SYNC_CLIENT_ID: ${OKTA_SYNC_CLIENT_ID:-}
|
||||
OKTA_SYNC_PRIVATE_KEY: ${OKTA_SYNC_PRIVATE_KEY:-}
|
||||
OKTA_SYNC_DPOP: ${OKTA_SYNC_DPOP:-}
|
||||
OKTA_SYNC_PROFILE_ATTRIBUTE: ${OKTA_SYNC_PROFILE_ATTRIBUTE:-}
|
||||
OKTA_SYNC_INTERVAL_SECONDS: ${OKTA_SYNC_INTERVAL_SECONDS:-}
|
||||
OKTA_SYNC_DRY_RUN: ${OKTA_SYNC_DRY_RUN:-}
|
||||
AUTH_SESSION_HOURS: ${AUTH_SESSION_HOURS:-12}
|
||||
# Optional — SMTP password for WP-assignment emails. Email is off by
|
||||
# default and enabled from the Admin console; this is the only email
|
||||
# secret and it is never stored in the DB. Leave unset until configured.
|
||||
SMTP_PASSWORD: ${SMTP_PASSWORD:-}
|
||||
# D13 — domain authentication. REQUIRED: the suite stores no passwords and
|
||||
# has no local fallback, so a wrong value here means nobody can sign in.
|
||||
# Connect to the DOMAIN NAME, never a DC or an IP (SAN + DNS round-robin
|
||||
# across six DCs). See server/ldap_auth.py and DEPLOYMENT.md.
|
||||
LDAP_DOMAIN: ${LDAP_DOMAIN:-prime.local}
|
||||
LDAP_HOST: ${LDAP_HOST:-prime.local}
|
||||
# Trust anchor for the DC certificate — public CA certs, baked into the image
|
||||
# at server/certs/. Override only to point at a mounted bundle.
|
||||
LDAP_CA_FILE: ${LDAP_CA_FILE:-/app/server/certs/prime-ca-chain.pem}
|
||||
# AD group required to sign in. Empty = any domain account. This is the
|
||||
# initial value; the live one is set in the Admin console (T10.5).
|
||||
LDAP_REQUIRED_GROUP: ${LDAP_REQUIRED_GROUP:-}
|
||||
# Optional — read-only SQL Server connection to the Micron asset catalog,
|
||||
# which backs the asset picker in the work package creator. Leave unset and
|
||||
# the picker cleanly falls back to manual entry (see server/assets_db.py).
|
||||
@@ -80,10 +58,15 @@ services:
|
||||
condition: service_healthy # waits for postgres to accept connections
|
||||
networks:
|
||||
- internal
|
||||
# Reaching the Micron database means leaving this compose project, and
|
||||
# `internal` is deliberately egress-free. `outbound` is attached to the api
|
||||
# container ONLY — the database and backup containers stay sealed. Detach it
|
||||
# again if you are not using the Micron asset picker.
|
||||
# Reaching the Micron database — and, since D13, the domain controllers —
|
||||
# means leaving this compose project, and `internal` is deliberately
|
||||
# egress-free. `outbound` is attached to the api container ONLY; the database
|
||||
# and backup containers stay sealed.
|
||||
#
|
||||
# DO NOT DETACH THIS. It used to be optional ("detach it if you are not using
|
||||
# the Micron asset picker"), but authentication now needs a route to
|
||||
# prime.local:636. Without it every sign-in fails and there is no local
|
||||
# password fallback to fall back to.
|
||||
- outbound
|
||||
|
||||
db:
|
||||
@@ -147,7 +130,7 @@ networks:
|
||||
# An ordinary bridge network, i.e. one that HAS a default gateway. `internal`
|
||||
# above removes the gateway entirely, which blocks not just the internet but
|
||||
# the LAN and the VPN too — so the api container needs this second network to
|
||||
# reach the Micron asset database. Attached to `api` alone: `db` and `backup`
|
||||
# remain on `internal` only and still have no way off the host.
|
||||
# Detach it from api if you are not using the Micron asset picker.
|
||||
# reach the domain controllers (LDAPS, D13) and the Micron asset database.
|
||||
# Attached to `api` alone: `db` and `backup` remain on `internal` only and
|
||||
# still have no way off the host. Required — see the note on the api service.
|
||||
driver: bridge
|
||||
|
Before Width: | Height: | Size: 307 KiB After Width: | Height: | Size: 296 KiB |
|
Before Width: | Height: | Size: 260 KiB After Width: | Height: | Size: 243 KiB |
BIN
docs/reference/baseline/after-wave10/login-1440.png
Normal file
|
After Width: | Height: | Size: 26 KiB |
BIN
docs/reference/baseline/after-wave10/login-390.png
Normal file
|
After Width: | Height: | Size: 21 KiB |
BIN
docs/reference/baseline/before-wave10/login-1440.png
Normal file
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/reference/baseline/before-wave10/login-390.png
Normal file
|
After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 169 KiB After Width: | Height: | Size: 340 KiB |
|
Before Width: | Height: | Size: 125 KiB After Width: | Height: | Size: 299 KiB |
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 132 KiB After Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 123 KiB After Width: | Height: | Size: 81 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 66 KiB After Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 43 KiB |
|
Before Width: | Height: | Size: 136 KiB After Width: | Height: | Size: 116 KiB |
|
Before Width: | Height: | Size: 98 KiB After Width: | Height: | Size: 80 KiB |
|
Before Width: | Height: | Size: 128 KiB |
|
Before Width: | Height: | Size: 112 KiB |
|
Before Width: | Height: | Size: 97 KiB |
|
Before Width: | Height: | Size: 78 KiB |
@@ -283,9 +283,7 @@ python tests/triage_check.py # A6 - the sidebar answers the stand-up
|
||||
python tests/qa_gate_check.py # CR-014/D2/D9/D10 - QA gate + capture sink 41 checks
|
||||
python tests/files_check.py # CR-007/D8 - drawings upload + real offline 36 checks
|
||||
python tests/sticky_bar_check.py # B6 - save reachable on every wizard step 12 checks
|
||||
# tests/usage_check.py (D5) removed at T11.6 - it tested the per-browser
|
||||
# analytics core and admin report, both retired in favour of CR-019's
|
||||
# server-side Activity & usage card (see docs/waves/decisions-2026-09-17.md).
|
||||
python tests/usage_check.py # D5 - one analytics core, admin report 15 checks
|
||||
python tests/creator_dialogs_check.py # S1 creator - 0 natives, errors at fields 20 checks
|
||||
```
|
||||
|
||||
@@ -294,7 +292,7 @@ Wave 8 adds these:
|
||||
```bash
|
||||
python tests/kitting_check.py # CR-009/010/012 - statuses, owner, delivery 26 checks
|
||||
python tests/kitting_notify_check.py # CR-011 - kitting mail, coalesced, gated 17 checks
|
||||
python tests/materials_check.py # D6 - material list, the CR-005 pattern 20 checks
|
||||
python tests/materials_check.py # D6 - material list, the CR-005 pattern 17 checks
|
||||
python tests/mreq_check.py # CR-013 - lightweight request, end to end 19 checks
|
||||
```
|
||||
|
||||
@@ -318,17 +316,6 @@ python tests/critical_reopen_check.py # BL-021 - on-hold mail reaches PM + CM
|
||||
python tests/console_dialogs_check.py # BL-024 - consoles/launcher: 21 natives -> 0 17 checks
|
||||
```
|
||||
|
||||
Wave 12 (CR-020, bulk user editing) adds these:
|
||||
|
||||
```bash
|
||||
python tests/bulk_users_check.py # CR-020 - bulk routes, guards, audit, CSV; NO browser 61 checks
|
||||
python tests/bulk_users_ui_check.py # CR-020 - selection, toolbar, CSV, typed delete at 1440/390px
|
||||
```
|
||||
|
||||
`console_dialogs_check.py` gained section 4 (the bulk delete prompt). `tests/cdp.py`
|
||||
passes `--do-not-de-elevate` on Windows so the probes start from an Administrator
|
||||
shell (same change as wave 16, T16.4).
|
||||
|
||||
**Three probes were re-pointed at `T7.1`.** `sections_check.py` 5b drove the live
|
||||
cross-frame toggle hand-off, which no longer exists; it now pins the surviving path and
|
||||
the fact that an UNSAVED toggle correctly does not travel - a behaviour change, recorded
|
||||
|
||||
@@ -555,289 +555,97 @@ deliberately deferred.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass, with the check
|
||||
widened so it cannot recur.
|
||||
|
||||
### BL-026 — No version stamp: "is live current?" cannot be answered from the app
|
||||
### BL-026 — CLOSED 2026-08-21 (removed; nothing referenced it)
|
||||
|
||||
- **Found during:** the 2026-08-21 outage triage (the question that started it)
|
||||
- **Where:** `Dockerfile` / build, `server/app.py` `/api/health`, admin console
|
||||
- **What:** the app carries no record of what code it is running. `/api/health`
|
||||
returns `{"ok": true}` and nothing identifies the deployed commit, so
|
||||
answering "is the live site on the latest code?" took fingerprinting
|
||||
(probing for files/routes that only exist after certain merges) in the
|
||||
middle of an outage. The fix: bake the git SHA into the image at build time
|
||||
(`ARG GIT_SHA`), return it from `/api/health`
|
||||
(`{"ok": true, "version": "<sha>"}`), and show it on the admin console's
|
||||
diagnostics card. Then currency is one glance against `git log -1`.
|
||||
- **Why not now:** new scope — needs its own item id per the working rules
|
||||
(D13 is the natural next), and it touches the image build, which deserves a
|
||||
deploy alongside someone with host access.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass; ~1 task including a
|
||||
probe check that /api/health carries a version field.
|
||||
- **Found during:** `T10.3` (D13), stripping the password code paths
|
||||
- **Where:** `server/notify.py`, `send_now()`
|
||||
- **What:** `send_now` sends one message immediately, outside the outbox queue. Its
|
||||
only caller was `forgot_password`, because a reset link must not sit in a queue.
|
||||
`T10.3` deleted that endpoint, so the function now has no callers anywhere in
|
||||
`server/` or `tests/` — verified by grep, not assumed.
|
||||
- **Resolution:** deleted. Raised as a judgement call between "remove it" and "keep
|
||||
it as the documented immediate-send path"; answered on Aug 21 — remove it. Nothing
|
||||
in `server/` or `tests/` referenced it, and its docstring explained itself entirely
|
||||
in terms of password resets, which no longer exist. Keeping an unused sender that
|
||||
bypasses the outbox is a liability, not an asset: the next person to need immediate
|
||||
mail should write it against the requirement they actually have.
|
||||
- **Note:** `send_email` (the raw SMTP call it wrapped) is untouched and still used by
|
||||
the outbox.
|
||||
|
||||
### BL-027 — Migrations are rehearsed on SQLite only; production is Postgres
|
||||
### BL-027 — Okta exists on this estate; OIDC is a live alternative to the LDAPS bind
|
||||
|
||||
- **Found during:** the 2026-08-21 production outage (D6's `material_items`
|
||||
migration crash-looped the api container)
|
||||
- **Where:** `DEPLOYMENT.md` (the update/deploy steps), `tests/`
|
||||
- **What:** the migration chain is verified end-to-end on scratch SQLite, but
|
||||
production runs Postgres, and the dialects disagree exactly where it hurts:
|
||||
`server_default=sa.text('1')` on a Boolean passed every SQLite rehearsal and
|
||||
was refused by Postgres at deploy (DatatypeMismatch), taking the API down
|
||||
until the table was created by hand. The hotfix (64eac0c) fixed that one
|
||||
instance and pinned the Boolean-default class in `materials_check`; the
|
||||
CLASS of dialect drift is still unguarded. Two cheap layers: (1) a runbook
|
||||
step — render `alembic upgrade --sql` for the postgresql dialect and read it
|
||||
before restarting (offline, needs no live DB; this render would have shown
|
||||
`DEFAULT 1` on a boolean); (2) better, a probe that renders every migration
|
||||
for the postgresql dialect on each run and fails on anything the dialect
|
||||
rejects or on known-bad patterns.
|
||||
- **Why not now:** the outage is resolved and the one known instance is fixed
|
||||
and pinned; the systematic guard is its own small task, not a hotfix rider.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass, paired with BL-026
|
||||
(both are "deploys should be boring" work).
|
||||
- **Found during:** `T10.6` (D13), repointing "Forgot password?" at
|
||||
`https://primecontrols.okta.com/`
|
||||
- **Where:** authentication as a whole — `server/ldap_auth.py`, `server/app.py` `login()`
|
||||
- **What:** D13 chose an LDAPS simple bind, decided before it was known that the company
|
||||
runs an Okta tenant. Okta presumably federates to `prime.local` (which is why the
|
||||
Windows password is still the one that binds), but its existence means an OIDC
|
||||
authorization-code flow is available in principle. That would be strictly better on
|
||||
three counts the LDAPS design cannot match: this app would never see a password at all,
|
||||
MFA would come for free, and the domain-lockout hazard that forced
|
||||
`AUTH_MAX_ATTEMPTS` down to 2 would disappear entirely, because failed attempts would
|
||||
land on Okta rather than on a bind this endpoint makes.
|
||||
- **Why not now:** D13 was decided and reaffirmed, T10.1–T10.4 are built and verified
|
||||
against the live domain, and swapping the mechanism mid-wave is exactly the reordering
|
||||
`CLAUDE.md` forbids. Recording it is not the same as reopening it.
|
||||
- **Suggested wave or follow-up:** its own item and its own decision, with Nick and
|
||||
whoever administers the Okta tenant. Not a widening of D13.
|
||||
|
||||
### BL-028 — `okta_auth.describe()` is never called
|
||||
### BL-028 — `assets_check` fails on any machine that has `MICRON_DB_URL` set
|
||||
|
||||
- **Found during:** T10.9 (writing the deploy runbook's live-verification step)
|
||||
- **Where:** `server/okta_auth.py` (`describe()`), `server/app.py` (no caller anywhere)
|
||||
- **What:** `describe()` exists specifically to shout `"*** FAKE OKTA PROVIDER
|
||||
ACTIVE..."` or report missing config at a glance, and both
|
||||
`server/.env.example` and `server/README.md` tell an operator to "check the
|
||||
startup log line" for it. Nothing prints it. `app.py` never imports or calls
|
||||
`describe()` at process start, so that log line does not exist and an operator
|
||||
following the docs will not find it.
|
||||
- **Why not now:** a runbook is documentation, not server code; wiring a
|
||||
startup log call is a real (if small) change to `app.py` and wants its own
|
||||
diff and its own verification, not a rider on T10.9.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass. One call
|
||||
(`logger.info(okta_auth.describe())` near startup) plus updating
|
||||
`DEPLOY-runbook-2026-09-03.md` Step 4 to check the log line once it exists.
|
||||
- **Found during:** `T10.7` (D13), running the full suite
|
||||
- **Where:** `tests/assets_check.py`, the "no `MICRON_DB_URL`" case
|
||||
- **What:** the check asserts `/api/assets` answers `configured:false` when the catalog
|
||||
is not configured, but `start_server` passes the ambient environment through. On a
|
||||
developer machine whose `.env` sets `MICRON_DB_URL` — which is the normal state for
|
||||
anyone who has ever used the asset picker — the API is genuinely configured, returns
|
||||
real Micron tags, and three checks fail. Nothing is wrong with the app; the test's
|
||||
premise is violated by the environment it runs in.
|
||||
- **Fix:** SET `MICRON_DB_URL` empty for that server — do not pop it. `server/db.py`
|
||||
calls `load_dotenv()` at import, and python-dotenv only skips keys already present in
|
||||
`os.environ`, so a *popped* variable is restored from the developer's `.env` inside the
|
||||
subprocess and the test runs against the real catalog anyway. An empty string counts as
|
||||
present and therefore wins. `start_server` does exactly this for `LDAP_REQUIRED_GROUP`
|
||||
(`T10.7`), after the pop-based version was caught doing the wrong thing.
|
||||
- **Why not now:** it is not this wave's defect and the fix belongs with whoever owns
|
||||
the asset picker's tests. Recorded so the failure is not mistaken for D13 fallout.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass.
|
||||
|
||||
### BL-029 — `users.failed_attempts` / `users.locked_until` are vestigial
|
||||
### BL-029 — `generalinfo_check` flags a pre-existing `rgba()` in the creator stylesheet
|
||||
|
||||
- **Found during:** T10.6
|
||||
- **Where:** `server/models.py` (`User.failed_attempts`, `User.locked_until`)
|
||||
- **What:** both columns exist to support local-password lockout, which T10.4
|
||||
removed. They are still reset to `0`/`None` on every Okta sign-in but nothing
|
||||
increments them anymore — dead columns, not a bug, but schema drift from the
|
||||
D15 cutover.
|
||||
- **Why not now:** T10.6 is documentation scope; dropping columns is a migration
|
||||
and belongs with the rest of the local-password cleanup, not folded into a
|
||||
docs task.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass, alongside any other
|
||||
post-cutover schema tidy-up.
|
||||
- **Found during:** `T10.7` (D13), running the full suite
|
||||
- **Where:** `html/wp-creation-styles.css:929` — `box-shadow:0 8px 24px rgba(20,30,50,.18)`
|
||||
- **What:** `generalinfo_check`'s token-rule check reports "no colour literal was added
|
||||
to the creator's stylesheet" and fails on `rgba(`. The literal predates this wave —
|
||||
last touched by `8efe624` (F6) — and `git diff main...HEAD` shows the file untouched
|
||||
by the LDAPS branch.
|
||||
- **The real question is which is wrong.** `C4`'s recorded exception allows rgba
|
||||
**alphas** as opacity recipes, which is arguably what a shadow is; if so the check is
|
||||
too strict and should match a colour literal rather than the `rgba(` token. If not,
|
||||
the shadow needs a token. Either way it is a one-line change plus a decision, and
|
||||
the decision is not this wave's to make.
|
||||
- **Why not now:** drive-by fixes to the token system are what `CLAUDE.md` forbids, and
|
||||
this one needs the C4 exception interpreted rather than guessed.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass, with `C4` re-read first.
|
||||
|
||||
### BL-031 — A raw `rgba()` shadow survives in the creator's stylesheet
|
||||
### BL-030 — `token_version` is now near-vestigial; decide whether it earns its place
|
||||
|
||||
- **Found during:** T10.8 (the full suite could finally run through Docker; the
|
||||
dev sandbox never had a headless browser to run it in before)
|
||||
- **Where:** `html/wp-creation-styles.css:929`, `.asset-results { ... box-shadow:0
|
||||
8px 24px rgba(20,30,50,.18); }`
|
||||
- **What:** `generalinfo_check.py` asserts the whole file carries no raw colour
|
||||
literal (comments excluded) as part of its CR-003 priority-colour check, and
|
||||
this one line fails it: 48/49. Confirmed via `git show HEAD` that the literal
|
||||
is already committed, byte-identical, unrelated to wave 10 — it is the Micron
|
||||
asset picker's dropdown shadow, which arrived with the `origin/Micron-Assets`
|
||||
merge (D11, 2026-08-20) and was never swept by `C4`'s token pass (`T9.9`
|
||||
closed before D11 merged). The fix is a straight swap:
|
||||
`theme-light.css:217` already declares `--wp-shadow-menu: 0 8px 24px
|
||||
rgba(20, 30, 50, .18)`, the identical value — this line should read
|
||||
`box-shadow:var(--wp-shadow-menu);`.
|
||||
- **Why not now:** unrelated to the Okta wave; fixing a D11-era CSS literal
|
||||
inside T10.8 (auth verification) is exactly the drive-by `CLAUDE.md` forbids.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass, with `C4`'s other
|
||||
leftovers. One-line fix, `generalinfo_check.py` already pins it (49/49 once
|
||||
fixed).
|
||||
|
||||
### BL-030 — `DEPLOY-login-portal.md` is fully stale
|
||||
|
||||
- **Found during:** T10.9
|
||||
- **Where:** `DEPLOY-login-portal.md` (repo root)
|
||||
- **What:** the original username/password login rollout doc. References
|
||||
`bcrypt`, `create-admin --password`, `AUTH_SECRET_KEY` as the only secret,
|
||||
and a login form — none of which describe the app since T10.4/T10.5. Someone
|
||||
handed this to IT today would be told to do things that no longer work.
|
||||
- **Why not now:** no task currently owns deploy-doc cleanup as a category;
|
||||
deleting or archiving a doc is a product/records call (`CLAUDE.md`'s "removed
|
||||
fields are hidden, not deleted" spirit likely applies to docs too, but that is
|
||||
worth confirming rather than assuming).
|
||||
- **Suggested wave or follow-up:** next housekeeping pass — needs Nick on
|
||||
whether to delete, archive, or rewrite it as historical record.
|
||||
|
||||
### BL-060 — A super user is told they can change access the server then refuses
|
||||
|
||||
- **Found during:** T12.6 (CR-020 verification, the CSV path)
|
||||
- **Where:** `server/app.py` `manage_user_problem` (the reason text), `get_user_projects` / `set_user_projects` (the rule)
|
||||
- **What:** for an account that is also on a project the super user does not
|
||||
administer, the refusal reason ends "You can still change their access and
|
||||
role on your own projects." Neither the project-access dialog's routes nor
|
||||
the CR-020 bulk project route allow that: all of them call
|
||||
`require_manage_user`, which refuses the account. The bulk route mirrors the
|
||||
single route on purpose (CR-020: same rules), so the words promise something
|
||||
neither path does. Either the text or the rule is wrong; which one is a
|
||||
product call.
|
||||
- **Why not now:** changing either is out of CR-020's scope (the wave must
|
||||
not widen what a super user can do), and it needs a decision.
|
||||
- **Suggested wave or follow-up:** needs Nick: should a super user be able to
|
||||
add or remove a shared account on their own projects? Then fix the text or
|
||||
the rule, not both.
|
||||
|
||||
### BL-061 — The sync badge covers controls while it shows
|
||||
|
||||
- **Found during:** T12.6 (the wave 12 screenshots)
|
||||
- **Where:** `html/project-data.js` `renderSyncBadge` (fixed bottom-right, `z-index:9998`)
|
||||
- **What:** for about 2 seconds after each sync the "Everything sent to the
|
||||
project" badge sits over whatever is in the bottom-right corner: a Delete
|
||||
button on the User Directory at 1440px, the bulk bar's "Set permissions" at
|
||||
390px. It is `pointer-events:none`, so clicks pass through, but the control is
|
||||
hidden while it shows, and on the console pages there is no outbox work to
|
||||
report at all.
|
||||
- **Why not now:** `project-data.js` is shared by every page and owned by the
|
||||
outbox work in wave 14 (T14.1 to T14.3 change this badge's states anyway).
|
||||
- **Suggested wave or follow-up:** wave 14, alongside T14.1's badge changes:
|
||||
do not show the badge on pages with nothing to sync, and keep it clear of
|
||||
page controls.
|
||||
|
||||
<<<<<<< ours
|
||||
### BL-069 - The sync has no cap on one run and no last-admin guard
|
||||
|
||||
- **Found during:** T13.3 (D18)
|
||||
- **Where:** `server/okta_sync.py` `run_sync()`
|
||||
- **What:** a run disables every account the rules select, however many. If the
|
||||
identity attribute is partly wrong (it matches some accounts and not others),
|
||||
one run can disable most of the company, including every admin. The
|
||||
zero-match guard only stops the case where nothing matches. Disabled accounts
|
||||
cannot sign in, so re-enabling needs an admin who is still active, or the
|
||||
`manage_users.py` command line on the host.
|
||||
- **Why not now:** D18 does not ask for it, and the right limit is a product
|
||||
call: a count, a share of accounts, a rule that the last active admin never
|
||||
disables, or all three.
|
||||
- **Suggested wave or follow-up:** before the first live run, or in T13.6 if
|
||||
Matt decides. Needs Matt.
|
||||
|
||||
=======
|
||||
## Future build: mobile app and scaling
|
||||
|
||||
Logged 2026-10-12 from the meeting with Nick. The answers are in
|
||||
`docs/waves/decisions-2026-10-12.md` (Q2 to Q14). The path from here to a
|
||||
mobile version outside the VPN, across projects, is in
|
||||
`docs/waves/roadmap-mobile-scaling.md`. These are features for a future
|
||||
build. They have no wave and no `CR-`/`D-` id yet. Give each one an id when a
|
||||
wave is planned. Items marked "to confirm" have an open question listed in the
|
||||
decision file ("Still open"). Do not build them until it is answered.
|
||||
|
||||
Follow-up answers from Matt on 2026-10-12 are folded into the entries below.
|
||||
|
||||
Server work is needed for BL-062 to BL-066 (CLAUDE.md, "Frontend and backend
|
||||
boundary"). Do not use `localStorage` as the store of record.
|
||||
|
||||
### BL-062 - Offline Field View for crews
|
||||
|
||||
- **From:** Q2, Q3
|
||||
- **What:** Field View opens offline for up to **7 days** after the last sign-in
|
||||
(today: 12 hours). Only crews in Field View work offline. The creator has no
|
||||
offline mode. When the app opens online again and the account is disabled,
|
||||
wipe that account's local data.
|
||||
- **Why not now:** new scope. It needs an id, and it follows the outbox work in
|
||||
wave 14 (T14.1 to T14.3).
|
||||
- **Suggested wave or follow-up:** future mobile wave. Check it against the D18
|
||||
session rules (idle timeout, absolute ceiling): a 7 day offline window and a
|
||||
session ceiling must agree on what "signed in" means.
|
||||
|
||||
### BL-063 - Offline edit conflicts: merge, notify, log
|
||||
|
||||
- **From:** Q4
|
||||
- **What:** When an offline edit meets a newer server version, the app merges
|
||||
the two, shows a notification to the crew, writes a log entry, and updates the
|
||||
owner. If both sides changed the same field, **the field value wins**, and the
|
||||
app keeps a **history of changes**. This replaces the earlier default (keep
|
||||
both, crew chooses).
|
||||
- **To confirm:** who "the owner" is, how long the history is kept, and who can
|
||||
read it. See the decision file, "Still open" item 2.
|
||||
- **Suggested wave or follow-up:** same wave as BL-062.
|
||||
|
||||
### BL-064 - Field photo limits
|
||||
|
||||
- **From:** Q5
|
||||
- **What:** a limit of **5 MB per photo**. This equals the D8 limit that the
|
||||
server already enforces for drawings (`FILE_MAX_BYTES`), so photos can use the
|
||||
same upload path and the same D19 download headers.
|
||||
- **To confirm:** the count per package, and whether the app resizes a photo
|
||||
before upload (phone photos are often 3 MB to 8 MB). Decision file, "Still
|
||||
open" item 1.
|
||||
- **Suggested wave or follow-up:** same wave as BL-062.
|
||||
|
||||
### BL-065 - Batch print and merged PDF
|
||||
|
||||
- **From:** Q6, Q7, Q8, Q9
|
||||
- **What:** print many packages in one PDF.
|
||||
- Limit: **25 packages on phones**. On desktop the user can scale the filter
|
||||
up to 50 or 100. Open: who sets the larger value (each user, or an admin
|
||||
setting). Decision file, "Still open" item 5.
|
||||
- Drawings go **after the form**, in **upload order**, **scaled to fit**.
|
||||
- SVG drawings are **left out**. A page names each file that was left out.
|
||||
- Every page shows the **package number, the print date, and page X of Y**.
|
||||
- **Related:** BL-000d (merge or list attachments on export) asked the same
|
||||
question for CR-008. This entry answers the layout part of it.
|
||||
- **Suggested wave or follow-up:** future print wave.
|
||||
|
||||
### BL-066 - Keep drawings when a package is deleted
|
||||
|
||||
- **From:** Q13
|
||||
- **What:** deleting a package no longer deletes its drawings. Keep them for
|
||||
data retention. **The storage quota is freed** when the package is deleted.
|
||||
Storage will move to cloud storage in a future deployment. This replaces the
|
||||
earlier default (delete with the package).
|
||||
- **Today:** drawing bytes live in the Postgres `wp_files` table (CR-007, D8).
|
||||
The 2 GB per project limit counts them. Kept files must not count toward that
|
||||
limit, so the count has to change.
|
||||
- **To confirm:** retention period, who can delete for good, who can recover.
|
||||
See the decision file, "Still open" item 3.
|
||||
- **Suggested wave or follow-up:** roadmap Phase 3 (object storage). It affects
|
||||
D19 (safe download) paths too: recovered files must keep the attachment and
|
||||
sandbox headers.
|
||||
|
||||
### BL-067 - Ready for QA progress weight is 0.85
|
||||
|
||||
- **From:** Q12
|
||||
- **What:** change the progress weight for Ready for QA from 0 to **0.85**.
|
||||
Today a package falls from 75% to 0% when it reaches Ready for QA.
|
||||
- **Why not now:** it changes a shipped number on dashboards and roll-ups. Use
|
||||
its own item id and re-run the roll-up checks.
|
||||
- **Suggested wave or follow-up:** future wave. Small task.
|
||||
|
||||
### BL-068 - One cost-code list, kept in the SOP
|
||||
|
||||
- **From:** Q14
|
||||
- **What:** the creator has 38 cost codes, the SOP has 39, and 13 differ. Keep
|
||||
**one list, in the SOP**, and make the creator read it.
|
||||
- **Blocked on:** the correct codes. The **PM** supplies them (decided
|
||||
2026-10-12). The date is not set. This is a data question and not a code
|
||||
question.
|
||||
- **Related:** BL-019 (closed) made a stored code that has left the list stay
|
||||
as an option. Keep that behavior when the list changes.
|
||||
- **Suggested wave or follow-up:** future wave, after the codes arrive.
|
||||
>>>>>>> theirs
|
||||
|
||||
### BL-070 - Shell scripts get CRLF line endings on Windows, and the backup container cannot start
|
||||
|
||||
- **Found during:** T13.8 (local Docker run)
|
||||
- **Where:** `scripts/*.sh`, no `.gitattributes` in the repository
|
||||
- **What:** Git for Windows checks out `scripts/entrypoint.sh` with CRLF line endings.
|
||||
The container then fails with `exec /app/entrypoint.sh: no such file or directory`
|
||||
and restarts in a loop. The files are stored with LF in Git, so the host (Linux) is
|
||||
not affected. Any PC build is.
|
||||
- **Why not now:** T13.8 only makes the local run work. The override turns the backup
|
||||
service off. A `.gitattributes` rule (`*.sh text eol=lf`) is a repository-wide change.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass. Add `*.sh text eol=lf` and
|
||||
renormalize.
|
||||
|
||||
### BL-071 - smoketest.py cannot sign in against http://localhost
|
||||
|
||||
- **Found during:** T13.6 (final verification)
|
||||
- **Where:** `server/smoketest.py` `seed_session_cookie()`
|
||||
- **What:** the script puts the session cookie in a Python cookie jar for the domain `localhost`. The jar treats
|
||||
a host without a dot as `localhost.local`, so it does not send the cookie, and every call after sign-in returns 401.
|
||||
With `http://127.0.0.1:PORT` the same script passes 27 of 27.
|
||||
- **Why not now:** it is a test-script quirk and not part of D18. The documented usage lines show `http://localhost:8000`.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass: use the domain `localhost.local` for a dotless host,
|
||||
or change the usage lines to `127.0.0.1`.
|
||||
- **Found during:** `T10.7` (D13), closing the done-when that assumed a role change bumps it
|
||||
- **Where:** `server/models.py` (`User.token_version`), `server/auth.py` (`create_token`,
|
||||
`get_current_user`), `server/manage_users.py` (`_set_active`)
|
||||
- **What:** `token_version` existed to invalidate live sessions when a password changed.
|
||||
D13 removed passwords, and **nothing in `app.py` bumps it any more** — not
|
||||
`set_user_role`, not `set_user_active`. Nor do they need to: `get_current_user` loads
|
||||
the account from the database on every request, so a role change or a deactivation
|
||||
takes effect on the next request regardless. `T10.3`'s note that "role changes and
|
||||
deactivation should bump it" describes an intention, not the code.
|
||||
- **Its one remaining trigger** is the bump added to `manage_users._set_active` in
|
||||
`T10.9`, which is belt-and-braces rather than load-bearing — `is_active` alone already
|
||||
refuses the request.
|
||||
- **The question:** is there still a case for invalidating a live cookie *without* also
|
||||
disabling the account? If yes, wire it to something (a "sign out everywhere" control is
|
||||
the usual shape) and say so. If no, the column, the claim, and the check are three
|
||||
places carrying a mechanism nothing triggers.
|
||||
- **Why not now:** it is a design question about session handling, not an auth-wave bug,
|
||||
and the mechanism works correctly — it is exercised in `ldap_auth_check`.
|
||||
- **Suggested wave or follow-up:** next housekeeping pass.
|
||||
|
||||
@@ -1,97 +0,0 @@
|
||||
# Context handoff: Work Package Suite
|
||||
|
||||
> Update 2026-10-16: waves 11 and 13 (T13.2 to T13.5) are on the release branch `release/waves-11-13-okta-sync`, with T13.1 held back. The branch and wave status tables below describe 2026-10-12. See `docs/waves/wave-13.md` for the current state.
|
||||
|
||||
Date: 2026-10-12
|
||||
Purpose: Give a new chat the facts about waves 11, 12, 13, and 16.
|
||||
This file is a handoff note. It is not a spec. The spec files stay the source of truth (`IMPLEMENTATION.md`, `docs/waves/*`, `CLAUDE.md`).
|
||||
It was checked against `git` on 2026-10-12. Earlier chat summaries about this repo are out of date. Use this file.
|
||||
|
||||
## 1. Branch state
|
||||
|
||||
| Branch | State |
|
||||
|---|---|
|
||||
| `main` | At `d42ae0c` (2026-10-06). Contains wave 12 (CR-020, bulk user editing) and wave 16 (D19, D20, D21), both merged by PR. |
|
||||
| `feat/waves-11-13` | Local and `origin` are the same commit, `da1325c`. It is pushed. It is not merged. It is 13 commits ahead of `main` and 19 behind. |
|
||||
| `notes/cr019-usage-metrics-d18-deprovisioning` | Holds the same wave 11 work plus the session notes. |
|
||||
|
||||
Correction to an earlier statement: the Gitea push is no longer blocked. The branch is on `origin`.
|
||||
|
||||
Merge rule from `wave-12.md`: T13.1 (idle timeout) must not reach `main` before T14.1. Do not merge `feat/waves-11-13` into `main` as a whole without a decision from the user. Wave 11 and T13.1 are on the same branch.
|
||||
|
||||
Working tree on `main` (2026-10-12) has two untracked files: `WorkPackageSuite_Consolidated_Change_Request_R2.docx` and `docs/waves/decisions-2026-08-25.md`. Do not delete them.
|
||||
|
||||
## 2. What is on `feat/waves-11-13`
|
||||
|
||||
| Commit | Task | Item |
|
||||
|---|---|---|
|
||||
| `75ac930` | Planning docs for CR-019, CR-020, D18 | CR-019, CR-020, D18 |
|
||||
| `0652fa7` | T11.1 UsageEvent model and migration | CR-019 |
|
||||
| `850b789` | T11.2 capture usage events | CR-019 |
|
||||
| `3584695`, `6cde6e3` | T13.1 idle timeout with an absolute ceiling | D18 |
|
||||
| `8e863ae` | T11.3 aggregation endpoint with filters | CR-019 |
|
||||
| `2de76d5` | T11.4 usage export (raw and sanitized CSV) | CR-019 |
|
||||
| `a6c3fbf`, `0b5ab59` | T11.5 admin console "Activity & usage" card, checked at 390px and 1440px | CR-019 |
|
||||
| `b2a083a` | T11.6 retire the per-browser Usage report | CR-019 |
|
||||
| `2842ec9` | Session notes for 2026-09-23 | none |
|
||||
| `4f3a94b` | T11.6 follow-up: fix `tests/autosave_check.py` | CR-019 |
|
||||
| `da1325c` | T11.7 full verification pass. Wave 11 closed on 2026-09-24. | CR-019 |
|
||||
|
||||
Notes:
|
||||
- `html/wp-usage.js` and `tests/usage_check.py` were deleted in T11.6. The `track()` functions in `wp-creation-app.js` and `work-package-suite-app.js` are now documented no-ops. About 45 call sites stay.
|
||||
- T11.7 found a real regression that T11.6 caused. `tests/autosave_check.py` still expected the retired tracker to write to `localStorage`. The test was fixed. It now passes 33 of 33. The cause was that T11.6 ran only `tests/baseline_shots.py`, not the full suite. Run the full suite for any frontend task.
|
||||
|
||||
## 3. T11.7 verification results (2026-09-24)
|
||||
|
||||
- Alembic: upgrade, downgrade, upgrade on SQLite passed. The SQL render for Postgres was clean (this catches SQLite-only DDL, the "BL-027 class" of defect).
|
||||
- Test scripts: 38 of 39 passed after the autosave fix.
|
||||
- Two known failures that are not regressions:
|
||||
- `token_check.py` exits 2. This is a CLI usage detail.
|
||||
- `generalinfo_check.py` finds an old color-literal gap in `wp-creation-styles.css`.
|
||||
|
||||
## 4. Wave status
|
||||
|
||||
| Wave | Items | Status |
|
||||
|---|---|---|
|
||||
| 10 | Okta OIDC sign-in (D15, D16) | Done. In production. |
|
||||
| 11 | CR-019 usage and activity metrics | Done on `feat/waves-11-13`. Not on `main`. |
|
||||
| 12 | CR-020 bulk user editing | Done. Merged to `main` on 2026-10-06 (T12.1 to T12.6). |
|
||||
| 13 | D18 Okta/AD deprovisioning sync | T13.1 done on `feat/waves-11-13`. T13.2 and later are not started. T13.3 must fail closed. Do not relax that. |
|
||||
| 14, 15 | Not checked in this handoff | T14.1 must land before T13.1 reaches `main`. Read the wave files before you plan. |
|
||||
| 16 | D19 safe downloads, D20 one SOP per project, D21 session decode fails closed | Done. Merged to `main` on 2026-10-06. |
|
||||
|
||||
Wave 16 decisions (`docs/waves/decisions-2026-10-02.md`): SEC-06 (session revocation) waits for the AWS work. Other SEC findings stay as backlog drafts in `docs/reference/security-review/backlog-drafts.md`.
|
||||
|
||||
## 5. Rules that apply here (`CLAUDE.md`)
|
||||
|
||||
- Every change traces to an item ID (`CR-`, `F`, `S`, `A`, `B`, `C`, `D`, task `T<wave>.<n>`). New scope gets a new ID.
|
||||
- One task per PR. Put the task ID and item IDs in the commit message and PR title.
|
||||
- Do not fix other problems that you see. Log them in `docs/waves/backlog.md`.
|
||||
- Do not reorder waves. Do not start a wave before the previous wave is merged, unless the task says it is independent.
|
||||
- Server work is needed for CR-004, CR-018, CR-007, CR-011, CR-014, CR-013, and B4. Do not use `localStorage` for these.
|
||||
- Do not change: Actual Hours in Closeout (CR-017), localization (A7), uppercase card headers in `console.css` (A5), the logged-override path `confirmEarlyRelease()` (A1), or hidden-not-deleted fields (CR-002, CR-016).
|
||||
- Token rule: one place defines color, spacing, and type. Do not add raw hex values to page stylesheets.
|
||||
- Accessibility (C1): use real `<button>`, `<a>`, or input elements. Add `aria-live` for status changes. Keep focus visible. Text contrast is 4.5:1 (3:1 for large text).
|
||||
- Frontend checks: run `uvicorn server.app:app` on a throwaway SQLite database. Check 390px and 1440px. Capture before and after screenshots. Run the smoke test.
|
||||
- If a done-when check cannot be run, do not mark the task complete. Say which check failed and why.
|
||||
|
||||
## 6. Environment on the user's PC
|
||||
|
||||
- Python was installed with `winget`. Tests use the repo `.venv`.
|
||||
- Browser tests (`tests/cdp.py` and about 40 `*_check.py` scripts) need Edge or Chrome. `cdp.py` starts from an elevated shell (wave 16 note). The Linux sandbox cannot run them.
|
||||
- See `C:\Users\m.mabrey\GIT\Field Value Driver\sde-meeting-toolkit\docs\context\environment-notes.md` for tool problems (PowerShell `$` removal, long git paths, the 180 second command limit).
|
||||
|
||||
## 7. Open items
|
||||
|
||||
1. Decide how `feat/waves-11-13` reaches `main`. The T13.1 and T14.1 order is the constraint.
|
||||
2. Plan the next wave. T13.2 and later need an explicit instruction.
|
||||
3. Future build list added 2026-10-12: `BL-062` to `BL-068` in `docs/waves/backlog.md` (mobile app, offline Field View, batch print, and related items). Answers are in `docs/waves/decisions-2026-10-12.md` (follow-ups from Matt included). The path to a mobile version outside the VPN is in `docs/waves/roadmap-mobile-scaling.md` (phases 0 to 5; confirmed: all users in the Okta group, multiple customers, company-managed devices; nine open questions in its section 7). These files are uncommitted edits on `main`.
|
||||
4. Work from the other chat (the SDE Meeting Toolkit) does not touch this repo. See the toolkit `docs/context/` folder.
|
||||
|
||||
## 8. Related files
|
||||
|
||||
- `IMPLEMENTATION.md` (sections 2 and 4)
|
||||
- `docs/waves/wave-11.md`, `wave-12.md`, `wave-13.md` (on `feat/waves-11-13`), `wave-16.md`
|
||||
- `docs/waves/decisions-2026-09-17.md` (CR-019, CR-020, D18), `decisions-2026-10-02.md` (D19, D20, D21)
|
||||
- `docs/waves/notes-2026-09-23.md` (on `feat/waves-11-13`)
|
||||
- `docs/waves/backlog.md`
|
||||
210
docs/waves/decisions-2026-08-21.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Decisions — August 21, 2026
|
||||
|
||||
One item, and it is the largest single change to the auth model since the login portal
|
||||
shipped. Like the August 18 and August 20 sets it is a **new item** with its own `D` id,
|
||||
not a reinterpretation of an existing one. `D1`–`D12` are taken; this is `D13`.
|
||||
|
||||
Raised by Cody Schaefer on Aug 21 2026 while asking how the suite handles HTTPS. Nothing in
|
||||
`IMPLEMENTATION.md`, in `CR`/`F`/`S`/`A`/`B`/`C`, or in `docs/waves/backlog.md` covers
|
||||
authentication against the domain — so this is new scope, and it gets a new ID rather than
|
||||
being folded into the login-portal work that produced `server/auth.py`.
|
||||
|
||||
---
|
||||
|
||||
## D13 — Authentication moves to the domain over LDAPS
|
||||
|
||||
- **Amends:** the authentication model shipped in `DEPLOY-login-portal.md` (bcrypt hashes in
|
||||
`users.password_hash`, verified in-process). That document describes what is being
|
||||
replaced, not what is wrong — it was correct for a suite with no directory behind it.
|
||||
- **Surface:** `server/` (`auth.py`, `app.py`, `models.py`, `manage_users.py`, `notify.py`,
|
||||
a new `ldap_auth.py`, a new migration), `html/` (`login.html`, `login.js`, `admin.js`,
|
||||
`users.js`), `requirements.txt`, `docker-compose.yml`, `Dockerfile`, deployment docs.
|
||||
- **Wave:** 10 (`docs/waves/wave-10.md`). Depends on wave 9 merged, which it is.
|
||||
|
||||
### The decision
|
||||
|
||||
The suite stops storing passwords. A sign-in becomes a **simple bind to
|
||||
`ldaps://prime.local:636`** as `<username>@prime.local` using the password the person typed.
|
||||
A successful bind is the authentication. `users.password_hash` is dropped from the schema.
|
||||
|
||||
Four parts, all four required for the item to be done:
|
||||
|
||||
1. **LDAPS bind replaces local password verification.** `password_hash` is removed from the
|
||||
model and from the database by migration. No password is stored, hashed or otherwise.
|
||||
2. **Accounts are provisioned just-in-time.** A successful bind for a username with no
|
||||
`users` row creates one, at the default role, with `full_name`/`email` read from the
|
||||
directory.
|
||||
3. **A required group gates login.** An AD group is configured; a bind that succeeds but
|
||||
whose account is not in that group is refused. Membership is evaluated including nested
|
||||
groups.
|
||||
4. **Existing accounts keep their roles, and roles stay local.** An existing `admin` stays
|
||||
an admin on first directory login. Granting admin to an existing account continues to
|
||||
work from the Admin console. The directory supplies *identity*; this app supplies
|
||||
*authorization*.
|
||||
|
||||
### Why LDAPS and not the certificate already in play
|
||||
|
||||
Recorded because the question was asked directly and the answer is not obvious.
|
||||
|
||||
The site's serving certificate is a **Let's Encrypt** cert (`CN=wp.controls.dev`, issued by
|
||||
`Let's Encrypt YE2`, expiring 2026-11-08) held by an **OpenResty** instance at
|
||||
`192.168.3.56` that is not part of this repo. It is a public domain-validated certificate.
|
||||
It attests that whoever presented it controls DNS for `wp.controls.dev`; it carries no user
|
||||
identity and no relationship to `prime.local`. There is no configuration that turns it into
|
||||
a domain credential, so cert-based auth was never available "for free".
|
||||
|
||||
Client-certificate auth (mTLS) was considered and rejected for this wave: TLS terminates two
|
||||
hops upstream at OpenResty, so the API never sees the handshake, and doing it in-app would
|
||||
mean bypassing the proxy and losing the CSP/HSTS headers and static serving with it.
|
||||
|
||||
### What was verified before writing this (Aug 21 2026)
|
||||
|
||||
| Fact | Value |
|
||||
|---|---|
|
||||
| LDAPS reachable | `192.168.3.37:636` open, TLS 1.3, `TLS_AES_256_GCM_SHA384` |
|
||||
| DC cert issuer | `CN=PRIME CONTROLS ISSUING CA 1, DC=prime, DC=local` |
|
||||
| Root of that chain | `CN=PRIME CONTROLS ROOT CA` (self-signed, expires 2051-09-09) |
|
||||
| Issuing CA expiry | 2036-09-09 |
|
||||
| DC cert SAN | `DR-DC10Core.prime.local`, `prime.local`, `PRIME` |
|
||||
| DCs published in `_ldap._tcp.prime.local` | six — `nla-dc10`, `lew-dc20`, `dr-dc30-core`, `lew-dc40`, `SABINEDC`, `dr-dc10core` |
|
||||
| Chain validates against root+issuing bundle | yes — `Verify return code: 0 (ok)` |
|
||||
|
||||
Two consequences of that table, both binding on the build:
|
||||
|
||||
- **Connect to `prime.local`, not to a DC name or an IP.** Every DC's certificate carries
|
||||
`prime.local` in its SAN, so the domain name both passes hostname validation and
|
||||
round-robins across all six DCs. Verified: `prime.local` gives `0 (ok)`; the raw IP
|
||||
`192.168.3.37` gives `62 (hostname mismatch)`, because there is no IP SAN.
|
||||
- **The trust anchor is a CA certificate, not a certificate issued to this app.** The API is
|
||||
the TLS *client*; clients present nothing. It needs `PRIME CONTROLS ROOT CA` plus
|
||||
`PRIME CONTROLS ISSUING CA 1` as a PEM bundle, which is public information. No CSR, no
|
||||
enrollment, no private key, nothing to request from IT.
|
||||
|
||||
### Non-negotiables
|
||||
|
||||
These are the ways this change goes wrong, and each has a done-when check in wave 10.
|
||||
|
||||
- **An empty password must be rejected before `bind()` is called.** In LDAP a simple bind
|
||||
with an empty password is an *anonymous* bind and it **succeeds**. Without an explicit
|
||||
guard, a blank password authenticates as any username submitted. This is the single
|
||||
highest-severity failure mode in the item and it gets its own test.
|
||||
- **`validate=ssl.CERT_REQUIRED` with an explicit CA file.** Not `CERT_NONE`, and not the
|
||||
system trust store. `CERT_NONE` still encrypts, so it fails silently — what it loses is
|
||||
the ability to distinguish the real DC from an attacker who terminates the TLS session,
|
||||
harvests the domain password and relays the bind onward. Since domain credentials now
|
||||
cross that channel, a compromise escalates from "this app" to Windows, mail and file
|
||||
shares. The system store is refused separately because it currently trusts five other
|
||||
self-signed CAs (`prime-DR-CAPRIME-CA`, `prime-DR-CA_PRIME-CA`, `prime-DR-DC20-CA`,
|
||||
`PRIME CONTROLS ISSUING CA 2`, and a stray `L55401TDKLY3.prime.local` machine cert in
|
||||
Trusted Root).
|
||||
- **The app's lockout must trip below the domain's.** `LOGIN_MAX_ATTEMPTS` currently writes
|
||||
to the local `users` row. Once failures are binds, they count against the **AD** lockout
|
||||
policy, so an unauthenticated caller hammering `/api/auth/login` can lock real domain
|
||||
accounts out of Windows. The local throttle must stop calling the DC before the domain
|
||||
threshold is reached.
|
||||
- **Never leak which usernames exist.** `login()` today equalises response timing on purpose
|
||||
so a caller cannot enumerate accounts. Directory error 49 sub-codes (`52e` bad password,
|
||||
`532` password expired, `533` disabled, `775` locked) are useful in the log and must not
|
||||
reach the response body.
|
||||
|
||||
### Answered August 21, 2026 — both were raised as open and both were decided
|
||||
|
||||
**Break-glass: none. LDAPS is the only way in.** Asked and reaffirmed after the lockout risk
|
||||
was stated. There is no emergency local account, no env-var bypass, and no CLI-minted
|
||||
session. The consequence is explicit and belongs in the runbook rather than being discovered:
|
||||
**if the domain is unreachable, or `LDAP_CA_FILE` is wrong, or the required group is
|
||||
misconfigured, nobody can sign in — including admins — and no amount of shell access fixes
|
||||
it except correcting the configuration and restarting.** `T10.5`'s validate-on-save guard is
|
||||
therefore not a nicety; with no fallback it is the only thing standing between a typo in the
|
||||
group field and a total outage.
|
||||
|
||||
Three things follow, and they are done-when checks in wave 10 rather than advice:
|
||||
|
||||
- The startup log must state whether LDAP is configured and reachable, so a broken deploy is
|
||||
visible in `docker compose logs api` and not only at the login box.
|
||||
- `/api/health` stays exempt from auth (it already is) so the outage is diagnosable.
|
||||
- The group setting cannot be saved without proving the saving admin is a member.
|
||||
|
||||
**Identity: bind on `sAMAccountName`, match on `sAMAccountName` *or* `mail`.** A simple bind
|
||||
can only carry one identifier, and AD accepts the UPN form — so the bind is
|
||||
`sAMAccountName@prime.local` and that is what the login box takes. Matching an existing local
|
||||
row is a separate question, and it uses **both**: after a successful bind the directory's
|
||||
`sAMAccountName` and `mail` are both read, and `auth.find_user` is extended to match a local
|
||||
row on either, case-insensitively. That is what keeps an existing admin's role whether their
|
||||
hand-typed username was `c.schaefer` or `c.schaefer@prime-controls.com`.
|
||||
|
||||
Two consequences worth knowing:
|
||||
|
||||
- The mail domain (`prime-controls.com`) is not the AD domain (`prime.local`), so `mail` is
|
||||
never a valid bind string. It is a matching key only.
|
||||
- If someone types an address at the login box, the local part is used as the
|
||||
`sAMAccountName` — **one** bind attempt, never several, because each failed bind counts
|
||||
against the domain lockout policy. That assumes the mail local part equals the
|
||||
`sAMAccountName`. Where it does not, the person must type their short logon name; this is
|
||||
logged when it happens and documented in `T10.8`.
|
||||
- The production `users` table should still be compared against AD before this deploys. A
|
||||
row matching on neither key gets a *second*, JIT-provisioned account at the default role
|
||||
rather than keeping its admin. Matching on two keys narrows that risk; it does not remove
|
||||
it.
|
||||
|
||||
### Explicitly out of scope
|
||||
|
||||
- mTLS / client-certificate authentication (see above).
|
||||
- Kerberos / SPNEGO single sign-on. It is the better long-term answer for domain-joined
|
||||
desktops and needs a keytab, an SPN and browser trust configuration; it is not this item.
|
||||
- Group-to-role mapping (e.g. an AD group that confers `project_admin`). Criterion 4 keeps
|
||||
authorization local on purpose. Worth its own item later; logged in `backlog.md`.
|
||||
- Replacing the Let's Encrypt certificate or changing anything on the OpenResty host.
|
||||
|
||||
---
|
||||
|
||||
## D14 — The CLI authenticates against the domain, and stops creating accounts
|
||||
|
||||
- **Amends:** `D13` criterion 4, which said role granting keeps working *from the Admin
|
||||
console*. It said nothing about `manage_users.py`, which had no authentication of any
|
||||
kind. Requiring one is a new requirement, so it gets its own id rather than widening
|
||||
criterion 4.
|
||||
- **Surface:** `server/manage_users.py`
|
||||
- **Task:** `T10.9`
|
||||
|
||||
### The decision
|
||||
|
||||
1. **`create-admin` and `create` are removed.** `D13` provisions accounts on first
|
||||
successful sign-in, so creating them by hand is redundant. Removing them also closes a
|
||||
class of problem: every row now originates from a bind, so a username cannot be typed
|
||||
in wrong and end up orphaned from the directory identity it was meant to match. That
|
||||
risk now applies only to rows the old CLI already created.
|
||||
2. **`promote` and `demote` replace them.** The directory supplies identity; this app
|
||||
supplies authorization, and this is where authorization is assigned from a shell.
|
||||
3. **Every state-changing command requires a domain bind.** Prompted, via `getpass`.
|
||||
There is deliberately no `--password` flag: that would put a live domain password into
|
||||
shell history and into `ps` output for every other user on the box.
|
||||
4. **`list` needs no credential**, so an outage stays diagnosable.
|
||||
|
||||
### Bootstrapping the first admin, which changed shape
|
||||
|
||||
Two steps, in order: **sign in once** (which provisions the account at `project_user`),
|
||||
then **`promote <sAMAccountName>`**. Before D14 the first admin was created with a
|
||||
password; there is no password now, and no account to create.
|
||||
|
||||
### What this is worth, stated plainly
|
||||
|
||||
Anyone with a shell on the api container can still write to the `users` table directly
|
||||
with `psql` or `sqlite3`. So the bind is **defence in depth and, mostly,
|
||||
ACCOUNTABILITY** — not a security boundary. Before D14 every role change made from a
|
||||
shell was invisible in `AuditLog` while the same change through the console was recorded;
|
||||
now both are recorded and both name a person. Any-domain-user was accepted as sufficient
|
||||
(no privileged group exists on this estate, and machine access is already restricted to a
|
||||
few people), which was decided knowing the above.
|
||||
|
||||
### Two deliberate divergences from the API
|
||||
|
||||
- **The bind does NOT apply the login group gate.** If a mistyped required group locks
|
||||
everyone out of the console, this tool has to still work — otherwise the only route to
|
||||
fixing the lockout is the thing the lockout prevents.
|
||||
- **Changing your OWN role is permitted here.** `set_user_role` in `app.py` forbids it to
|
||||
stop an admin locking themselves out of the console. Here it is the entire bootstrap
|
||||
path, so it is allowed and recorded with `{"self": true}` in the audit detail.
|
||||
|
||||
The last-admin guard is kept, matching `set_user_role`: an app with no admin cannot be
|
||||
administered, and there is no password login left to recover through.
|
||||
@@ -1,75 +0,0 @@
|
||||
# Decisions — September 2, 2026
|
||||
|
||||
One item, and it retires two decided-and-built items rather than amending them.
|
||||
|
||||
---
|
||||
|
||||
## D15 — Authentication moves to Okta OIDC; D13 and D14 are retired before deployment
|
||||
|
||||
- **Amends:** retires `D13` (LDAPS simple bind against `prime.local`) and `D14` (the CLI
|
||||
authenticates against the domain). Both were decided and reaffirmed August 21 2026,
|
||||
built across nine tasks (`T10.1`–`T10.9`), and verified against the live domain. Neither
|
||||
reached production. Approved by Nick Siegfried.
|
||||
- **Surface:** `server/auth.py`, `server/app.py` (`login()`), `html/login.html`,
|
||||
`html/login.js`, `html/auth-guard.js`. `server/ldap_auth.py` does not carry forward —
|
||||
there is no LDAPS bind in the new design, not even as a fallback.
|
||||
- **Wave:** 10. The label is reused fresh: the LDAPS work that previously answered to
|
||||
"wave 10" was built on `feat/ldaps-directory-auth`, which is deleted rather than merged,
|
||||
and never appeared in `IMPLEMENTATION.md`'s wave table. It carries no claim on the
|
||||
number.
|
||||
|
||||
### What D13/D14 were, for the record
|
||||
|
||||
The branch carrying them is deleted, not merged, so their decision record
|
||||
(`docs/waves/decisions-2026-08-21.md`) no longer exists on any branch. Preserved here so
|
||||
the reasoning isn't lost along with it:
|
||||
|
||||
D13 chose a direct LDAPS simple bind to `ldaps://prime.local:636` as the sign-in
|
||||
mechanism: no password stored, a successful bind was the authentication, accounts were
|
||||
provisioned just-in-time from the directory, and roles stayed local. D14 moved the CLI
|
||||
onto the same bind, removing `create-admin`/`create`. Both were built, tested
|
||||
(1284/1288 checks, Aug 24), and screenshotted at 390px and 1440px. Neither ever deployed —
|
||||
`wp.controls.dev` still runs the pre-D13 local-password login as of this decision.
|
||||
|
||||
### The decision
|
||||
|
||||
Skip LDAPS entirely. Authentication becomes an Okta OIDC authorization-code flow,
|
||||
replacing local passwords directly — the same full replacement D13 intended, just via
|
||||
Okta instead of a domain bind. No LDAPS bind exists in this design at any point.
|
||||
|
||||
Four things carry forward from D13 unchanged, because they were never LDAPS-specific to
|
||||
begin with:
|
||||
|
||||
1. **No password is stored.** The app never sees a credential of any kind; Okta owns
|
||||
authentication entirely.
|
||||
2. **Accounts are provisioned just-in-time.** A first successful Okta sign-in with no
|
||||
matching local `users` row creates one, at the default role. The matching logic that
|
||||
was going to key off a directory search instead keys off an OIDC identity claim.
|
||||
3. **Roles stay local.** Okta, and AD behind it, supplies identity only. This app decides
|
||||
what an identity may do. Restated because it is the one rule the whole access-control
|
||||
design depends on — see `BL-029` and the governance discussion that followed it.
|
||||
4. **Existing accounts keep their roles** on first Okta login, exactly as D13's criterion
|
||||
4 read for LDAPS.
|
||||
|
||||
### Why this, and not LDAPS first and Okta second
|
||||
|
||||
`BL-029` (recorded on this branch as `BL-027` before the renumbering forced by main's
|
||||
independent use of that number) already laid out why OIDC beats the LDAPS bind on three
|
||||
counts: this app never sees a password, MFA comes from Okta rather than needing to be
|
||||
built, and the domain-lockout hazard that forced `AUTH_MAX_ATTEMPTS` down to 2 disappears,
|
||||
because failed attempts land on Okta rather than on a bind this app makes. D13 was decided
|
||||
before it was known the company already runs an Okta tenant. Once that was confirmed
|
||||
(security's scoping reply, September 2026), shipping LDAPS first and replacing it with
|
||||
Okta days later would mean building and deploying the weaker mechanism on purpose. Going
|
||||
straight to Okta avoids that.
|
||||
|
||||
### What still needs answering before this is buildable
|
||||
|
||||
Open from the security scoping thread, not yet closed:
|
||||
|
||||
- Which OIDC claim carries the AD `sAMAccountName` equivalent (`preferred_username`,
|
||||
`upn`, or a custom claim) — asked of security, answer pending.
|
||||
- The exact redirect/callback URI once the hostname situation is reconfirmed
|
||||
(`https://wp.controls.dev/api/auth/okta/callback` proposed).
|
||||
- The `Business Technology Group` pilot in Okta, requested for initial testing, with
|
||||
normal Okta session/MFA behavior rather than a stricter per-app rule.
|
||||
@@ -1,122 +0,0 @@
|
||||
# Decisions — 2026-09-03
|
||||
|
||||
## D16: Okta admin bootstrap, break-glass posture, and the real scope of T10.4
|
||||
|
||||
Raised during hazard review for T10.4 (remove the local password path). D15 settled
|
||||
*that* local passwords go away and Okta OIDC is the sole replacement; it did not settle
|
||||
how an admin account gets named once there is no password to set, or what happens if
|
||||
Okta itself is unreachable. Both are decided here.
|
||||
|
||||
### Admin bootstrap
|
||||
|
||||
`server/manage_users.py` stays the bootstrap tool — its own docstring already says so
|
||||
("the `/api/auth/users` endpoint needs an existing admin, so you have to bootstrap one
|
||||
here") — but it changes from *creating* an account to *promoting* one:
|
||||
|
||||
- An operator with shell/DB access on the server runs it against an account that
|
||||
already signed in through Okta once and was JIT-provisioned by T10.3 (landing at
|
||||
`project_user`, per that task). The command sets `role = admin` on that existing row
|
||||
by username.
|
||||
- It does **not** create a `User` row from scratch and does not touch `password_hash`
|
||||
(the column is gone after T10.4's migration).
|
||||
|
||||
Rejected: minting a brand-new admin row by hand-typed username. `OKTA_IDENTITY_CLAIM`'s
|
||||
exact format is still unconfirmed by security (open item carried from D15/wave-10.md).
|
||||
A hand-typed username that doesn't exactly match what Okta actually sends produces a
|
||||
second, orphaned account instead of promoting the real one. Promoting an
|
||||
already-JIT-provisioned row sidesteps that entirely — it never has to guess the future
|
||||
claim value.
|
||||
|
||||
Ongoing (non-bootstrap) admin naming needs no new work: `html/users.js` already has a
|
||||
live role dropdown (`roleSelect`, gated by server-supplied `grantable_roles`) that lets
|
||||
an existing admin promote any other account, including one JIT-provisioned via Okta.
|
||||
That path is unrelated to the password removal and keeps working unchanged.
|
||||
|
||||
### Break glass
|
||||
|
||||
No break-glass path, by design. If Okta is unreachable or misconfigured, the app is
|
||||
unreachable for everyone, including admins, until Okta is restored.
|
||||
|
||||
This matches the precedent already on record for the abandoned LDAPS design (D13/D14):
|
||||
"LDAPS is the *only* path, no local fallback, no break-glass." Carried forward
|
||||
deliberately rather than assumed to still apply, given Okta's failure modes differ from
|
||||
an internal LDAP bind — considered and confirmed, not defaulted into.
|
||||
|
||||
Rejected: a toggleable emergency local login gated behind an env flag. It would
|
||||
reintroduce a stored local credential, exactly what D15 exists to eliminate, for a
|
||||
scenario (Okta down) judged less likely and less costly than the standing risk of a
|
||||
forgotten emergency backdoor.
|
||||
|
||||
The server-shell CLI (`manage_users.py`, promoting an existing row) is not a formal
|
||||
break-glass mechanism — it cannot help if no account has ever signed in through Okta —
|
||||
but it is the same trust tier as "someone with SSH/container access to prod could
|
||||
already edit the database directly," and it costs no new engineering.
|
||||
|
||||
### T10.4 scope correction
|
||||
|
||||
Hazard review found real call sites of `hash_password` / `verify_password` /
|
||||
`password_problem` that the original T10.4 bullet in `wave-10.md` didn't name and that
|
||||
break the moment those functions are deleted:
|
||||
|
||||
- `create_user()` and `admin_reset_password()` in `server/app.py` (the admin console's
|
||||
"add user" and "reset password" routes).
|
||||
- `html/users.js`'s "add user" form (`nu-password` field) and "Reset password" button.
|
||||
- `server/manage_users.py`'s `create`, `create-admin`, and `reset-password` subcommands
|
||||
(see bootstrap section above for its replacement).
|
||||
- `tests/browser_check.py` and `tests/launcher_check.py`, which call
|
||||
`auth.hash_password()` to seed fixture rows.
|
||||
|
||||
Also found: `server/smoketest.py` and `server/seed_demo.py` authenticate via
|
||||
`POST /api/auth/login`, which T10.4 removes, and CLAUDE.md's own verification section
|
||||
names both scripts as required checks. Fix folded into T10.4 rather than deferred to
|
||||
T10.7: both scripts switch to minting a session with `auth.create_token()` and setting
|
||||
the cookie directly, the same technique `tests/browser_check.py` already uses instead
|
||||
of scripting a login form. No live Okta tenant needed, and T10.4 no longer depends on
|
||||
T10.7's timing.
|
||||
|
||||
`wave-10.md`'s T10.4 bullet is updated to reflect this full scope.
|
||||
|
||||
## D17: A dedicated rollback-aware runbook for the Okta cutover deploy
|
||||
|
||||
Raised while preparing to close out wave 10: T10.4's migration
|
||||
(`server/alembic/versions/1d60a608bb51_drop_local_password.py`) drops the
|
||||
`password_hash` column, and its `downgrade()` re-adds the column with
|
||||
`server_default=''`. That restores the schema, not the data — the real bcrypt hashes
|
||||
are destroyed the moment `upgrade()`'s `op.drop_column` commits, and no amount of
|
||||
`alembic downgrade` brings them back. `DEPLOY-runbook-2026-08-04.md`, the existing
|
||||
precedent for how a deploy of this repo is handed to IT, has no equivalent case in its
|
||||
own Rollback section — its migrations are additive or reversible, so nothing there
|
||||
warns an operator that this one is different.
|
||||
|
||||
Three options were on the table: write this runbook now; also document a staged
|
||||
deploy sequence (ship T10.5's Okta-live-alongside-password state first, verify real
|
||||
sign-ins, then ship T10.4's column drop as a separate follow-up deploy); or log the
|
||||
hazard to `backlog.md` and stop there. Decided: write the runbook only. Staged
|
||||
sequencing is real risk reduction but is a second deploy plan on top of a wave that is
|
||||
otherwise a single cutover (D15's "full replacement," not a toggle) — worth
|
||||
proposing on its own if IT wants it, not worth building unasked. Backlog-only was
|
||||
rejected because the hazard is concrete and dated (this wave, this migration), not a
|
||||
someday item.
|
||||
|
||||
### What the runbook has to do differently from the 2026-08-04 precedent
|
||||
|
||||
- Name the five `OKTA_*` environment variables as newly required for this deploy —
|
||||
the precedent's own "no new environment variables" note does not apply here and
|
||||
restating it unchanged would be actively wrong.
|
||||
- Treat the pre-deploy backup (`docker exec wp_db_backup /scripts/db-backup.sh`) as
|
||||
the only way back once `1d60a608bb51` commits, not as routine due diligence.
|
||||
- Separate two failure modes that look similar but are not: an Okta app integration
|
||||
that is misconfigured after a clean deploy (redirect URI, client secret, an
|
||||
unassigned test account) is fixable in place — fix the config, redeploy the `api`
|
||||
service, no data at risk, migration already applied and stays applied. Deciding to
|
||||
abandon Okta and restore local-password code is the severe case — the empty
|
||||
`password_hash` column means the old code has nothing to check a password against,
|
||||
so the only way back is the destructive backup restore (`DEPLOY-runbook-2026-08-04.md`
|
||||
Case C's own procedure, reused here). Conflating these two would send an operator
|
||||
straight to a destructive restore for a problem that a config fix would have solved.
|
||||
- Fold in D16's no-break-glass posture: if Okta is down or misconfigured, the app is
|
||||
down for everyone, including admins, by design — not a defect to roll back from.
|
||||
|
||||
Filed as **T10.9** in `wave-10.md` rather than folded into T10.6 (already merged and
|
||||
verified) or T10.8 (UI/test verification, a different kind of check). New scope found
|
||||
after the task that raised it closed gets a new ID, per `CLAUDE.md`.
|
||||
@@ -1,355 +0,0 @@
|
||||
# Decisions — September 17, 2026
|
||||
|
||||
Three items. Like `D11`, `D15`, `D16` and `D17`, these are new scope raised after
|
||||
R2 closed out (see `docs/reference/completion.md`, T9.7), not a reopening of
|
||||
anything already decided there.
|
||||
|
||||
`CR-019` and `CR-020` get `CR` ids because they are field/product-facing feature
|
||||
requests — the same kind of thing `CR-001`-`CR-018` were — not internal
|
||||
engineering calls made mid-build. `D18` gets a `D` id because it is exactly that:
|
||||
an internal security/architecture call, the same category as `D15` (Okta vs.
|
||||
LDAPS), not a feature a user asked for.
|
||||
|
||||
Requested/raised by Matt Mabrey, 2026-09-17.
|
||||
|
||||
---
|
||||
|
||||
## CR-019 — Usage and activity metrics (admin console)
|
||||
|
||||
- **Area:** Admin Console / Monitoring
|
||||
- **Priority:** proposed High — the current admin console has no reliable way to
|
||||
answer "who is using this and how much," which is the same visibility gap the
|
||||
original UX review found in `B4` (numbers that look authoritative but are not).
|
||||
- **Source:** Matt Mabrey, 2026-09-17.
|
||||
|
||||
### Why this is not already built
|
||||
|
||||
`D5`/`T7.10` already shipped a usage-analytics feature — `html/wp-usage.js`, with
|
||||
a report at `admin.js:666-699` — but it reads `localStorage`, which is scoped to
|
||||
one browser. The report's own empty state says exactly this: *"No usage recorded
|
||||
in this browser yet."* It cannot show who across the team is active or what they
|
||||
use, because each person's activity exists only on their own machine. This is the
|
||||
same class of defect `B4` named for the pipeline strip — a number that looks
|
||||
authoritative but is not — just never generalized to this feature. `CR-019` is
|
||||
therefore new server-side work, not a UI addition on top of what exists.
|
||||
|
||||
Two things already in the schema are relevant and reused rather than duplicated:
|
||||
`User.last_login_at` (one timestamp, no history) and `AuditLog` (append-only,
|
||||
already records business mutations — WP created, status changed, role changed —
|
||||
per user, with a timestamp). Neither captures navigation or feature-open events,
|
||||
which is the actual gap.
|
||||
|
||||
### Intent
|
||||
|
||||
Give admins a real, server-backed picture of who is using the suite, what parts
|
||||
of it they use, and how active they are — replacing the per-browser report as
|
||||
the thing anyone actually looks at.
|
||||
|
||||
### Decisions, made 2026-09-17
|
||||
|
||||
1. **Retention: indefinite.** No automatic purge of usage-event data. (Separate
|
||||
from `AuditLog`'s own retention, which this does not change.)
|
||||
2. **Scope: suite-wide, filterable.** Not per-project by default; the console
|
||||
provides filters (date range, project, user, tool/page) rather than scoping
|
||||
the data itself.
|
||||
3. **Export: raw view shows real identities; export supports sanitization.**
|
||||
The admin console's own tables and the CSV export both default to real
|
||||
usernames — this is an internal audit tool, not a public one. But the export
|
||||
also offers a "sanitize" toggle that replaces the actor with a **stable
|
||||
pseudonymous id** (a per-user hash, consistent across rows and across
|
||||
export runs) rather than dropping the identity field outright — so an
|
||||
external system (Power BI or similar) can still group and trend "by user"
|
||||
without ever receiving a real name. Flagged here as the recommended
|
||||
approach rather than the only one Matt confirmed in so many words: if a
|
||||
fully-anonymous (no stable id at all) export turns out to be what's
|
||||
actually wanted, that is a one-line change to the same feature, raise it
|
||||
in the PR rather than treating it as blocking.
|
||||
4. **The old per-browser report is retired**, not kept alongside the new one.
|
||||
Once `CR-019` ships, `admin.js`'s existing `usage-admin` panel (reading
|
||||
`WPUsage.load(...)` per browser) is removed rather than left next to the
|
||||
real report, where it would show a smaller, misleading number for whoever
|
||||
happens to have it open. `html/wp-usage.js` and its two call sites
|
||||
(`html/work-package-suite-app.js`'s wizard dwell-tracking, and the
|
||||
creator's equivalent) are a separate question — the *recording* code can
|
||||
stay or go independent of the *admin report* being retired, since dwell
|
||||
events were never reliably tied to a real identity anyway. Default to
|
||||
removing both unless a task finds a reason to keep the recorder; log that
|
||||
reason rather than deciding it here.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- A new admin-only tab in `admin.html` (same role gate as the User Directory)
|
||||
shows: active users over a selectable date range (day/week/month), each
|
||||
user's last-active timestamp, and a breakdown of which tools/pages get
|
||||
opened and how often.
|
||||
- Server-side event capture, keyed to the authenticated session (real identity,
|
||||
not a browser-local guess) — a new table, not an extension of `AuditLog`,
|
||||
since page-open/navigation events are not business mutations and mixing them
|
||||
in would make `AuditLog` noisy for its existing, narrower purpose.
|
||||
- The console's filters cover date range, project, user, and tool/page, and
|
||||
combine (e.g., "user X, last 30 days, field view only").
|
||||
- CSV export from the console, in both raw (real usernames) and sanitized
|
||||
(stable pseudonymous id per user) modes.
|
||||
- Retention is indefinite; nothing in this item purges data.
|
||||
- View-only, refresh-on-load. No alerting — matches how the rest of the admin
|
||||
console works today; if that changes later it is new scope, not a rider on
|
||||
this item.
|
||||
- The old per-browser "Usage" report and its admin-console panel are removed
|
||||
in the same wave, not left running alongside the new one.
|
||||
- Accessible per `CLAUDE.md`'s standing `C1` rules (this is a new component,
|
||||
not a legacy one — it ships accessible or it is not done, same as
|
||||
everything else built since wave 7).
|
||||
|
||||
### Frontend/backend boundary
|
||||
|
||||
This needs server work, the same way `CR-004`/`CR-018`/`B4` did: a real table,
|
||||
a capture endpoint, an aggregation endpoint, and an export endpoint. If a task
|
||||
under this item is being built by writing to `localStorage`, it is rebuilding
|
||||
the exact defect this item exists to replace — stop and say so, per
|
||||
`CLAUDE.md`.
|
||||
|
||||
### Scheduling
|
||||
|
||||
New wave. Wave 10 (Okta) is merged, so this does not wait on anything.
|
||||
Task breakdown: `docs/waves/wave-11.md`.
|
||||
|
||||
---
|
||||
|
||||
## CR-020 — Bulk editing of users in the admin console
|
||||
|
||||
- **Area:** Admin Console / User Directory
|
||||
- **Priority:** proposed High — three of the four actions below touch access
|
||||
control (role, project assignment, active/disabled) and the fourth is a hard
|
||||
delete; getting the guardrails right matters more than getting it built fast.
|
||||
- **Source:** Matt Mabrey, 2026-09-17.
|
||||
|
||||
### Why this is not already built
|
||||
|
||||
Every user-editing action in `html/users.js` today is one row, one action:
|
||||
a role `<select>` per row, an activate/disable button per row, a
|
||||
per-user project-membership checklist opened one user at a time, and a
|
||||
per-row delete. There is no row selection in the User Directory table at all.
|
||||
Server-side, every corresponding endpoint
|
||||
(`/api/auth/users/{id}/active`, `/role`, `/project-role`, `/projects`, and
|
||||
`DELETE /api/auth/users/{id}`) takes exactly one `user_id`. Bulk editing is new
|
||||
UI (selection) and, for most actions, either a loop over the existing
|
||||
single-user endpoints or new endpoints that accept a list — the task decides
|
||||
which, per user count and transaction-safety needs.
|
||||
|
||||
**Deletion is already a hard delete today** (`delete_user`, `server/app.py:1121`
|
||||
— `db.delete(u)`, not a deactivate). Bulk delete inherits that: it is not this
|
||||
item's job to invent a soft-delete pattern that does not exist for the single
|
||||
case, but the confirmation step around it has to be sized for the fact that a
|
||||
bad multi-select now removes more than one account at once, permanently.
|
||||
|
||||
### Decisions, made 2026-09-17
|
||||
|
||||
1. **All four bulk actions are in scope:** role change, activate/disable,
|
||||
project assignment (add to / remove from a project, including the
|
||||
project-role), and delete.
|
||||
2. **Selection works two ways:** checkboxes (select-all and individual) in the
|
||||
existing User Directory table, respecting whatever filter is already
|
||||
applied (role, active/disabled, project) — and a CSV upload, for a one-off
|
||||
bulk operation against an external list (e.g., an offboarding list that
|
||||
didn't originate in this app). Both are in scope, not a choice between them.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- The User Directory table gains row checkboxes and a select-all that respects
|
||||
the current filter; a bulk-action toolbar appears once at least one row is
|
||||
selected.
|
||||
- CSV upload as an alternative to checkbox selection: a list of usernames plus
|
||||
the action to apply. Validates every row, reports rejected ones by row (bad
|
||||
username, user not found, actor lacks permission over that user) rather than
|
||||
silently skipping them — the same validate-and-report pattern `CR-005`
|
||||
established for list uploads.
|
||||
- Every existing single-user guardrail carries forward unchanged: an actor
|
||||
cannot include their own account in a bulk action that would disable, demote,
|
||||
or delete it; a super user's bulk action is scoped to only the users and
|
||||
projects `require_see_user`/`require_manage_user` already let them touch
|
||||
today (a super user cannot use a bulk action to reach a user or project
|
||||
outside what they manage, even via CSV); `grantable_roles` still gates which
|
||||
roles an actor may assign in bulk, the same as one at a time.
|
||||
- Every affected row is written to `AuditLog` individually, exactly as the
|
||||
single-user endpoints do today (one `role_changed` / `user_deleted` / etc.
|
||||
row per user) — a bulk action is many audited changes, not one opaque batch
|
||||
entry, so per-user history stays intact and readable in isolation.
|
||||
- Confirmation before applying, using the `wp-dialog` kit (`T7.9`), not a
|
||||
native `confirm()`. The dialog names exactly how many users are affected and,
|
||||
for delete specifically, lists the affected usernames before committing.
|
||||
- Partial failure is reported, not hidden: if some rows in a batch fail (scope,
|
||||
already-deleted, bad CSV row), the action applies to what it can and states
|
||||
exactly which rows failed and why. It never reports success on a batch that
|
||||
partly failed.
|
||||
- Accessible per `C1`: real controls, keyboard-operable selection and bulk-
|
||||
action toolbar, `aria-live` announcing the result.
|
||||
|
||||
### Recommended, not yet confirmed — raise in the PR if this is wrong
|
||||
|
||||
- **Bulk delete gets an extra confirmation step beyond naming the count** —
|
||||
proposed as typing a confirmation phrase (e.g. the word `DELETE`) regardless
|
||||
of how many rows are selected, since one bad multi-select now removes more
|
||||
than one account, permanently, with no soft-delete to fall back on. This is
|
||||
a recommendation, not a confirmed requirement — Matt has not signed off on
|
||||
the exact mechanism.
|
||||
- **Project assignment is add/remove, not replace-the-whole-list** — a bulk
|
||||
"add these users to project X" or "remove these users from project X"
|
||||
action, rather than a bulk action that overwrites a user's entire project
|
||||
list. Proposed because add/remove is less likely to clobber project
|
||||
memberships the actor didn't intend to touch; a replace-the-whole-list
|
||||
version is a materially different (and riskier) feature if that turns out to
|
||||
be what's actually wanted.
|
||||
|
||||
### Confirmed 2026-10-06 (Matt Mabrey, at the start of wave 12)
|
||||
|
||||
Both recommendations above are confirmed as written, and the two details
|
||||
`wave-12.md` left to the build are decided:
|
||||
|
||||
1. **Bulk delete:** the dialog lists the affected usernames and the request is
|
||||
not sent until the word `DELETE` is typed, whatever the count.
|
||||
2. **Project assignment is add/remove** to or from one project at a time, with
|
||||
the per-project permissions role (`ProjectMember.role`) set on add. It never
|
||||
replaces a user's whole project list.
|
||||
3. **Changing the table filter clears the selection** (T12.2), and the toolbar
|
||||
says so, so no row hidden by the filter stays selected.
|
||||
4. **The CSV holds usernames only** (T12.4). The action and its settings are
|
||||
chosen in the toolbar and apply to every valid row of the file.
|
||||
|
||||
### Frontend/backend boundary
|
||||
|
||||
Selection state (which rows are checked) is fine as client-side UI state — it
|
||||
is not persisted data. Everything the bulk action actually does (role,
|
||||
active/disabled, project membership, delete) already requires server work
|
||||
today for the single-user case, and bulk does not change that: no new
|
||||
localStorage-derived state, no client-side aggregation of what changed.
|
||||
|
||||
### Scheduling
|
||||
|
||||
New wave. Independent of wave 11 (`CR-019`) — the two do not touch the same
|
||||
code and can build in either order or in parallel. Task breakdown:
|
||||
`docs/waves/wave-12.md`.
|
||||
|
||||
---
|
||||
|
||||
## D18 — Detecting and acting on Okta/AD deprovisioning
|
||||
|
||||
- **Raised by:** Matt Mabrey, 2026-09-17, in response to a direct question about
|
||||
what happens when someone's AD account is removed and Okta subsequently drops
|
||||
them.
|
||||
- **Amends:** nothing decided, closes a gap `D15`/`D16` left unaddressed. Those
|
||||
items designed how identity flows *into* this app (Okta authenticates, this
|
||||
app JIT-provisions and owns roles); neither addressed what happens when an
|
||||
identity is withdrawn. This app has never had any deprovisioning signal —
|
||||
push or pull — since Okta went live.
|
||||
|
||||
### What was found
|
||||
|
||||
Traced through `server/auth.py` and `server/okta_auth.py`: this app has no
|
||||
connection back to Okta after initial sign-in. Consequences, confirmed against
|
||||
the actual code:
|
||||
|
||||
1. A local `users` row is never touched by anything Okta-side. `is_active`
|
||||
stays `True` indefinitely unless an admin manually disables or deletes the
|
||||
account through the User Directory. There is no flag distinguishing a
|
||||
terminated employee's account from a current one.
|
||||
2. `get_current_user` (`server/auth.py:237`) re-checks `is_active` and
|
||||
`token_version` on **every request** — so a manual disable takes effect
|
||||
immediately, on the very next request. The gap is not enforcement, it's
|
||||
detection: nothing tells an admin to go flip that switch.
|
||||
3. A session already live when someone is deprovisioned keeps working, fully,
|
||||
for up to `AUTH_SESSION_HOURS` (12 hours today, `server/auth.py:63`),
|
||||
because validity is checked against this app's own JWT and DB state only,
|
||||
never against Okta.
|
||||
4. A NEW session can't be established once Okta drops the account —
|
||||
`okta_login`/`okta_callback` requires completing Okta's own sign-in, which
|
||||
Okta itself refuses. The front door closes on its own; the back door (an
|
||||
already-open session, and the stale local record) does not.
|
||||
|
||||
### Decisions, made 2026-09-17
|
||||
|
||||
1. **Build a scheduled sync against Okta's Management API**, not an Event Hook.
|
||||
This app has, since `D15`, only ever reached out to Okta — never received
|
||||
anything from it — and a polling design keeps that shape rather than
|
||||
introducing a new inbound, internet-reachable endpoint with its own
|
||||
signature-verification surface. Traded deliberately: this is
|
||||
poll-interval-late rather than real-time, which is judged acceptable for an
|
||||
HR/offboarding-driven event, not a to-the-second requirement.
|
||||
2. **Revised 2026-09-23, in response to Matt's question about idle time
|
||||
instead of a flat session length: sessions now slide on activity, with a
|
||||
hard ceiling underneath.** A flat `AUTH_SESSION_HOURS` forces a re-check
|
||||
with Okta on a fixed schedule regardless of activity; a pure idle timer
|
||||
with no ceiling does the opposite — a continuously-active session would
|
||||
never force a fresh Okta check on its own, which is a worse fit for the
|
||||
exact threat this item exists to address (someone still clicking around
|
||||
after being deprovisioned). Decided: **both**.
|
||||
- `AUTH_IDLE_MINUTES` (new, default **30**): a session with no request
|
||||
for this long stops being valid. Implemented as a sliding JWT expiry —
|
||||
the token is reissued with a fresh `exp` on activity, throttled so the
|
||||
cookie isn't rewritten on literally every request.
|
||||
- `AUTH_SESSION_HOURS` (existing var, meaning changes to an **absolute
|
||||
ceiling**): no session survives past this many hours from the original
|
||||
sign-in, no matter how continuously active it is. Default changing from
|
||||
12 to a proposed **8** — flagged as a recommendation, not confirmed.
|
||||
- Both defaults, and the mechanism itself, should be sanity-checked
|
||||
against the tenant's actual Okta SSO session policy — if Okta's own
|
||||
session silently outlives either number, re-authentication here is
|
||||
likely a fast redirect, not a real re-login screen, so these numbers
|
||||
cost less than they look like they do. Confirm before treating either
|
||||
as final.
|
||||
3. **The sync only ever disables an account — it never re-enables one.** A
|
||||
rehire showing active in Okta again does not automatically restore access;
|
||||
an admin re-enabling the account is a deliberate act, consistent with
|
||||
`D16`'s posture that this app never auto-grants access on its own initiative.
|
||||
4. **Fail closed on the side of INACTION, not disablement.** This is the
|
||||
opposite failure direction from `D16`'s login-time posture ("if Okta is
|
||||
unreachable, the app is unreachable for everyone"). Here, an Okta API
|
||||
error, timeout, empty response, or anything the sync can't confidently
|
||||
parse must result in **no change to any account** that cycle, plus a
|
||||
logged failure. A sync job that treats "couldn't reach Okta" as "nobody is
|
||||
active" is a far worse outcome than a missed cycle — it would lock out the
|
||||
entire org on an Okta API hiccup. This is the single most important
|
||||
acceptance criterion in this item.
|
||||
5. **Every auto-disable is audited individually**, same as every other
|
||||
account-state change in this app: an `AuditLog` row per user, with an actor
|
||||
value that's clearly the sync job and not a person (e.g.
|
||||
`system:okta_sync`), so it reads correctly in the User Directory's history
|
||||
and is never confused with an admin's own action.
|
||||
6. **New credential required:** a read-scoped Okta API token (or an Okta
|
||||
service-app OAuth2 client), separate from the `OKTA_CLIENT_ID`/
|
||||
`OKTA_CLIENT_SECRET` pair used for sign-in. This needs provisioning by
|
||||
whoever administers the Okta tenant — the same dependency that gated the
|
||||
original OIDC rollout (D15's "security scoping reply").
|
||||
|
||||
### Recommended, not yet confirmed — raise in the PR if this is wrong
|
||||
|
||||
- **Sync interval:** proposed every 15 minutes. Frequent enough that the
|
||||
detection gap is small, infrequent enough not to hammer Okta's API or need
|
||||
special rate-limit handling. Not confirmed with IT/security.
|
||||
- **Where the job runs:** proposed as an in-process background task inside the
|
||||
existing `api` container (it already has `outbound` network access to reach
|
||||
Okta, and already holds the Okta client config) rather than a new sidecar
|
||||
container. The `backup` container (`docker-compose.yml`) is the existing
|
||||
precedent for a scheduled-interval container in this stack, if isolation
|
||||
from the `api` process is preferred instead — a reasonable alternative, not
|
||||
the recommendation.
|
||||
- **Admin visibility:** at minimum, an auto-disable is a normal, readable
|
||||
`AuditLog` entry (visible whever admin already reviews audit history, and
|
||||
naturally covered once `CR-019`'s activity view exists). Whether it should
|
||||
also trigger an email/notification to admins is a genuine open question —
|
||||
proposed as a fast-follow rather than blocking this item, since `D10`
|
||||
already established the pattern for admin-controlled email toggles this
|
||||
could reuse.
|
||||
|
||||
### Frontend/backend boundary
|
||||
|
||||
Entirely server-side and infrastructure. No new `localStorage` state, no
|
||||
frontend surface beyond what already reads `is_active` and `AuditLog` today
|
||||
(the User Directory, and eventually `CR-019`'s activity view).
|
||||
|
||||
### Scheduling
|
||||
|
||||
New wave, independent of wave 11 and wave 12 in the sense that nothing here is
|
||||
blocked by them — but note it touches the same `is_active`/account-state
|
||||
surface `CR-020`'s bulk actions touch in `server/app.py`. Not a hard
|
||||
dependency; sequence commits to avoid an avoidable merge conflict, per
|
||||
`CLAUDE.md`'s "one task per PR" spirit. Task breakdown: `docs/waves/wave-13.md`.
|
||||
@@ -1,84 +0,0 @@
|
||||
# Decisions — October 2, 2026
|
||||
|
||||
Three items, from the security review of 2026-10-01
|
||||
(`docs/reference/security-review-2026-10-01.md`). They get `D` ids because they
|
||||
are internal security calls made mid-build, the same category as `D15` and
|
||||
`D18`, not features a user asked for.
|
||||
|
||||
Decided by Matt Mabrey, 2026-10-02.
|
||||
|
||||
| Item | Title | Review finding | Task |
|
||||
|---|---|---|---|
|
||||
| `D19` | Uploaded files download safely | SEC-01, SEC-15e (BL-035, BL-036) | T16.2 |
|
||||
| `D20` | One SOP per project | SEC-02 (BL-048) | T16.3 |
|
||||
| `D21` | Session decode fails closed; PyJWT upgraded | SEC-07 (BL-052) | T16.1 |
|
||||
|
||||
**Schedule:** wave 16. It is **independent of waves 12 to 15**: it touches
|
||||
`server/` only, and no file in it is changed by a task in those waves except
|
||||
`server/app.py`, in functions they do not touch (`get_wp_file`, `upsert_sop`,
|
||||
the SOP baseline readers). Wave 16 may merge before wave 12.
|
||||
|
||||
**Out of this round, by decision:** SEC-06 (session revocation) waits for the
|
||||
AWS work. All other SEC findings stay as backlog drafts in
|
||||
`docs/reference/security-review/backlog-drafts.md`.
|
||||
|
||||
---
|
||||
|
||||
## D19 — Uploaded files download safely
|
||||
|
||||
- **Problem:** an SVG drawing can carry a script. The server sends it back
|
||||
`inline` with its own content type, on the app's origin, so the script runs
|
||||
as whoever opens it (SEC-01). Separately, a file name that is not Latin-1
|
||||
(for example `Plan é.pdf`) makes the download fail with 500, and CR/LF in a
|
||||
name reaches the response header (SEC-15e).
|
||||
- **Decision:** SVG uploads stay **accepted**, but every file that is not a
|
||||
PDF or a raster image downloads as an **attachment** inside a **sandbox**:
|
||||
`Content-Disposition: attachment` and
|
||||
`Content-Security-Policy: sandbox; default-src 'none'`. PDF and raster images
|
||||
(PNG, JPEG, GIF, WebP, BMP, AVIF) keep opening inline. Every file name goes
|
||||
out in the RFC 6266 / RFC 5987 form (ASCII fallback plus `filename*`).
|
||||
- **Why accept SVG instead of refusing it:** no change for the person who
|
||||
uploads, and no migration for SVGs already stored. The protection is on the
|
||||
way out, which also covers any SVG already in the database.
|
||||
- **Must not change:** inline preview of PDF and images (CR-007), the
|
||||
`Cache-Control` the offline drawing cache relies on, the D8 limits, and the
|
||||
upload API.
|
||||
|
||||
## D20 — One SOP per project
|
||||
|
||||
- **Problem:** the rule "changing a completed SOP is a Project Admin action"
|
||||
checks only the SOP row being posted. A `project_user` can post a NEW SOP id
|
||||
with `complete: true`. Every reader picks "the latest complete SOP", so that
|
||||
row becomes the baseline every page loads and the source of PM, CM and QA
|
||||
mail routing (SEC-02, probe S3).
|
||||
- **Decision:**
|
||||
1. A project has one SOP, with the id `sop__<project_id>`. The browser has
|
||||
always written that id (`pushSOP` in `project-data.js`). A request with no
|
||||
id gets it. A request that would CREATE a SOP with any other id on a
|
||||
project is refused with 400.
|
||||
2. Existing SOP rows with other ids (for example rows `seed_demo.py` made)
|
||||
stay. They can still be updated under the old rules. Nothing is deleted.
|
||||
3. While a project has a complete SOP, writing any SOP on that project with
|
||||
`complete: true`, and changing a complete SOP, needs Project Admin on the
|
||||
project.
|
||||
4. The readers prefer the canonical row: `project_sop_team`,
|
||||
`project_qa_group`, `project_summary` and `GET /api/sops/latest` with
|
||||
`complete=true&project_id=` read `sop__<project_id>` when it is complete,
|
||||
and fall back to "latest complete" only when it is not. So a rogue row
|
||||
made before this fix cannot stay the baseline.
|
||||
- **Must not change:** a project member drafting the SOP and completing it the
|
||||
first time (allowed today, allowed after); admin access to project-less
|
||||
SOPs; the response shape of every SOP route.
|
||||
|
||||
## D21 — Session decode fails closed; PyJWT upgraded
|
||||
|
||||
- **Problem:** a crafted 1.6 KB cookie makes PyJWT 2.13.0 raise an error that
|
||||
`decode_token` does not catch, so an unauthenticated request gets a 500 and
|
||||
a stack trace in the log (SEC-07, probe S12). `pip-audit` lists 13
|
||||
advisories for 2.13.0.
|
||||
- **Decision:** pin **PyJWT 2.15.1** (`pip-audit`: no known vulnerabilities on
|
||||
2026-10-02). `decode_token` treats ANY decode failure, and any cookie longer
|
||||
than 4096 characters, as "not signed in" (401). It also requires the `exp`
|
||||
and `sub` claims, which every token this app issues carries.
|
||||
- **Must not change:** every valid session, the D18 sliding refresh and
|
||||
ceiling, and the fake Okta test seam.
|
||||
@@ -1,51 +0,0 @@
|
||||
# Decisions: October 12, 2026 (meeting with Nick)
|
||||
|
||||
Topic: mobile app (offline Field View), batch print, and related scaling questions.
|
||||
Recorded by Matt Mabrey from the meeting with Nick, 2026-10-12. Follow-up answers from Matt are in the section "Follow-up answers".
|
||||
|
||||
This file records the answers. It does not schedule any work. The features that come from these answers are logged in `docs/waves/backlog.md` as `BL-062` to `BL-068` for a future build. The path to a mobile version that works outside the VPN is in `docs/waves/roadmap-mobile-scaling.md`. None of these have a wave or a `CR-` or `D-` id yet. Assign the ids when a wave is planned.
|
||||
|
||||
Question numbers (`Q2` to `Q14`) come from the decision table that Matt received. `Q1`, `Q10`, and `Q11` were not in the table. They are not recorded here.
|
||||
|
||||
## Answers
|
||||
|
||||
| Q | Decision needed | Default that was proposed | Answer |
|
||||
|---|---|---|---|
|
||||
| Q2 | Days the app may open offline after the last sign-in (today: 12 hours) | 7 days. Wipe a disabled account's data on the next online open. | **7 days.** The default wipe rule stands. |
|
||||
| Q3 | Must planners edit in the creator offline, or only crews in Field View? | Field View only | **Only crews in the field.** The creator needs no offline mode. |
|
||||
| Q4 | An offline edit meets a newer server version. What does the crew see? | Keep both, show differences, crew chooses. Server wins if nobody acts. | **Merge with a notification. Log it. Update the owner.** If the same field changed on both sides, **the field value wins**, and the app keeps a history of changes. This replaces the default. |
|
||||
| Q5 | Photo limit per photo and per package | Resize to 1280 px, 50 per package | **5 MB per photo.** |
|
||||
| Q6 | Maximum packages in one batch print | 50, with a message to narrow the filter | **25 on phones.** On desktop the user can scale the filter up to 50 or 100. |
|
||||
| Q7 | Where drawings go in the PDF, and at what size | After the form, upload order, scaled to fit | **After the form, upload order, scaled to fit.** Same as the default. |
|
||||
| Q8 | SVG drawings in the merged PDF | Leave out, with a page that names the file | **Leave out, with a page that names the file.** Same as the default. |
|
||||
| Q9 | What goes on every page | Package no., print date, page X of Y | **Package no., print date, page X of Y.** Same as the default. |
|
||||
| Q12 | Progress weight for Ready for QA (today 0, so a package drops from 75% to 0%) | 0.85 | **0.85.** Same as the default. |
|
||||
| Q13 | What happens to a package's drawings when the package is deleted | Delete with the package | **Keep them (data retention). The storage quota is freed.** Storage will move to cloud storage in a future deployment. This replaces the default. |
|
||||
| Q14 | Which cost-code list is correct (creator has 38, SOP has 39, 13 differ) | One list in the SOP. Needs codes from Accounting or the PM. | **One list in the SOP.** The **PM** supplies the codes. |
|
||||
|
||||
## Follow-up answers (Matt, 2026-10-12)
|
||||
|
||||
These answer the six questions that were open after the first record.
|
||||
|
||||
1. **Q5:** the 5 MB limit is **per photo**. This matches the limit that already exists for drawings (D8, enforced in `server/app.py`: 5 MB a file, 2 GB per project).
|
||||
2. **Q6:** 25 on phones. Desktop users can scale up (50 or 100).
|
||||
3. **Q4:** on a conflict in the same field, **the field value wins**. The app keeps a history of changes.
|
||||
4. **Q13:** the quota is freed. Cloud storage will hold the kept files in a future deployment.
|
||||
5. **Q14:** the **PM** gives the codes.
|
||||
6. **Scaling:** Matt asked for a path to a mobile version that scales to multiple projects, outside VPN access, for field agents on phones and tablets on site. That path is in `docs/waves/roadmap-mobile-scaling.md`.
|
||||
7. **Who uses it:** all end users will eventually be in the Okta group.
|
||||
8. **Scale:** expect multiple **customers**. The data model needs a customer (organization) level above a project. See Phase 4 of the roadmap.
|
||||
9. **Devices:** company-managed.
|
||||
|
||||
## Still open
|
||||
|
||||
1. **Q5:** the count of photos per package, and whether the app resizes a photo before upload. Phone photos are often 3 MB to 8 MB. A 5 MB cap per photo with no resize will reject some normal photos.
|
||||
2. **Q4:** who "the owner" is (package owner, project owner, or the person who made the server change). Also: how long the history of changes is kept, and who can read it.
|
||||
3. **Q13:** how long a kept drawing is retained, who can delete it for good, and who can recover it. The quota is freed, so the retained bytes must not count toward the 2 GB project limit. Decide where they are counted instead.
|
||||
4. **Q14:** the date the PM gives the codes.
|
||||
5. **Q6:** who sets the larger desktop limit (each user, or an admin setting).
|
||||
6. The questions in `roadmap-mobile-scaling.md`, section 7 (nine open). The first two (one person on more than one customer, and the isolation model) change the data design. Answer them first.
|
||||
|
||||
## Source
|
||||
|
||||
Meeting with Nick. Status column in the original table: "Open. Team builds to the default" for every row, as of October 12. The answers above came after that status.
|
||||
@@ -1,115 +0,0 @@
|
||||
# Decisions: October 16, 2026
|
||||
|
||||
## D22: dry run for the Okta deprovisioning sync
|
||||
|
||||
**Asked by:** Matt Mabrey, 2026-10-16. **Extends:** D18 (wave 13). **Task:** T13.7.
|
||||
|
||||
**Why:** The sync disables a local account when Okta does not list the person.
|
||||
If the Okta profile attribute is wrong for some accounts, the first live run can
|
||||
disable people who have not left (see BL-069). The attribute `profile.login` is
|
||||
the default for `preferred_username`. It is not confirmed against the tenant, and
|
||||
the person who deploys has no access to the Okta admin console.
|
||||
|
||||
**Decision:** Add the environment variable `OKTA_SYNC_DRY_RUN`.
|
||||
|
||||
- Values `1`, `true`, `yes`, `on` (any case) turn it on. Any other value, or no
|
||||
value, leaves the sync live. It is off by default, so a deploy that does not set
|
||||
it behaves as before.
|
||||
- In a dry run the sync does every step of a live run: the fetch, the match, the
|
||||
zero-match guard and the fail-closed rules. It then changes no account and writes
|
||||
no audit row.
|
||||
- It logs one line for each account it would disable, and one summary line with the
|
||||
number of Okta users, active local accounts, matches, and accounts that would be
|
||||
disabled. Read them with `docker compose logs api | grep "Okta sync"`.
|
||||
- The startup line shows the mode.
|
||||
|
||||
**Not decided here:** a limit on accounts disabled in one run, and a rule to keep the
|
||||
last active admin (BL-069). The dry run lets a person see the result before the
|
||||
first live run. It does not stop a bad live run.
|
||||
|
||||
**Rules from D18 that stay:** fail closed, only disable, one audit row for each
|
||||
change, actor `system:okta_sync`.
|
||||
|
||||
## D23: sign in to the Okta Management API as an OAuth service app
|
||||
|
||||
**Asked by:** Matt Mabrey, 2026-10-16. **Extends:** D18, T13.2. **Task:** T13.9.
|
||||
|
||||
**Why:** The first deploy of the sync ended with `Okta answered HTTP 401`. The
|
||||
credential that Okta security gave Matt is an API Services app that uses client
|
||||
authentication `private_key_jwt`. It is a private key (a JWK with the fields `kty`,
|
||||
`use` and `kid`), not an SSWS API token. The sync sent that value as an SSWS token,
|
||||
and Okta refused it.
|
||||
|
||||
**Decision:** The sync accepts a second credential.
|
||||
|
||||
- `OKTA_SYNC_CLIENT_ID` and `OKTA_SYNC_PRIVATE_KEY` (a JWK as JSON, or as base64 of
|
||||
that JSON). The sync signs a JWT (RS256 or ES256, from the key's `alg`; `kid` goes
|
||||
in the header; `iss` and `sub` are the client ID; `aud` is `<org>/oauth2/v1/token`;
|
||||
life 5 minutes; a new `jti` each time) and posts it to `<org>/oauth2/v1/token`
|
||||
with `grant_type=client_credentials` and `scope=okta.users.read`.
|
||||
- The access token is used as `Authorization: Bearer` on `/api/v1/users`. It is
|
||||
requested again at the start of each run. It is not stored.
|
||||
- `OKTA_API_TOKEN` still works. If both are set, the token wins. A deploy that sets
|
||||
only a token is unchanged.
|
||||
- A DPoP token (`token_type` not Bearer) is refused with a clear message.
|
||||
|
||||
**Rules from D18 that stay:** fail closed. Any problem with the key, the token
|
||||
request or the user list raises an error, and the sync changes no account. The key,
|
||||
the signed JWT and the access token are never logged and never put in an error
|
||||
message. An error carries the HTTP status and the Okta error code only when that
|
||||
code is a short lower-case word.
|
||||
|
||||
**Not decided here:** how often the key is replaced. A key is registered on the Okta
|
||||
app and has no expiry that this code checks.
|
||||
|
||||
## D24: DPoP for the Okta Management API calls
|
||||
|
||||
**Asked by:** Matt Mabrey, 2026-10-16. **Extends:** D23. **Task:** T13.10.
|
||||
|
||||
**Why:** The first live token request with the service-app key ended with
|
||||
`error invalid_dpop_proof`. The Okta app requires DPoP (RFC 9449). With DPoP, every
|
||||
request carries a signed proof from a key that only the caller holds, so a stolen
|
||||
access token alone does not work. The choice was to ask the Okta admin to switch DPoP
|
||||
off, or to build it. Matt chose to build it.
|
||||
|
||||
**Decision:**
|
||||
|
||||
- `OKTA_SYNC_DPOP` is `auto` (default), `on` or `off`. In auto mode the sync asks for a
|
||||
plain Bearer token first. If Okta answers `invalid_dpop_proof`, the sync asks again with
|
||||
DPoP. So one build works whether the Okta app requires DPoP or not.
|
||||
- Each run makes its own throwaway EC P-256 key. It is held in memory only, never
|
||||
stored, logged or configured. The public half goes in each proof header.
|
||||
- Each request gets its own proof (ES256, `typ` dpop+jwt): `htm`, `htu` without the
|
||||
query, a one-time `jti`, `iat`, the server's latest `nonce`, and on an API call `ath`
|
||||
(a hash of the access token). The same key is used for the token request and the API
|
||||
calls. A new client assertion is built for every token attempt.
|
||||
- A nonce challenge is answered once per request, at the token endpoint and at the API.
|
||||
The token request is tried at most 4 times.
|
||||
- A DPoP-bound token is sent as `Authorization: DPoP <token>`. If the setting is `off`
|
||||
and Okta returns a DPoP-bound token, the sync stops with a clear message.
|
||||
|
||||
**Rules from D18 and D23 that stay:** fail closed; the key, the assertions, the proofs and
|
||||
the access token are never logged or put in an error message; an error carries the HTTP
|
||||
status and Okta's short error code only. The SSWS token path is unchanged.
|
||||
|
||||
**Not verified:** this has been tested only against a fake Okta that follows the RFC. The
|
||||
first run against the real tenant is the real test.
|
||||
|
||||
## D25: the session limit is 8 hours for now
|
||||
|
||||
**Decided by:** Matt Mabrey, 2026-10-17. **Closes:** the 2-versus-8 question in `wave-13.md`. **Task:** T13.11.
|
||||
|
||||
**The conflict:** the wave 13 exit criteria said `AUTH_SESSION_HOURS` defaults to 2. T13.1's own text and
|
||||
the T13.1 code say 8. The shipped default on `main` was 12.
|
||||
|
||||
**Decision:** The default is **8 hours**. This replaces the exit criterion of 2 hours.
|
||||
|
||||
- `AUTH_SESSION_HOURS` defaults to 8 in `server/auth.py`, `docker-compose.yml`, `server/.env.example` and
|
||||
`DEPLOY-login-portal.md`. A value that is set still wins.
|
||||
- Until T13.1 lands, 8 hours is one flat limit from the moment of sign-in, with no sliding. Once T13.1 lands, the
|
||||
same variable is the absolute ceiling and an idle timer sits under it. The default does not change then.
|
||||
- A person who signs in at the start of a shift is signed out 8 hours later, whatever they were doing. Signing in
|
||||
again needs Okta to be reachable.
|
||||
|
||||
**Open, for wave 14:** how the limit works for a crew that is offline. `wave-14.md` sets that rule.
|
||||
**Not decided here:** the idle time (T13.1 proposes 30 minutes). It is a proposed value, not a decision.
|
||||
@@ -1,30 +0,0 @@
|
||||
# Decisions: October 17, 2026
|
||||
|
||||
Status key: **Proposed** means the text is a recommendation. It needs Matt's OK before any build starts.
|
||||
|
||||
## D26: a sign-in problem never destroys a queued change (Proposed)
|
||||
|
||||
**Why:** The outbox (`html/project-data.js`) marks any `4xx` answer except `429` as dead. A `401` means the session ended, and it
|
||||
gets the same treatment. With a session limit (D25, 8 hours) or an idle timeout (T13.1), a crew that works offline past the limit
|
||||
comes back online and every queued change is rejected for good. The outbox also hides a full device store, and it sends a queued
|
||||
change under whoever is signed in, not under the person who made it.
|
||||
|
||||
**Proposal:**
|
||||
|
||||
- `401` holds the queue. It does not mark anything dead and does not count as a try. The queue sends after a good sign-in.
|
||||
- `403` stays a permanent refusal, with a clear reason.
|
||||
- A full device store is reported. The change is never dropped silently.
|
||||
- Each queued change has an owner. It is sent only when that person is signed in.
|
||||
|
||||
**Tasks:** `T14.1`, `T14.3`. **Needs Matt:** open questions 1 and 3 in `wave-14.md`.
|
||||
|
||||
## D27: the offline sign-in window follows the server (Proposed)
|
||||
|
||||
**Why:** `auth-guard.js` allows the app to open offline for a fixed 12 hours after the last good check, and every page load resets that
|
||||
time. The server session lasts 8 hours (D25). The two do not agree.
|
||||
|
||||
**Proposal:** `/api/auth/me` returns `session_expires_at`. The browser stores it and does not extend it. Offline, the app opens until
|
||||
that time. After that time, offline, it works in read-and-queue mode and does not redirect. Online, a `401` goes to sign-in and the
|
||||
queue is kept. The 7 day offline window (`BL-062`) is a later wave.
|
||||
|
||||
**Task:** `T14.2`. **Needs Matt:** open question 2 in `wave-14.md`.
|
||||
@@ -1,85 +0,0 @@
|
||||
# Session notes — 2026-09-23
|
||||
|
||||
Working notes for the `feat/waves-11-13` line (CR-019, CR-020 reserved, D18),
|
||||
written up before merge. Not a spec document — `wave-11.md`, `wave-13.md` and
|
||||
`decisions-2026-09-17.md` are the source of truth for scope and acceptance
|
||||
criteria. This is the "what actually happened building it" record.
|
||||
|
||||
## What shipped today
|
||||
|
||||
**CR-019 (wave 11) — usage/activity metrics, T11.1 through T11.6 complete:**
|
||||
|
||||
- `UsageEvent` table + migration (T11.1), a capture endpoint wired into
|
||||
`auth-guard.js` so every protected page pings it once per load, plus a
|
||||
`login` event at Okta sign-in (T11.2).
|
||||
- `GET /api/usage/summary` (T11.3) — active users by day/week/month,
|
||||
per-user last-active, per-tool breakdown, filterable by date/project/
|
||||
user/tool, all combinable.
|
||||
- `GET /api/usage/export` (T11.4) — raw and sanitized CSV. Sanitized mode
|
||||
replaces the username with an HMAC-SHA256 pseudonym (keyed with
|
||||
`auth.SECRET_KEY`), stable per user across rows and across separate
|
||||
export calls, so an external tool (Power BI etc.) can still group by
|
||||
user without ever seeing a real name.
|
||||
- A new "Activity & usage" card in the admin console (T11.5): real filter
|
||||
controls, the summary tables, both export buttons. Client-side gated
|
||||
admin-only same as the rest of the console; the API underneath is
|
||||
independently gated server-side regardless.
|
||||
- Retired the old per-browser "Usage logs" panel and `wp-usage.js`
|
||||
entirely (T11.6) — it had no reader left and was never a real data
|
||||
source for the new report anyway. The scattered `track()` call sites in
|
||||
the creator and wizard were left in place calling a documented no-op,
|
||||
rather than deleting ~45 individual call sites for the same effect.
|
||||
|
||||
Only **T11.7 (final wave verification)** is left before wave 11 is fully
|
||||
closed out — everything under it has already been verified per-task, so
|
||||
this is a consolidation pass, not new work.
|
||||
|
||||
**D18 (wave 13) — Okta/AD deprovisioning, T13.1 only:**
|
||||
|
||||
- Session lifetime changed from one flat `AUTH_SESSION_HOURS` to a sliding
|
||||
idle timeout (`AUTH_IDLE_MINUTES`, default 30) capped by a hard ceiling
|
||||
from original sign-in (`AUTH_SESSION_HOURS`, default 8, meaning changed
|
||||
from "session length" to "absolute ceiling"). Both defaults are flagged
|
||||
in `.env.example` and `DEPLOYMENT.md` as proposed, not confirmed against
|
||||
the tenant's actual Okta SSO policy.
|
||||
- **T13.2 onward (the actual Okta Management API sync job) is paused** —
|
||||
explicit call from Matt: no Okta API credential yet, come back to it
|
||||
later. Not started, not blocked on anything code-side.
|
||||
|
||||
**CR-020 (wave 12, bulk user editing):** not started. Reserved, scoped in
|
||||
`wave-12.md`, no code touched.
|
||||
|
||||
## Environment work (not itself a task, but load-bearing)
|
||||
|
||||
- Fixed a CRLF/LF mismatch that was making every tracked file look modified
|
||||
to this session's git client (`core.autocrlf true`, repo-local, no file
|
||||
content changed).
|
||||
- This machine had no Python. Installed it via `winget` (`Python.Python.3.12`)
|
||||
and set up a `.venv` in the repo with `server/requirements.txt` installed,
|
||||
specifically so `tests/baseline_shots.py` could run locally — this
|
||||
sandbox has no headless-capable browser and can't download one (network
|
||||
allowlist), so the 390px/1440px screenshot verification CLAUDE.md asks
|
||||
for had to run on Matt's own machine instead, using the browser already
|
||||
installed there (Edge).
|
||||
- Established a repeatable local verification loop for every task: throwaway
|
||||
SQLite, fake-Okta sign-in, promote to admin, `seed_demo.py` +
|
||||
`smoketest.py` (27/27 passing throughout), plus `baseline_shots.py` for
|
||||
anything touching `html/`.
|
||||
|
||||
## Standing constraints, still in effect
|
||||
|
||||
- Everything stays local on this branch line. No `git push` at any point
|
||||
today.
|
||||
- One task per PR discipline was kept even though all of it landed on one
|
||||
branch — each commit corresponds to exactly one task ID, in wave order,
|
||||
each individually verified before the next started.
|
||||
|
||||
## Before merging
|
||||
|
||||
- Run T11.7 (full wave-11 verification pass) and record it in `wave-11.md`.
|
||||
- Decide where this branch actually merges to — `feat/waves-11-13` has all
|
||||
of today's commits already; this notes branch was cut from it so it can
|
||||
fast-forward back in, or merge as its own PR if the notes should be
|
||||
reviewed separately from the code.
|
||||
- T13.2+ and all of wave 12 remain explicitly out of scope until Matt says
|
||||
otherwise.
|
||||
@@ -1,178 +0,0 @@
|
||||
# Roadmap: mobile version, multiple projects, access outside the VPN
|
||||
|
||||
Date: 2026-10-12
|
||||
Status: plan for a future build. It is not a spec. No wave, `CR-`, or `D-` id exists for it yet.
|
||||
Inputs: `docs/waves/decisions-2026-10-12.md` (Q2 to Q14), `BL-062` to `BL-068` in `docs/waves/backlog.md`, and the code as of `main` (`d42ae0c`).
|
||||
|
||||
Goal (from Matt, 2026-10-12): field agents use the app on phones and tablets on site, from outside the VPN, across more than one project.
|
||||
|
||||
Scope facts confirmed by Matt on 2026-10-12:
|
||||
- All end users will be in the Okta group. There are no contractors without an Okta account.
|
||||
- The product will scale to **multiple customers**, not only more projects for one customer.
|
||||
- The devices will be **company-managed**.
|
||||
|
||||
## 1. Where the product is today
|
||||
|
||||
| Area | Fact today | Source |
|
||||
|---|---|---|
|
||||
| Mobile shell | A PWA already exists: `manifest.webmanifest` (standalone, "Field View" shortcut) and `sw.js` (caches the app shell and uploaded drawings). | `html/manifest.webmanifest`, `html/sw.js` |
|
||||
| Offline writes | Writes queue in a sync outbox in `project-data.js`. Reads fall back to a `localStorage` cache. `/api/*` is never cached by the service worker. | `html/sw.js` header |
|
||||
| Offline drawings | Drawings for the user's assigned packages are prefetched and cached (CR-007, D8). | `html/sw.js`, `html/field.js` |
|
||||
| Files | The bytes live in the Postgres `wp_files` table. Limit: 5 MB a file, 2 GB per project. | `server/models.py` |
|
||||
| Sign-in | Okta OIDC. A signed cookie (`HttpOnly`, `SameSite=Lax`, `Secure` over HTTPS). Idle timeout (D18, T13.1) is on `feat/waves-11-13`, not on `main`. | `server/auth.py`, `docs/waves/wave-13.md` |
|
||||
| Projects | `Project` and `ProjectMember` exist. Access is by project role. There is no organization or customer level above the project. | `server/models.py` |
|
||||
| Hosting | Docker Compose on an internal host. NGINX serves the site. An external proxy ends TLS. The database and backup containers have no internet route. | `docker-compose.yml`, `nginx/conf.d/wp-suite.conf` |
|
||||
| Asset picker | Reads the Micron SQL Server catalog through `MICRON_DB_URL`. That database sits on the company network. | `server/assets_db.py` |
|
||||
| Abuse limits | No rate limiting or login throttling was found in `server/`. CSRF origin checks and security headers (CSP, HSTS) exist. | `server/app.py`, `wp-suite.conf` |
|
||||
| Security review | The 2026-10-01 review put session revocation (SEC-06) on hold until the AWS work. Wave 16 fixed SEC-01, SEC-02, SEC-07. | `docs/waves/decisions-2026-10-02.md` |
|
||||
|
||||
Result: the "mobile app" is mostly built as a PWA. The main work is not a new app. It is (a) finishing offline Field View, (b) making the service safe to put on the internet, and (c) removing the single-host limits.
|
||||
|
||||
## 2. Path in phases
|
||||
|
||||
Each phase has a gate. Do not start a phase before the gate of the one before it is met, unless this file says the phases are independent. Sizes are rough estimates (S under 1 week, M 1 to 3 weeks, L over 3 weeks). They are not commitments.
|
||||
|
||||
### Phase 0: Close the open decisions (S)
|
||||
|
||||
- Answer the questions in section 7 and the "Still open" list in `decisions-2026-10-12.md`.
|
||||
- Assign `CR-`/`D-` ids and write the wave files.
|
||||
- **Gate:** every item in `BL-062` to `BL-068` is free of "to confirm".
|
||||
|
||||
### Phase 1: Finish offline Field View, still inside the VPN (L)
|
||||
|
||||
Scope: `BL-062`, `BL-063`, `BL-064`.
|
||||
|
||||
1. Land the outbox work (wave 14, T14.1 to T14.3). `wave-12.md` says T13.1 must not reach `main` before T14.1.
|
||||
2. Set the offline window to 7 days (Q2). Reconcile it with the D18 idle timeout and absolute ceiling. Define what "signed in" means offline. Decide what the 7 day window does when Okta says the account is disabled (wipe on the next online open).
|
||||
3. Conflict handling (Q4): merge, field value wins on the same field, history of changes, a notification to the crew, a log entry, and an update to the owner.
|
||||
4. Photos: capture on the device, 5 MB per photo (Q5). Add resize before upload if Matt chooses it. Store photos like drawings (server-side, with D19 download headers).
|
||||
5. Add a phone and tablet test matrix (real devices): iOS Safari installed to the home screen, Android Chrome, one tablet.
|
||||
6. Test the weak-link case: no signal, then a slow signal, then a sync with a conflict.
|
||||
|
||||
Known platform risks to test on the devices (verify; do not assume):
|
||||
- iOS may delete site storage after a period of no use unless the PWA is installed to the home screen.
|
||||
- iOS Safari has no Background Sync. The outbox then sends only while the app is open. A crew member must open the app to push changes.
|
||||
- A lost device holds up to 7 days of project data. Web storage is not encrypted by the app. See Phase 2.
|
||||
|
||||
**Gate:** the crew completes a full shift offline on a test device, reconnects, and the server holds every change. The conflict case works as Q4 says. `tests/mobile_check.py` and the 390px/1440px checks pass.
|
||||
|
||||
### Phase 2: Make the service safe to reach from the internet (M to L)
|
||||
|
||||
Today the design assumes the firewall. Outside the VPN, the app becomes the perimeter. Do this before any real user connects from the internet.
|
||||
|
||||
| Control | Why |
|
||||
|---|---|
|
||||
| Rate limiting and login throttling on the API (none today) | Stops guessing and scraping. The toolkit (`sde-meeting-toolkit`) needed the same fix. |
|
||||
| A WAF or reverse proxy with request limits in front of NGINX | Filters bad requests before they reach the API. |
|
||||
| Real client IP handling (`X-Forwarded-For` from the trusted proxy only) | Limits and logs must use the real address, not the proxy. |
|
||||
| Okta policy for the app: MFA, session length, device trust | Okta is the only sign-in path (D15, D16). The policy is the control. Ask the Okta admin. |
|
||||
| Session revocation (SEC-06) | When a phone is lost, an admin must end that session now. This was put on hold for the AWS work. Bring it forward. |
|
||||
| A rule for lost devices | Devices are company-managed (decided). Require a device PIN and disk encryption through the device policy. Remote wipe through the device manager. Pair it with session revocation (above), because a wipe cannot reach an offline device. Confirm with IT that the policy covers every phone and tablet that runs the app, and that a lost device is reported quickly. |
|
||||
| Okta access rule | All end users are in the Okta group (decided). Gate the app on that group. Today the API creates the account on first sign-in; check that a person who is not in the group is refused, and that removal from the group ends access (this is what D18 and wave 13 do). Ask the Okta admin to add MFA and device-trust conditions for the outside path. |
|
||||
| Cookie flags on every cookie (the OIDC state cookie uses `https_only=False` in `server/app.py`) | Must be `Secure` on the public site. |
|
||||
| Review the 2026-10-01 findings that stayed in backlog drafts | Re-rank them for an internet-facing service. |
|
||||
| Outside review (a penetration test) | Required before the customer-IP data is reachable from the internet. |
|
||||
| Alerting on failed sign-ins and on odd upload sizes | Detect abuse early. |
|
||||
|
||||
**Gate:** the controls above are in place and an outside test finds no high findings open.
|
||||
|
||||
### Phase 3: Hosting that can leave the office network (L)
|
||||
|
||||
The AWS work is already planned (SEC-06 note). Proposed shape. The choice of services is open for Matt and the AWS owner.
|
||||
|
||||
- A public edge (load balancer, WAF, TLS) in front of the API and the static site.
|
||||
- API containers on a managed container service, with a managed Postgres database.
|
||||
- Files in object storage instead of the database (`BL-066`, Q13). Move the bytes out of `wp_files`. Keep the metadata in Postgres. Kept files from deleted packages go to a retention area with a lifecycle rule. The quota counts only live files.
|
||||
- Backups and restore tests on the new stack (the current backup container writes to a host folder).
|
||||
- A private link back to the Micron asset database, or a different design for the asset picker (the catalog is on the company network). Until this exists, the picker falls back to manual entry outside the VPN. Check that fallback works for a user who is online but cannot reach the database (the code treats "unconfigured" as a normal state, but not "unreachable").
|
||||
- Infrastructure as code, so the environment can be rebuilt.
|
||||
- Keep the internal deployment working until the cutover.
|
||||
|
||||
**Gate:** a full restore test passes, the migration runs on Postgres (render the SQL for the Postgres dialect first, BL-027), and a rollback plan is written and rehearsed.
|
||||
|
||||
### Phase 4: Many projects and many customers (L)
|
||||
|
||||
Matt confirmed multiple customers. A customer boundary is now part of the plan, not an option. The data model has `Project` and `ProjectMember` but nothing above a project, so this phase changes the base design. Plan for it early. Phase 3 choices (storage layout, database layout) must already allow it.
|
||||
|
||||
- Add an organization (customer) level above `Project`. Every project, user role, file, report, export, and search belongs to one organization. A user may belong to more than one organization (for example Prime Controls staff who work for several customers). Decide this rule first (section 7, question 1).
|
||||
- Isolation: choose the model before any code. Options: one database with an organization id on every row and checks on every query; a separate schema per customer; or a separate database or stack per customer. Matt and the AWS owner decide. The choice sets cost, backup, and the strength of the separation that a customer can be shown.
|
||||
- Files: one storage prefix per customer, with its own access rule and, if a customer asks, its own encryption key.
|
||||
- Customer-specific data: the cost-code list, the asset catalog (today Micron only), and the SOP templates must belong to the organization or the project. `BL-068` (one cost-code list in the SOP) must not become one list for all customers.
|
||||
- Okta: map Okta groups to organizations and projects, so the Okta admin controls who sees which customer.
|
||||
- Reports and the admin console: super users see only the organizations they are given. Check CR-019 usage reports, the user directory, and the bulk user tools from wave 12 against this rule.
|
||||
- Onboarding a customer: a runbook with the steps and a checklist.
|
||||
- Project onboarding: create a project, load its SOP, cost codes (`BL-068`, one list in the SOP, codes from the PM), people, and roles. Use the bulk user tools from wave 12.
|
||||
- Okta group to project membership mapping, so the Okta admin controls who joins a project.
|
||||
- Per-project storage and photo quotas (2 GB per project exists today) and per-project usage reports (CR-019 on `feat/waves-11-13`).
|
||||
- Performance work with a load test: many crews syncing at shift start. Check the outbox flush, the `wp_files` move, and the list endpoints on a large project.
|
||||
- Data retention rules per project.
|
||||
|
||||
**Gate:** two real customers run side by side. A test user in one customer cannot reach any data of the other through any screen, report, export, search, file link, or API call. A test that tries to cross the boundary on purpose passes. The load test meets targets that Matt sets.
|
||||
|
||||
### Phase 5: Native wrapper (only if needed) (M)
|
||||
|
||||
Wrap the PWA in a native shell (for example Capacitor) only if Phase 1 testing shows a platform limit that the PWA cannot meet: storage eviction, no background sync, camera control, or a company rule for app-store distribution. A wrapper adds app-store review, signing, and update cost. Do not start it by default.
|
||||
|
||||
## 3. Order and dependencies
|
||||
|
||||
```
|
||||
Phase 0 -> Phase 1 -> Phase 2 -> Phase 3 -> Phase 4
|
||||
\_ Phase 5 (decide after Phase 1 device tests)
|
||||
```
|
||||
|
||||
- Phase 2 may start in part while Phase 1 runs (rate limiting, Okta policy review). No crew uses the internet path before Phase 2 is done.
|
||||
- Phase 3 (storage move) and `BL-066` (retained drawings) are the same work. Do them together.
|
||||
- Phase 4 needs the Phase 2 and Phase 3 gates. Opening a second project to the internet first would repeat any gap twice.
|
||||
|
||||
## 4. Work that this path adds to the backlog
|
||||
|
||||
| Id | Item | Phase |
|
||||
|---|---|---|
|
||||
| BL-062 to BL-068 | Already logged | 1, 3, 4 |
|
||||
| New | API rate limiting and login throttling | 2 |
|
||||
| New | Real client IP handling behind the proxy | 2 |
|
||||
| New | Session revocation (SEC-06) brought forward | 2 |
|
||||
| New | Device policy check with IT (PIN, encryption, remote wipe) | 1, 2 |
|
||||
| New | Okta group gate and MFA/device-trust conditions for the outside path | 2 |
|
||||
| New | Object storage and lifecycle rules for files, one prefix per customer | 3 |
|
||||
| New | Asset picker when the Micron database is unreachable | 3 |
|
||||
| New | Organization (customer) level above `Project`, with the isolation model chosen first | 3, 4 |
|
||||
| New | Per-customer cost codes, asset catalog, and SOP templates | 4 |
|
||||
| New | Okta group to organization and project mapping | 4 |
|
||||
| New | Cross-customer access tests (a test that tries to cross the boundary) | 4 |
|
||||
| New | Customer onboarding runbook | 4 |
|
||||
| New | Load test and capacity targets | 4 |
|
||||
|
||||
Log these in `docs/waves/backlog.md` when Matt agrees with the plan. This file does not add them, so the backlog stays free of unconfirmed scope.
|
||||
|
||||
## 5. Risks
|
||||
|
||||
1. **Customer data on lost devices.** Offline data for 7 days on a phone or tablet. Devices are company-managed, which lowers this risk a lot, but only if the device policy (PIN, disk encryption, remote wipe) is real and covers every device. An offline device cannot receive a wipe until it connects. Keep the 7 day window only if IT confirms the policy.
|
||||
2. **Customer boundary added late.** The data model has no organization level. If Phases 1 to 3 are built without it, every later change touches every table and every query. Choose the isolation model in Phase 0 and design Phase 3 storage around it.
|
||||
3. **Contract terms.** Customer drawings and asset data may have rules about where they are stored and who can reach them. With several customers, each contract may differ. Check before Phase 3 (cloud storage) and before Phase 2 (internet access).
|
||||
4. **Okta.** The app has no password of its own. A weak Okta policy for the outside path is a weak app. The Okta admin owns that setting.
|
||||
5. **Single database host.** The current database is one container with a host-folder backup. Phase 3 fixes this. Until then, do not add projects that need high availability.
|
||||
6. **Sequence risk.** T13.1 (idle timeout) must wait for T14.1 (outbox). A short idle timeout can end a session while a crew is offline. Settle the rule in Phase 1.
|
||||
|
||||
## 6. What does not change
|
||||
|
||||
These decisions stay as recorded: Actual Hours stays (CR-017), localization stays (A7), uppercase card headers stay (A5), the logged-override path for predecessors stays (A1), removed fields are hidden and not deleted (CR-002, CR-016), and the token rule for CSS. Mobile work follows the accessibility rules (C1): real buttons, visible focus, `aria-live` for status, hover is not enough on tablets.
|
||||
|
||||
## 7. Questions that decide the plan
|
||||
|
||||
Answered on 2026-10-12:
|
||||
- Who are the outside users? **All end users will be in the Okta group.** No separate sign-in design is needed.
|
||||
- What does "multiple projects" mean? **Multiple customers.** See Phase 4.
|
||||
- Which devices? **Company-managed.**
|
||||
|
||||
Answer these before Phase 0 ends. The first four are new and follow from the answers above.
|
||||
|
||||
1. **Can one person work for more than one customer?** For example, a Prime Controls planner on two customers' projects. This sets how the organization level and the Okta groups map to each other.
|
||||
2. **Which isolation model?** One database with an organization id on every row, a schema per customer, or a database or stack per customer. Do any customers already require a separate stack in their contract?
|
||||
3. **Who manages the Okta groups?** One group for all users, or one group per customer or project? Does the Okta admin accept that mapping?
|
||||
4. **What does the device policy enforce today?** PIN, disk encryption, remote wipe, and a time limit for a device to check in. Ask IT.
|
||||
5. **Connectivity on site.** No signal for days, or weak signal that comes and goes? This sets how long the offline window must really be, and how big the photo queue gets.
|
||||
6. **AWS.** Is the AWS move approved? Who owns the account? Which region? Can the Micron database be reached from it?
|
||||
7. **Contract.** Can customer drawings and asset data be stored in cloud storage and reached from the internet? Does each customer have its own terms?
|
||||
8. **Distribution.** Is an installed PWA enough, or does the company need an app-store app? Company-managed devices can often install a web app from a device policy. Ask IT.
|
||||
9. **Targets.** How many customers, projects, and users, and how many crews syncing at the same time, in the first year?
|
||||
@@ -1,233 +1,399 @@
|
||||
# Wave 10 — Okta OIDC authentication
|
||||
# Wave 10 — Domain authentication over LDAPS
|
||||
|
||||
Fresh wave 10. The label was previously used by the LDAPS work under `D13`/`D14`, built on
|
||||
`feat/ldaps-directory-auth`; that branch was deleted rather than merged and never appeared
|
||||
in `IMPLEMENTATION.md`'s wave table, so it carries no claim on the number. See
|
||||
`docs/waves/decisions-2026-09-02.md` (`D15`) for why LDAPS was retired before deployment
|
||||
and Okta chosen instead.
|
||||
**Items:** `D13`, `D14`
|
||||
**Depends on:** wave 9 merged (it is — `a8e28bf`)
|
||||
|
||||
Depends only on `main` as it stands after `D15`. Not sequenced behind any other wave.
|
||||
One item, eight tasks. The item is stated in `docs/waves/decisions-2026-08-21.md`; read it
|
||||
before starting, particularly the **Non-negotiables** section, which is where this change
|
||||
goes wrong if it goes wrong.
|
||||
|
||||
## Tasks
|
||||
**This wave is field-visible in one direction only.** Nobody gains a screen. People sign in
|
||||
with their Windows password instead of an app password, the "Forgot password?" link
|
||||
disappears, and admins stop issuing passwords. Everything else is invisible — which means
|
||||
the done-when checks are the only evidence the wave worked.
|
||||
|
||||
- **T10.1 — Add the Okta OIDC client.** Authlib as a dependency. Config via env vars
|
||||
(`OKTA_ISSUER`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`, `OKTA_REDIRECT_URI`), same
|
||||
pattern `AUTH_SECRET_KEY` already uses in `server/auth.py`.
|
||||
> **BEFORE PRODUCTION: `LDAP_REQUIRED_GROUP` must be set.** It is empty by default,
|
||||
> and empty means *no group gate* — every account in `prime.local` may sign in. The
|
||||
> successful live sign-in on Aug 24 was made without it, so it proved the bind, the
|
||||
> certificate chain and JIT provisioning, but **not** the group check: that path never
|
||||
> executed. The group gate is covered against the fake directory in `ldap_auth_check`
|
||||
> and has never run against the real directory. The startup line says which state you
|
||||
> are in — `required group: (none configured — every domain account may sign in)`.
|
||||
|
||||
- **T10.2 — Login-redirect and callback routes.** A route that sends the browser to
|
||||
Okta's authorize endpoint, and a callback route that exchanges the code for tokens and
|
||||
validates the ID token. Access gating is Okta's job, not this app's: only accounts
|
||||
assigned to the app integration in Okta can reach it at all, so there is no app-side
|
||||
required-group or claim check layered on top. This is a deliberate difference from D13,
|
||||
which had to gate on a required AD group itself because an LDAPS bind alone could not
|
||||
distinguish an assigned user from any other domain account.
|
||||
**Build order is task order** for once. `T10.1` is a standalone module with no callers and
|
||||
should merge first; nothing else can be tested until it exists.
|
||||
|
||||
- **T10.3 — Identity matching and JIT provisioning.** Reuses D13's shape
|
||||
(`_provision_from_directory`-style matching) keyed off an OIDC claim instead of an LDAP
|
||||
search result. **Open dependency:** which claim carries the AD `sAMAccountName`
|
||||
equivalent (`preferred_username`, `upn`, or a custom claim) is asked of security and not
|
||||
yet answered. Build with a configurable claim name and a documented default, not a
|
||||
hardcoded one, so the answer can drop in without a code change.
|
||||
---
|
||||
|
||||
- **T10.4 — Remove the local password path entirely.** Drop `password_hash` (Alembic
|
||||
migration; plain `op.drop_column`, matching existing precedent for other NOT NULL
|
||||
columns on `users` — no `batch_alter_table` needed), remove the bcrypt-based
|
||||
`login()`, remove the username/password form. Real deletion, matching `D15`'s "full
|
||||
replacement," not a toggle or a fallback. Scope corrected by `D16` after hazard
|
||||
review turned up more call sites than the original bullet named:
|
||||
- `create_user()` and `admin_reset_password()` in `server/app.py` (admin console's
|
||||
"add user" and "reset password" routes) — rework to drop the password field
|
||||
entirely rather than break.
|
||||
- `html/users.js`'s "add user" form (`nu-password`) and "Reset password" button —
|
||||
matching frontend change.
|
||||
- `server/manage_users.py` — reworked per `D16` from account *creation* to
|
||||
*promotion*: `create-admin`/`create`/`reset-password` (password-based) are
|
||||
replaced by a promote-by-username command that operates on a row Okta's JIT
|
||||
provisioning (T10.3) already created, never a hand-typed new one. This is now
|
||||
the documented admin-bootstrap path — see `D16`.
|
||||
- `tests/browser_check.py` and `tests/launcher_check.py` — stop calling
|
||||
`auth.hash_password()` to seed fixture rows.
|
||||
- `server/smoketest.py` and `server/seed_demo.py` — currently authenticate via
|
||||
`POST /api/auth/login`. Switch to minting a session with `auth.create_token()`
|
||||
directly, the same technique `browser_check.py` already uses, so both scripts
|
||||
(named explicitly in `CLAUDE.md`'s verification section) keep working without
|
||||
depending on `T10.7`'s timing.
|
||||
### T10.1 — The LDAPS client
|
||||
|
||||
- **T10.5 — Frontend: login becomes a redirect, not a form.** `login.html`/`login.js`
|
||||
change to a "Sign in with Okta" flow. Sign-out lands back on the app's own login page.
|
||||
- **Items:** `D13` (1)
|
||||
- **Depends on:** nothing
|
||||
- **Blocks:** T10.2, T10.4, T10.5, T10.7
|
||||
- **Surface:** `server/`
|
||||
- **Files:** new `server/ldap_auth.py`, `server/requirements.txt`, `docker-compose.yml`,
|
||||
`Dockerfile`, `server/.env.example`
|
||||
|
||||
- **T10.6 — Deployment docs and env var reference.** `DEPLOYMENT.md`,
|
||||
`server/.env.example`, `server/README.md` describe the Okta config in place of the LDAP
|
||||
config they never ended up describing (D13 never shipped, so these still describe the
|
||||
original local-password system today).
|
||||
**Problem:** There is no directory client in the repo. `ldap3` is not a dependency, the API
|
||||
container has no CA bundle, and the `api` service sits on the `internal` network, which has
|
||||
no default gateway and therefore no route to `192.168.3.x` at all.
|
||||
|
||||
Built: all three rewritten — the five `OKTA_*` vars documented the same way
|
||||
`AUTH_SECRET_KEY` already was, the login-portal/self-service-reset sections replaced
|
||||
with the Okta flow and the promote-not-create admin bootstrap (D16), the smoke-test
|
||||
walkthrough updated for `WP_SMOKE_USER`-only / must-share-`AUTH_SECRET_KEY`-and-DB
|
||||
(T10.4's `smoketest.py` rewrite). Also `docker-compose.yml`, not originally named in
|
||||
this bullet: its `api` service sets `environment:` as an explicit allowlist, not
|
||||
`env_file`, so the documented vars would silently never reach the container without
|
||||
adding them there too — found and fixed in the same commit rather than shipping docs
|
||||
for a config path that doesn't work. `OKTA_IDENTITY_CLAIM` mirrors
|
||||
`okta_auth.py`'s own default (`preferred_username`) in the compose file rather than
|
||||
defaulting to an empty string, which would 503 every sign-in.
|
||||
**Do:** Add `ldap3` (pinned, per the convention at the top of `requirements.txt`). Write
|
||||
`server/ldap_auth.py` exposing two functions and nothing else:
|
||||
|
||||
Logged, not fixed here (out of scope): `users.failed_attempts`/`locked_until` are
|
||||
vestigial (still reset on every Okta sign-in, nothing increments them since local
|
||||
`login()` is gone); `server/README.md`'s own "Production — Docker Compose" section
|
||||
is a self-contained alternate quickstart that already diverged from the real root
|
||||
`docker-compose.yml` before this task and still does.
|
||||
- `verify(username, password) -> LdapResult | None` — simple bind as
|
||||
`f"{username}@{domain}"` against `ldaps://{host}:636`.
|
||||
- `member_of(conn, group) -> bool` — nested-group aware, via
|
||||
`LDAP_MATCHING_RULE_IN_CHAIN` (`1.2.840.113556.1.4.1941`). `memberOf` alone is direct
|
||||
membership only and will wrongly refuse anyone in a nested group.
|
||||
|
||||
- **T10.7 — Test coverage without a live Okta dependency.** A fake-OIDC-provider test
|
||||
seam, mirroring `ldap_fake.py`, so the suite runs with no live Okta tenant reachable.
|
||||
Built: `server/okta_fake.py` (env-driven, `WP_OKTA_FAKE_DIRECTORY`, production-refusing
|
||||
the same way `ldap_fake.py` does), dispatched from `okta_auth._build_oauth()` before
|
||||
the real Authlib client is considered. Only the two Authlib calls that touch the
|
||||
network — `authorize_redirect` / `authorize_access_token` — are faked; `app.py`'s
|
||||
`okta_login()`/`okta_callback()` (the `?next=` guard, the disabled-account check, JIT
|
||||
provisioning, the identity-claim lookup) run unmodified against the fake, same
|
||||
boundary the LDAP predecessor drew around the anonymous-bind guard. Two fake-only
|
||||
routes (`/_fake_provider`, `/_fake_provider/consent`) stand in for Okta's own sign-in
|
||||
screen and are registered in `app.py` only when the fake is active at import time —
|
||||
in production they do not exist, not merely refuse. `tests/browser_check.py`'s
|
||||
`start_server()` now takes an optional `extra_env` and sets
|
||||
`WP_OKTA_FAKE_DIRECTORY` unconditionally (same reasoning `ldap_fake`'s equivalent
|
||||
used: almost nothing signs in, but the one check that does should not fail
|
||||
mysteriously). `tests/url_state_check.py` scenario 2 is un-skipped and drives the
|
||||
real round trip — login.html's button, the fake picker page, the fake consent
|
||||
redirect, `okta_callback()` — proving `?next=` survives it, same tightened
|
||||
"actually left login.html" assertion the LDAP predecessor's own bug fix used.
|
||||
`tests/okta_auth_check.py` is new: the production guard, single-use/replay on the
|
||||
authorization code, an unsolicited callback hit, a tampered state, a denied consent,
|
||||
an unknown identity, a disabled account, JIT provisioning, an existing admin
|
||||
surviving unchanged, same-site vs. off-site `?next=`, and `OKTA_IDENTITY_CLAIM`
|
||||
genuinely working under a non-default claim name — 22/22.
|
||||
Configuration by environment: `LDAP_HOST` (default `prime.local`), `LDAP_DOMAIN` (default
|
||||
`prime.local`), `LDAP_CA_FILE`, `LDAP_REQUIRED_GROUP`, `LDAP_TIMEOUT_SECONDS`. Attach the
|
||||
`outbound` network to `api` in `docker-compose.yml` — the same reason `assets_db.py` needed
|
||||
it, and the comment there already explains the gateway-less `internal` network. Mount or
|
||||
`COPY` the PEM bundle and point `LDAP_CA_FILE` at it.
|
||||
|
||||
The dev sandbox this was built in has no headless browser and no way to install
|
||||
one, so `tests/url_state_check.py` and `tests/browser_check.py` (both need
|
||||
`tests/cdp.py`'s real headless Chromium) could not be run there — only
|
||||
`okta_auth_check.py`'s HTTP-level coverage of the same mechanism. Run for real
|
||||
afterward on a machine with Docker, via a separate general-purpose tool
|
||||
(`headless-py-test-runner`, kept out of this repo — it is not Work Package Suite
|
||||
specific): `url_state_check.py` 26/26, including scenario 2's real click-through of
|
||||
the fake-Okta round trip, and `browser_check.py` 71/71. Gap closed.
|
||||
Connect to **`prime.local`**, never a DC hostname and never an IP. See the decision doc for
|
||||
why: SAN coverage plus round-robin across six DCs in one move. Wrap the bind in a retry
|
||||
across resolved addresses, because round-robin will hand out a rebooting DC's address.
|
||||
|
||||
**Validated 2026-09-03:** `tests/okta_auth_check.py` 22/22 (no browser needed) ·
|
||||
`tests/url_state_check.py` 26/26 · `tests/browser_check.py` 71/71 — all three run
|
||||
clean, the last two against real headless Chromium via Docker.
|
||||
**Done when:**
|
||||
|
||||
- **T10.8 — Verification.** 390px and 1440px, full suite, done-when checks per task,
|
||||
matching the rigor D13 was held to.
|
||||
- [x] `ldap3` is pinned to an exact version in `requirements.txt`
|
||||
- [x] an empty or whitespace-only password returns failure **without calling `bind()`** — proven with `Connection` nulled, so any call to `bind()` would raise
|
||||
- [x] an empty username returns failure without calling `bind()`
|
||||
- [x] `Tls` is constructed with `validate=ssl.CERT_REQUIRED` and an explicit `ca_certs_file`
|
||||
- [x] no code path sets `CERT_NONE`, and none falls back to the system trust store — asserted by an AST walk in `ldap_auth_check`, not a grep: the docstring names it to explain the ban
|
||||
- [~] `member_of` returns true for an account in a **nested** child of the required group — **partially closed Aug 24.** The transitive matching rule was exercised against the live directory for a DIRECT member (`CN=Prime Employees`, 2,003 members) and returned a match, so the rule and the filter are correct on this estate. A genuinely NESTED case (member of a group that is a member of the required group) still has no test, because no such account was to hand. `member_of` now also warns loudly if the transitive query returns nothing where a direct check succeeds, which is how a broken nested lookup would announce itself rather than refusing real members silently.
|
||||
- [x] a bind against `192.168.3.37` (raw IP) fails hostname validation rather than silently passing — `selftest()` to the raw IP returns `untrusted`; to `prime.local`, `0 (ok)`
|
||||
- [ ] `docker compose exec api openssl s_client -connect prime.local:636 -CAfile $LDAP_CA_FILE` reports `Verify return code: 0 (ok)`
|
||||
- [x] the module imports cleanly with no LDAP env set (unconfigured is a first-class state, as with `MICRON_DB_URL`)
|
||||
|
||||
Done-when checks per task, verified against the actual code rather than
|
||||
re-reading this file's own claims: T10.1 (Authlib pinned, the four env vars,
|
||||
`is_configured()`/`describe()`), T10.2 (the login/callback routes, no
|
||||
app-side group or claim gate layered on Okta's own), T10.3 (identity-claim
|
||||
matching, JIT at the lowest role, local deprovisioning still enforced after
|
||||
Okta approves), T10.4 (zero remaining references to `bcrypt` /
|
||||
`password_hash` / `hash_password` / `verify_password` anywhere in `.py` or
|
||||
`.js`, `manage_users.py promote`, `smoketest.py` / `seed_demo.py` /
|
||||
`browser_check.py` / `launcher_check.py` all minting via `create_token()`),
|
||||
T10.5 (`login.html` is one Okta link, no password field). All matched what
|
||||
this file already claimed — no drift found.
|
||||
---
|
||||
|
||||
Full suite, run through the Docker test runner (all 41 files in `tests/`,
|
||||
bare invocation): 39 passed clean. `tests/token_check.py` "failed" at exit 2,
|
||||
but that is a harness mismatch, not a check failure — it is a two-step
|
||||
snapshot/diff tool (`--out` to capture, `--compare A B` to diff) and prints
|
||||
usage + exits 2 when run with no arguments, which is what a bare full-suite
|
||||
pass does to every file. `tests/generalinfo_check.py` scored 48/49 — the one
|
||||
failure is a raw `rgba()` shadow literal in `wp-creation-styles.css`,
|
||||
confirmed via `git show HEAD` to already be committed and unrelated to this
|
||||
wave (it is the Micron asset picker's dropdown shadow from the `D11` merge,
|
||||
2026-08-20, predating this wave by two weeks). Logged as `BL-031` rather than
|
||||
fixed here — an unrelated CSS token-rule violation is not this wave's to fix.
|
||||
`tests/okta_auth_check.py` re-run fresh (no browser needed): 22/22.
|
||||
### T10.2 — The login path binds instead of hashing
|
||||
|
||||
390px and 1440px: `tests/baseline_shots.py` captured all fourteen shots
|
||||
(login, launcher, sop, creator, admin, users, field × two widths) into
|
||||
`docs/reference/baseline/`. `login-390.png`/`login-1440.png` and
|
||||
`users-390.png`/`users-1440.png` visually confirmed: the login page is a
|
||||
single "Sign in with Okta" button with no username/password form at either
|
||||
width, and the User Directory's table and "Add a user" form both carry no
|
||||
password column and no reset-password action anywhere, at either width.
|
||||
- **Items:** `D13` (1)
|
||||
- **Depends on:** T10.1
|
||||
- **Blocks:** T10.3, T10.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py` (`login`), `server/auth.py`
|
||||
|
||||
Wave 10 is complete. The three items in "Still open" below are external
|
||||
(security team / Okta admin), not blocked on any task in this wave.
|
||||
**Problem:** `login()` at `server/app.py:681` calls `auth.verify_password` against
|
||||
`user.password_hash`. The lockout counter it maintains is about to start counting *domain*
|
||||
bind failures, which changes what that counter is for.
|
||||
|
||||
- **T10.10 — Audit `manage_users.py promote`.** Raised in review after T10.8:
|
||||
`cmd_promote()` changed a user's role with no audit trail at all, unlike the
|
||||
identical role change from the web Admin Console (`app.py`'s
|
||||
`set_user_role()` → `log_event()`, action `"role_changed"`). Not a new
|
||||
privilege — anyone with Portainer/container-exec access to `wp_api` already
|
||||
has shell access to the database directly, same trust tier D16 already named
|
||||
for this command — but there was no record of who ran it or what changed.
|
||||
**Do:** Replace the credential check with `ldap_auth.verify`. Keep the surrounding shape —
|
||||
the deliberate timing equalisation, the generic `401`, the `403` for a disabled local
|
||||
account, `last_login_at`, the session cookie. Rework the throttle so the local counter trips
|
||||
**before** the domain policy is reached and short-circuits without calling the DC: the
|
||||
failure mode to avoid is this endpoint being usable to lock domain accounts out of Windows.
|
||||
Log directory error-49 sub-codes for diagnosis; return the same generic message regardless.
|
||||
|
||||
Built: `cmd_promote()` now writes an `AuditLog` row with the same
|
||||
`action`/`detail` shape `set_user_role()` uses (`{"from": old_role, "to":
|
||||
role}`), tagged `"via": "cli"` (mirrors JIT provisioning's own `"via":
|
||||
"okta_jit"` tag) and `actor="cli:manage_users"` — a container shell exec
|
||||
carries no signed-in identity to attribute the change to a real person, so
|
||||
it names the tool rather than guessing one. Verified end to end against a
|
||||
scratch SQLite database: the audit row lands with the exact expected shape,
|
||||
the role change persists, and the existing "no such user" refusal still
|
||||
exits 1 with no partial write.
|
||||
**Break-glass: none — decided Aug 21, see the decision doc.** LDAPS is the only way in, so
|
||||
this task adds no fallback path. What it must add instead is *visibility*: a startup log line
|
||||
stating whether LDAP is configured and whether the DC answered, because with no fallback a
|
||||
misconfigured deploy is indistinguishable from a forgotten password at the login box.
|
||||
|
||||
- **T10.9 — Rollback-aware deploy runbook.** Raised after hazard review found
|
||||
`DEPLOY-runbook-2026-08-04.md`'s Rollback section has no case for a migration whose
|
||||
`downgrade()` cannot restore the data it drops — see `D17`. `T10.4`'s
|
||||
`1d60a608bb51_drop_local_password` is exactly that: the schema comes back, the
|
||||
bcrypt hashes do not.
|
||||
**Done when:**
|
||||
|
||||
Built: `DEPLOY-runbook-2026-09-03.md`, following the 2026-08-04 runbook's structure
|
||||
(fill-in table, numbered deploy steps, case-by-case Rollback section, Notes). Names
|
||||
the five `OKTA_*` vars as newly required (the precedent's "no new environment
|
||||
variables" note does not carry over), treats the pre-deploy backup as the only way
|
||||
back once the migration commits, and splits Rollback into the fixable case (Okta app
|
||||
integration misconfigured — fix and redeploy `api`, no data at risk, migration stays
|
||||
applied) versus the severe case (abandoning Okta for local-password code — only the
|
||||
destructive backup restore gets there, reusing the 2026-08-04 runbook's own Case C
|
||||
procedure). D16's no-break-glass posture is stated plainly rather than left implicit.
|
||||
- [x] the API logs one line at startup saying whether LDAP is configured and which group gates sign-in — configuration only, so an unreachable DC cannot hang startup. This is what `DEPLOYMENT.md`, `DEPLOY-login-portal.md` and `server/README.md` all send people to first; it was specified in this task on Aug 21 and not actually written until Aug 24.
|
||||
- [x] a correct domain password signs in and sets the session cookie — confirmed against the live domain Aug 24, and in `ldap_auth_check`
|
||||
- [x] a wrong password is refused with the generic message
|
||||
- [x] a blank password is refused (guards `T10.1` from the caller's side too)
|
||||
- [x] a user not in the required group is refused even though the bind succeeded
|
||||
- [x] `is_active = false` locally still refuses, independent of the directory — a disabled account is refused 403 even though the bind succeeds
|
||||
- [x] the local throttle trips below the domain lockout threshold and stops calling the DC — proved by presenting a CORRECT password once the budget is spent: a 429 for a credential that would otherwise work is only possible if the throttle runs before the directory is consulted
|
||||
- [x] no response body distinguishes "no such user" from "wrong password"
|
||||
- [x] error-49 sub-codes appear in the log and nowhere in any response — asserted both ways: `_err49` parses a real AD message, and no sub-code appears in any response body
|
||||
|
||||
Logged, not fixed here (out of scope): `okta_auth.describe()`'s startup log line
|
||||
(referenced by `DEPLOYMENT.md`/`server/README.md`) has no caller anywhere in
|
||||
`server/app.py` — nothing actually prints it at process start. The runbook's Step 4
|
||||
therefore verifies via a live Okta sign-in rather than a log line, and this gap is
|
||||
flagged in `docs/waves/backlog.md` as a candidate fix (wiring `describe()` into
|
||||
startup) since it directly bears on deploy verifiability. `DEPLOY-login-portal.md`
|
||||
is now fully stale (bcrypt, `create-admin --password`, none of which still exist) —
|
||||
not touched, no task claims it.
|
||||
---
|
||||
|
||||
## Still open
|
||||
### T10.3 — Drop `password_hash`
|
||||
|
||||
- The `Business Technology Group` pilot assignment in Okta. Originally six names
|
||||
(Carlee Swihart, Drew Hilliard, Matt Mabrey, Nick Siegfried, Rachel Schreiber, Terry
|
||||
Sajan); Cody and Cameron added 2026-09-09. Adrian added only Matt at first,
|
||||
deliberately, pending the live sign-in confirmation below — awaiting his response to
|
||||
add the rest of the group now that it has.
|
||||
- **Items:** `D13` (1)
|
||||
- **Depends on:** T10.2
|
||||
- **Blocks:** T10.6, T10.8
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/models.py`, new migration, `server/app.py`, `server/auth.py`,
|
||||
`server/manage_users.py`
|
||||
|
||||
Closed since first written: admin bootstrap and break-glass posture, previously open
|
||||
questions, decided in `D16` (2026-09-03) and folded into `T10.4` above.
|
||||
**Problem:** With binds doing the work, every password code path is dead weight and a
|
||||
liability. It is also the criterion that makes this item irreversible, so it lands on its own
|
||||
commit.
|
||||
|
||||
**Closed 2026-09-09, live in production:** the redirect/callback URI
|
||||
(`https://wp.controls.dev/api/auth/okta/callback`) is confirmed working, and so is the
|
||||
OIDC claim mapping (`T10.3`) — `preferred_username` (the code's documented default,
|
||||
never actually confirmed by name in Request 50649's thread) is correct, no
|
||||
`OKTA_IDENTITY_CLAIM` override needed. Both settled by an actual live sign-in against
|
||||
the real Okta tenant after `main` was merged (`cc64c88`) and deployed: Matt signed in
|
||||
as himself, matched his existing pre-Okta admin account by `find_user()` rather than
|
||||
JIT-provisioning a duplicate (the account already existed — this app has ~40 real
|
||||
users, not the seeded test fixture), landed on `index.html` signed in, admin role and
|
||||
project access untouched. One real deploy-time snag on the way, worth recording since
|
||||
it's exactly the Case B scenario `DEPLOY-runbook-2026-09-03.md` anticipated: the first
|
||||
redeploy left `OKTA_CLIENT_ID`/`OKTA_CLIENT_SECRET`/`OKTA_ISSUER` as empty rows in
|
||||
Portainer (env var names added, values never filled in) — caught via
|
||||
`is_configured()`'s all-four-required check failing closed (the 503 "Sign-in is
|
||||
temporarily unavailable"), not silently. A second snag after filling those in:
|
||||
`OKTA_ISSUER` was pasted without its `https://` scheme, which surfaced as
|
||||
`httpx.UnsupportedProtocol` from Authlib's OIDC discovery fetch rather than anything
|
||||
the app's own code raises deliberately — the exact case the runbook's Notes flagged as
|
||||
having no startup-time confirmation (`okta_auth.describe()` still has no caller,
|
||||
`BL-028`). Both fixed by correcting the env var values in Portainer and redeploying;
|
||||
neither needed the backup or the database.
|
||||
**Do:** Remove `password_hash` from `models.User` and drop the column in a new Alembic
|
||||
revision with `down_revision = 'a1b8c6d4e2f9'` (the current head — confirm with
|
||||
`alembic heads` rather than trusting this line). Remove from `auth.py`: `hash_password`,
|
||||
`verify_password`, `password_problem`, `MIN_PASSWORD_LEN`, `_COMMON_PASSWORDS`,
|
||||
`create_reset_token`, `decode_reset_token`, `RESET_MINUTES`. Remove from `app.py`:
|
||||
`/api/auth/forgot-password`, `/api/auth/reset-password`, `/api/auth/reset-available`,
|
||||
`/api/auth/password`, `/api/auth/users/{user_id}/password`, and the `_reset_last` throttle
|
||||
with `reset_body`. Remove `reset-password` from `manage_users.py` and the password prompt
|
||||
from `create` / `create-admin`.
|
||||
|
||||
`token_version` **stays.** It is still the session-revocation mechanism — role changes and
|
||||
deactivation should bump it even though password changes no longer exist.
|
||||
|
||||
**Do not** remove the account-management endpoints themselves. `/api/auth/users/{id}/role`
|
||||
is criterion 4 and must keep working.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `grep -rn "password_hash\|hash_password\|verify_password\|password_problem" server/` returns nothing outside the migration — only the migration and one docstring naming the dropped column
|
||||
- [x] `alembic upgrade head` then `downgrade -1` round-trips on SQLite and on Postgres (16.15, the compose image — Aug 24; needed a pre-existing T8.6 migration bug fixed first, see `495d87d`)
|
||||
- [x] the migration's `downgrade()` recreates the column nullable, not `NOT NULL` — there are no hashes to put back — verified on SQLite and Postgres
|
||||
- [x] `token_version` still invalidates an already-issued session — but **not** via a role change, which was the wrong premise. Nothing in `app.py` bumps it any more: `get_current_user` re-reads the account every request, so `role` and `is_active` changes take effect immediately without it. Its one remaining trigger is `manage_users` on disable. Tested by bumping it directly: the old cookie 401s and every other session is untouched. See `BL-030`.
|
||||
- [x] `manage_users.py list`, `disable`, `enable` still work; `reset-password` is gone
|
||||
- [x] no CLI command prompts for a password — superseded by `T10.9`, which removed `create-admin` and `create` outright; the first admin is now bootstrapped by signing in and then `promote`
|
||||
|
||||
---
|
||||
|
||||
### T10.4 — Just-in-time provisioning, without trampling existing accounts
|
||||
|
||||
- **Items:** `D13` (2, 4)
|
||||
- **Depends on:** T10.2
|
||||
- **Blocks:** T10.7
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py` (`login`), `server/auth.py`
|
||||
|
||||
**Problem:** Criteria 2 and 4 pull in opposite directions. Provisioning on first login must
|
||||
create accounts that do not exist, and must not touch the role of accounts that do — an
|
||||
existing `admin` signing in for the first time after this wave must still be an admin
|
||||
afterwards.
|
||||
|
||||
**Do:** On a successful bind that passes the group check, look the account up with
|
||||
`auth.find_user` (already case-insensitive across username **and** email). If it exists,
|
||||
update only `last_login_at` and — if empty locally — `full_name` and `email` from the
|
||||
directory. **Never write `role`.** If it does not exist, create it at
|
||||
`ROLE_PROJECT_USER` with `full_name`/`email` from the directory.
|
||||
|
||||
**A JIT account gets NO project access, and that is deliberate.** An earlier draft of this
|
||||
task said to honour the `auto_add_projects` machinery so a new account "lands in the right
|
||||
projects" — that was wrong about how the flag works. `auto_add_projects` is evaluated when a
|
||||
**project** is created (`app.py:245`), marking accounts that should join every *new* job; it
|
||||
cannot retroactively add a new account to existing ones. There is no correct default, so
|
||||
least privilege applies: the account exists, can sign in, and sees nothing until someone
|
||||
grants access. That is a real UX cliff — a successful sign-in into an empty app — so it has
|
||||
to be visible to admins rather than silent, which is what the `AuditLog` row is for.
|
||||
|
||||
Note the flush-order warning in the `models.py` docstring: `create_user` in `app.py` handles
|
||||
account-then-membership correctly in one flush — follow it if you add rows.
|
||||
|
||||
Write an `AuditLog` row for each JIT creation. An account appearing without an administrator
|
||||
creating it is exactly the kind of event that record exists for.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] an unknown username with a valid bind and group membership gets a `users` row at `project_user`
|
||||
- [x] `full_name` and `email` are populated from the directory on creation
|
||||
- [x] an existing `admin` signing in is still `admin` afterwards — asserted, not assumed — asserted in `ldap_auth_check` against a real server
|
||||
- [x] an existing account with a locally-set `full_name` does not have it overwritten
|
||||
- [x] a JIT account has NO `ProjectMember` rows and sees no projects
|
||||
- [x] the new account appears in the Admin console user list so access can be granted — asserted through `GET /api/auth/users`, the request the console makes
|
||||
- [x] each JIT creation writes an `AuditLog` row
|
||||
- [x] a failed bind creates **no** row
|
||||
- [x] a bind that succeeds but fails the group check creates **no** row
|
||||
|
||||
---
|
||||
|
||||
### T10.5 — CLOSED, NOT BUILT (Aug 24 2026): the required group stays an env var
|
||||
|
||||
- **Items:** `D13` (3)
|
||||
- **Status:** **won't build.** `LDAP_REQUIRED_GROUP` in the environment is the answer.
|
||||
|
||||
**Do not build this later by reading the original task and assuming it was skipped.**
|
||||
It was proposed, examined and rejected on purpose, and the reasoning is below.
|
||||
|
||||
**What it was going to be:** the required group moved out of the environment into an
|
||||
Admin console setting, with a validate-on-save guard that resolved the group in the
|
||||
directory and confirmed the saving admin was a member.
|
||||
|
||||
**Why it is not being built:**
|
||||
|
||||
1. **The console requirement was invented here, not asked for.** D13 criterion 3 says
|
||||
*"An AD group is configured"* — not "configurable from the console". The env var
|
||||
satisfies the criterion as written.
|
||||
2. **The validate-on-save guard existed only to defend against a risk the console
|
||||
itself introduced.** A feature whose complexity exists to defend against itself is
|
||||
usually the wrong feature.
|
||||
3. **The lockout scenario it defended against is already handled.** A group that does
|
||||
not resolve raises `LookupError` in `member_of`, which `verify()` maps to
|
||||
`GROUP_NOT_FOUND`, which `is_config_problem` classifies as ours — so `login()`
|
||||
answers **503**, not 401, and the log says *"required group 'X' does not resolve in
|
||||
DC=prime,DC=local — refusing the sign-in. This is a configuration fault, not a bad
|
||||
password."* A genuine non-member still gets 401. The two are already distinguishable
|
||||
in both the log and the response.
|
||||
4. **A redeploy is deliberate and reviewable; a text box is not.** The group is set
|
||||
once and effectively never changes — it is not SMTP configuration.
|
||||
5. **The console version creates a circular failure.** Fixing a lockout would require
|
||||
the console the lockout prevents you from reaching. Editing the env var does not.
|
||||
|
||||
**What is genuinely lost, and accepted:**
|
||||
|
||||
- **Discoverability.** An app admin cannot see which group is required without
|
||||
Portainer or shell access. A read-only line in the Admin console diagnostics would
|
||||
give the useful half without the dangerous half; it was offered and declined on
|
||||
Aug 24 as not needed.
|
||||
- **Deploy-time validation.** Nothing confirms the group resolves until the first
|
||||
sign-in attempt. This is not fixable: resolving a group needs an authenticated
|
||||
search, anonymous bind is disabled on this estate, and there is no service account
|
||||
by design. The first-attempt 503 is the earliest possible detection.
|
||||
|
||||
### T10.6 — Strip the password UI
|
||||
|
||||
- **Items:** `D13` (1)
|
||||
- **Depends on:** T10.3
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/login.html`, `html/login.js`, `html/admin.js`, `html/users.js`,
|
||||
`html/auth-guard.js`
|
||||
|
||||
**Problem:** `login.html` has three views — sign-in, forgot-password, set-new-password — and
|
||||
two of them now point at endpoints that no longer exist. `auth-guard.js` has a
|
||||
change-password dialog, and the user-admin UI has a "reset password" action per row.
|
||||
|
||||
**Decided Aug 21: "Forgot password?" is KEPT and repointed at
|
||||
`https://primecontrols.okta.com/`.** An earlier draft of this task removed the link, and a
|
||||
plain sentence saying "contact IT" was proposed instead. Okta is the better answer — it is a
|
||||
real self-service path, and with no app password and no break-glass it is the only recovery
|
||||
route that exists. Note this is the first sign of an Okta tenancy on this estate; see the
|
||||
new backlog entry.
|
||||
|
||||
Mechanics that matter: it is a plain `<a href>`, not a form post, so the `form-action 'self'`
|
||||
in the CSP does not apply and no `navigate-to` directive is set — off-origin link navigation
|
||||
is allowed as-is. `target="_blank"` needs `rel="noopener noreferrer"`, and there must be NO
|
||||
click handler on `#forgot-link`: the old one called `preventDefault()` to swap views, and
|
||||
leaving it would silently swallow the navigation.
|
||||
|
||||
**Do:** Remove the `#view-forgot` and `#view-reset` sections and the reset-token handling in
|
||||
`login.js`, and repoint `#forgot-link` as above. Remove the change-password dialog from `auth-guard.js`
|
||||
(`backlog.md:180` refers to it) and the per-row password reset from the users UI. Keep the
|
||||
sign-in form, and relabel the password field's hint to say it is the Windows/domain password
|
||||
— people need to know which password to type.
|
||||
|
||||
Keep the role-granting controls exactly as they are. That is criterion 4.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `grep -rn "forgot\|reset-password\|new-password" html/` returns nothing but prose
|
||||
- [x] "Forgot password?" opens `https://primecontrols.okta.com/` in a new tab — by inspection of the markup: `target="_blank"` with `rel="noopener noreferrer"`
|
||||
- [x] `#forgot-link` has NO click handler (a `preventDefault()` would swallow the navigation)
|
||||
- [x] a 503 from the login endpoint says sign-in is unavailable, not that the password is wrong
|
||||
- [x] the sign-in form still submits, and a failure still announces through `role="alert"` (`login.html` already does this correctly — do not regress it) — `url_state_check` drives the real form end to end; the `role="alert"` region is untouched
|
||||
- [x] the password field says which password to enter — see the screenshots
|
||||
- [x] no dead `<a href="#">` or handler remains for a removed view
|
||||
- [x] granting admin to an existing user still works from the console — asserted through `POST /api/auth/users/{id}/role`, the request `users.js` sends, and the role really changes
|
||||
- [x] exercised at 390px and at 1440px, screenshots in the PR — `docs/reference/baseline/before-wave10/` and `after-wave10/`, captured Aug 24 with `tests/baseline_shots.py`. "Before" comes from a detached worktree at `main` (`a8e28bf`) so each half was shot against its own server.
|
||||
- [x] no raw hex added to any stylesheet (the token rule) — no CSS was added at all — the hint reuses the `.hint` class the page already had
|
||||
|
||||
---
|
||||
|
||||
### T10.7 — Make the suite testable without a domain controller
|
||||
|
||||
- **Items:** `D13` (1, 2, 3)
|
||||
- **Depends on:** T10.1, T10.4
|
||||
- **Blocks:** T10.8
|
||||
- **Surface:** `tests/` + `server/`
|
||||
- **Files:** `server/ldap_auth.py`, `tests/browser_check.py`, `tests/launcher_check.py`,
|
||||
`tests/console_dialogs_check.py`, `tests/url_state_check.py`, `server/smoketest.py`,
|
||||
`server/seed_demo.py`, new `tests/ldap_auth_check.py`
|
||||
|
||||
**Problem:** This is the task most likely to be underestimated. Four existing checks build
|
||||
users with `password_hash=auth.hash_password(PW)` and sign in over HTTP;
|
||||
`console_dialogs_check.py` drives the password-reset prompt specifically. `smoketest.py` and
|
||||
`seed_demo.py` both sign in. None of them can reach a DC, and CI has no domain.
|
||||
|
||||
**Do:** Make the bind injectable — a module-level seam in `ldap_auth.py` that a test can
|
||||
substitute (a fake directory: usernames, passwords, groups, full names), selected by an env
|
||||
var that is refused when a real `DATABASE_URL` is configured, mirroring how
|
||||
`auth._load_secret` refuses an ephemeral key in production. Port the four checks onto it.
|
||||
Delete the password-reset half of `console_dialogs_check.py` — the flow it covers no longer
|
||||
exists — and say so in the PR rather than leaving a skipped test.
|
||||
|
||||
Add `tests/ldap_auth_check.py` covering the non-negotiables from the decision doc: empty
|
||||
password, empty username, `CERT_REQUIRED` asserted by inspecting the constructed `Tls`,
|
||||
nested group membership, group-check refusal creating no user, and existing-admin role
|
||||
preservation.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the stub backend cannot be selected when a non-SQLite `DATABASE_URL` is set — asserted by a test
|
||||
- [x] `tests/ldap_auth_check.py` covers the cases above — 20/20
|
||||
- [x] the empty-password case is proved by nulling `Connection`, so any call to `bind()` would raise — it asserts the guard returns *before* the transport, not merely that the result is a failure
|
||||
- [x] `smoketest.py` and `seed_demo.py` document which credentials they now need (T10.8)
|
||||
- [x] the removed password-reset checks are called out, not silently dropped — `console_dialogs_check.py`'s docstring records the coverage loss and where the prompt kit is still covered
|
||||
- [x] the full `tests/` suite passes with no DC reachable — **1284/1288 checks across 40 files**, Aug 24. Two files fail, both proven pre-existing and unrelated (`BL-028` `assets_check`, `BL-029` `generalinfo_check`): `git diff main...HEAD` shows this branch touches neither file. `token_check.py` is not a member of the suite — it is a capture/diff tool that requires `--out` or `--compare`, and a sweep script that runs it bare gets a usage message and exit 2.
|
||||
|
||||
**Scope note.** This task was estimated as far larger than it turned out to be. The
|
||||
premise was that four checks sign in and would all need the seam; in fact `seed()` mints
|
||||
a token with `auth.create_token()` and sets the cookie directly, so **no** browser check
|
||||
signs in except `url_state_check`'s deep-link case. `browser_check` and `launcher_check`
|
||||
needed one kwarg deleted each — and since 39 files import `seed`/`start_server` from
|
||||
`browser_check`, that single line unblocked nearly the whole suite.
|
||||
|
||||
---
|
||||
|
||||
### T10.8 — Documentation and the deploy runbook
|
||||
|
||||
- **Items:** `D13`
|
||||
- **Depends on:** T10.3, T10.5, T10.7
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** docs
|
||||
- **Files:** `DEPLOYMENT.md`, `server/README.md`, `DEPLOY-login-portal.md`, `CLAUDE.md`,
|
||||
`IMPLEMENTATION.md`
|
||||
|
||||
**Problem:** `DEPLOY-login-portal.md` documents creating the first admin with a password and
|
||||
is the page an admin will reach for. `DEPLOYMENT.md` describes `AUTH_SECRET_KEY` and SMTP but
|
||||
knows nothing about a directory. `CLAUDE.md`'s verification section tells anyone touching the
|
||||
frontend to run the smoke test, which changes here.
|
||||
|
||||
**Do:** Document the LDAP variables, how to produce the CA bundle from the two thumbprints
|
||||
in the decision doc, and the `prime.local`-not-an-IP rule with the reason. Add the
|
||||
`openssl s_client -CAfile` check as the first-line diagnostic. Rewrite the
|
||||
`DEPLOY-login-portal.md` bootstrap step: the first admin is now an existing directory account
|
||||
promoted with `manage_users.py`, not an account created with a password. State plainly what
|
||||
happens when the DC is unreachable, whatever `T10.2` decides.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] every new env var is documented in `server/.env.example` and `DEPLOYMENT.md`
|
||||
- [x] the CA bundle procedure is reproducible by an admin who has not read this thread — thumbprints and a `Get-ChildItem` one-liner in `DEPLOYMENT.md`
|
||||
- [x] `DEPLOY-login-portal.md` no longer instructs anyone to set a password — rewritten, with a note saying what it replaced so an admin holding the old copy is not misled
|
||||
- [x] the DC-unreachable behaviour is stated explicitly, with the diagnostic commands
|
||||
- [x] `IMPLEMENTATION.md` section 4 lists wave 10
|
||||
- [x] no doc still claims passwords are stored as bcrypt hashes (swept; remaining matches all say the opposite)
|
||||
- [x] `CLAUDE.md` carries the four load-bearing auth rules, next to the token rule
|
||||
|
||||
---
|
||||
|
||||
### T10.9 — D14: the CLI authenticates, and stops creating accounts
|
||||
|
||||
- **Items:** `D14`
|
||||
- **Depends on:** T10.3
|
||||
- **Blocks:** T10.8
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/manage_users.py`
|
||||
|
||||
**Problem:** `manage_users.py` writes to the `users` table with no authentication at all.
|
||||
It also still offers `create-admin` / `create`, which are redundant now that accounts
|
||||
provision themselves — and worse than redundant, because a hand-typed username can end up
|
||||
matching no directory identity.
|
||||
|
||||
**Do:** As stated in `D14`. Remove the two create commands, add `promote` / `demote`, gate
|
||||
every state-changing command on a prompted domain bind, and write an `AuditLog` row naming
|
||||
the operator. Write the audit row by hand rather than importing `log_event` from `app.py` —
|
||||
that would pull FastAPI and the whole application into a CLI startup for one INSERT.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `create-admin`, `create` and `reset-password` are rejected as invalid choices
|
||||
- [x] `list` works with no credential and with no LDAP configured
|
||||
- [x] a state-changing command with LDAP misconfigured refuses instead of proceeding
|
||||
- [x] there is no `--password` flag on any command
|
||||
- [x] `promote` raises a role; `demote` returns an account to `project_user`
|
||||
- [x] promoting YOURSELF is allowed and recorded with `self: true`
|
||||
- [x] the last active admin cannot be demoted
|
||||
- [x] an unknown account gives an error that says accounts are made on first sign-in
|
||||
- [x] every change writes an `AuditLog` row naming the operator
|
||||
- [x] verified against a real domain bind — `promote` and `demote` confirmed working Aug 24 2026
|
||||
|
||||
@@ -1,280 +0,0 @@
|
||||
# Wave 11 — Usage and activity metrics
|
||||
|
||||
**Items:** `CR-019`
|
||||
**Depends on:** wave 10 merged (it is; this wave does not wait on anything else)
|
||||
**Decision record:** `docs/waves/decisions-2026-09-17.md`
|
||||
|
||||
Seven tasks, one concern each, in build order. Do not start a task whose
|
||||
dependency is not merged. `CR-020` (bulk user editing) is reserved but not
|
||||
scoped — it does not belong in this wave.
|
||||
|
||||
---
|
||||
|
||||
### T11.1 — CR-019: `usage_events` table + migration
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** nothing (first task)
|
||||
- **Blocks:** T11.2
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/models.py`, `server/alembic/versions/`
|
||||
|
||||
**Do:** Add a `UsageEvent` model — append-only, same spirit as `AuditLog` but for
|
||||
navigation/feature-open events rather than business mutations. Suggested shape:
|
||||
`id`, `at` (indexed), `user_id` (or username — match whatever `AuditLog.actor`
|
||||
does today for consistency), `project_id` (nullable — not every event is
|
||||
project-scoped, e.g. opening the admin console), `tool` (e.g. `creator`,
|
||||
`wizard`, `field_view`, `dashboard`, `admin`, `directory`), `event` (e.g.
|
||||
`page_open`, `login`), `detail` (JSON, optional). Write the migration. Do not
|
||||
touch `AuditLog` — this is a new table, not an extension of it (see the
|
||||
decision record's reasoning).
|
||||
|
||||
**Do not:** fold this into `AuditLog`. They serve different questions and mixing
|
||||
them makes the existing audit trail noisier for its existing readers.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] `UsageEvent` exists with an indexed `at` column (this table will be scanned
|
||||
by date range constantly)
|
||||
- [ ] migration applies cleanly against both SQLite (dev) and Postgres (prod) —
|
||||
render `alembic upgrade --sql` for postgresql and read it before calling
|
||||
this done, per the class of defect `BL-027` logged
|
||||
- [ ] no change to `AuditLog`'s shape or behavior
|
||||
|
||||
---
|
||||
|
||||
### T11.2 — CR-019: capture the events
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.1
|
||||
- **Blocks:** T11.3
|
||||
- **Surface:** `server/` + `html/`
|
||||
- **Files:** `server/app.py` (new endpoint), `html/auth-guard.js`
|
||||
|
||||
**Problem:** Six pages need this and none should implement it separately — that
|
||||
is exactly how `S4`'s "no global nav on two pages" and the four parallel token
|
||||
systems (`S5`) happened. `auth-guard.js` is already loaded first, in the `<head>`,
|
||||
on all six protected pages (`index.html`, `field.html`, `users.html`,
|
||||
`wp-creation-index.html`, `work-package-suite.html`, `admin.html`) and already
|
||||
knows the verified user once the `wp-auth-ready` event fires. That is the one
|
||||
place this belongs.
|
||||
|
||||
**Do:** Add a small `POST /api/usage/ping`-style endpoint that writes one
|
||||
`UsageEvent` row per call, keyed to the session (server trusts the session, not
|
||||
anything the client claims about identity). Call it once from `auth-guard.js`
|
||||
after `wp-auth-ready`, tagging `tool` from the page's own path. Also write a
|
||||
`login` event at the point a session is actually established (reuse whatever
|
||||
`okta_callback` already does at sign-in — do not add a second source of truth
|
||||
for "did this person log in").
|
||||
|
||||
**Do not:** build a per-page capture call. If a page needs this and
|
||||
`auth-guard.js` does not cover it, fix `auth-guard.js`, not the page.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] one `page_open` event is recorded for a real sign-in on each of the six
|
||||
pages, verified per page
|
||||
- [ ] exactly one `login` event per Okta sign-in, not one per page load after
|
||||
it
|
||||
- [ ] the endpoint rejects a request with no valid session (this is server-
|
||||
enforced identity, not client-reported)
|
||||
- [ ] no page other than `auth-guard.js` calls this endpoint directly
|
||||
|
||||
---
|
||||
|
||||
### T11.3 — CR-019: aggregation endpoint with filters
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.2
|
||||
- **Blocks:** T11.4, T11.5
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py`
|
||||
|
||||
**Do:** Build the read side: active-user counts by day/week/month, per-user
|
||||
last-active timestamp (derived from `UsageEvent`, not `User.last_login_at`,
|
||||
which only ever holds one value), and a per-tool usage breakdown. Accept query
|
||||
filters: date range, project, user, tool — combinable, per the decision record.
|
||||
This is server aggregation, the same principle `B4` established for the
|
||||
pipeline strip: the browser asks for a number, the server computes it from real
|
||||
rows, nothing is derived client-side from a partial cache.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] active-user counts are correct against a seeded fixture with known dates
|
||||
- [ ] filters combine correctly (verified: user + date range + tool together
|
||||
narrows correctly, not just each alone)
|
||||
- [ ] a project filter that matches nothing returns an empty result, not an
|
||||
error or the unfiltered total
|
||||
|
||||
---
|
||||
|
||||
### T11.4 — CR-019: export, raw and sanitized
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.3
|
||||
- **Blocks:** T11.5
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py`
|
||||
|
||||
**Do:** A CSV export endpoint over the same filtered query T11.3 exposes.
|
||||
Two modes: raw (real usernames, the console's default) and sanitized. Sanitized
|
||||
mode replaces the actor field with a stable pseudonymous id — a per-user hash,
|
||||
consistent across rows in the same export and across separate export runs —
|
||||
so an external system (Power BI or similar) can still group and trend "by
|
||||
user" without ever receiving a real name. Do not simply drop the identity
|
||||
column; that breaks per-user grouping downstream, which defeats the point of
|
||||
an activity export.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] raw export contains real usernames
|
||||
- [ ] sanitized export never contains a real username or email anywhere in the
|
||||
file, including in a `detail` blob if one is included
|
||||
- [ ] the same real user maps to the same pseudonymous id within one export AND
|
||||
across two separate export runs (a hash of something stable, not a
|
||||
per-request random id)
|
||||
- [ ] both modes otherwise contain identical rows for the same filter
|
||||
|
||||
---
|
||||
|
||||
### T11.5 — CR-019: admin console Activity tab
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.3, T11.4
|
||||
- **Blocks:** T11.7
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/admin.html`, `html/admin.js`
|
||||
|
||||
**Do:** New tab, same role gate as the User Directory. Filters (date range,
|
||||
project, user, tool) driving the tables from T11.3; export buttons (raw and
|
||||
sanitized) calling T11.4. Build accessible from the start per `C1` — this is a
|
||||
new component, not a legacy one carrying an old defect forward: real
|
||||
`<button>`/`<select>` controls, keyboard-reachable, `aria-live` on any
|
||||
count that updates without a page reload, focus visible throughout.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the tab is reachable only by an admin (the card lives inside admin.html,
|
||||
already gated client-side by gateByRole(); the API underneath it is
|
||||
independently gated server-side by require_user_manager regardless)
|
||||
- [x] every filter is a real form control, keyboard-operable (date/select/text
|
||||
inputs and a `<button>`, no click-div)
|
||||
- [x] both export buttons produce the files T11.4 defines (verified against
|
||||
the live endpoint in T11.4's own checks, and present/wired here)
|
||||
- [x] works at 390px and 1440px — verified 2026-09-23 via
|
||||
`tests/baseline_shots.py --pages admin` run locally on Windows (this
|
||||
sandbox has no headless browser available; the script was run on the
|
||||
user's machine instead, after installing Python via winget since it
|
||||
wasn't present). Screenshots in `docs/reference/baseline/admin-390.png`
|
||||
/ `admin-1440.png`. No JS errors, no horizontal overflow at either
|
||||
width; the card rendered with real seeded data (events, by-tool,
|
||||
per-user-last-active tables) confirming the filters and summary read
|
||||
correctly, not just that the markup exists.
|
||||
|
||||
---
|
||||
|
||||
### T11.6 — CR-019: retire the per-browser Usage report
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.5
|
||||
- **Blocks:** T11.7
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/admin.js` (the `usage-admin` panel, `admin.js:666-699`),
|
||||
`html/wp-usage.js` and its two call sites
|
||||
|
||||
**Do:** Remove the old per-browser `usage-admin` panel from `admin.js` now that
|
||||
the real one exists, per the 2026-09-17 decision. Decide what happens to
|
||||
`wp-usage.js`'s recording calls (wizard dwell-tracking, the creator's
|
||||
equivalent): they were never reliably tied to a real identity, so they are not
|
||||
a data source the new report can adopt. Default to removing the recorder too
|
||||
unless it is still doing something useful on its own (re-read what it actually
|
||||
records before deciding — do not assume from this file alone).
|
||||
|
||||
**Do not:** leave the old panel in place "just in case." Two activity reports
|
||||
showing two different numbers is worse than one.
|
||||
|
||||
**Decision (2026-09-23):** `wp-usage.js` is removed, not kept — it had no
|
||||
reader left once the admin panel above it was removed (the "download the
|
||||
full event log" button lived only in that panel), and per the original
|
||||
decision record it was never reliably tied to a real identity, so it was
|
||||
never a candidate source for the new report either. The file itself and its
|
||||
three `<script>` includes (`admin.html`, `wp-creation-index.html`,
|
||||
`work-package-suite.html`) are gone. Its two call sites
|
||||
(`wp-creation-app.js`, `work-package-suite-app.js`) keep a local `track()`
|
||||
function as a documented no-op rather than having each of their ~45
|
||||
individual `track('event', …)` call sites deleted one at a time — that
|
||||
would be a far larger, riskier diff for the same outcome (no more data is
|
||||
recorded either way), and it keeps each call site as a marker of what was
|
||||
worth recording if usage analytics are ever rebuilt server-side. The
|
||||
dwell-timer plumbing that only ever fed `track()` (`work-package-suite-app.js`'s
|
||||
`_stepEnter`/`trackStepDwell`) was left in place for the same reason — it is
|
||||
inert now, not broken, and touching it buys nothing.
|
||||
|
||||
Also removed: `tests/usage_check.py` (tested exactly the retired feature —
|
||||
D5/T7.10's per-browser analytics core and admin report) and its line in
|
||||
`docs/reference/file-map.md`, replaced with a note pointing at this decision.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the old `usage-admin` panel and its markup are gone from `admin.html`/
|
||||
`admin.js`
|
||||
- [x] a decision on `wp-usage.js` itself is recorded (removed, or kept with a
|
||||
stated reason) — not left ambiguous — see above
|
||||
- [x] nothing else in the app references the removed code; grep confirms
|
||||
(only remaining hits are this file, the 2026-09-17 decision record, and
|
||||
the two explanatory code comments left at the retired call sites — all
|
||||
prose, not live references)
|
||||
|
||||
---
|
||||
|
||||
### T11.7 — CR-019: verification
|
||||
|
||||
- **Items:** `CR-019`
|
||||
- **Depends on:** T11.6
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `html/` + `server/`
|
||||
- **Files:** as touched above
|
||||
|
||||
**Do:** Full verification per `CLAUDE.md`: run the app locally, exercise the
|
||||
new tab at 390px and 1440px, before/after screenshots, run the existing smoke
|
||||
test and `seed_demo.py`, run the full suite.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] all `CR-019` acceptance criteria in `decisions-2026-09-17.md` are met or
|
||||
a failure is stated with a reason — all met
|
||||
- [x] screenshots committed — `admin-390.png`/`admin-1440.png` (and
|
||||
`creator`/`sop` at both widths, touched by T11.6's script-tag removal)
|
||||
- [x] smoke test and `seed_demo.py` both still pass — 27/27, verified
|
||||
2026-09-24 against the exact branch state about to be considered
|
||||
deployable
|
||||
- [x] full test suite passes — verified 2026-09-24: ran all 39
|
||||
`tests/*_check.py` scripts plus the `usage_events` migration
|
||||
round-trip. Result: 38/39 exit 0.
|
||||
- `token_check.py` exits 2 with no arguments by design (needs `--out`
|
||||
or `--compare`) — a CLI-invocation detail, not a test failure;
|
||||
already confirmed non-regression in wave 10.
|
||||
- `generalinfo_check.py` has one pre-existing failure (a raw colour
|
||||
literal in `html/wp-creation-styles.css`, a file no wave 11/13 task
|
||||
touched) — already diagnosed as pre-existing in wave 10.
|
||||
- `autosave_check.py` **did** regress from T11.6 (it asserted the
|
||||
retired analytics tracker still wrote to localStorage) — found by
|
||||
this run, fixed same day (commit `4f3a94b`), now 33/33.
|
||||
- Migration (T11.1): SQLite upgrade → downgrade → upgrade round-trip
|
||||
clean; `alembic upgrade ... --sql` against the `postgresql` dialect
|
||||
renders valid DDL (`TIMESTAMP WITH TIME ZONE`, `JSON`, no
|
||||
SQLite-only syntax) — no `BL-027`-class defect.
|
||||
|
||||
---
|
||||
|
||||
## Wave 11 exit criteria
|
||||
|
||||
- [x] real, server-side activity data exists per user, indefinitely retained
|
||||
- [x] the admin console shows it, filterable by date/project/user/tool
|
||||
- [x] export works in both raw and sanitized form
|
||||
- [x] the old per-browser report is gone, not duplicated
|
||||
- [x] `CR-019` fully accounted for, no open acceptance criteria
|
||||
|
||||
Wave 11 is closed out as of 2026-09-24. `CR-020` (wave 12) remains reserved
|
||||
and unstarted. `D18`/wave 13 (`T13.2` onward) remains paused pending an Okta
|
||||
API credential, per standing instruction — `T13.1`'s session changes were
|
||||
included in this same verification pass and did not regress anything above.
|
||||
@@ -1,263 +0,0 @@
|
||||
# Wave 12 — Bulk editing of users
|
||||
|
||||
**Items:** `CR-020`
|
||||
**Depends on:** wave 10 merged (it is). Independent of wave 11 (`CR-019`) — no
|
||||
shared files, may build in either order or in parallel.
|
||||
**Decision record:** `docs/waves/decisions-2026-09-17.md` (open details
|
||||
confirmed 2026-10-06, see "Confirmed 2026-10-06" in the CR-020 section)
|
||||
|
||||
**Branch (decided 2026-10-06):** `feat/wave-12-bulk-users`, cut from `main`
|
||||
(`df20b8f`, production). Only this file and the decision record come across
|
||||
from `feat/waves-11-13`, so the PR into `main` is wave 12 alone: no wave 11
|
||||
code and no T13.1, which must not reach `main` before T14.1. Wave 16 is not
|
||||
merged yet; it touches different functions, and whichever lands second rebases.
|
||||
|
||||
Six tasks, in build order.
|
||||
|
||||
---
|
||||
|
||||
### T12.1 — CR-020: bulk endpoints
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** nothing (first task)
|
||||
- **Blocks:** T12.2, T12.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py`
|
||||
|
||||
**Do:** Add bulk variants of the four existing single-user actions — role
|
||||
change, active/disabled, project assignment (add/remove + project-role), and
|
||||
delete. Each takes a list of `user_id`s plus the action's parameters and
|
||||
applies `require_see_user`/`require_manage_user`/`grantable_roles` **per row**,
|
||||
exactly as the single-user endpoint does today — a super user's bulk request
|
||||
cannot reach further than their existing single-user requests can. Do not skip
|
||||
the self-action guard: an actor's own account is rejected out of any batch
|
||||
that would disable, demote, or delete it, same as today.
|
||||
|
||||
Each successful row writes its own `AuditLog` entry via `log_event`, same
|
||||
action names the single endpoints already use. A row that fails is reported in
|
||||
the response (user id, reason) and does not stop the rest of the batch from
|
||||
being attempted.
|
||||
|
||||
**Do not:** invent a single opaque "bulk_action" audit entry in place of the
|
||||
per-row entries. Do not build a soft-delete path for bulk delete that doesn't
|
||||
exist for the single case — bulk delete stays a hard delete, matching
|
||||
`delete_user` today.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] each of the four bulk actions is callable with a list of user ids and a
|
||||
single set of parameters
|
||||
- [x] a batch containing the actor's own account rejects only that row, not
|
||||
the whole batch — verified for disable, demote, and delete
|
||||
- [x] a super user's batch that includes a user/project outside what they
|
||||
manage rejects only that row, with a stated reason
|
||||
- [x] every successful row produces its own `AuditLog` entry, identical in
|
||||
shape to what the single-user endpoint would have written
|
||||
- [x] a batch with some failing rows still applies to the rows that succeed,
|
||||
and the response lists exactly which rows failed and why
|
||||
|
||||
---
|
||||
|
||||
### T12.2 — CR-020: row selection in the User Directory table
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** T12.1
|
||||
- **Blocks:** T12.3
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/users.js`, `html/users.html`
|
||||
|
||||
**Do:** Add a checkbox per row and a select-all control, respecting whatever
|
||||
filter (`role`, `active`/`disabled`, project) is currently applied — select-all
|
||||
selects the filtered set, not every user in the system regardless of what's
|
||||
shown. A bulk-action toolbar appears once at least one row is checked and
|
||||
disappears at zero.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] select-all selects exactly the rows currently visible under the active
|
||||
filter, not the full unfiltered table
|
||||
- [x] changing the filter while rows are selected does something sane and
|
||||
visible (either clears the selection or keeps it explicit which rows are
|
||||
still selected) — pick one and state it, don't leave it undefined
|
||||
- [x] the toolbar is keyboard-reachable and only present when >=1 row is
|
||||
selected
|
||||
|
||||
---
|
||||
|
||||
### T12.3 — CR-020: bulk-action toolbar
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** T12.2
|
||||
- **Blocks:** T12.5
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/users.js`
|
||||
|
||||
**Do:** Wire the toolbar to T12.1's endpoints for role change, activate/
|
||||
disable, and project assignment (add to / remove from a project + project-
|
||||
role). Confirmation before applying uses the `wp-dialog` kit (`T7.9`) —
|
||||
`wpConfirmDialog`, not a native `confirm()` — naming exactly how many users are
|
||||
affected. On completion, report per-row results if anything failed (T12.1
|
||||
already returns this) rather than a single success/failure toast that hides a
|
||||
partial failure.
|
||||
|
||||
**Delete is built separately, in T12.5** — do not wire delete here.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] role change, activate/disable, and project assignment each work end to
|
||||
end against a multi-row selection
|
||||
- [x] the confirmation dialog names the exact affected count before anything is
|
||||
sent
|
||||
- [x] a batch with a partial failure shows which rows failed, not just an
|
||||
undifferentiated error
|
||||
- [x] `aria-live` announces the outcome
|
||||
|
||||
---
|
||||
|
||||
### T12.4 — CR-020: CSV upload path
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** T12.1
|
||||
- **Blocks:** T12.6
|
||||
- **Surface:** `html/` + `server/`
|
||||
- **Files:** `html/users.js`, `server/app.py`
|
||||
|
||||
**Do:** An upload accepting a list of usernames plus the action to apply,
|
||||
following the validate-and-report pattern `CR-005` established: reject and
|
||||
report bad rows (username not found, actor lacks permission over that user)
|
||||
rather than silently dropping them. This is a second entry point onto the same
|
||||
T12.1 endpoints, not a third implementation of the bulk logic.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] a CSV with a mix of valid and invalid usernames applies to the valid
|
||||
rows and reports the invalid ones by row, with a reason
|
||||
- [x] the same permission/self-action guards from T12.1 apply here — a CSV
|
||||
cannot reach a user a checkbox-driven batch couldn't
|
||||
- [x] duplicate usernames in one CSV are handled without double-applying or
|
||||
erroring confusingly
|
||||
|
||||
---
|
||||
|
||||
### T12.5 — CR-020: bulk delete confirmation
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** T12.3
|
||||
- **Blocks:** T12.6
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/users.js`
|
||||
|
||||
**Do:** Wire delete into the toolbar with a heavier confirmation than the other
|
||||
three actions, per the decision record's recommendation: list the affected
|
||||
usernames and require typing a confirmation phrase (e.g. `DELETE`) before the
|
||||
request is sent, regardless of how many rows are selected. This is flagged in
|
||||
the decision record as a recommendation Matt has not explicitly signed off on
|
||||
— if the PR reviewer wants a lighter or heavier mechanism, that's the moment to
|
||||
change it, not a reason to skip building a real confirmation now.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the affected usernames are listed in the confirmation dialog before
|
||||
delete is sent
|
||||
- [x] the request is not sent until the confirmation phrase is typed correctly
|
||||
- [x] the actor's own account, if somehow selected, is rejected with a clear
|
||||
reason rather than silently included or silently dropped
|
||||
|
||||
---
|
||||
|
||||
### T12.6 — CR-020: verification
|
||||
|
||||
- **Items:** `CR-020`
|
||||
- **Depends on:** T12.4, T12.5
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `html/` + `server/`
|
||||
- **Files:** as touched above
|
||||
|
||||
**Do:** Full verification per `CLAUDE.md`: run locally, exercise bulk role
|
||||
change, activate/disable, project assignment, CSV upload, and bulk delete at
|
||||
390px and 1440px, before/after screenshots, smoke test, `seed_demo.py`, full
|
||||
suite.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] all `CR-020` acceptance criteria in `decisions-2026-09-17.md` are met or
|
||||
a failure is stated with a reason
|
||||
- [x] screenshots committed
|
||||
- [x] smoke test and `seed_demo.py` both still pass
|
||||
- [x] full test suite passes
|
||||
|
||||
---
|
||||
|
||||
## Wave 12 exit criteria
|
||||
|
||||
- [x] all four bulk actions work against both a checkbox selection and a CSV
|
||||
upload
|
||||
- [x] every existing single-user guardrail (self-action, scope, grantable
|
||||
roles) holds under bulk use
|
||||
- [x] bulk delete requires typed confirmation and lists affected usernames
|
||||
- [x] partial failures are always reported, never hidden behind a blanket
|
||||
success
|
||||
- [x] `CR-020` fully accounted for, no open acceptance criteria
|
||||
|
||||
## Verification record
|
||||
|
||||
Built 2026-10-06 on `feat/wave-12-bulk-users`
|
||||
(from `main`, `df20b8f`), one commit per task. Run in the build sandbox (Linux,
|
||||
Python 3.10, no browser).
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| `tests/bulk_users_check.py` (new, no browser) | **61/61**: all four actions, own-row refusals, super-user scope, per-row audit in the single route's shape, partial failure, project add/remove keeping other projects and roles, CSV resolve, 403/401/422 gates |
|
||||
| Same check against `main` | 7/18: the 7 single-route checks pass; every bulk check fails, because the routes do not exist there |
|
||||
| Single-user routes before/after (16 calls: 200/400/403/404, as admin and super user) | **Identical** responses, audit rows and memberships against `main`. The routes now call the same `apply_*` functions as the bulk routes |
|
||||
| Page logic, DOM harness (jsdom, the real `users.html` and scripts, mocked API) | **48/48**: selection, select-all over the filtered rows, filter clears selection, toolbar, confirm counts, per-row report, CSV, typed DELETE |
|
||||
| Same flows, jsdom against a real server seeded by `browser_check.seed()` | **13/13**, including the CSV report texts the browser probe expects |
|
||||
| `server/smoketest.py` | **27/27** |
|
||||
| `server/seed_demo.py` | Seeds the demo project |
|
||||
|
||||
**Decisions applied (confirmed 2026-10-06):** typed `DELETE`; project assignment
|
||||
is add/remove per project, with the per-project role (`ProjectMember.role`) set
|
||||
on add; filter or search change clears the selection; CSV holds usernames only.
|
||||
A row already in the requested state reports `unchanged` and writes no audit
|
||||
row (nothing changed). An email address in the CSV resolves only when exactly
|
||||
one account has it.
|
||||
|
||||
**Found and logged, not fixed:** BL-060, a super user's refusal reason promises
|
||||
a project-access change that neither the dialog nor the bulk route allows.
|
||||
|
||||
**Browser probes, run 2026-10-06 on Matt's machine (Windows, Chrome 153 / Edge 154,
|
||||
`.venv`), one at a time:**
|
||||
|
||||
| Probe | Result |
|
||||
|---|---|
|
||||
| `tests/bulk_users_ui_check.py` (new) | **19/19**: selection, Space on a row box, role change, super-user CSV (another job / not found / herself / duplicate, each by line), add-to-project with a role, typed DELETE, 390px bar fit, no JS errors |
|
||||
| `tests/console_dialogs_check.py` | **16/16**, including the new section 4 (bulk delete prompt, natives poisoned) |
|
||||
| `tests/mobile_check.py` | **24/24**, users page included |
|
||||
| `tests/a11y_check.py` | **22/22**: users page 66 focusable elements, all with a visible ring; helper text 5.02:1 at worst |
|
||||
| `tests/browser_check.py` | **67/71**, then re-pointed (below); **rerun after the re-point: all passed** (reported by Matt, 2026-10-06) |
|
||||
|
||||
**`browser_check.py` re-pointed (T12.6).** Its four failures were assertions
|
||||
written against column POSITIONS: the manager table had 9 columns, and the
|
||||
own-row checks read `r.cells[3]` (Permissions) and `r.cells[4]` (Project role).
|
||||
CR-020's selection column is first, so the table has 10 and those indexes
|
||||
landed on Username and Email. Not an app defect. The probe now expects 10
|
||||
columns with the selection column first, finds the two cells by their header
|
||||
name rather than their position (so the next column cannot break it the same
|
||||
way), and adds one check: your own row has no selection box. Verified against
|
||||
the real page in the DOM harness, then rerun in the browser: all passed.
|
||||
|
||||
**Screenshots** (after; the before-shots are `baseline/users-1440.png` and
|
||||
`baseline/after-wave9/users-390.png`): `baseline/wave-12/users-1440.png`,
|
||||
`users-1440-selected.png`, `users-390.png`, `users-390-selected.png`. Reviewed:
|
||||
the bar, its four groups and the selected-row marking render as designed at
|
||||
both widths; nothing scrolls sideways at 390px.
|
||||
|
||||
**Seen in the screenshots, not caused by wave 12, logged as BL-061:** the
|
||||
pre-existing sync badge ("Everything sent to the project", `project-data.js`)
|
||||
is drawn over a row's Delete button at 1440px and over "Set permissions" at
|
||||
390px for about 2 seconds after a load. It is `pointer-events:none`, so it never
|
||||
blocks a click, but it hides a control while it shows.
|
||||
|
||||
**Wave 12 closed 2026-10-06.** Every task done-when and every exit criterion
|
||||
above is checked. Pushed as `feat/wave-12-bulk-users`; PR into `main` open.
|
||||
Merge after wave 16 (`feat/wave-16-on-main`); both orders tested conflict-free.
|
||||
@@ -1,486 +0,0 @@
|
||||
# Wave 13 — Okta/AD deprovisioning sync
|
||||
|
||||
**Items:** `D18`
|
||||
**Depends on:** wave 10 merged (it is). Not blocked by wave 11 or wave 12, but
|
||||
shares `server/app.py` account-state surface with wave 12 (`CR-020`) — sequence
|
||||
commits to avoid an avoidable conflict.
|
||||
**Decision record:** `docs/waves/decisions-2026-09-17.md`
|
||||
|
||||
Six tasks, in build order. **T13.3's fail-closed behavior is the most
|
||||
important done-when list in this wave — do not relax it to ship faster.**
|
||||
|
||||
---
|
||||
|
||||
### T13.1 — D18: idle timeout with an absolute ceiling
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** nothing (first task, independent of the rest)
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/auth.py`, `server/app.py` (`auth_gate` middleware),
|
||||
`server/.env.example`, `DEPLOYMENT.md`
|
||||
|
||||
**Revised 2026-09-23** — originally just "shrink `AUTH_SESSION_HOURS`". Matt
|
||||
asked whether an idle timeout would be a better fit than a flat session
|
||||
length. It is, but not by itself — see the decision record's reasoning on why
|
||||
idle-with-no-ceiling is actually a worse fit for this item's own threat model
|
||||
than a flat expiry would have been. Build both.
|
||||
|
||||
**Do:**
|
||||
|
||||
- Add `login_at` to the JWT payload in `create_token()` — the original
|
||||
sign-in time, distinct from `iat`, which becomes "when THIS token was
|
||||
issued" once tokens start getting reissued. `login_at` never changes across
|
||||
reissues; it's what the absolute ceiling is measured from.
|
||||
- Add `AUTH_IDLE_MINUTES` (default 30). `AUTH_SESSION_HOURS` stays the name
|
||||
for the absolute ceiling, default changing from 12 to a proposed 8 — update
|
||||
its docstring/comment in `auth.py` and `.env.example`, since its MEANING is
|
||||
changing (session length -> hard ceiling on top of a sliding idle window),
|
||||
not just its value.
|
||||
- In `auth_gate` (`server/app.py`), after confirming a request is
|
||||
authenticated: if `now < login_at + AUTH_SESSION_HOURS` (the ceiling hasn't
|
||||
passed), compute `new_exp = min(now + AUTH_IDLE_MINUTES, login_at +
|
||||
AUTH_SESSION_HOURS)`. If `new_exp` is meaningfully later than the current
|
||||
token's `exp` (throttle this — do not reissue on every single request, only
|
||||
when enough time has passed to be worth a new cookie; a few minutes of
|
||||
slack is fine), mint a refreshed token carrying forward `sub`/`username`/
|
||||
`role`/`ver`/`login_at` unchanged, and set it on the response.
|
||||
- If the ceiling HAS passed, do not refresh — let the existing token expire
|
||||
on its own terms (it may already be invalid, or may tick over within the
|
||||
idle window; either way, no new one is issued past the ceiling).
|
||||
- The middleware should not need a DB round trip to do this — everything
|
||||
needed (`sub`, `username`, `role`, `ver`, `login_at`) is already in the
|
||||
validated claims. `get_current_user`'s existing per-request `is_active`/
|
||||
`token_version` check is unaffected and still runs separately.
|
||||
|
||||
**Do not:** reissue the cookie on every request unconditionally — that's a
|
||||
`Set-Cookie` header on every API call for no benefit over a coarser refresh.
|
||||
Do not let the ceiling check silently vanish for tokens issued before this
|
||||
change ships — a token with no `login_at` claim should fall back to treating
|
||||
its own `iat` as `login_at`, not bypass the ceiling entirely.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] a session with continuous activity stays alive past 30 minutes but is
|
||||
cut off at the `AUTH_SESSION_HOURS` ceiling regardless
|
||||
*(2026-10-16, T13.6: a request every minute for 10 hours: alive well past 30 minutes, never extended past login + 8 h, cut off at the ceiling, original `login_at` kept.)*
|
||||
- [x] a session with no activity for 30+ minutes is rejected on its next
|
||||
request
|
||||
*(2026-10-16, T13.6: an idle token gets 401 on a gated route; one inside the window gets 200.)*
|
||||
- [x] the cookie is not rewritten on every single request — verify the
|
||||
refresh is throttled, not unconditional
|
||||
*(2026-10-16, T13.6: 20 rapid requests on a fresh session: 0 rewrites; 480 requests over 8 h: about one rewrite per 10 minutes; a refreshed cookie is not rewritten again on the next request. Mutation test: removing the throttle fails 3 checks.)*
|
||||
- [x] a pre-existing token with no `login_at` claim (simulating a session
|
||||
issued before this shipped) still gets a hard ceiling, via the `iat`
|
||||
fallback
|
||||
*(2026-10-16, T13.6: a token with iat 9 h ago and a still-valid old exp is not extended; one with iat 1 h ago is refreshed with `login_at` taken from `iat`; no `login_at` and no `iat` is not refreshed and does not crash. Mutation test: giving it a fresh ceiling fails.)*
|
||||
- [x] `.env.example` and `DEPLOYMENT.md` explain both variables and flag both
|
||||
defaults as proposed, not confirmed against Okta's own session policy
|
||||
*(2026-10-16, T13.6: both variables are in both files, and both call the defaults proposed.)*
|
||||
- [x] existing session/auth tests updated for the new mechanism, not just a
|
||||
new number
|
||||
*(2026-10-16, T13.6: there were none. T13.1 shipped with no test of its own. `tests/session_idle_check.py` is that test (T13.6 added it).)*
|
||||
|
||||
---
|
||||
|
||||
**Found while writing that test (T13.6, 2026-10-16):**
|
||||
- Nothing under `/api/auth/` slides the session. `auth._EXEMPT_PREFIXES` covers
|
||||
that whole prefix, so `auth_gate` never refreshes there (including
|
||||
`/api/auth/me`). A page that only called `/api/auth/me` would not extend its
|
||||
session. The spec says "after confirming a request is authenticated", and these
|
||||
routes are not confirmed by the gate, so this is as written. Noted, not changed.
|
||||
- The wave's exit criteria below say `AUTH_SESSION_HOURS` defaults to **2**. T13.1
|
||||
(this section), `auth.py`, `.env.example` and `DEPLOYMENT.md` all say **8**. The
|
||||
code and the T13.1 text agree, so the exit line looks like a leftover from
|
||||
before the 2026-09-23 revision. Not changed here: it is a product number. Needs
|
||||
Matt to say which one he means.
|
||||
|
||||
### T13.2 — D18: Okta Management API client
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** nothing (independent of T13.1)
|
||||
- **Blocks:** T13.3
|
||||
- **Surface:** `server/`
|
||||
- **Files:** new `server/okta_sync.py` (or extend `server/okta_auth.py` —
|
||||
task's call), `server/.env.example`
|
||||
|
||||
**Do:** A small client for Okta's user-list endpoint, authenticated with a new,
|
||||
separate credential (e.g. `OKTA_API_TOKEN`) — not the OIDC client secret used
|
||||
for sign-in. Fetch the full user list (paginated per Okta's API) rather than
|
||||
one-by-one lookups per local user; this app has ~20-odd accounts today, and a
|
||||
list-and-diff is simpler and cheaper than N calls. Return each Okta user's
|
||||
identity-claim value (matching `OKTA_IDENTITY_CLAIM`, already confirmed live
|
||||
per wave 10) and status.
|
||||
|
||||
Follow the existing pattern for external credentials in this repo (`MICRON_DB_URL`,
|
||||
`SMTP_PASSWORD`): env-only, never logged, never returned to the browser in an
|
||||
error message.
|
||||
|
||||
**Do not:** reuse `OKTA_CLIENT_ID`/`OKTA_CLIENT_SECRET` for this. Sign-in and
|
||||
the management API are different trust boundaries with different scopes;
|
||||
conflating them means a compromise or rotation of one affects the other
|
||||
unnecessarily.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the client authenticates with its own credential, distinct from the OIDC
|
||||
client
|
||||
*(2026-10-16: `OKTA_API_TOKEN`, sent as `Authorization: SSWS`. `tests/okta_sync_check.py` sets a different OIDC client secret and asserts it is never sent.)*
|
||||
- [x] it fetches the complete Okta user list, handling pagination
|
||||
*(2026-10-16: follows `Link: rel="next"`, 200 per page, 2-page case checked. A next link to another host is refused, a chain longer than 50 pages raises instead of cutting the list off, redirects are never followed.)*
|
||||
- [x] an auth failure or malformed response raises a clear, specific error
|
||||
rather than returning an empty list indistinguishable from "everyone was
|
||||
deprovisioned" — this distinction is what T13.3 depends on
|
||||
*(2026-10-16: `OktaSyncError` for HTTP 401/403/404/429/5xx, redirects, network errors, timeouts, non-JSON, non-list, a bad item (never skipped), and an empty list. 31 failure checks. Mutation test: making the client return `[]` on an error fails 10 of them.)*
|
||||
- [x] the credential is never logged or surfaced in any API response
|
||||
*(2026-10-16: error messages carry the class name and HTTP status only, never the URL or a header. `describe()` has no token. Nothing is wired to an API response yet; T13.4 wires the startup log.)*
|
||||
|
||||
---
|
||||
|
||||
### T13.3 — D18: the sync job
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** T13.2
|
||||
- **Blocks:** T13.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/okta_sync.py`, `server/app.py` (or wherever `log_event`
|
||||
lives)
|
||||
|
||||
**Do:** Compare the Okta user list (T13.2) against local `users` rows. For any
|
||||
local `is_active=True` user whose Okta identity is missing from the list, or
|
||||
present with a non-active status, set `is_active=False` and write an
|
||||
`AuditLog` row (`actor="system:okta_sync"`, action e.g.
|
||||
`user_deprovisioned_by_sync`, detail naming the Okta status found). Never
|
||||
touch a user already `is_active=False`. Never re-enable anyone.
|
||||
|
||||
**The fail-closed rule, non-negotiable:** if T13.2's client raises an error of
|
||||
any kind (network, auth, malformed response, timeout), this task takes **no
|
||||
action on any account** for that run and logs the failure clearly (server log,
|
||||
at minimum). An error is never treated as "Okta returned zero active users."
|
||||
Write a test that asserts this directly: feed the sync a failing client and
|
||||
assert zero rows changed and zero `AuditLog` entries written.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] a user missing from Okta's list, or present but not active, is disabled
|
||||
with a correctly-detailed audit row
|
||||
*(2026-10-16: see "Decided 2026-10-16" below for which statuses count as "not active". Audit row: actor `system:okta_sync`, action `user_deprovisioned_by_sync`, `entity_type` user, `detail` `{okta_status, via}`; a missing user is recorded as `MISSING`.)*
|
||||
- [x] a user already disabled is left alone (no duplicate audit row each run)
|
||||
*(2026-10-16: a second run over the same data writes no new rows.)*
|
||||
- [x] an active Okta user already active locally produces no audit row (only
|
||||
changes are logged, not a clean bill of health every cycle)
|
||||
*(2026-10-16: verified in `tests/okta_sync_job_check.py`.)*
|
||||
- [x] **a simulated Okta API failure results in zero account changes and zero
|
||||
audit rows** — this is the one check that must never be skipped or
|
||||
weakened
|
||||
*(2026-10-16: 10 stand-in failures (OktaSyncError, RuntimeError, ConnectionError, TimeoutError, ValueError, KeyError, empty list, None, two kinds of garbage), 4 through the real client (HTTP 401/403/429/500), the default path with no token, a failed commit, and a wrong identity attribute. Each: `ok` is False, zero accounts changed, zero audit rows. Mutation test: removing the fail-closed branch and the zero-match guard fails 28 of these.)*
|
||||
- [x] the job never re-enables an account under any input
|
||||
*(2026-10-16: a disabled account that is ACTIVE in Okta stays disabled, and `okta_sync.py` contains no assignment of `is_active` to True.)*
|
||||
|
||||
---
|
||||
|
||||
**Decided 2026-10-16 (Matt, in chat):** which Okta statuses disable an account.
|
||||
The spec says "a non-active status". Read literally, that also catches
|
||||
`PASSWORD_EXPIRED`, `LOCKED_OUT` and `RECOVERY`, which people leave on their
|
||||
own, and this job never re-enables, so one AD password expiry would lock someone
|
||||
out of the app until an admin stepped in. Decided: an account disables when it is
|
||||
**missing** from Okta's list, or every Okta entry for it is **SUSPENDED** or
|
||||
**DEPROVISIONED** (`DISABLING_STATUSES` in `server/okta_sync.py`). Okta's default
|
||||
user list already leaves out DEPROVISIONED users, so those arrive as "missing".
|
||||
|
||||
**Added 2026-10-16, inside decision 4's "anything the sync can't confidently
|
||||
parse":** if there are active local accounts and **none** of them matches any
|
||||
Okta user, the run is refused and nothing changes. That pattern means the
|
||||
identity attribute is wrong (`OKTA_SYNC_PROFILE_ATTRIBUTE`), not that the whole
|
||||
company left. It is a guard, not a new feature. Raise it in the PR.
|
||||
|
||||
**Open, for the PR / Nick:** which Okta profile attribute equals the
|
||||
`preferred_username` claim in this tenant. The client assumes `profile.login`,
|
||||
Okta's default. Confirm before the first live run. A wrong value is caught by the
|
||||
zero-match guard above only when it matches nobody at all; a value that matches
|
||||
some accounts and not others would disable the rest. See `BL-069`.
|
||||
|
||||
### T13.4 — D18: run it on a schedule
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** T13.3
|
||||
- **Blocks:** T13.6
|
||||
- **Surface:** `server/`, `docker-compose.yml`
|
||||
- **Files:** `server/app.py` (startup hook) or a new sidecar per the `backup`
|
||||
container's pattern — task's call, per the decision record's noted
|
||||
alternative
|
||||
|
||||
**Do:** Wire T13.3 to run on an interval (proposed 15 minutes, env-overridable
|
||||
— e.g. `OKTA_SYNC_INTERVAL_SECONDS`, matching `BACKUP_INTERVAL_SECONDS`'s
|
||||
naming). Default choice is an in-process background task in the `api`
|
||||
container; if a separate container is chosen instead, follow the `backup`
|
||||
service's shape (own Dockerfile or script, `internal` network plus whatever
|
||||
egress reaching Okta requires — check whether `outbound` as currently defined
|
||||
is sufficient or Okta needs a distinct allowance).
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the job runs automatically on the configured interval without manual
|
||||
invocation
|
||||
*(2026-10-16: a daemon timer thread starts from the app's lifespan hook (`server/app.py`), checks once a minute, and ran the sync on its own in `tests/okta_sync_schedule_check.py`. With `OKTA_API_TOKEN` unset it starts nothing and the startup log says `Okta sync DISABLED`. Booted the real app both ways; the thread starts and ends with the app.)*
|
||||
- [x] interval is env-configurable with a sane default
|
||||
*(2026-10-16: `OKTA_SYNC_INTERVAL_SECONDS`, default 900. A non-number uses the default. A value under 300 is raised to 300. Passed through `docker-compose.yml`.)*
|
||||
- [x] a container restart does not produce a duplicate/overlapping run, and a
|
||||
slow cycle does not stack with the next one
|
||||
*(2026-10-16: the api runs 2 gunicorn workers, so each starts its own timer. One row in `app_settings` (key `okta_sync`) is the gate: a worker claims a cycle with one atomic conditional UPDATE, so exactly one wins. Checked with 8 racing workers on a file database, 15 rounds plus the first-insert race: exactly 1 winner every time. The row outlives a restart, so a restart inside the interval starts nothing. A slow run cannot overlap the next: a fetch is capped at 120 s in total and the interval cannot go below 300 s. Inside one process the thread runs one cycle at a time. This needed no migration: `app_settings` already exists.)*
|
||||
|
||||
---
|
||||
|
||||
**Decided 2026-10-16 (task's call, per this task's "Do"):** in-process timer in the
|
||||
`api` container, as D18 proposed, not a sidecar. The `backup` pattern was the
|
||||
alternative; it would need its own image and would not remove the 2-worker
|
||||
duplicate question, because the sync reads the application database anyway.
|
||||
**Network check, as the task asked:** the `outbound` network the `api` service
|
||||
already joins is an ordinary bridge with a gateway, so Okta is reachable with no
|
||||
network change. The host firewall must allow https to the Okta org.
|
||||
**One change to T13.2's code:** `fetch_users()` now also stops after 120 seconds in
|
||||
total (`TOTAL_DEADLINE_SECONDS`), which is what lets the scheduler promise no
|
||||
overlap. Tested in `tests/okta_sync_check.py` section 8.
|
||||
|
||||
**T13.4 follow-up, 2026-10-16:** the sync's INFO log lines did not appear in
|
||||
`docker compose logs api`. Nothing in the app configures Python logging, and
|
||||
gunicorn configures only its own loggers, so INFO from any `wpsuite.*` logger is
|
||||
dropped. The T13.4 check booted the app in-process with logging switched on,
|
||||
which hid it. With the exact Dockerfile launch (2 gunicorn workers), a healthy
|
||||
start printed zero Okta lines. `okta_sync.py` now gives its own logger one stderr
|
||||
handler (only when the root logger has none). Re-run with the real gunicorn
|
||||
command: `configured` and `scheduled` (or `DISABLED`) now print once per worker.
|
||||
No other module's output changed. App-wide logging stays a separate question
|
||||
(BL-028 is the same family).
|
||||
|
||||
### T13.5 — D18: admin visibility
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** T13.3
|
||||
- **Blocks:** T13.6
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/users.js` / `html/admin.js` (wherever audit history is
|
||||
already surfaced)
|
||||
|
||||
**Do:** Confirm an auto-disable reads clearly wherever admins already look at
|
||||
account history — the actor string (`system:okta_sync`) should be
|
||||
self-explanatory in context, not require reading server logs to understand.
|
||||
Do not build new UI beyond making sure the existing audit surface renders this
|
||||
actor sensibly. Email/notification to admins on auto-disable is a noted
|
||||
fast-follow (the decision record flags it as open, not required here) — do not
|
||||
build it in this task; log it instead if it's tempting to add.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] an auto-disabled account's audit entry is visible and legible in the
|
||||
existing admin UI without special-casing
|
||||
*(2026-10-16: run on the PC against the real page, 1440px and 390px, `tests/okta_sync_ui_check.py` 28/28. The admin Activity log card reads: Who `system:okta_sync`, Action `user deprovisioned by sync`, Type `user`, Item the username, Detail `okta_status: SUSPENDED, via: okta_sync` (a person missing from Okta reads `okta_status: MISSING`). Search for `okta_sync` and the User accounts filter both find the rows. No sideways scroll, no JavaScript errors. The disabled account is refused on its very next request; an account still active in Okta is not. A project super user does not see these rows: they belong to no project, so only admins do, the same as other user-management events. No code in `html/` changed.)*
|
||||
- [x] nothing here silently assumes `CR-019`'s activity view exists yet — this
|
||||
must work standalone
|
||||
*(2026-10-16: the check reads only the Activity log (AuditLog) card. The new Activity & usage card is on the page but is not read.)*
|
||||
|
||||
---
|
||||
|
||||
**No UI was built.** The existing card renders the new rows legibly as is. Two
|
||||
things you might expect and did not get, both on purpose: no admin email on an
|
||||
auto-disable (D18 calls it a fast-follow; not built, not logged as a new item
|
||||
because D18 already names it), and no per-user history view in the User
|
||||
Directory (it has none today, and the task says not to build one).
|
||||
|
||||
### T13.6 — D18: verification
|
||||
|
||||
- **Items:** `D18`
|
||||
- **Depends on:** T13.4, T13.5
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `server/`
|
||||
- **Files:** as touched above
|
||||
|
||||
**Do:** Full verification per `CLAUDE.md`. Beyond the usual run: specifically
|
||||
re-run T13.3's fail-closed test in isolation and confirm it still passes after
|
||||
T13.4's scheduling wrapper is in place — the scheduling layer must not
|
||||
introduce a path that swallows the client's error and proceeds anyway.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] all `D18` acceptance criteria in `decisions-2026-09-17.md` are met or a
|
||||
failure is stated with a reason
|
||||
- [x] the fail-closed behavior is verified end to end through the scheduled
|
||||
wrapper, not just the bare sync function
|
||||
- [x] smoke test and `seed_demo.py` both still pass
|
||||
- [x] full test suite passes (48 of 50; the two failures are the known ones, see the result note below)
|
||||
|
||||
---
|
||||
|
||||
## Wave 13 exit criteria
|
||||
|
||||
- [x] `AUTH_SESSION_HOURS` defaults to 8, documented (D25 replaced the 2 hours in this line; T13.1's idle timer is still held back)
|
||||
- [x] the sync job runs on a schedule and correctly disables accounts Okta no
|
||||
longer shows as active
|
||||
- [x] every auto-disable is individually audited with a clearly non-human actor
|
||||
- [x] an Okta API failure of any kind changes zero accounts — verified, not
|
||||
assumed
|
||||
- [x] the sync never re-enables an account
|
||||
- [ ] `D18` fully accounted for, no open acceptance criteria
|
||||
|
||||
## Release note (2026-10-16)
|
||||
|
||||
T13.1 (commit `6cde6e3`) is held back from `main` until T14.1 lands, per the merge
|
||||
rule in `wave-12.md`. The release branch contains wave 11 and T13.2 to T13.5.
|
||||
`tests/session_idle_check.py` skips (exit 0) when `auth.maybe_refresh_token` is absent.
|
||||
Sessions keep the flat `AUTH_SESSION_HOURS` lifetime (default 12) until T13.1 lands.
|
||||
|
||||
T13.6 result (2026-10-16, merged release tree, Edge on the PC): 47 test scripts, 45 pass.
|
||||
The two failures are not regressions. `token_check.py` exits 2 (CLI usage detail).
|
||||
`generalinfo_check.py` finds an old color-literal gap in `wp-creation-styles.css`.
|
||||
Alembic upgrade, downgrade, upgrade passed. Import check passed.
|
||||
|
||||
## T13.7: D22 dry run for the Okta sync
|
||||
|
||||
**Item:** D22 (`docs/waves/decisions-2026-10-16.md`). Extends T13.3 and T13.4.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `OKTA_SYNC_DRY_RUN` on: the sync fetches and matches, logs the accounts it would disable, and changes no account and writes no audit row (`tests/okta_sync_dry_run_check.py`)
|
||||
- [x] both guards (zero match, fail closed) still apply in a dry run
|
||||
- [x] flag off or unset: behavior is unchanged (`okta_sync_job_check.py` still passes)
|
||||
- [x] the startup line names the mode
|
||||
- [x] `.env.example`, `docker-compose.yml` and `DEPLOYMENT.md` describe the flag and the first-deploy steps
|
||||
- [x] mutation check: if the dry-run guard is removed, the new test fails
|
||||
|
||||
Result 2026-10-16: all Okta sync tests and `security_check.py` pass in the sandbox.
|
||||
This task changes no frontend file.
|
||||
|
||||
## T13.8: run the stack in Docker on a PC
|
||||
|
||||
**Item:** D22 (`docs/waves/decisions-2026-10-16.md`), as a way to check T13.7 and later builds before a deploy.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] one command starts the api, the database and the web server from the shipped compose file plus `docker-compose.local.yml`
|
||||
- [x] `http://localhost:8080/api/health` answers 200 and `/api/projects` answers 401 without a session
|
||||
- [x] every migration runs on Postgres (head `8e2cb3003f8a`)
|
||||
- [x] the api log shows the `Okta sync` startup line
|
||||
- [x] the steps are in `DEPLOYMENT.md`, "Run the stack on your own PC"
|
||||
- [x] the shipped `docker-compose.yml` and nginx config are not changed
|
||||
|
||||
Result 2026-10-16 (Docker Desktop 29.7.2, Compose 5.4.0, Windows): passed. Three
|
||||
things in the shipped files stop a local run. The override handles the first two
|
||||
and the third is logged:
|
||||
|
||||
1. The web server publishes no port (the host's reverse proxy reaches it). The override publishes 8080 on loopback.
|
||||
2. An existing `proxy` network on a PC can have no gateway, and Docker then does not publish ports. The override uses its own bridge. The stock nginx `default.conf` also answers "localhost" first and the app server answers only wp.controls.dev, so the override removes the stock file and makes the app server the default.
|
||||
3. The backup container cannot start on Windows: `scripts/entrypoint.sh` has CRLF line endings (BL-070). The override turns the backup service off.
|
||||
|
||||
## T13.9: D23 sign in as an OAuth service app (private_key_jwt)
|
||||
|
||||
**Item:** D23 (`docs/waves/decisions-2026-10-16.md`). Extends T13.2.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] with `OKTA_SYNC_CLIENT_ID` and `OKTA_SYNC_PRIVATE_KEY`, the sync gets an access token and lists users with `Bearer` (`tests/okta_sync_oauth_check.py`)
|
||||
- [x] the assertion verifies against the public key: `iss`, `sub`, `aud`, `kid`, life, `jti`
|
||||
- [x] RSA and EC keys; JSON and base64 forms
|
||||
- [x] a failed token request, a missing token, a DPoP token, a public key, or an unreadable key raises, and the users endpoint is never called
|
||||
- [x] `OKTA_API_TOKEN` still works and wins when both are set
|
||||
- [x] the startup line names the credential and holds no secret; no error message holds key text
|
||||
- [x] mutation checks: Bearer to SSWS, wrong `aud`, DPoP accepted, public-key check removed: each makes the test fail
|
||||
- [x] `.env.example`, `docker-compose.yml`, `DEPLOYMENT.md` describe the variables and the Okta app setup
|
||||
|
||||
Result 2026-10-16: sandbox, fake Okta. Not yet run against the real tenant.
|
||||
No new dependency: PyJWT signs with `cryptography`, which Authlib already installs.
|
||||
|
||||
T13.9 follow-up (2026-10-16): the first live deploy failed with "OKTA_SYNC_PRIVATE_KEY is not a
|
||||
JWK as JSON or as base64 of JSON". The first loader used strict base64, which rejects any
|
||||
space or line break, and it gave one message for every failure. The loader now forgives quote
|
||||
marks, spaces, line breaks, missing padding, the URL-safe alphabet, a byte-order mark and a
|
||||
one-key JWK Set, and each failure names its step (counts only, no key text). The new checks
|
||||
in `tests/okta_sync_oauth_check.py` fail against the first loader and pass now.
|
||||
|
||||
T13.9 follow-up 2 (2026-10-16): the second deploy decoded the value but the text was not JSON.
|
||||
The loader now also names a PEM key, adds missing outer braces, unwraps a value that was encoded
|
||||
twice, and its "not JSON" message gives the length and the kind of first character (counts only).
|
||||
|
||||
T13.9 follow-up 3 (2026-10-16): the third deploy decoded the base64 to 1,760 characters that start
|
||||
with a brace, but Python's strict JSON reader refused them (PowerShell accepted the same text).
|
||||
The loader now accepts control characters such as line breaks inside a string, curly quote marks and
|
||||
a trailing comma, removes spaces inside the key's number fields, and a real syntax error reports the
|
||||
line and column (position and rule only, never key text).
|
||||
|
||||
## T13.10: D24 DPoP for the Okta Management API
|
||||
|
||||
**Item:** D24 (`docs/waves/decisions-2026-10-16.md`). Extends T13.9.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] auto mode: a plain Bearer token is tried first; `invalid_dpop_proof` makes the sync retry with DPoP (`tests/okta_sync_dpop_check.py`)
|
||||
- [x] each proof verifies: header (`dpop+jwt`, ES256, public jwk only), signature, `htm`, `htu` without query, current `iat`, one-time `jti`, `ath` on API calls, same key for token and API calls
|
||||
- [x] nonce challenges at the token endpoint and at the API are answered once, and the retries are bounded
|
||||
- [x] paging: a new proof for every page
|
||||
- [x] mode `on` and mode `off`; a DPoP-bound token with mode off is refused; each run makes a new key
|
||||
- [x] no secret in any message or the startup line; the SSWS path is unchanged
|
||||
- [x] mutation checks: query kept in `htu`, `ath` omitted, `jti` reused, nonce not retried (token and API), private key in the proof header, and auto detection removed each make a test fail
|
||||
- [x] `.env.example`, `docker-compose.yml`, `DEPLOYMENT.md` updated
|
||||
|
||||
Result 2026-10-16: sandbox, strict fake Okta. Not yet run against the real tenant.
|
||||
|
||||
## Live run and final verification (2026-10-17)
|
||||
|
||||
**Live deploy.** The api container runs the build from `main` (`1a3468e`) in Portainer. It signs in with the
|
||||
service-app key (`private_key_jwt`) and DPoP. The first dry run (2026-10-17 18:31) fetched 2,564 Okta users and
|
||||
checked 42 active local accounts. 41 matched (so `profile.login` is the right attribute) and 1 would be disabled:
|
||||
`admin`, Okta status MISSING. Matt confirmed that `admin` is a leftover account, and switched the dry run off.
|
||||
|
||||
Live run log lines (api log):
|
||||
|
||||
- 18:46:21 `Okta sync disabled 'admin' (Okta status: MISSING)`, then `done: 2564 Okta user(s), 42 active local account(s) checked, 1 disabled`
|
||||
- 19:01:50 `done: ... 41 active local account(s) checked, 0 disabled`
|
||||
- 19:16:30 `done: ... 41 active local account(s) checked, 0 disabled`
|
||||
|
||||
This shows: the job runs on its schedule (every 900 seconds), it disables an account that Okta no longer lists, a
|
||||
disabled account is not touched again and gets no new row, and the account count fell from 42 to 41.
|
||||
The first session logs of fail-closed behavior are in the earlier runs: with a rejected token, a bad key, and an
|
||||
unreadable key, the sync logged `SKIPPED, no account was changed` every time and no account changed.
|
||||
|
||||
**Admin recovery.** `python -m server.manage_users list | promote | enable | disable` works from the Portainer
|
||||
console of `wp_api` (no `docker compose exec` prefix). `promote` changes an existing account. It does not create one.
|
||||
|
||||
**Full verification on the final tree (`1a3468e`).**
|
||||
|
||||
- Test suite on Matt's PC (Edge): 50 scripts, 48 pass. The two failures are not regressions:
|
||||
`token_check.py` exits 2 (it needs `--out` or `--compare`), and `generalinfo_check.py` finds an old colour literal
|
||||
(`rgba(`) in `wp-creation-styles.css`.
|
||||
- `server/smoketest.py`: 27 of 27 checks pass. `server/seed_demo.py`: runs clean. Both ran in the sandbox against
|
||||
a throwaway SQLite database. Note: use `http://127.0.0.1:PORT`, not `http://localhost:PORT`, because Python's cookie
|
||||
jar does not send a cookie set for `localhost` (logged as BL-071).
|
||||
- The Okta tests (`okta_sync_check`, `_job_`, `_schedule_`, `_dry_run_`, `_oauth_`, `_dpop_`, `_ui_`) and `security_check.py` pass.
|
||||
|
||||
**Still open for wave 13.**
|
||||
|
||||
- `T13.1` (idle timeout) is held back from `main` until T14.1 lands. The exit criterion "`AUTH_SESSION_HOURS` defaults to 2"
|
||||
is not met, and it conflicts with T13.1's own text (8 hours). Matt has not chosen.
|
||||
- ~~"Every auto-disable is individually audited with a clearly non-human actor" was not checked after the live run.~~
|
||||
Checked 2026-10-17: the Admin Console activity list shows one row, actor `system:okta_sync`, action "user deprovisioned
|
||||
by sync", item `admin`, detail `okta_status: MISSING, via: okta_sync`, at 11:46 AM local (18:46 UTC).
|
||||
- `D18` cannot be called fully accounted for while T13.1 is outstanding.
|
||||
- `BL-069` (a cap on one run and a last-admin guard) is open.
|
||||
|
||||
## T13.11: D25 the session limit is 8 hours
|
||||
|
||||
**Item:** D25 (`docs/waves/decisions-2026-10-16.md`).
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `AUTH_SESSION_HOURS` defaults to 8 in `server/auth.py`, `docker-compose.yml`, `server/.env.example`, `DEPLOY-login-portal.md` (`tests/session_default_check.py`)
|
||||
- [x] the token expiry and the cookie max-age follow it; a set value overrides it
|
||||
- [x] mutation check: putting the default back to 12 makes the test fail
|
||||
- [x] the wave 13 exit criterion that said 2 is updated
|
||||
|
||||
Effect on the live system: after the next deploy, sessions last 8 hours instead of 12. To get the same result
|
||||
before a deploy, set `AUTH_SESSION_HOURS` to `8` in the Portainer stack variables.
|
||||
|
||||
## Gate for T13.1 (2026-10-17)
|
||||
|
||||
T13.1 now has a written gate: `docs/waves/wave-14.md`. It lands in T14.4, after T14.1 (a `401` holds the outbox and does not
|
||||
destroy it) and T14.2 (the offline window follows the server) are done. The reason is a fault found in the outbox on
|
||||
2026-10-17: it marks a `401` as a permanent rejection, so an idle timeout would reject a crew's queued changes for good.
|
||||
That fault already exists with the 8 hour limit, to a lesser degree.
|
||||
@@ -1,182 +0,0 @@
|
||||
# Wave 14: The outbox keeps every change, and the sign-in limit cannot destroy it
|
||||
|
||||
**Items:** `D26`, `D27`, `BL-061` (`B5` is context only: its wording rules stay, and this wave does not widen it)
|
||||
**Depends on:** wave 13 merged (it is, except T13.1). Independent of wave 15.
|
||||
**Decision record:** `docs/waves/decisions-2026-10-17.md` (D26 and D27 are **proposed**; they need Matt's OK, see "Open questions")
|
||||
**Unblocks:** `T13.1` (idle timeout). T13.1 must not reach `main` before T14.1 and T14.2 are done.
|
||||
**Branch rule:** one task for each pull request. Cut each branch from `main`.
|
||||
|
||||
## Why this wave exists
|
||||
|
||||
The outbox in `html/project-data.js` queues each save in `localStorage` and sends it later. A crew in the field
|
||||
can work with no signal, and the changes go out when the network returns. The code was checked on 2026-10-17
|
||||
against the 8 hour session limit (D25) and the idle timeout that T13.1 adds. It has four faults that lose or hide
|
||||
work. They are small now. The idle timeout would make them common.
|
||||
|
||||
| # | Fault | Where | Result |
|
||||
|---|---|---|---|
|
||||
| 1 | A `401` (session ended) or `403` is treated like any other `4xx`. The change is marked **dead** and is never sent again. | `project-data.js`, `flush()` | A crew that works past the session limit, or past an idle timeout, comes back online and every queued change is rejected for good. The badge says "rejected by the project". The change is not lost from the device, but nothing can send it. |
|
||||
| 2 | `qWrite()` swallows a storage error. | `project-data.js`, `qWrite()` | If the device storage is full, a change is **not queued and nobody is told**. |
|
||||
| 3 | The queue belongs to the browser, not to a person. A queued change has no owner. | `project-data.js`, `enqueue()` | On a shared device, person B signs in and the queue of person A is sent under the name of person B. |
|
||||
| 4 | The offline sign-in window is a fixed 12 hours in the browser. | `auth-guard.js`, around line 183 | It does not follow `AUTH_SESSION_HOURS` (8 since D25). It also slides: every online page load resets it. The browser and the server disagree about when the session ends. |
|
||||
|
||||
Also: the sync badge sits over page controls (`BL-061`) and cannot be used with a keyboard or a finger. The
|
||||
badge is a `div` with `pointer-events:none`. A badge that must ask a person to sign in again needs a real link or button.
|
||||
|
||||
## Rules for this wave
|
||||
|
||||
- Do not use a `div` with `onclick` (`CLAUDE.md`, accessibility). The sign-in action is an `<a>` or a `<button>`.
|
||||
- Status text goes in an `aria-live` region. The badge already has `role="status"`. Keep it.
|
||||
- Server work is needed for T14.2 (one new field). Do not store session data in `localStorage` as the source of truth.
|
||||
- Colors, spacing and type come from the shared tokens. Do not add a raw hex value to a page stylesheet.
|
||||
- Frontend checks: run the app on a throwaway SQLite database, check at 390 px and 1440 px, capture before and after
|
||||
screenshots, run the smoke test (use `http://127.0.0.1`, see `BL-071`).
|
||||
- Do not fix other problems you see. Log them in `docs/waves/backlog.md`.
|
||||
|
||||
---
|
||||
|
||||
### T14.1: D26 a sign-in problem never destroys a queued change
|
||||
|
||||
- **Items:** `D26`
|
||||
- **Depends on:** nothing (first task)
|
||||
- **Blocks:** T14.2, T14.3, T13.1
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/project-data.js`, `html/auth-guard.js`, a new `tests/outbox_check.py`
|
||||
|
||||
**Do:**
|
||||
|
||||
1. In `flush()`, treat `401` as **held**, not dead. Stop the run. Do not add to `tries`. Do not mark any change
|
||||
dead. Keep the whole queue in its order. Set a "held for sign-in" state that the badge can read through
|
||||
`ProjectData.syncStatus()` (add a field, for example `held: true`).
|
||||
2. Keep `403` as a permanent refusal, but say why in the reason text ("you no longer have access to this project").
|
||||
Keep `409` (archived project) and the other `4xx` as they are.
|
||||
3. When the person signs in again (the page loads with a good session, or `wp-auth-ready` fires), clear the held
|
||||
state and flush at once. The `online` event, the 20 second timer and the tab-focus trigger must **not** clear it
|
||||
early: a held queue sends only after a good session check.
|
||||
4. Make `qWrite()` return `true` or `false`. If it fails, `enqueue()` must tell the caller and raise the
|
||||
`device full` state. The change stays in the page memory and the form stays open. The badge says the change is
|
||||
**not saved on this device**. Do not drop it silently.
|
||||
5. Give each queued change an `owner` (the signed-in username) when it is queued. At flush time, if `WP_USER` is not the
|
||||
owner, hold that change and name the owner in the message. Do not send it. Do not discard it. (See open question 1.)
|
||||
6. Make sure `auth-guard.js` does not delete the queue when it sends a person to `login.html` after a `401`. It must
|
||||
keep `wp_sync_outbox_v1`.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] a queue of N changes meets a `401`: all N are still in the queue, none is dead, `tries` did not change, and the badge state is "held"
|
||||
- [ ] after a good sign-in, all N changes reach the server in their original order, and the queue is empty
|
||||
- [ ] a `403` marks only that change dead, with a reason that names the cause
|
||||
- [ ] a full device store (a forced `QuotaExceededError`) is reported to the caller and the badge. No change disappears silently
|
||||
- [ ] a change queued by person A is not sent when person B is signed in; it is sent after A signs in
|
||||
- [ ] `tests/outbox_check.py` covers each case above and fails when `flush()` is put back to the old rule (a mutation check)
|
||||
- [ ] the full suite passes, at 390 px and 1440 px
|
||||
|
||||
---
|
||||
|
||||
### T14.2: D27 the offline sign-in window follows the server
|
||||
|
||||
- **Items:** `D27`
|
||||
- **Depends on:** T14.1
|
||||
- **Blocks:** T13.1
|
||||
- **Surface:** `server/` and `html/`
|
||||
- **Files:** `server/app.py` (`whoami()`), `html/auth-guard.js`, `html/wp-format.js` (line 223 writes the cache), tests
|
||||
|
||||
**Do:**
|
||||
|
||||
1. Add one field to `/api/auth/me`: `session_expires_at` (the `exp` claim of the session, as a UTC time). Read the claim from the
|
||||
token that `get_current_user` already validated. Do not add a database column. When T13.1 lands, this field is the
|
||||
current `exp` and moves with each refresh.
|
||||
2. In `auth-guard.js`, store `session_expires_at` in `wp_auth_cache`. Replace the fixed `12 * 3600 * 1000` with a rule
|
||||
that uses it. The rule for this wave (see open question 2):
|
||||
- offline, the app **opens** while the current time is before `session_expires_at`;
|
||||
- after that time, offline, the app still opens in a **read and queue** mode: the person can see cached data and add
|
||||
changes, which go to the outbox and are held (T14.1) until a good sign-in. The app does not go to `login.html`
|
||||
while it has no network, because that page cannot load an Okta sign-in without a network;
|
||||
- online, a `401` goes to `login.html` as now, and the outbox is kept (T14.1).
|
||||
3. Stop sliding the window. A page load must not extend `wp_auth_cache`. Only the server can extend a session.
|
||||
4. Show the person which mode they are in. One line: "Working offline. Sign in again when you have a signal to send your changes."
|
||||
Use the same `aria-live` region as the badge.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] `/api/auth/me` returns `session_expires_at`, and it matches the token (`tests/` check, no database change)
|
||||
- [ ] the fixed 12 hours is gone from `auth-guard.js`
|
||||
- [ ] opening the app offline before the time works; opening it offline after the time gives read-and-queue mode and does not redirect
|
||||
- [ ] online with a dead session: redirect to `login.html?next=...`, queue kept, changes sent after sign-in
|
||||
- [ ] a page load does not extend the cached window
|
||||
- [ ] the mode line is announced by a screen reader (`aria-live`) and fits at 390 px
|
||||
|
||||
---
|
||||
|
||||
### T14.3: D26 and BL-061 the sync badge shows the true state and gets out of the way
|
||||
|
||||
- **Items:** `D26`, `BL-061`
|
||||
- **Depends on:** T14.1
|
||||
- **Blocks:** nothing
|
||||
- **Surface:** `html/`
|
||||
- **Files:** `html/project-data.js` (`renderSyncBadge`), `html/wp-chrome.css` or the shared token file, `tests/a11y_check.py`, `tests/autosave_check.py` (it reads the badge strings)
|
||||
|
||||
**Do:**
|
||||
|
||||
1. Show these states, each with its own words that name the **project**, never a draft save (the `B5` rule that wave 4 set): `sending`, `retrying`,
|
||||
`held for sign-in` (with a link or button "Sign in"), `not saved on this device` (store full), `rejected` (with the reason),
|
||||
and `all sent` (hides after a short time).
|
||||
2. Make the badge usable: the "Sign in" and "Dismiss" controls are `<a>` or `<button>` elements with a visible focus ring
|
||||
and a touch target of at least 44 px. Remove `pointer-events:none` for the states that have controls.
|
||||
3. Keep the badge clear of page controls (`BL-061`): do not show it on pages that have no outbox work (the console
|
||||
pages), and place it so that it does not cover the bottom-right action buttons at 390 px or 1440 px.
|
||||
4. Keep text contrast at 4.5:1 or better in every state.
|
||||
5. Update the tests that read the badge text (`autosave_check.py` reads its symbols; `a11y_check.py` reads the element).
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] each state shows in a browser test, with its text, at 390 px and 1440 px
|
||||
- [ ] "Sign in" works with the keyboard and by touch, and goes to `login.html?next=...`
|
||||
- [ ] the badge covers no control on the User Directory at 1440 px or the bulk bar at 390 px (the two places `BL-061` named)
|
||||
- [ ] no badge on the console pages
|
||||
- [ ] the contrast check passes for every state
|
||||
- [ ] `autosave_check.py` and `a11y_check.py` pass
|
||||
|
||||
---
|
||||
|
||||
### T14.4: verify the wave and release T13.1
|
||||
|
||||
- **Items:** `D26`, `D27`, `BL-061`, `T13.1`
|
||||
- **Depends on:** T14.1, T14.2, T14.3
|
||||
- **Blocks:** nothing
|
||||
|
||||
**Do:** Run the full suite, the smoke test and `seed_demo.py`. Then test the real case by hand on a phone or tablet:
|
||||
sign in, set the device to airplane mode, make three changes in Field View, wait until the session limit has passed
|
||||
(use `AUTH_SESSION_HOURS=1` on a test stack with a clock change, or a forced expiry), turn the network on, and check that the badge shows
|
||||
"held for sign-in", that signing in sends all three, and that the server has them. Then rebase `feat/waves-11-13`
|
||||
T13.1 (`6cde6e3`) onto `main`, run `tests/session_idle_check.py` and the same hand test with the idle timeout on, and merge T13.1 as its own pull request.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [ ] the hand test passes on one iPhone and one Android device (or the failure and the reason are written here)
|
||||
- [ ] the full suite and the smoke test pass on the final tree
|
||||
- [ ] T13.1 is on `main`, and `tests/session_idle_check.py` runs (it no longer skips)
|
||||
- [ ] the wave 13 exit line about D18 is ticked
|
||||
|
||||
---
|
||||
|
||||
## Open questions (needs Matt before T14.1 and T14.2 start)
|
||||
|
||||
1. **Shared devices.** If person B signs in on a device that holds unsent changes from person A, what must happen?
|
||||
Proposed: hold A's changes, name A in the badge, send them when A signs in. Do not send them as B and do not discard them.
|
||||
Other choices: allow B to discard A's changes after a confirmation; or send them as B (not proposed, wrong author in the log).
|
||||
2. **Offline window.** Proposed for this wave: the app opens offline until the session ends, and after that works in read-and-queue mode.
|
||||
The 7 day offline window (`BL-062`, Q2) is a **later** wave. Do you accept this order, or must 7 days come first?
|
||||
3. **Device full.** Proposed: do not drop the change, keep it in the page memory, and tell the person. Is "tell the person and keep the
|
||||
form open" enough, or must the app also stop new edits?
|
||||
4. **Idle time.** T13.1 proposes 30 minutes. It is a proposed value, not a decision. It matters here because every minute of idle
|
||||
time offline ends the session on the server side.
|
||||
|
||||
## Wave 14 exit criteria
|
||||
|
||||
- [ ] a session that ends while changes are queued loses none of them
|
||||
- [ ] a full device store is never silent
|
||||
- [ ] a change is sent only under the signed-in person who made it
|
||||
- [ ] the offline window follows the server (no fixed 12 hours in the browser)
|
||||
- [ ] the badge shows the true state, is usable, and covers no control
|
||||
- [ ] T13.1 is merged to `main` and `D18` is fully accounted for
|
||||
@@ -1,155 +0,0 @@
|
||||
# Wave 16 — Urgent security fixes
|
||||
|
||||
**Items:** `D19`, `D20`, `D21`
|
||||
**Depends on:** nothing. Independent of waves 12 to 15 (see the decision record).
|
||||
**Decision record:** `docs/waves/decisions-2026-10-02.md`
|
||||
**Background:** `docs/reference/security-review-2026-10-01.md`
|
||||
|
||||
Four tasks, in build order. All server-side. No page markup or stylesheet
|
||||
changes, so the 390px / 1440px screenshot rule does not apply; the
|
||||
browser probes that read files and SOPs are still listed for a run on a
|
||||
machine with Edge.
|
||||
|
||||
New check for this wave: `tests/security_check.py`. It is self-contained (its
|
||||
own SQLite database, in-process, no browser), so it runs anywhere.
|
||||
|
||||
---
|
||||
|
||||
### T16.1 — D21: session decode fails closed; PyJWT 2.15.1
|
||||
|
||||
- **Items:** `D21`
|
||||
- **Depends on:** nothing (first task)
|
||||
- **Blocks:** T16.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/requirements.txt`, `server/auth.py` (`decode_token`), `tests/security_check.py` (new)
|
||||
|
||||
**Do:** pin `PyJWT==2.15.1`. In `decode_token`, return `None` for an empty or
|
||||
over-long token (over 4096 characters) and for any exception from
|
||||
`jwt.decode`. Require the `exp` and `sub` claims.
|
||||
|
||||
**Do not:** change token contents, the cookie, or the D18 refresh.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] the crafted-cookie request returns 401, not 500
|
||||
- [x] a valid session still works, and the D18 refresh still reissues
|
||||
- [x] `pip-audit -r server/requirements.txt` reports no PyJWT advisory
|
||||
- [x] smoke test 27/27
|
||||
|
||||
---
|
||||
|
||||
### T16.2 — D19: uploaded files download safely
|
||||
|
||||
- **Items:** `D19`
|
||||
- **Depends on:** nothing
|
||||
- **Blocks:** T16.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/files_http.py` (new), `server/app.py` (`get_wp_file`), `tests/security_check.py`
|
||||
|
||||
**Do:** serve PDF and raster images inline as today. Serve every other type,
|
||||
SVG included, as an attachment with `Content-Security-Policy: sandbox;
|
||||
default-src 'none'`. Send `X-Content-Type-Options: nosniff` from the API too
|
||||
(NGINX already does; the dev server does not). Build `Content-Disposition`
|
||||
with an ASCII fallback and an RFC 5987 `filename*`. Reference code:
|
||||
`docs/reference/architecture-review/proposals/server/files_http.py` (P-6).
|
||||
|
||||
**Do not:** refuse SVG uploads (decided: accept, download only). Do not change
|
||||
`Cache-Control`.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] an SVG downloads as an attachment with the sandbox header
|
||||
- [x] PNG, JPEG and PDF still open inline
|
||||
- [x] `Plan é.pdf` downloads (was 500)
|
||||
- [x] a name with CR/LF produces a valid header
|
||||
- [x] `tests/files_check.py` passes on a machine with Edge (CR-007 offline drawings)
|
||||
|
||||
---
|
||||
|
||||
### T16.3 — D20: one SOP per project
|
||||
|
||||
- **Items:** `D20`
|
||||
- **Depends on:** nothing
|
||||
- **Blocks:** T16.4
|
||||
- **Surface:** `server/`
|
||||
- **Files:** `server/app.py` (`upsert_sop`, `latest_sop`, `project_summary`, `project_sop_team`, `project_qa_group`), `tests/security_check.py`
|
||||
|
||||
**Do:** the four rules in D20. One helper picks the project's baseline SOP
|
||||
(canonical row if complete, else latest complete) and every baseline reader
|
||||
uses it.
|
||||
|
||||
**Do not:** delete or rename existing SOP rows. Do not change any response shape.
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] a `project_user` cannot create a second SOP on a project (400) or post
|
||||
`complete: true` while a complete SOP exists (403)
|
||||
- [x] a `project_user` can still draft and complete the first SOP of a project
|
||||
- [x] a Project Admin can still change the completed SOP
|
||||
- [x] POST without an id lands on `sop__<project_id>`
|
||||
- [x] a rogue complete SOP made before the fix no longer drives the baseline
|
||||
or the QA and PM/CM recipients
|
||||
- [x] `tests/sample_check.py` and `tests/critical_reopen_check.py` pass on a
|
||||
machine with Edge
|
||||
|
||||
---
|
||||
|
||||
### T16.4 — D19, D20, D21: verification
|
||||
|
||||
- **Items:** `D19`, `D20`, `D21`
|
||||
- **Depends on:** T16.1 to T16.3
|
||||
- **Surface:** verification
|
||||
- **Files:** this file (verification record)
|
||||
|
||||
**Done when:**
|
||||
|
||||
- [x] `tests/security_check.py` passes
|
||||
- [x] `docs/reference/security-review/sec_probe.py`: S3 and S12 change as
|
||||
expected; every other line is unchanged
|
||||
- [x] the architecture review `equivalence_check.py` (current branch vs wave
|
||||
16) is IDENTICAL: the scenario does not use these paths, so it proves the
|
||||
rest of the work-package flow did not move
|
||||
- [x] smoke test 27/27
|
||||
- [x] the browser probes named in T16.2 and T16.3 are listed for a run on a
|
||||
machine with Edge (not available in the build sandbox)
|
||||
|
||||
## Verification record
|
||||
|
||||
Run 2026-10-02 in the build sandbox (Linux, Python 3.10, no browser), on branch
|
||||
`feat/wave-16-security` at T16.3.
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| `tests/security_check.py` | **36/36** (D21 6, D19 14, D20 16) |
|
||||
| Same check against `da1325c` with PyJWT 2.13.0 | 20/36. The 16 failures are the findings (D21 3, D19 6, D20 7). The 20 passes are the "still works" checks plus three that already held (over-long cookie 401, non-member 404, SOP move refused by the existing completed-SOP rule) |
|
||||
| `docs/reference/security-review/sec_probe.py`, before vs after | Exactly 4 of 27 lines change: S3 (new complete SOP 200 -> **400**; baseline `sop_rogue` -> **`sop__proj_a`**; QA group attacker -> **real group**) and S12 (crafted cookie 500 -> **401**). All other lines identical |
|
||||
| `equivalence_check.py` (architecture review), `da1325c` vs wave 16 | **IDENTICAL**: 78 HTTP results, 89 audit rows, 24 notifications. The scenario's SOP id was changed from `sop_eq` to the canonical `sop__proj_eq` on both sides, because D20 refuses a non-canonical id on purpose |
|
||||
| `server/smoketest.py` | **27/27** after each of T16.1, T16.2, T16.3 |
|
||||
| `server/seed_demo.py` | Seeds the demo project; its SOP lands on the canonical id |
|
||||
| `pip-audit -r server/requirements.txt` | No known vulnerabilities |
|
||||
|
||||
**Browser probes, run 2026-10-02 on Matt's machine (Windows, Edge 154,
|
||||
Python 3.12.10, `.venv`), one at a time:**
|
||||
|
||||
| Probe | Task | Result |
|
||||
|---|---|---|
|
||||
| `tests/files_check.py` | T16.2 | **36/36**, including the 1440px creator, 390px Field View, and the offline drawing cache with the server gone |
|
||||
| `tests/sample_check.py` | T16.3 | **10/10** |
|
||||
| `tests/critical_reopen_check.py` | T16.3 | **11/11**, PM + CM + assignee mail, sink-verified |
|
||||
|
||||
T16.2 and T16.3 are done.
|
||||
|
||||
**Production data check for D20, 2026-10-02.** On the production database
|
||||
(`wp_db`, psql): projects with more than one complete SOP: **0 rows**. D20 has
|
||||
no legacy duplicates to handle on deploy.
|
||||
|
||||
**Harness fix needed to get there (`tests/cdp.py`, committed with this record).**
|
||||
Every probe failed first with "browser would not start ... exited rc=0
|
||||
without binding the port". Cause: the PowerShell session was elevated, and
|
||||
Edge and Chrome de-elevate by relaunching themselves through Explorer as a
|
||||
normal user; the relaunch drops `--remote-debugging-port`. Edge's log said so
|
||||
(`Edge is running elevated: 1`). No browser policy was involved (all hives
|
||||
checked). Two changes, both inert on a normal shell and on Linux/macOS:
|
||||
`--do-not-de-elevate` on Windows, and a 15-second grace for the port when the
|
||||
launched process exits rc=0. Probe results are unchanged by it; it only lets
|
||||
the browser start.
|
||||
@@ -34,12 +34,12 @@
|
||||
/* Every container admin.js paints a table into is a scrollport of its own, so a
|
||||
sticky header always has something to stick to rather than sliding up behind
|
||||
the app bar. Same rule as console.css's .tscroll. */
|
||||
#comments-admin, #audit-admin, #notif-box, #activity-admin, #projects-table, #defmem-table{
|
||||
#comments-admin, #audit-admin, #notif-box, #usage-admin, #projects-table, #defmem-table{
|
||||
overflow:auto; max-height:min(70vh,640px); overscroll-behavior:contain; }
|
||||
/* If admin.js wraps its table in its own .tscroll, the outer box steps aside so
|
||||
one table never ends up with two scrollbars. */
|
||||
#comments-admin:has(.tscroll), #audit-admin:has(.tscroll), #notif-box:has(.tscroll),
|
||||
#activity-admin:has(.tscroll), #projects-table:has(.tscroll), #defmem-table:has(.tscroll){
|
||||
#usage-admin:has(.tscroll), #projects-table:has(.tscroll), #defmem-table:has(.tscroll){
|
||||
overflow:visible; max-height:none; }
|
||||
|
||||
/* Comment text and audit detail are the two columns you are actually here to
|
||||
@@ -53,7 +53,7 @@
|
||||
border:1px solid var(--border-strong); border-radius:0; margin-bottom:var(--s3); }
|
||||
|
||||
@media (max-width:900px){
|
||||
#comments-admin, #audit-admin, #notif-box, #activity-admin, #projects-table, #defmem-table{
|
||||
#comments-admin, #audit-admin, #notif-box, #usage-admin, #projects-table, #defmem-table{
|
||||
max-height:none; }
|
||||
}
|
||||
</style>
|
||||
@@ -175,38 +175,16 @@
|
||||
<div id="audit-admin" class="note">Click refresh to load.</div>
|
||||
</div>
|
||||
|
||||
<!-- ACTIVITY & USAGE (CR-019) -->
|
||||
<!-- USAGE LOGS -->
|
||||
<div class="card">
|
||||
<h2>Activity & usage</h2>
|
||||
<div class="sub">Who is using the suite, which tools, and how often — recorded server-side on every
|
||||
sign-in and page open, kept indefinitely. Filter below, or export a CSV: raw (real usernames) for
|
||||
internal use, or sanitized (each user replaced with a stable, non-reversible id) for feeding into
|
||||
Power BI or another external reporting tool without carrying real identities.</div>
|
||||
<h2>Usage logs</h2>
|
||||
<div class="sub">Engagement recorded by both tools — the work package creator and the SOP wizard —
|
||||
sessions, actions and counts, with a download per tool (D5). Note: stored locally per browser,
|
||||
so this reflects activity on <strong>this</strong> machine.</div>
|
||||
<div class="toolbar">
|
||||
<label for="act-from">From</label>
|
||||
<input type="date" id="act-from" onchange="loadActivity()">
|
||||
<label for="act-to">To</label>
|
||||
<input type="date" id="act-to" onchange="loadActivity()">
|
||||
<select id="act-project" onchange="loadActivity()"><option value="">All projects</option></select>
|
||||
<input id="act-user" placeholder="Username…" oninput="loadActivity()">
|
||||
<select id="act-tool" onchange="loadActivity()">
|
||||
<option value="">All tools</option>
|
||||
<option value="launcher">Launcher</option>
|
||||
<option value="wizard">SOP wizard</option>
|
||||
<option value="creator">Work package creator</option>
|
||||
<option value="field_view">Field view</option>
|
||||
<option value="admin">Admin console</option>
|
||||
<option value="directory">User directory</option>
|
||||
</select>
|
||||
<button onclick="loadActivity()">Refresh</button>
|
||||
<button onclick="loadUsage()">Refresh</button>
|
||||
</div>
|
||||
<div id="activity-banner" class="banner" style="display:none"></div>
|
||||
<div id="activity-admin" class="note">Loading…</div>
|
||||
<div class="toolbar" style="margin-top:var(--s3)">
|
||||
<button onclick="exportActivity(false)">Download CSV (raw)</button>
|
||||
<button onclick="exportActivity(true)">Download CSV (sanitized)</button>
|
||||
</div>
|
||||
<div id="activity-export-banner" class="banner" style="display:none"></div>
|
||||
<div id="usage-admin" class="note">Click refresh to load.</div>
|
||||
</div>
|
||||
|
||||
<!-- DB SNAPSHOT -->
|
||||
@@ -237,6 +215,7 @@
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script src="wp-usage.js"></script>
|
||||
<script src="console-util.js"></script>
|
||||
<script src="wp-dialog.js"></script>
|
||||
<script src="admin.js"></script>
|
||||
|
||||
141
html/admin.js
@@ -24,7 +24,7 @@ function reveal(){
|
||||
loadNotifications();
|
||||
loadComments();
|
||||
loadAudit();
|
||||
loadActivity();
|
||||
loadUsage();
|
||||
}
|
||||
function showDenied(){
|
||||
document.getElementById('admin-denied').style.display='';
|
||||
@@ -189,19 +189,6 @@ async function loadProjects(){
|
||||
banner.style.display='none';
|
||||
_adminProjects = json;
|
||||
renderProjects();
|
||||
populateActivityProjectFilter();
|
||||
}
|
||||
|
||||
// The activity project filter reuses the same project list the Projects card
|
||||
// already fetched — no second /api/projects call just to fill a <select>.
|
||||
function populateActivityProjectFilter(){
|
||||
const sel = document.getElementById('act-project');
|
||||
if(!sel) return;
|
||||
const cur = sel.value;
|
||||
sel.innerHTML = '<option value="">All projects</option>' +
|
||||
_adminProjects.slice().sort((a,b)=>String(a.name||'').localeCompare(String(b.name||'')))
|
||||
.map(p => '<option value="'+uesc(p.id)+'">'+uesc(p.name||p.number||p.id)+'</option>').join('');
|
||||
sel.value = cur;
|
||||
}
|
||||
|
||||
function renderProjects(){
|
||||
@@ -478,90 +465,6 @@ function renderAudit(){
|
||||
'</tr>').join('')+'</tbody></table>';
|
||||
}
|
||||
|
||||
// ── activity & usage (CR-019) ────────────────────────────────────────────────────
|
||||
// Server-side, per-user activity — distinct from the "Activity log" card above
|
||||
// (that's AuditLog: business mutations) and from the "Usage logs" card below
|
||||
// (that's per-browser localStorage, D5/T7.10, on the way out per T11.6). This is
|
||||
// /api/usage/summary and /api/usage/export: real rows, aggregated server-side,
|
||||
// filterable by date/project/user/tool, and exportable raw or sanitized.
|
||||
function _activityFilters(){
|
||||
const q = new URLSearchParams();
|
||||
const from = document.getElementById('act-from').value; if(from) q.set('from', from);
|
||||
const to = document.getElementById('act-to').value; if(to) q.set('to', to);
|
||||
const proj = document.getElementById('act-project').value; if(proj) q.set('project_id', proj);
|
||||
const user = (document.getElementById('act-user').value||'').trim(); if(user) q.set('username', user);
|
||||
const tool = document.getElementById('act-tool').value; if(tool) q.set('tool', tool);
|
||||
return q;
|
||||
}
|
||||
async function loadActivity(){
|
||||
const banner = document.getElementById('activity-banner');
|
||||
const box = document.getElementById('activity-admin');
|
||||
if(!box) return;
|
||||
banner.style.display='none';
|
||||
box.textContent = 'Loading…';
|
||||
const { status, json } = await api('GET', '/api/usage/summary?'+_activityFilters().toString());
|
||||
if(status===403){
|
||||
banner.className='banner bad'; banner.style.display='';
|
||||
banner.textContent = '✕ Your account can’t see suite-wide activity here — this needs admin, or Project Super User on at least one project.';
|
||||
box.innerHTML=''; return;
|
||||
}
|
||||
if(status!==200 || !json){
|
||||
banner.className='banner bad'; banner.style.display='';
|
||||
banner.textContent = '✕ Could not load activity ('+apiError(status, json, 'load failed')+').';
|
||||
box.innerHTML=''; return;
|
||||
}
|
||||
renderActivity(json);
|
||||
}
|
||||
function renderActivity(sum){
|
||||
const box = document.getElementById('activity-admin');
|
||||
if(!sum.event_count){ box.innerHTML = '<div class="note">No activity matches this filter.</div>'; return; }
|
||||
const fmt = s => s ? wpFormatDateTime(s) : '—';
|
||||
const bucket = (label, obj, take) => {
|
||||
const entries = Object.entries(obj).sort((a,b)=> b[0].localeCompare(a[0])).slice(0, take);
|
||||
if(!entries.length) return '';
|
||||
return '<table class="kv" style="margin-top:8px"><caption style="text-align:left;font-weight:600;margin-bottom:4px">'+
|
||||
uesc(label)+'</caption>'+entries.map(([k,v]) => '<tr><th>'+uesc(k)+'</th><td>'+v+' active user'+(v===1?'':'s')+'</td></tr>').join('')+
|
||||
'</table>';
|
||||
};
|
||||
const perTool = Object.entries(sum.by_tool||{});
|
||||
const toolTable = perTool.length ? '<table class="users"><thead><tr><th>Tool</th><th>Events</th></tr></thead><tbody>'+
|
||||
perTool.map(([t,n]) => '<tr><td>'+uesc(t||'(login)')+'</td><td>'+n+'</td></tr>').join('')+'</tbody></table>' :
|
||||
'<div class="note">No per-tool data.</div>';
|
||||
const perUser = Object.entries(sum.per_user_last_active||{}).sort((a,b)=> String(b[1]).localeCompare(String(a[1])));
|
||||
const userTable = perUser.length ? '<table class="users"><thead><tr><th>User</th><th>Last active</th></tr></thead><tbody>'+
|
||||
perUser.map(([u,t]) => '<tr><td><strong>'+uesc(u)+'</strong></td><td style="color:var(--muted)">'+fmt(t)+'</td></tr>').join('')+
|
||||
'</tbody></table>' : '<div class="note">No per-user data.</div>';
|
||||
box.innerHTML =
|
||||
'<div class="note">'+sum.event_count+' event'+(sum.event_count===1?'':'s')+' matched.</div>'+
|
||||
'<div class="row" style="gap:var(--s4);flex-wrap:wrap;align-items:flex-start">'+
|
||||
'<div>'+bucket('Active users by day', sum.active_users.by_day, 30)+'</div>'+
|
||||
'<div>'+bucket('Active users by week', sum.active_users.by_week, 12)+'</div>'+
|
||||
'<div>'+bucket('Active users by month', sum.active_users.by_month, 12)+'</div>'+
|
||||
'</div>'+
|
||||
'<h2 style="margin-top:16px">By tool</h2>'+toolTable+
|
||||
'<h2 style="margin-top:16px">Per-user last active</h2>'+userTable;
|
||||
}
|
||||
async function exportActivity(sanitize){
|
||||
const banner = document.getElementById('activity-export-banner');
|
||||
banner.className='banner'; banner.style.display=''; banner.textContent='Preparing export…';
|
||||
const q = _activityFilters();
|
||||
if(sanitize) q.set('sanitize', 'true');
|
||||
const { status, json } = await api('GET', '/api/usage/export?'+q.toString());
|
||||
if(status!==200 || typeof json !== 'string'){
|
||||
banner.className='banner bad';
|
||||
banner.textContent = '✕ Export failed ('+apiError(status, json, 'export failed')+').';
|
||||
return;
|
||||
}
|
||||
const blob = new Blob([json], { type:'text/csv' });
|
||||
const a = document.createElement('a');
|
||||
a.href = URL.createObjectURL(blob);
|
||||
a.download = 'usage_export_'+(sanitize?'sanitized':'raw')+'_'+new Date().toISOString().slice(0,10)+'.csv';
|
||||
document.body.appendChild(a); a.click(); a.remove();
|
||||
setTimeout(() => URL.revokeObjectURL(a.href), 1000);
|
||||
banner.className='banner ok';
|
||||
banner.textContent = '✓ Downloaded the '+(sanitize?'sanitized':'raw')+' export.';
|
||||
}
|
||||
|
||||
// ── notifications / email settings ──────────────────────────────────────────────
|
||||
let _settings = {};
|
||||
async function loadSettings(){
|
||||
@@ -753,6 +656,48 @@ async function loadNotifications(){
|
||||
'</tr>').join('')+'</tbody></table>';
|
||||
}
|
||||
|
||||
// ── usage logs (read from this browser's localStorage) ──────────────────────────
|
||||
// D5 / T7.10: the report for BOTH tools' recorded usage, in the one place an
|
||||
// operator-facing readout belongs - behind the same admin gate as this whole
|
||||
// page (gateByRole() below shows nothing else either). Data comes from
|
||||
// wp-usage.js, the single implementation; the keys predate the move, so
|
||||
// everything recorded before it is still here.
|
||||
function loadUsage(){
|
||||
const box = document.getElementById('usage-admin');
|
||||
if(!box) return;
|
||||
const tools = [
|
||||
['Work package creator', WPUsage.KEYS.creator, 'wp-iwp-usage'],
|
||||
['SOP wizard', WPUsage.KEYS.wizard, 'wp-suite-usage'],
|
||||
];
|
||||
let html = '';
|
||||
tools.forEach(([label, key, prefix]) => {
|
||||
const evs = (WPUsage.load(key).events) || [];
|
||||
html += '<h2 style="margin-top:16px">' + uesc(label) + '</h2>';
|
||||
if(!evs.length){
|
||||
html += '<div class="note">No usage recorded in this browser yet.</div>';
|
||||
return;
|
||||
}
|
||||
const byEvent = {}, sessions = new Set();
|
||||
let first = evs[0].ts, last = evs[0].ts;
|
||||
evs.forEach(e => {
|
||||
byEvent[e.event] = (byEvent[e.event]||0)+1;
|
||||
if(e.session) sessions.add(e.session);
|
||||
if(e.ts < first) first = e.ts; if(e.ts > last) last = e.ts;
|
||||
});
|
||||
const fmt = v => v ? wpFormatDateTime(v) : '—';
|
||||
html += '<table class="kv">'+
|
||||
'<tr><th>Sessions</th><td>'+sessions.size+'</td></tr>'+
|
||||
'<tr><th>Events</th><td>'+evs.length+'</td></tr>'+
|
||||
'<tr><th>Range</th><td style="font-weight:600">'+fmt(first)+' → '+fmt(last)+'</td></tr></table>';
|
||||
html += '<table class="users"><thead><tr><th>Event</th><th>Count</th></tr></thead><tbody>';
|
||||
Object.keys(byEvent).sort().forEach(k => html += '<tr><td>'+uesc(k)+'</td><td>'+byEvent[k]+'</td></tr>');
|
||||
html += '</tbody></table>';
|
||||
html += '<div class="toolbar" style="margin-top:8px"><button onclick="WPUsage.download(WPUsage.KEYS.'+
|
||||
(key === WPUsage.KEYS.creator ? 'creator' : 'wizard')+', ' + jsq(prefix) + ')">Download the full event log</button></div>';
|
||||
});
|
||||
box.innerHTML = html;
|
||||
}
|
||||
|
||||
// ── access control: admins only ─────────────────────────────────────────────────
|
||||
// auth-guard.js requires a login and sets window.WP_USER (firing 'wp-auth-ready').
|
||||
// Show the console for admins; otherwise show the "Admins only" notice.
|
||||
|
||||
@@ -60,11 +60,6 @@
|
||||
.then(function () { window.location.replace('login.html'); });
|
||||
};
|
||||
|
||||
// window.wpChangePassword used to open a change-password dialog here. Removed in
|
||||
// T10.4 (D15/D16): there is no local password to change anymore — identity is
|
||||
// Okta's job. The "Password" item that called this is gone from wp-sidenav.js
|
||||
// too.
|
||||
|
||||
// ── permissions helpers ────────────────────────────────────────────────────
|
||||
// The server enforces all of this; these are for hiding controls the signed-in
|
||||
// user can't use, so nobody clicks a button just to get a 403.
|
||||
@@ -119,46 +114,17 @@
|
||||
// Admin, Users and Sign out from the navigation drawer, and being one unbreakable
|
||||
// 412px run with an inline white-space:nowrap, it was what clipped the bar at 390px
|
||||
// and cut "Sign out" in half — F2. wp-sidenav.js now carries all of it, including
|
||||
// the item that was only here: Language & time. (Password was the other one; T10.4
|
||||
// removed it along with the rest of local auth — D15/D16.)
|
||||
// the two items that were only here: Language & time, and Password.
|
||||
//
|
||||
// Nothing replaces it. Every signed-in page mounts the drawer, so there is no page
|
||||
// left that would need a floating fallback pill.
|
||||
|
||||
// ── CR-019: usage ping ───────────────────────────────────────────────────
|
||||
// One page_open event per authenticated load, sent from exactly ONE place
|
||||
// (here) rather than from each page's own script - the shared-chrome lesson
|
||||
// S4 and the token-drift lesson S5 both taught this codebase the hard way.
|
||||
// Fire-and-forget: never blocks reveal(), never retries, never surfaces an
|
||||
// error to the person using the app - a missed usage ping is not something
|
||||
// anyone here should notice happening.
|
||||
var TOOL_BY_PAGE = {
|
||||
'index.html': 'launcher',
|
||||
'work-package-suite.html': 'wizard',
|
||||
'wp-creation-index.html': 'creator',
|
||||
'field.html': 'field_view',
|
||||
'admin.html': 'admin',
|
||||
'users.html': 'directory'
|
||||
};
|
||||
function pingUsage() {
|
||||
var page = (location.pathname.split('/').pop() || 'index.html');
|
||||
var tool = TOOL_BY_PAGE[page] || page.replace(/\.html$/, '');
|
||||
try {
|
||||
fetch('/api/usage/ping', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ tool: tool })
|
||||
}).catch(function () {});
|
||||
} catch (e) {}
|
||||
}
|
||||
|
||||
function proceed(user) {
|
||||
clearTimeout(safety);
|
||||
window.WP_USER = user;
|
||||
reveal();
|
||||
if (window.WP_USER) {
|
||||
window.wpFlags(); // start the feature-flag fetch; pages await it as needed
|
||||
pingUsage();
|
||||
try { document.dispatchEvent(new CustomEvent('wp-auth-ready', { detail: window.WP_USER })); } catch (e) {}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -31,23 +31,34 @@
|
||||
margin-bottom: 1.5rem;
|
||||
}
|
||||
.brand img { height: 36px; width: auto; }
|
||||
.brand .name { font-weight: 700; font-size: 0.95rem; color: var(--cds-text-primary); }
|
||||
h1 { font-size: 1.5rem; margin-bottom: 0.25rem; }
|
||||
.sub { color: var(--cds-text-secondary); font-size: 0.875rem; margin-bottom: 1.75rem; }
|
||||
.btn {
|
||||
display: block;
|
||||
label { display: block; font-size: 0.75rem; color: var(--cds-text-secondary); margin-bottom: 0.375rem; }
|
||||
.field { margin-bottom: 1.25rem; }
|
||||
input[type=text], input[type=password] {
|
||||
width: 100%;
|
||||
padding: 0.75rem;
|
||||
font-size: 1rem;
|
||||
background: var(--cds-field);
|
||||
border: none;
|
||||
border-bottom: 1px solid var(--cds-border-strong);
|
||||
outline: 2px solid transparent;
|
||||
outline-offset: -2px;
|
||||
}
|
||||
input:focus { outline: 2px solid var(--cds-focus); background: var(--cds-field-hover); }
|
||||
button {
|
||||
width: 100%;
|
||||
padding: 0.875rem 1rem;
|
||||
font-size: 1rem;
|
||||
font-weight: 600;
|
||||
text-align: center;
|
||||
text-decoration: none;
|
||||
color: var(--cds-text-on-color);
|
||||
background: var(--cds-button-primary);
|
||||
border: none;
|
||||
transition: background 0.15s;
|
||||
}
|
||||
.btn:hover { background: var(--cds-hover-primary); }
|
||||
.btn:focus-visible { outline: 2px solid var(--cds-focus); outline-offset: 2px; }
|
||||
button:hover:not(:disabled) { background: var(--cds-hover-primary); }
|
||||
button:disabled { background: var(--cds-disabled-02); cursor: not-allowed; }
|
||||
.error {
|
||||
display: none;
|
||||
background: var(--wp-status-error-bg);
|
||||
@@ -58,6 +69,7 @@
|
||||
margin-bottom: 1.25rem;
|
||||
}
|
||||
.error.show { display: block; }
|
||||
.foot { margin-top: 1.5rem; font-size: 0.75rem; color: var(--cds-text-helper); text-align: center; }
|
||||
.ok {
|
||||
display: none;
|
||||
background: var(--wp-status-success-bg);
|
||||
@@ -68,7 +80,15 @@
|
||||
margin-bottom: 1.25rem;
|
||||
}
|
||||
.ok.show { display: block; }
|
||||
.foot { margin-top: 1.5rem; font-size: 0.75rem; color: var(--cds-text-helper); text-align: center; }
|
||||
.note {
|
||||
font-size: 0.8125rem; color: var(--cds-text-secondary);
|
||||
background: var(--cds-layer-accent); border-left: 3px solid var(--cds-link-primary);
|
||||
padding: 0.75rem; margin-bottom: 1.25rem;
|
||||
}
|
||||
.hint { font-size: 0.75rem; color: var(--cds-text-helper); margin-top: -0.75rem; margin-bottom: 1.25rem; }
|
||||
a.link { color: var(--cds-link-primary); text-decoration: none; font-size: 0.8125rem; }
|
||||
a.link:hover { text-decoration: underline; }
|
||||
.center { text-align: center; margin-top: 1.25rem; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
@@ -79,10 +99,30 @@
|
||||
<div id="error" class="error" role="alert"></div>
|
||||
<div id="ok" class="ok" role="status"></div>
|
||||
|
||||
<h1>Sign in</h1>
|
||||
<p class="sub">Work Package Suite uses your organization's Okta sign-in. Select the
|
||||
button below and follow the prompts there.</p>
|
||||
<a id="okta-signin" class="btn" href="/api/auth/okta/login" autofocus>Sign in with Okta</a>
|
||||
<!-- SIGN IN -->
|
||||
<section id="view-login">
|
||||
<h1>Sign in</h1>
|
||||
<p class="sub">Work Package Suite</p>
|
||||
<form id="login-form" autocomplete="on">
|
||||
<div class="field">
|
||||
<label for="username">Username</label>
|
||||
<input id="username" name="username" type="text" autocomplete="username" autofocus required>
|
||||
</div>
|
||||
<div class="field">
|
||||
<label for="password">Password</label>
|
||||
<input id="password" name="password" type="password" autocomplete="current-password" required>
|
||||
</div>
|
||||
<div class="hint">Use your Windows password — the same one you use to sign in to your computer.</div>
|
||||
<button id="submit" type="submit">Sign in</button>
|
||||
</form>
|
||||
<!-- D13: there is no app password to reset. Self-service goes to Okta.
|
||||
A plain external link, not a form post — CSP sets form-action 'self'
|
||||
and does not set navigate-to, so link navigation off-origin is allowed.
|
||||
rel="noopener noreferrer" because target="_blank" without it hands the
|
||||
opened page a window.opener handle back to this one. -->
|
||||
<p class="center"><a href="https://primecontrols.okta.com/" id="forgot-link" class="link"
|
||||
target="_blank" rel="noopener noreferrer">Forgot password?</a></p>
|
||||
</section>
|
||||
|
||||
<p class="foot">Authorized use only · BTG / Pilot</p>
|
||||
</main>
|
||||
|
||||
@@ -1,15 +1,19 @@
|
||||
/* Login page logic for the Work Package Suite.
|
||||
|
||||
One action: sign in with Okta. There is no local password anymore (D15/D16,
|
||||
T10.4) — this page's only job is building the link to /api/auth/okta/login
|
||||
(carrying ?next=, if there was one) and showing a plain-language message for
|
||||
the failure states server/app.py's okta_callback() sends back here (T10.5). */
|
||||
One view. Sign in posts to /api/auth/login, the server authenticates by binding
|
||||
to the domain over LDAPS (D13), and on success sets an HttpOnly session cookie —
|
||||
not readable from here, which is the point — after which we redirect to ?next=
|
||||
or the home page. The password entered is the person's WINDOWS password.
|
||||
|
||||
There is no forgot-password flow and no reset view: the suite holds no password
|
||||
to reset. "Forgot password?" is a plain external link to Okta in login.html, so
|
||||
there is deliberately no click handler for it here — one that called
|
||||
preventDefault() would swallow the navigation. */
|
||||
(function () {
|
||||
'use strict';
|
||||
|
||||
var errorBox = document.getElementById('error');
|
||||
var okBox = document.getElementById('ok');
|
||||
var signinLink = document.getElementById('okta-signin');
|
||||
|
||||
function byId(id) { return document.getElementById(id); }
|
||||
|
||||
@@ -18,38 +22,73 @@
|
||||
errorBox.textContent = msg;
|
||||
errorBox.classList.add('show');
|
||||
}
|
||||
function clearBanners() {
|
||||
errorBox.classList.remove('show');
|
||||
okBox.classList.remove('show');
|
||||
}
|
||||
|
||||
// Same-site path only — mirrors the check server/app.py's _safe_next_path()
|
||||
// makes again on the way back, so a crafted ?next= can't become an open
|
||||
// redirect even if this client-side check were somehow bypassed.
|
||||
function safeNext() {
|
||||
// Where to go after signing in: the ?next= param if it's a safe same-site
|
||||
// path, otherwise the home page. (Reject absolute/scheme URLs to avoid an
|
||||
// open-redirect.)
|
||||
function nextTarget() {
|
||||
try {
|
||||
var next = new URLSearchParams(location.search).get('next') || '';
|
||||
if (next && next.charAt(0) === '/' && next.charAt(1) !== '/') return next;
|
||||
} catch (e) {}
|
||||
return '';
|
||||
return 'index.html';
|
||||
}
|
||||
|
||||
if (signinLink) {
|
||||
var next = safeNext();
|
||||
if (next) signinLink.href = '/api/auth/okta/login?next=' + encodeURIComponent(next);
|
||||
function postJson(url, payload) {
|
||||
return fetch(url, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(payload)
|
||||
}).then(function (r) {
|
||||
return r.json().catch(function () { return null; }).then(function (j) {
|
||||
return { status: r.status, ok: r.ok, json: j };
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
var ERROR_MESSAGES = {
|
||||
disabled: 'Your account has been disabled. Contact an administrator.',
|
||||
cancelled: 'Sign-in was not completed. Select the button below to try again.'
|
||||
};
|
||||
function detail(res, fallback) {
|
||||
var d = res && res.json && res.json.detail;
|
||||
return (typeof d === 'string' && d) ? d : fallback;
|
||||
}
|
||||
|
||||
// ── sign in ────────────────────────────────────────────────────────────────
|
||||
var form = byId('login-form');
|
||||
var submitBtn = byId('submit');
|
||||
// Guarded: an unguarded addEventListener on null would break sign-in itself if a
|
||||
// cached older login.html were served.
|
||||
if (!form || !submitBtn) return;
|
||||
form.addEventListener('submit', function (e) {
|
||||
e.preventDefault();
|
||||
clearBanners();
|
||||
var username = byId('username').value.trim();
|
||||
var password = byId('password').value;
|
||||
if (!username || !password) { showError('Enter your username and password.'); return; }
|
||||
|
||||
submitBtn.disabled = true;
|
||||
submitBtn.textContent = 'Signing in…';
|
||||
postJson('/api/auth/login', { username: username, password: password })
|
||||
.then(function (res) {
|
||||
if (res.ok) { location.replace(nextTarget()); return; }
|
||||
if (res.status === 401) showError('Invalid username or password.');
|
||||
else if (res.status === 403) showError(detail(res, 'Your account is disabled.'));
|
||||
else if (res.status === 429) showError(detail(res, 'Too many failed attempts. Try again later.'));
|
||||
// 503 means the directory is unreachable or misconfigured — OUR fault, not a
|
||||
// wrong password. Saying so stops people hunting for a password they no
|
||||
// longer have while a deploy is broken.
|
||||
else if (res.status === 503) showError(detail(res, 'Sign-in is temporarily unavailable. Contact IT.'));
|
||||
else showError(detail(res, 'Sign-in failed (HTTP ' + res.status + ').'));
|
||||
submitBtn.disabled = false;
|
||||
submitBtn.textContent = 'Sign in';
|
||||
})
|
||||
.catch(function () {
|
||||
showError('Could not reach the server. Check your connection and try again.');
|
||||
submitBtn.disabled = false;
|
||||
submitBtn.textContent = 'Sign in';
|
||||
});
|
||||
});
|
||||
|
||||
(function showErrorFromQuery() {
|
||||
try {
|
||||
var code = new URLSearchParams(location.search).get('error') || '';
|
||||
if (!code) return;
|
||||
showError(ERROR_MESSAGES[code] || 'Sign-in was not completed. Select the button below to try again.');
|
||||
// Out of the address bar once shown — an error code has no reason to
|
||||
// survive a refresh or get copied along with the link.
|
||||
var url = new URL(location.href);
|
||||
url.searchParams.delete('error');
|
||||
history.replaceState(null, '', url.pathname + url.search);
|
||||
} catch (e) {}
|
||||
})();
|
||||
})();
|
||||
|
||||
@@ -245,63 +245,25 @@
|
||||
// local cache still updates immediately, so rendering never waits on the network.
|
||||
var OUTBOX_KEY = 'wp_sync_outbox_v1';
|
||||
var _flushTimer = null, _backoff = 0, _flushing = false;
|
||||
// D26. `_held` is set when the server answers 401: the session ended, so the
|
||||
// queue waits for a good sign-in. It is cleared ONLY by `wp-auth-ready` (a page
|
||||
// load with a good session check), never by the online event, the timer or tab
|
||||
// focus, because none of those prove the session is back.
|
||||
var _held = false;
|
||||
// D26. Changes the device could not store (localStorage full) stay here, in page
|
||||
// memory, and are still sent. They are lost if the page closes, so the badge says
|
||||
// they are not saved on this device. They are never dropped without a word.
|
||||
var _mem = [];
|
||||
var _deviceFull = false;
|
||||
|
||||
function qRead() { try { return JSON.parse(localStorage.getItem(OUTBOX_KEY) || '[]') || []; } catch (e) { return []; } }
|
||||
// Returns true when the list is stored. A storage error used to be swallowed here,
|
||||
// so a full device lost the change and nobody knew (D26, fault 2).
|
||||
function qWrite(list) {
|
||||
try { localStorage.setItem(OUTBOX_KEY, JSON.stringify(list)); return true; }
|
||||
catch (e) { return false; }
|
||||
}
|
||||
// Stored ops plus any held only in memory, stored ones first (send order).
|
||||
function qAll() {
|
||||
var q = qRead();
|
||||
if (!_mem.length) return q;
|
||||
var ids = {};
|
||||
q.forEach(function (o) { ids[o.opId] = true; });
|
||||
return q.concat(_mem.filter(function (o) { return !ids[o.opId]; }));
|
||||
}
|
||||
// Remove one op everywhere it can be held.
|
||||
function qDrop(opId) {
|
||||
_mem = _mem.filter(function (o) { return o.opId !== opId; });
|
||||
qWrite(qRead().filter(function (o) { return o.opId !== opId; }));
|
||||
}
|
||||
function sameUser(a, b) { return String(a || '').toLowerCase() === String(b || '').toLowerCase(); }
|
||||
function qWrite(list) { try { localStorage.setItem(OUTBOX_KEY, JSON.stringify(list)); } catch (e) {} }
|
||||
|
||||
// Append an op, coalescing by (kind,key) so only the latest write per entity is
|
||||
// queued. A delete supersedes any pending upsert for the same id. Returns true
|
||||
// when the change is stored on this device, false when it is only in memory.
|
||||
// queued. A delete supersedes any pending upsert for the same id.
|
||||
function enqueue(op) {
|
||||
var supersedes = (op.kind === 'wp-del')
|
||||
? function (o) { return o.key === op.key && (o.kind === 'wp' || o.kind === 'wp-del'); }
|
||||
: function (o) { return o.kind === op.kind && o.key === op.key; };
|
||||
var q = qRead().filter(function (o) { return !supersedes(o); });
|
||||
_mem = _mem.filter(function (o) { return !supersedes(o); });
|
||||
var q = qRead();
|
||||
if (op.kind === 'wp-del') {
|
||||
q = q.filter(function (o) { return !(o.key === op.key && (o.kind === 'wp' || o.kind === 'wp-del')); });
|
||||
} else {
|
||||
q = q.filter(function (o) { return !(o.kind === op.kind && o.key === op.key); });
|
||||
}
|
||||
op.opId = op.kind + ':' + op.key + ':' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
|
||||
op.tries = 0;
|
||||
op.owner = currentUser(); // D26: sent only when this person is signed in
|
||||
q.push(op);
|
||||
var stored = qWrite(q);
|
||||
if (stored) {
|
||||
// Room again: bring anything held in memory onto the device.
|
||||
if (_mem.length && qWrite(q.concat(_mem))) _mem = [];
|
||||
_deviceFull = _mem.length > 0;
|
||||
} else {
|
||||
_mem.push(op); _deviceFull = true;
|
||||
}
|
||||
qWrite(q);
|
||||
notifySync();
|
||||
scheduleFlush(0);
|
||||
return stored;
|
||||
}
|
||||
|
||||
function opRequest(op) {
|
||||
@@ -313,63 +275,41 @@
|
||||
});
|
||||
}
|
||||
|
||||
// Apply `fn` to the op with this id, wherever it is held (device or memory).
|
||||
function patchOp(opId, fn) {
|
||||
var q = qRead(), hit = false;
|
||||
for (var i = 0; i < q.length; i++) { if (q[i].opId === opId) { fn(q[i]); hit = true; break; } }
|
||||
if (hit) qWrite(q);
|
||||
for (var j = 0; j < _mem.length; j++) { if (_mem[j].opId === opId) { fn(_mem[j]); break; } }
|
||||
}
|
||||
function bumpTries(opId, err) {
|
||||
patchOp(opId, function (o) { o.tries = (o.tries || 0) + 1; o.lastErr = err; });
|
||||
var q = qRead();
|
||||
for (var i = 0; i < q.length; i++) { if (q[i].opId === opId) { q[i].tries = (q[i].tries || 0) + 1; q[i].lastErr = err; break; } }
|
||||
qWrite(q);
|
||||
}
|
||||
// Permanently-failed op (a 4xx client error) — keep it for visibility but stop
|
||||
// retrying, so a rejected write can't loop forever. `err` is the server's own
|
||||
// explanation when it sent one; it is what the sync badge shows the user.
|
||||
function markDead(opId, err) {
|
||||
patchOp(opId, function (o) { o.dead = true; o.lastErr = err; });
|
||||
var q = qRead();
|
||||
for (var i = 0; i < q.length; i++) { if (q[i].opId === opId) { q[i].dead = true; q[i].lastErr = err; break; } }
|
||||
qWrite(q);
|
||||
}
|
||||
|
||||
// True when this op is waiting for another person to sign in (D26). An op with no
|
||||
// owner (queued before the sign-in check finished) can be sent by anyone, which is
|
||||
// what every op did before owners existed.
|
||||
function foreignOp(o) {
|
||||
var me = currentUser();
|
||||
return !!o.owner && !sameUser(o.owner, me);
|
||||
}
|
||||
function liveOps() { return qAll().filter(function (o) { return !o.dead; }); }
|
||||
function sendableOps() { return liveOps().filter(function (o) { return !foreignOp(o); }); }
|
||||
|
||||
// Attempt every live op that belongs to the signed-in person; successes are
|
||||
// removed. A 401 HOLDS the queue (D26): the session ended, which says nothing
|
||||
// about the changes, so nothing is marked dead and no try is counted. A 403 or
|
||||
// other 4xx is marked dead (it will not succeed on retry); transient failures
|
||||
// (429/5xx/network) stay queued.
|
||||
// Attempt every live op; successes are removed, 4xx client errors are marked
|
||||
// dead (won't succeed on retry), transient failures (429/5xx/network) stay queued.
|
||||
function flush() {
|
||||
if (_flushing) return Promise.resolve();
|
||||
if (_held) { notifySync(); return Promise.resolve(); }
|
||||
var q = sendableOps();
|
||||
var q = qRead().filter(function (o) { return !o.dead; });
|
||||
if (!q.length) { notifySync(); return Promise.resolve(); }
|
||||
_flushing = true; notifySync();
|
||||
var chain = Promise.resolve(), anyFail = false, halted = false;
|
||||
var chain = Promise.resolve(), anyFail = false;
|
||||
q.forEach(function (op) {
|
||||
chain = chain.then(function () {
|
||||
if (halted) return; // a 401 stops the run; later ops keep their place
|
||||
return opRequest(op).then(function (r) {
|
||||
var status = r ? r.status : 0;
|
||||
var done = r && (r.ok || (op.kind === 'wp-del' && status === 404)); // 404 on delete = already gone
|
||||
if (done) { qDrop(op.opId); }
|
||||
else if (status === 401) { halted = true; _held = true; }
|
||||
if (done) { qWrite(qRead().filter(function (o) { return o.opId !== op.opId; })); }
|
||||
else if (status >= 400 && status < 500 && status !== 429) {
|
||||
// Refused once, refused forever — so the only useful thing left is the
|
||||
// reason. A 409 here is the archived-project gate, whose detail tells
|
||||
// the user the project is read-only and how to get it unarchived; a
|
||||
// bare "HTTP 409" would leave them staring at a change that vanished.
|
||||
return r.json().catch(function () { return null; }).then(function (j) {
|
||||
var detail = (j && typeof j.detail === 'string' && j.detail) || '';
|
||||
var why = status === 403
|
||||
? 'You no longer have access to this project.' + (detail ? ' (' + detail + ')' : '')
|
||||
: (detail || ('HTTP ' + status));
|
||||
var why = (j && typeof j.detail === 'string' && j.detail) || ('HTTP ' + status);
|
||||
markDead(op.opId, why);
|
||||
});
|
||||
}
|
||||
@@ -380,8 +320,7 @@
|
||||
return chain.then(function () {
|
||||
_flushing = false;
|
||||
notifySync();
|
||||
if (_held) return; // wait for wp-auth-ready; no timer retries a dead session
|
||||
if (sendableOps().length) {
|
||||
if (qRead().filter(function (o) { return !o.dead; }).length) {
|
||||
_backoff = anyFail ? Math.min((_backoff || 5000) * 2, 60000) : 0;
|
||||
scheduleFlush(_backoff || 15000);
|
||||
} else { _backoff = 0; }
|
||||
@@ -397,21 +336,14 @@
|
||||
// `failed` stays the total not-getting-through count (what listeners already
|
||||
// read); `dead` splits out the ops the server has permanently refused, with the
|
||||
// first reason it gave, because those two states need different words.
|
||||
// D26 adds: `held` (the session ended; the queue waits for a sign-in), `others`
|
||||
// and `otherOwner` (changes that belong to someone else, waiting for them),
|
||||
// `deviceFull` and `unsaved` (changes that exist only in page memory).
|
||||
function syncCounts() {
|
||||
var q = qAll(), pending = 0, failed = 0, dead = 0, reason = '', others = 0, otherOwner = '';
|
||||
var q = qRead(), pending = 0, failed = 0, dead = 0, reason = '';
|
||||
for (var i = 0; i < q.length; i++) {
|
||||
if (q[i].dead) { dead++; if (!reason && q[i].lastErr) reason = String(q[i].lastErr); }
|
||||
else if (foreignOp(q[i])) { others++; if (!otherOwner) otherOwner = String(q[i].owner); }
|
||||
else if ((q[i].tries || 0) >= 3) failed++;
|
||||
else pending++;
|
||||
}
|
||||
return {
|
||||
pending: pending, failed: failed + dead, dead: dead, reason: reason, syncing: _flushing,
|
||||
held: _held, others: others, otherOwner: otherOwner, deviceFull: _deviceFull, unsaved: _mem.length
|
||||
};
|
||||
return { pending: pending, failed: failed + dead, dead: dead, reason: reason, syncing: _flushing };
|
||||
}
|
||||
ProjectData.syncStatus = syncCounts;
|
||||
function notifySync() {
|
||||
@@ -463,15 +395,7 @@
|
||||
// Every string here now names the project explicitly. The draft indicator
|
||||
// (WPAutosave.mountIndicator) is the one that speaks for the form, and the two
|
||||
// can no longer be read as each other.
|
||||
// D26. These three are the states that used to be invisible or wrong. T14.3
|
||||
// gives them their final wording and controls; until then they are plain text.
|
||||
if (c.deviceFull) {
|
||||
el.textContent = '✕ ' + c.unsaved + ' change' + (c.unsaved === 1 ? ' is' : 's are') + ' not saved on this device. Keep this page open until it is sent to the project.';
|
||||
el.style.color = 'var(--wp-status-error-text)'; el.style.borderColor = 'var(--wp-status-error-border-a)'; el.style.background = 'var(--wp-status-error-bg)'; el.style.display = 'inline-flex';
|
||||
} else if (c.held) {
|
||||
el.textContent = '⚠ Sign in again to send your changes to the project. They are kept on this device.';
|
||||
el.style.color = 'var(--wp-status-warning-text)'; el.style.borderColor = 'var(--cds-support-warning)'; el.style.background = 'var(--wp-status-warning-bg)'; el.style.display = 'inline-flex';
|
||||
} else if (c.dead) {
|
||||
if (c.dead) {
|
||||
el.innerHTML = '<span>✕ ' + c.dead + ' change' + (c.dead === 1 ? '' : 's') + ' rejected by the project — not saved</span>' +
|
||||
(c.reason ? '<span style="font-weight:400">' + esc(c.reason) + '</span>' : '');
|
||||
el.style.color = 'var(--wp-status-error-text)'; el.style.borderColor = 'var(--wp-status-error-border-a)'; el.style.background = 'var(--wp-status-error-bg)'; el.style.display = 'inline-flex';
|
||||
@@ -481,9 +405,6 @@
|
||||
} else if (c.pending) {
|
||||
el.textContent = '↻ Sending ' + c.pending + ' change' + (c.pending === 1 ? '' : 's') + ' to the project…';
|
||||
el.style.color = 'var(--cds-text-secondary)'; el.style.borderColor = 'var(--cds-border-subtle)'; el.style.background = 'var(--cds-layer)'; el.style.display = 'inline-flex';
|
||||
} else if (c.others) {
|
||||
el.textContent = '⚠ ' + c.others + ' change' + (c.others === 1 ? ' belongs' : 's belong') + ' to ' + c.otherOwner + '. ' + (c.others === 1 ? 'It goes' : 'They go') + ' to the project when ' + c.otherOwner + ' signs in.';
|
||||
el.style.color = 'var(--wp-status-warning-text)'; el.style.borderColor = 'var(--cds-support-warning)'; el.style.background = 'var(--wp-status-warning-bg)'; el.style.display = 'inline-flex';
|
||||
} else {
|
||||
el.textContent = '✓ Everything sent to the project';
|
||||
el.style.color = 'var(--wp-status-success-text)'; el.style.borderColor = 'var(--wp-status-success-border-a)'; el.style.background = 'var(--wp-status-success-bg)'; el.style.display = 'inline-flex';
|
||||
@@ -497,11 +418,7 @@
|
||||
window.addEventListener('online', function () { _backoff = 0; scheduleFlush(0); });
|
||||
window.addEventListener('storage', function (e) { if (e.key === OUTBOX_KEY) { notifySync(); scheduleFlush(0); } });
|
||||
document.addEventListener('visibilitychange', function () { if (!document.hidden) scheduleFlush(0); });
|
||||
setInterval(function () { if (sendableOps().length) scheduleFlush(0); }, 20000);
|
||||
// D26: the one thing that releases a held queue. auth-guard fires this after a
|
||||
// good /api/auth/me (or the offline cache), and the next flush finds out for
|
||||
// itself whether the session is really good: a 401 holds the queue again.
|
||||
document.addEventListener('wp-auth-ready', function () { _held = false; _backoff = 0; notifySync(); scheduleFlush(0); });
|
||||
setInterval(function () { if (qRead().filter(function (o) { return !o.dead; }).length) scheduleFlush(0); }, 20000);
|
||||
} catch (e) {}
|
||||
if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', function () { notifySync(); scheduleFlush(0); }); }
|
||||
else { setTimeout(function () { notifySync(); scheduleFlush(0); }, 0); }
|
||||
@@ -511,7 +428,7 @@
|
||||
// project so re-completing updates the same row.
|
||||
ProjectData.pushSOP = function (projectId, sop, state) {
|
||||
if (!projectId) return Promise.resolve(null);
|
||||
return Promise.resolve(enqueue({
|
||||
enqueue({
|
||||
kind: 'sop', key: 'sop__' + projectId,
|
||||
body: {
|
||||
id: 'sop__' + projectId, project_id: projectId,
|
||||
@@ -519,21 +436,22 @@
|
||||
number: (sop && sop.project && sop.project.number) || '',
|
||||
complete: true, created_by: currentUser(), data: { sop: sop, state: state }
|
||||
}
|
||||
}));
|
||||
});
|
||||
return Promise.resolve(true);
|
||||
};
|
||||
|
||||
// Upsert a single Work Package. The local cache stays the source of truth for
|
||||
// immediate rendering; the outbox guarantees the write reaches the server.
|
||||
ProjectData.pushWP = function (p, projectId) {
|
||||
if (!p || !p.id) return Promise.resolve(null);
|
||||
// D26: resolves false when the device could not store the change (it is still
|
||||
// sent from memory, but it is lost if the page closes first).
|
||||
return Promise.resolve(enqueue({ kind: 'wp', key: p.id, body: pkgToServer(p, projectId) }));
|
||||
enqueue({ kind: 'wp', key: p.id, body: pkgToServer(p, projectId) });
|
||||
return Promise.resolve(true);
|
||||
};
|
||||
|
||||
ProjectData.removeWP = function (id) {
|
||||
if (!id) return Promise.resolve();
|
||||
return Promise.resolve(enqueue({ kind: 'wp-del', key: id }));
|
||||
enqueue({ kind: 'wp-del', key: id });
|
||||
return Promise.resolve(true);
|
||||
};
|
||||
|
||||
// Force a flush now and resolve when the queue drains (or a round-trip is done).
|
||||
|
||||
@@ -24,11 +24,10 @@
|
||||
The directory is one wide table, so the column exceptions live here: email is
|
||||
the one cell long enough to stretch a row, and the two role dropdowns need
|
||||
room for "Assistant Project Manager" without pushing Actions off screen. */
|
||||
/* The email cell, by its class: CR-020's selection column moved it from third to
|
||||
fourth on the managers' table, and a position-based rule would have followed
|
||||
the wrong column. */
|
||||
#users-table table td.ell{ max-width:230px; overflow:hidden; text-overflow:ellipsis; }
|
||||
#users-table table td:nth-child(3){ max-width:230px; overflow:hidden; text-overflow:ellipsis; }
|
||||
#users-banner:not(:empty), #scope-banner:not(:empty){ margin-bottom:var(--s3); }
|
||||
/* The create form is a lot of fields; let them wrap and
|
||||
let the project picker take a full row of its own. */
|
||||
#nu-projects{ margin-top:var(--s2); }
|
||||
#nu-projects .pickrow{ padding:var(--s1) var(--s1); }
|
||||
/* A manager with one project doesn't need a scrolling picker; a manager with
|
||||
@@ -36,45 +35,6 @@
|
||||
#nu-project-list{ max-height:200px; overflow:auto; border:1px solid var(--border); }
|
||||
.whoami-chip{ font-size:12px; color:var(--muted); }
|
||||
.whoami-chip strong{ color:var(--text); }
|
||||
|
||||
/* CR-020: row selection and the bulk bar. Tokens only (the token rule). */
|
||||
#sel-banner:not(:empty), #bulk-banner:not(:empty), #csv-banner:not(:empty){ margin-bottom:var(--s3); }
|
||||
#bulk-banner ul, #csv-banner ul{ margin:var(--s1) 0 0; padding-left:var(--s5); font-weight:400;
|
||||
max-height:220px; overflow:auto; }
|
||||
#csv-btn[hidden]{ display:none; }
|
||||
table.grid th.selcell, table.grid td.selcell{ width:1%; padding:0 var(--s1); text-align:center; }
|
||||
/* The label is the hit area: the 16px box alone is under the 24px floor. */
|
||||
.selhit{ display:inline-flex; align-items:center; justify-content:center;
|
||||
min-width:28px; min-height:28px; cursor:pointer; }
|
||||
.selhit input{ width:16px; height:16px; margin:0; accent-color:var(--accent); cursor:pointer; }
|
||||
.selhit input:focus-visible{ outline:2px solid var(--accent); outline-offset:2px; }
|
||||
.selhit input:disabled{ cursor:default; }
|
||||
/* Not --accent-soft: that is the admin pill's own fill (console.css, hover note). */
|
||||
table.grid tbody tr.is-selected td{ background:var(--cds-layer-selected); }
|
||||
table.grid tbody tr.is-selected td.selcell{ box-shadow:inset 3px 0 0 var(--accent); }
|
||||
.bulkbar{ border:1px solid var(--accent); border-left:3px solid var(--accent);
|
||||
background:var(--surface); padding:var(--s2) var(--s3); margin:0 0 var(--s3); }
|
||||
.bulkbar[hidden]{ display:none; }
|
||||
.bulkhead{ display:flex; align-items:center; justify-content:space-between; gap:var(--s2);
|
||||
flex-wrap:wrap; margin-bottom:var(--s2); }
|
||||
.bulkgroup{ display:flex; flex-wrap:wrap; align-items:center; gap:var(--s2);
|
||||
padding:var(--s2) 0; border-top:1px solid var(--border); }
|
||||
.bulkgroup > .bulklabel{ font-size:12px; font-weight:600; color:var(--muted); min-width:110px; }
|
||||
.bulkgroup select{ height:var(--ctl); padding:0 var(--s1) 0 var(--s2); font:inherit; font-size:13px;
|
||||
border:1px solid var(--border-strong); border-radius:0; background:var(--surface); color:var(--text);
|
||||
max-width:100%; }
|
||||
.bulkgroup select:focus-visible{ outline:2px solid var(--accent); outline-offset:-2px; }
|
||||
/* The bulk delete dialog lists every affected username; a long list scrolls
|
||||
inside the dialog instead of pushing its buttons off the screen. */
|
||||
#wp-dlg-msg{ max-height:50vh; overflow:auto; }
|
||||
@media (max-width:620px){
|
||||
.bulkgroup > .bulklabel{ min-width:0; flex:1 1 100%; }
|
||||
.bulkgroup select, .bulkgroup button{ flex:1 1 100%; }
|
||||
}
|
||||
@media (pointer:coarse){
|
||||
.selhit{ min-width:44px; min-height:44px; }
|
||||
.bulkbar button, .bulkgroup select{ min-height:44px; }
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
@@ -105,33 +65,15 @@
|
||||
<div class="sub" id="people-sub"></div>
|
||||
<div class="toolbar">
|
||||
<button onclick="loadUsers()">Refresh</button>
|
||||
<input id="user-search" placeholder="Search name / username / email / job function…" oninput="filterChanged()"
|
||||
aria-label="Search the directory">
|
||||
<select id="user-filter" onchange="filterChanged()" aria-label="Show">
|
||||
<input id="user-search" placeholder="Search name / username / email / job function…" oninput="renderUsers()">
|
||||
<select id="user-filter" onchange="renderUsers()">
|
||||
<option value="">Everyone</option>
|
||||
<option value="active">Active only</option>
|
||||
<option value="disabled">Disabled only</option>
|
||||
<option value="mine">Accounts I manage</option>
|
||||
</select>
|
||||
<!-- CR-020 (T12.4): a list of usernames from a file becomes the selection.
|
||||
Managers only; users.js shows it. -->
|
||||
<button type="button" id="csv-btn" onclick="pickCsv()" hidden
|
||||
title="A CSV with one username (or email) per line, first column. The action is chosen in the bulk bar.">Select from CSV…</button>
|
||||
<input type="file" id="csv-file" accept=".csv,.txt,text/csv,text/plain" hidden>
|
||||
</div>
|
||||
<div id="users-banner"></div>
|
||||
<div id="csv-banner"></div>
|
||||
<!-- CR-020: bulk actions on the selected rows. Present only while at least one
|
||||
row is selected (the hidden attribute also takes it out of the tab order). -->
|
||||
<div id="bulk-bar" class="bulkbar" role="region" aria-label="Bulk actions on the selected users" hidden>
|
||||
<div class="bulkhead">
|
||||
<strong id="bulk-count">0 selected</strong>
|
||||
<button type="button" onclick="clearSelection(true)">Clear selection</button>
|
||||
</div>
|
||||
<div id="bulk-actions"></div>
|
||||
</div>
|
||||
<div id="sel-banner"></div>
|
||||
<div id="bulk-banner"></div>
|
||||
<div id="users-table"><div class="note">Loading…</div></div>
|
||||
</div>
|
||||
|
||||
@@ -140,8 +82,7 @@
|
||||
<h2>Add a user</h2>
|
||||
<div class="sub" id="create-sub"></div>
|
||||
<div class="urow">
|
||||
<input id="nu-username" placeholder="Username *" autocomplete="off"
|
||||
title="Must exactly match this person's Okta sign-in identity — that's how their first Okta sign-in finds this account instead of creating a second one.">
|
||||
<input id="nu-username" placeholder="Username *" autocomplete="off">
|
||||
<input id="nu-fullname" placeholder="Full name" autocomplete="off">
|
||||
<input id="nu-email" placeholder="Email" autocomplete="off">
|
||||
<select id="nu-role" title="Permissions — what this account may do"></select>
|
||||
|
||||
323
html/users.js
@@ -23,10 +23,6 @@
|
||||
let _users = []; // the directory as the server scoped it
|
||||
let _scope = null; // GET /api/auth/user-scope
|
||||
let _meId = null;
|
||||
// CR-020: the rows checked for a bulk action. Client-side UI state only - every
|
||||
// bulk action is decided and audited by the server, row by row (T12.1).
|
||||
let _selected = new Set();
|
||||
let _shownSelectable = []; // ids the current filter shows AND this caller may select
|
||||
|
||||
// ── boot ──────────────────────────────────────────────────────────────────────
|
||||
async function boot(){
|
||||
@@ -44,7 +40,6 @@ async function boot(){
|
||||
renderScope();
|
||||
}
|
||||
renderCreateForm();
|
||||
renderBulkActions();
|
||||
loadUsers();
|
||||
}
|
||||
|
||||
@@ -95,309 +90,11 @@ async function loadUsers(){
|
||||
}
|
||||
banner('users-banner','', '');
|
||||
_users = json;
|
||||
// Fresh data: any earlier selection may name accounts that changed or are gone.
|
||||
clearSelection(false);
|
||||
renderUsers();
|
||||
}
|
||||
|
||||
function manages(){ return !!(_scope && _scope.can_manage_users); }
|
||||
|
||||
// ── selection (CR-020, T12.2) ─────────────────────────────────────────────────
|
||||
// A row is selectable when this caller may change the account. Your own row is
|
||||
// not: every bulk action that could touch it (disable, demote, delete) is refused
|
||||
// for your own account, so offering it would only produce a guaranteed failure.
|
||||
function selectable(u){ return manages() && !!u.manageable && u.id !== _meId; }
|
||||
|
||||
// The search box and the filter both decide which rows are shown. Changing either
|
||||
// clears the selection (decided 2026-10-06), so no row hidden by the filter can
|
||||
// stay selected and be acted on without being seen.
|
||||
function filterChanged(){
|
||||
const had = _selected.size;
|
||||
clearSelection(false);
|
||||
renderUsers();
|
||||
banner('sel-banner', '', had ? 'Selection cleared: the filter changed. Select the rows again.' : '');
|
||||
}
|
||||
|
||||
function clearSelection(announce){
|
||||
const had = _selected.size;
|
||||
_selected = new Set();
|
||||
updateSelectionUI();
|
||||
banner('sel-banner', '', (announce && had) ? 'Selection cleared.' : '');
|
||||
}
|
||||
|
||||
function setRowSelected(id, on){
|
||||
if(on) _selected.add(id); else _selected.delete(id);
|
||||
}
|
||||
|
||||
// Select-all acts on the rows the filter shows, never on the whole directory.
|
||||
function toggleSelectAll(on){
|
||||
_shownSelectable.forEach(id => setRowSelected(id, on));
|
||||
banner('sel-banner', '', '');
|
||||
updateSelectionUI();
|
||||
}
|
||||
|
||||
// Reflect _selected into the page without re-rendering the table, so keyboard
|
||||
// focus stays on the checkbox that was just used.
|
||||
function updateSelectionUI(){
|
||||
const wrap = document.getElementById('users-table');
|
||||
if(wrap){
|
||||
wrap.querySelectorAll('input.selbox').forEach(cb => {
|
||||
const on = _selected.has(cb.dataset.id);
|
||||
cb.checked = on;
|
||||
const tr = cb.closest('tr');
|
||||
if(tr) tr.classList.toggle('is-selected', on);
|
||||
});
|
||||
const all = document.getElementById('sel-all');
|
||||
if(all){
|
||||
const n = _shownSelectable.filter(id => _selected.has(id)).length;
|
||||
all.checked = n > 0 && n === _shownSelectable.length;
|
||||
all.indeterminate = n > 0 && n < _shownSelectable.length;
|
||||
all.disabled = !_shownSelectable.length;
|
||||
}
|
||||
}
|
||||
const bar = document.getElementById('bulk-bar');
|
||||
if(bar){
|
||||
const n = _selected.size;
|
||||
bar.hidden = n === 0;
|
||||
const c = document.getElementById('bulk-count');
|
||||
if(c) c.textContent = n + ' selected';
|
||||
}
|
||||
}
|
||||
|
||||
// One listener for every checkbox in the table (event delegation): no ids are
|
||||
// bound into inline handlers, so there is nothing to escape.
|
||||
document.addEventListener('change', e => {
|
||||
const t = e.target;
|
||||
if(!(t instanceof HTMLInputElement)) return;
|
||||
if(t.id === 'sel-all'){ toggleSelectAll(t.checked); return; }
|
||||
if(t.classList.contains('selbox')){
|
||||
setRowSelected(t.dataset.id, t.checked);
|
||||
banner('sel-banner', '', '');
|
||||
updateSelectionUI();
|
||||
}
|
||||
});
|
||||
|
||||
// ── bulk actions (CR-020, T12.3) ──────────────────────────────────────────────
|
||||
// The toolbar offers only what this caller may do: the roles they may grant, the
|
||||
// projects they administer, the per-project roles they may hand out. The server
|
||||
// re-checks every row anyway (T12.1); this is so nobody is offered a choice that
|
||||
// can only fail.
|
||||
function renderBulkActions(){
|
||||
const box = document.getElementById('bulk-actions');
|
||||
const csvBtn = document.getElementById('csv-btn');
|
||||
if(csvBtn) csvBtn.hidden = !manages();
|
||||
if(!box || !manages()) return;
|
||||
const grantable = PERM_ROLES.filter(r => (_scope.grantable_roles || []).indexOf(r) >= 0);
|
||||
const projects = (_scope.managed_projects || []).slice()
|
||||
.sort((a,b) => (a.archived?1:0) - (b.archived?1:0));
|
||||
const projRoles = PROJECT_SCOPED_ROLES.filter(r => (_scope.grantable_project_roles || []).indexOf(r) >= 0);
|
||||
const group = (label, inner) => '<div class="bulkgroup" role="group" aria-label="'+uesc(label)+'">'+
|
||||
'<span class="bulklabel">'+uesc(label)+'</span>'+inner+'</div>';
|
||||
box.innerHTML =
|
||||
group('Permissions',
|
||||
'<select id="bulk-role" aria-label="New permissions role">'+
|
||||
grantable.map(r => '<option value="'+r+'"'+(r==='project_user'?' selected':'')+'>'+uesc(PERM_LABELS[r])+'</option>').join('')+
|
||||
'</select>'+
|
||||
'<button type="button" onclick="bulkRole()">Set permissions</button>') +
|
||||
group('Sign-in',
|
||||
'<button type="button" onclick="bulkActive(true)">Enable</button>'+
|
||||
'<button type="button" onclick="bulkActive(false)">Disable</button>') +
|
||||
(projects.length ? group('Project access',
|
||||
'<select id="bulk-project" aria-label="Project">'+
|
||||
projects.map(p => '<option value="'+uesc(p.id)+'">'+uesc((p.name||'(unnamed)')+(p.number?' '+p.number:'')+
|
||||
(p.archived?' (archived)':''))+'</option>').join('')+
|
||||
'</select>'+
|
||||
'<select id="bulk-project-role" aria-label="Role on that project, for Add">'+
|
||||
'<option value="">Role: same as account</option>'+
|
||||
projRoles.map(r => '<option value="'+r+'">Role: '+uesc(PERM_LABELS[r])+' here</option>').join('')+
|
||||
'</select>'+
|
||||
'<button type="button" onclick="bulkProject(\'add\')">Add to project</button>'+
|
||||
'<button type="button" onclick="bulkProject(\'remove\')">Remove from project</button>') : '') +
|
||||
group('Delete',
|
||||
'<button type="button" class="danger" onclick="bulkDelete()">Delete selected…</button>');
|
||||
}
|
||||
|
||||
function selectedIds(){ return _users.filter(u => _selected.has(u.id)).map(u => u.id); }
|
||||
function people(n){ return n + ' user' + (n === 1 ? '' : 's'); }
|
||||
function selVal(id){ return (document.getElementById(id) || {}).value || ''; }
|
||||
function selText(id){
|
||||
const s = document.getElementById(id);
|
||||
return (s && s.selectedIndex >= 0) ? s.options[s.selectedIndex].text : '';
|
||||
}
|
||||
|
||||
// One path for every bulk action: confirm through the dialog kit with the exact
|
||||
// count, send, report row by row, reload. A reload clears the selection, which is
|
||||
// right: the rows may have changed underneath it.
|
||||
async function runBulk(path, body, ask){
|
||||
const ids = selectedIds();
|
||||
if(!ids.length) return;
|
||||
if(!(await wpConfirmDialog({title: ask.title, okLabel: ask.ok, message: ask.message(ids.length)}))) return;
|
||||
return sendBulk(path, body, ask.title, ids);
|
||||
}
|
||||
|
||||
async function sendBulk(path, body, title, ids){
|
||||
bannerHtml('bulk-banner', '', uesc(title)+': working on '+uesc(people(ids.length))+'…');
|
||||
const { status, json } = await api('POST', path, Object.assign({ user_ids: ids }, body));
|
||||
if(status !== 200 || !json || !Array.isArray(json.results)){
|
||||
bannerHtml('bulk-banner', 'bad', '✕ '+uesc(apiError(status, json, title+' failed'))+' Nothing was changed.');
|
||||
return;
|
||||
}
|
||||
showBulkResult(json, title);
|
||||
loadUsers();
|
||||
}
|
||||
|
||||
// T12.5: delete is permanent (a hard delete, as for one account) and one bad
|
||||
// multi-select now removes many, so it asks more than the other actions do:
|
||||
// every affected username is listed, and nothing is sent until the word DELETE
|
||||
// is typed, whatever the count (confirmed 2026-10-06). Your own account cannot
|
||||
// be selected; if it ever reached the request, the server refuses that row and
|
||||
// the report names it.
|
||||
async function bulkDelete(){
|
||||
const chosen = _users.filter(u => _selected.has(u.id));
|
||||
if(!chosen.length) return;
|
||||
const n = chosen.length;
|
||||
const typed = await wpPromptDialog({
|
||||
title: 'Delete '+people(n),
|
||||
message: 'Delete '+(n === 1 ? 'this account' : 'these '+n+' accounts')+'? Each one, and every project '+
|
||||
'assignment it has, is removed. This cannot be undone. Disable them instead if you only want to '+
|
||||
'block sign-in.\n\n'+chosen.map(u => '• '+u.username+(u.full_name ? ' ('+u.full_name+')' : '')).join('\n'),
|
||||
label: 'Type DELETE to confirm',
|
||||
value: '',
|
||||
okLabel: 'Delete '+people(n),
|
||||
validate: v => v === 'DELETE' ? '' : 'Type DELETE, in capital letters, to confirm.',
|
||||
});
|
||||
if(typed !== 'DELETE') return;
|
||||
return sendBulk('/api/auth/bulk-users/delete', {}, 'Delete accounts', chosen.map(u => u.id));
|
||||
}
|
||||
|
||||
// Every row is accounted for: changed, already so, or failed with the server's
|
||||
// reason. A batch that partly failed never reads as a success (CR-020).
|
||||
function showBulkResult(json, title){
|
||||
const failed = json.results.filter(r => r.status === 'failed');
|
||||
const parts = [json.ok+' changed'];
|
||||
if(json.unchanged) parts.push(json.unchanged+' already set');
|
||||
if(failed.length) parts.push(failed.length+' failed');
|
||||
const kind = !failed.length ? 'ok' : (json.ok + json.unchanged ? 'warn' : 'bad');
|
||||
const lead = (failed.length ? (kind === 'bad' ? '✕ ' : '⚠ ') : '✓ ')+uesc(title)+': '+parts.join(', ')+'.';
|
||||
const list = failed.length
|
||||
? '<ul>'+failed.map(r => '<li><strong>'+uesc(r.username || r.user_id)+'</strong>: '+uesc(r.reason)+'</li>').join('')+'</ul>'
|
||||
: '';
|
||||
bannerHtml('bulk-banner', kind, lead + list);
|
||||
}
|
||||
|
||||
function bannerHtml(id, kind, html){
|
||||
const el = document.getElementById(id);
|
||||
if(!el) return;
|
||||
el.className = 'banner' + (kind ? ' '+kind : '');
|
||||
el.innerHTML = html;
|
||||
}
|
||||
|
||||
function bulkRole(){
|
||||
const role = selVal('bulk-role');
|
||||
if(!role) return;
|
||||
return runBulk('/api/auth/bulk-users/role', { role }, {
|
||||
title: 'Set permissions', ok: 'Change permissions',
|
||||
message: n => 'Set permissions to '+(PERM_LABELS[role] || role)+' for '+people(n)+'?\n\n'+
|
||||
'Each account is checked on its own. Any that cannot be changed are listed afterwards.'});
|
||||
}
|
||||
|
||||
function bulkActive(on){
|
||||
return runBulk('/api/auth/bulk-users/active', { is_active: !!on }, {
|
||||
title: on ? 'Enable accounts' : 'Disable accounts', ok: on ? 'Enable' : 'Disable',
|
||||
message: n => (on ? 'Enable sign-in for ' : 'Disable sign-in for ')+people(n)+'?'+
|
||||
(on ? '' : '\n\nA disabled account cannot sign in. Nothing else about it changes.')});
|
||||
}
|
||||
|
||||
function bulkProject(op){
|
||||
const pid = selVal('bulk-project');
|
||||
if(!pid) return;
|
||||
const role = op === 'add' ? selVal('bulk-project-role') : '';
|
||||
const pname = selText('bulk-project');
|
||||
return runBulk('/api/auth/bulk-users/projects', { project_id: pid, op, role }, {
|
||||
title: op === 'add' ? 'Add to project' : 'Remove from project',
|
||||
ok: op === 'add' ? 'Add' : 'Remove',
|
||||
message: n => op === 'add'
|
||||
? 'Add '+people(n)+' to '+pname+' with '+(role ? PERM_LABELS[role]+' on that project' : 'their account role')+'?\n\n'+
|
||||
'Their other projects, and their roles there, stay as they are.'
|
||||
: 'Remove '+people(n)+' from '+pname+'?\n\nTheir other projects stay as they are.'});
|
||||
}
|
||||
|
||||
// ── CSV upload (CR-020, T12.4) ────────────────────────────────────────────────
|
||||
// The file holds usernames only (decided 2026-10-06). The server reads it and
|
||||
// answers line by line; the accepted accounts become the ordinary selection, so
|
||||
// the action, its confirmation and its row-by-row report are the same ones the
|
||||
// checkboxes use. A CSV cannot reach an account a checkbox could not: the bulk
|
||||
// route re-checks every row.
|
||||
const CSV_MAX_BYTES = 1024 * 1024;
|
||||
|
||||
// Blob.text() where the browser has it, FileReader where it does not (older
|
||||
// tablet browsers).
|
||||
function readFileText(file){
|
||||
if(typeof file.text === 'function') return file.text();
|
||||
return new Promise((resolve, reject) => {
|
||||
const r = new FileReader();
|
||||
r.onload = () => resolve(String(r.result || ''));
|
||||
r.onerror = () => reject(r.error);
|
||||
r.readAsText(file);
|
||||
});
|
||||
}
|
||||
|
||||
function pickCsv(){
|
||||
const f = document.getElementById('csv-file');
|
||||
if(f){ f.value = ''; f.click(); }
|
||||
}
|
||||
|
||||
document.addEventListener('change', e => {
|
||||
if(e.target && e.target.id === 'csv-file' && e.target.files && e.target.files[0]) loadCsv(e.target.files[0]);
|
||||
});
|
||||
|
||||
async function loadCsv(file){
|
||||
if(file.size > CSV_MAX_BYTES){
|
||||
bannerHtml('csv-banner', 'bad', '✕ '+uesc(file.name)+' is larger than 1 MB. Split it and load the parts one at a time.');
|
||||
return;
|
||||
}
|
||||
let text = '';
|
||||
try { text = await readFileText(file); }
|
||||
catch(_){ bannerHtml('csv-banner', 'bad', '✕ Could not read '+uesc(file.name)+'.'); return; }
|
||||
bannerHtml('csv-banner', '', 'Reading '+uesc(file.name)+'…');
|
||||
const { status, json } = await api('POST', '/api/auth/bulk-users/resolve', { text });
|
||||
if(status !== 200 || !json || !Array.isArray(json.rows)){
|
||||
bannerHtml('csv-banner', 'bad', '✕ '+uesc(apiError(status, json, 'Could not read the list')));
|
||||
return;
|
||||
}
|
||||
// Show everyone, so every accepted account is a visible, checked row: a
|
||||
// selection must never include a row the filter hides.
|
||||
const s = document.getElementById('user-search'), f = document.getElementById('user-filter');
|
||||
if(s) s.value = '';
|
||||
if(f) f.value = '';
|
||||
await loadUsers();
|
||||
const want = new Set(json.user_ids || []);
|
||||
_shownSelectable.forEach(id => { if(want.has(id)) _selected.add(id); });
|
||||
updateSelectionUI();
|
||||
const missed = [...want].filter(id => !_selected.has(id)).length;
|
||||
const rejected = json.rows.filter(r => r.status !== 'ok');
|
||||
const lead = (rejected.length || missed ? '⚠ ' : '✓ ')+uesc(file.name)+': '+json.read+' line'+(json.read===1?'':'s')+' read, '+
|
||||
_selected.size+' selected'+(rejected.length ? ', '+rejected.length+' rejected' : '')+'.'+
|
||||
(missed ? ' '+missed+' accepted account'+(missed===1?' is':'s are')+' no longer in the directory; reload and try again.' : '')+
|
||||
(_selected.size ? ' Pick an action in the bulk bar to apply it to the selected accounts.' : '');
|
||||
const list = rejected.length
|
||||
? '<ul>'+rejected.map(r => '<li>Line '+r.line+' ('+uesc(r.text)+'): '+uesc(r.reason)+'</li>').join('')+'</ul>'
|
||||
: '';
|
||||
bannerHtml('csv-banner', (rejected.length || missed) ? 'warn' : 'ok', lead + list);
|
||||
}
|
||||
|
||||
function selCell(u){
|
||||
if(!selectable(u)){
|
||||
const why = u.id === _meId ? 'Your own account: change it one setting at a time'
|
||||
: (u.manage_blocked_reason || 'You cannot change this account');
|
||||
return '<td class="selcell"><span class="selhit" title="'+uesc(why)+'">'+
|
||||
'<input type="checkbox" disabled aria-label="'+uesc('Cannot select '+u.username+': '+why)+'"></span></td>';
|
||||
}
|
||||
return '<td class="selcell"><label class="selhit">'+
|
||||
'<input type="checkbox" class="selbox" data-id="'+uesc(u.id)+'"'+(_selected.has(u.id)?' checked':'')+
|
||||
' aria-label="'+uesc('Select '+u.username)+'"></label></td>';
|
||||
}
|
||||
|
||||
function renderUsers(){
|
||||
const wrap = document.getElementById('users-table');
|
||||
const q = ((document.getElementById('user-search')||{}).value||'').trim().toLowerCase();
|
||||
@@ -419,8 +116,7 @@ function renderUsers(){
|
||||
(u.project_role||'')+' '+roleLabel(u.role)).toLowerCase().indexOf(q) >= 0;
|
||||
});
|
||||
const count = '<div class="note">'+list.length+' of '+total+' '+(total===1?'person':'people')+'</div>';
|
||||
_shownSelectable = list.filter(selectable).map(u => u.id);
|
||||
if(!list.length){ wrap.innerHTML = count+'<div class="note">Nothing matches.</div>'; updateSelectionUI(); return; }
|
||||
if(!list.length){ wrap.innerHTML = count+'<div class="note">Nothing matches.</div>'; return; }
|
||||
|
||||
const head = manages()
|
||||
? ['Username','Name','Email',
|
||||
@@ -434,16 +130,9 @@ function renderUsers(){
|
||||
'Status'];
|
||||
const ths = head.map(h => Array.isArray(h)
|
||||
? '<th title="'+uesc(h[1])+'">'+uesc(h[0])+'</th>' : '<th>'+uesc(h)+'</th>').join('');
|
||||
// CR-020: a selection column for anyone who manages accounts. Select-all names
|
||||
// how many rows it covers, because it covers only what the filter shows.
|
||||
const selTh = manages()
|
||||
? '<th class="selcell"><label class="selhit"><input type="checkbox" id="sel-all" aria-label="'+
|
||||
uesc('Select all '+_shownSelectable.length+' shown that you can change')+'"></label></th>'
|
||||
: '';
|
||||
const rows = list.map(manages() ? managerRow : readonlyRow).join('');
|
||||
wrap.innerHTML = count+'<div class="tscroll"><table class="grid"><thead><tr>'+selTh+ths+
|
||||
wrap.innerHTML = count+'<div class="tscroll"><table class="grid"><thead><tr>'+ths+
|
||||
'</tr></thead><tbody>'+rows+'</tbody></table></div>'+legend();
|
||||
updateSelectionUI();
|
||||
}
|
||||
|
||||
function legend(){
|
||||
@@ -497,10 +186,12 @@ function managerRow(u){
|
||||
if(can && !me) actions.push('<button class="mini" onclick="toggleActive(\''+uid+'\','+(!u.is_active)+')">'+
|
||||
(u.is_active?'Disable':'Enable')+'</button>');
|
||||
if(can && !me) actions.push('<button class="mini danger" onclick="deleteUser(\''+uid+'\',\''+uname+'\')">Delete</button>');
|
||||
// D13: no self-service action left on your own row — the domain owns the password
|
||||
// and role changes are never self-applied.
|
||||
if(me) actions.push('<span class="note" style="margin:0" title="Your own account">you</span>');
|
||||
if(!can && !me) actions.push('<span class="note" style="margin:0" title="'+uesc(why)+'">read-only</span>');
|
||||
|
||||
return '<tr'+(can||me ? '' : ' class="is-locked"')+'>'+
|
||||
selCell(u)+
|
||||
'<td><strong>'+uesc(u.username)+'</strong>'+(me?'<span class="me-tag">you</span>':'')+'</td>'+
|
||||
'<td>'+uesc(u.full_name||'')+'</td>'+
|
||||
// The address is truncated with the full value on the title: a long one used to
|
||||
@@ -641,10 +332,6 @@ function renderCreateForm(){
|
||||
async function createUser(){
|
||||
const msg = document.getElementById('users-create-msg');
|
||||
const val = id => (document.getElementById(id)||{}).value || '';
|
||||
// The username entered here MUST match what Okta's identity claim will send for
|
||||
// this person exactly — this creates the account ahead of their first sign-in,
|
||||
// and that's how a later Okta sign-in finds this row instead of provisioning a
|
||||
// second one. See create_user()'s docstring in server/app.py.
|
||||
const username = val('nu-username').trim();
|
||||
const project_ids = [...document.querySelectorAll('#nu-project-list input[type=checkbox]:checked')]
|
||||
.map(c => c.value);
|
||||
|
||||
@@ -2207,18 +2207,20 @@ function loadStepComments(){
|
||||
}
|
||||
}
|
||||
|
||||
// ── USAGE ANALYTICS (retired, T11.6) ────────────────────────────────────────
|
||||
// This used to write to wp-usage.js's per-browser localStorage log (D5/T7.10),
|
||||
// read back by the admin console's old "Usage logs" panel. CR-019 replaced
|
||||
// both with real, server-side, per-user activity (UsageEvent + the Activity &
|
||||
// usage card) - see decisions-2026-09-17.md for why this per-browser data was
|
||||
// never a source the new report could adopt. track() is now a no-op; kept
|
||||
// (rather than deleting its handful of call sites, including the dwell-timer
|
||||
// plumbing below) so this stays a one-line change instead of touching every
|
||||
// caller for the same outcome.
|
||||
// ── USAGE ANALYTICS ─────────────────────────────────────────────────────────
|
||||
// Lightweight usage analytics stored in localStorage so the tool owner can review
|
||||
// engagement over time. No field VALUES are stored (field-edit events record only
|
||||
// the field id), keeping captured data non-sensitive.
|
||||
// D5 / T7.10: the analytics implementation lives in wp-usage.js and the report
|
||||
// on the admin console. The wizard's own copy of showAnalytics() never had a
|
||||
// caller here - the button lived on the creator - and once B7 dissolved the
|
||||
// frame the duplicate sat in the same document as five colliding globals.
|
||||
// This page only records; dwell tracking keeps its page-local state below.
|
||||
let _stepEnter = Date.now();
|
||||
|
||||
function track(event, detail){ /* retired, T11.6 — see comment above */ }
|
||||
function track(event, detail){
|
||||
WPUsage.track(WPUsage.KEYS.wizard, event, detail);
|
||||
}
|
||||
function trackStepDwell(){
|
||||
const ms = Date.now() - _stepEnter;
|
||||
if(ms > 400 && ms < 1000*60*60) track('step_dwell', {step: currentStep, ms});
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
<!-- Addressable state (S3). Parses before the app scripts, which read the URL
|
||||
during their own boot. -->
|
||||
<script src="wp-url.js"></script>
|
||||
<script src="wp-usage.js"></script>
|
||||
<script src="wp-list-import.js"></script>
|
||||
<!-- Autosave, unsaved-work guard, draft recovery (S2). -->
|
||||
<script src="wp-autosave.js"></script>
|
||||
|
||||
@@ -3993,17 +3993,11 @@ function openSopModal(){
|
||||
document.getElementById('sop-modal').classList.add('open'); track('view_sop');
|
||||
}
|
||||
function closeSopModal(){ document.getElementById('sop-modal').classList.remove('open'); }
|
||||
// CR-019 / T11.6 (2026-09-23): this used to write to wp-usage.js's per-browser
|
||||
// localStorage log (D5/T7.10). Retired along with the admin console's old
|
||||
// "Usage logs" panel, its only reader - real, server-side, per-user activity
|
||||
// now exists (UsageEvent, the Activity & usage card, T11.1-T11.5) and this
|
||||
// data was never reliably tied to a real identity anyway, so it was not a
|
||||
// source the new report could adopt (decisions-2026-09-17.md). track() stays
|
||||
// as a no-op rather than deleting its ~35 call sites throughout this file:
|
||||
// removing every call individually is a much larger, riskier diff for the
|
||||
// same outcome, and a call site here still documents the moment worth
|
||||
// recording if usage analytics are ever rebuilt server-side.
|
||||
function track(event,detail){ /* retired, T11.6 — see comment above */ }
|
||||
// D5 / T7.10: the analytics implementation lives in wp-usage.js - ONE copy for
|
||||
// the whole suite - and its report lives on the admin console, where an
|
||||
// operator-facing readout belongs. This page only records. Same key, same
|
||||
// event shape: everything recorded before the move is still readable after it.
|
||||
function track(event,detail){ if(devMode) return; WPUsage.track(WPUsage.KEYS.creator, event, detail); }
|
||||
|
||||
// ── COMMENTS ─────────────────────────────────────────────────────────────────
|
||||
const COMMENTS_KEY='wp_iwp_comments_v1';
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
<!-- Addressable state (S3). Parses before the app scripts, which read the URL
|
||||
during their own boot. -->
|
||||
<script src="wp-url.js"></script>
|
||||
<script src="wp-usage.js"></script>
|
||||
<!-- Autosave, unsaved-work guard, draft recovery (S2). -->
|
||||
<script src="wp-autosave.js"></script>
|
||||
<!-- Which sections this project uses (CR-006). The same file the SOP wizard
|
||||
|
||||
@@ -105,18 +105,6 @@
|
||||
say(bits.join(''), problem);
|
||||
}
|
||||
|
||||
// A 500 answers plain text ("Internal Server Error"), and r.json() on that
|
||||
// throws - which used to land in catch() and read as "could not reach the
|
||||
// server" while the server was answering fine (found 2026-08-23, the
|
||||
// production locations import). Read text, parse if it parses, keep status.
|
||||
function readJson(r) {
|
||||
return r.text().then(function (t) {
|
||||
var j = null;
|
||||
try { j = t ? JSON.parse(t) : null; } catch (e) { /* not JSON: a proxy or 500 page */ }
|
||||
return { ok: r.ok, status: r.status, body: j };
|
||||
});
|
||||
}
|
||||
|
||||
function importText(dryRun) {
|
||||
var text = (el(p + '-paste') || {}).value || '';
|
||||
if (!text.trim()) { say('Paste some rows or choose a CSV file first.', true); return; }
|
||||
@@ -126,7 +114,7 @@
|
||||
method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
|
||||
body: JSON.stringify({ text: text, dry_run: !!dryRun }),
|
||||
})
|
||||
.then(readJson)
|
||||
.then(function (r) { return r.json().then(function (j) { return { ok: r.ok, status: r.status, body: j }; }); })
|
||||
.then(function (res) {
|
||||
if (!res.ok) {
|
||||
say('⚠ Import refused — ' + esc((res.body && res.body.detail) || ('HTTP ' + res.status)), true);
|
||||
@@ -154,7 +142,7 @@
|
||||
method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
|
||||
body: JSON.stringify(read.payload),
|
||||
})
|
||||
.then(readJson)
|
||||
.then(function (r) { return r.json().then(function (j) { return { ok: r.ok, status: r.status, body: j }; }); })
|
||||
.then(function (res) {
|
||||
if (!res.ok) {
|
||||
setAddError((res.body && res.body.detail) || ('Could not add it (HTTP ' + res.status + ')'));
|
||||
@@ -173,7 +161,7 @@
|
||||
method: 'PATCH', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
|
||||
body: JSON.stringify(patchBody),
|
||||
})
|
||||
.then(readJson)
|
||||
.then(function (r) { return r.json().then(function (j) { return { ok: r.ok, status: r.status, body: j }; }); })
|
||||
.then(function (res) {
|
||||
if (!res.ok) {
|
||||
say('⚠ ' + esc((res.body && res.body.detail) || ('HTTP ' + res.status)), true);
|
||||
|
||||
58
html/wp-usage.js
Normal file
@@ -0,0 +1,58 @@
|
||||
/* Usage analytics core — the ONE implementation (D5 / T7.10).
|
||||
|
||||
This existed three times: the creator's copy, the wizard's copy (which had no
|
||||
caller — the button lived on the creator), and the admin console's own reader.
|
||||
Once the creator stopped being an iframe (B7/T7.1) the first two sat in one
|
||||
document as five colliding globals; an unreferenced duplicate is exactly what
|
||||
produced D5. One core now; the pages keep only a thin track() wrapper because
|
||||
page state (the creator's dev-mode pause) belongs to the page.
|
||||
|
||||
The storage KEYS are unchanged on purpose: everything recorded before this
|
||||
file existed is still readable through it. No field VALUES are ever stored —
|
||||
a field-edit event records the field id, nothing else.
|
||||
|
||||
Classic script, no modules: exposes window.WPUsage. */
|
||||
'use strict';
|
||||
|
||||
(function () {
|
||||
var SESSION = 's_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
|
||||
|
||||
function load(key) {
|
||||
try { return JSON.parse(localStorage.getItem(key)) || { events: [] }; }
|
||||
catch (e) { return { events: [] }; }
|
||||
}
|
||||
|
||||
function save(key, data) {
|
||||
try { localStorage.setItem(key, JSON.stringify(data)); }
|
||||
catch (e) { /* storage unavailable — degrade silently */ }
|
||||
}
|
||||
|
||||
function track(key, event, detail) {
|
||||
try {
|
||||
var d = load(key);
|
||||
d.events.push({ ts: new Date().toISOString(), session: SESSION, event: event, detail: detail || null });
|
||||
if (d.events.length > 5000) d.events = d.events.slice(-5000);
|
||||
save(key, d);
|
||||
} catch (e) { /* never let telemetry break the tool it watches */ }
|
||||
}
|
||||
|
||||
function download(key, prefix) {
|
||||
var blob = new Blob([JSON.stringify(load(key), null, 2)], { type: 'application/json' });
|
||||
var a = document.createElement('a');
|
||||
a.href = URL.createObjectURL(blob);
|
||||
a.download = (prefix || 'wp-usage') + '-' + new Date().toISOString().slice(0, 10) + '.json';
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
a.remove();
|
||||
setTimeout(function () { URL.revokeObjectURL(a.href); }, 1000);
|
||||
}
|
||||
|
||||
window.WPUsage = {
|
||||
load: load,
|
||||
save: save,
|
||||
track: track,
|
||||
download: download,
|
||||
// The pre-D5 keys, verbatim — continuity of the recorded data is a done-when.
|
||||
KEYS: { creator: 'wp_iwp_analytics_v1', wizard: 'wp_suite_analytics_v1' },
|
||||
};
|
||||
})();
|
||||
@@ -12,101 +12,48 @@ DATABASE_URL=postgresql+psycopg://wpsuite:CHANGE_ME@localhost:5432/wpsuite
|
||||
# CORS_ORIGINS=http://localhost:5500
|
||||
|
||||
# ── Authentication ────────────────────────────────────────────────────────────
|
||||
# There is no local password (D15/D16) — Okta OIDC is the only way in. Sign-in
|
||||
# still ends the same way it always did: a signed JWT in an HttpOnly session
|
||||
# cookie, which is what the four vars right below this line are for. The five
|
||||
# OKTA_* vars after that are what makes the actual sign-in possible; without
|
||||
# them the API starts (this is not a hard failure like AUTH_SECRET_KEY), but
|
||||
# describe()'s startup log line says so and nobody can sign in.
|
||||
|
||||
# Secret used to sign session cookies (JWTs), AFTER Okta has confirmed who
|
||||
# someone is — this app still decides roles/authorization locally, unchanged
|
||||
# by Okta (see server/okta_auth.py). REQUIRED in production: if unset, the API
|
||||
# falls back to a random per-process key, so logins reset on every restart and
|
||||
# break across multiple gunicorn workers. Generate a strong one:
|
||||
# Secret used to sign session cookies (JWTs). REQUIRED in production: if unset,
|
||||
# the API falls back to a random per-process key, so logins reset on every
|
||||
# restart and break across multiple gunicorn workers. Generate a strong one:
|
||||
# python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||||
AUTH_SECRET_KEY=CHANGE_ME_run_the_command_above
|
||||
|
||||
# How long a login lasts before re-authentication (hours). Default 8 (D25).
|
||||
# AUTH_SESSION_HOURS=8
|
||||
# How long a login lasts before re-authentication (hours). Default 12.
|
||||
# AUTH_SESSION_HOURS=12
|
||||
|
||||
# ── Okta OIDC (required — this is the only sign-in path) ───────────────────────
|
||||
# The Okta *authorization server* issuer, e.g. https://yourorg.okta.com/oauth2/default
|
||||
# or a custom authorization server URL. The API discovers the authorize/token/
|
||||
# jwks endpoints from <OKTA_ISSUER>/.well-known/openid-configuration — nothing
|
||||
# else about Okta's endpoints is hand-entered.
|
||||
OKTA_ISSUER=https://your-org.okta.com/oauth2/default
|
||||
|
||||
# Client ID and secret from the Okta app integration (Sign-in method: OIDC -
|
||||
# Authorization Code, Application type: Web Application). The secret is exactly
|
||||
# that — treat it like AUTH_SECRET_KEY, never commit it.
|
||||
OKTA_CLIENT_ID=CHANGE_ME
|
||||
OKTA_CLIENT_SECRET=CHANGE_ME
|
||||
|
||||
# Must exactly match a "Sign-in redirect URI" registered on the Okta app
|
||||
# integration, scheme and path included, e.g.:
|
||||
# https://wp-suite.company.local/api/auth/okta/callback
|
||||
OKTA_REDIRECT_URI=CHANGE_ME
|
||||
|
||||
# Which ID token claim carries this person's directory identity, matched
|
||||
# against the local users.username column (server/app.py's okta_callback()).
|
||||
# preferred_username is Okta's usual default for an AD-imported user; override
|
||||
# it if your security team's Okta configuration uses a different claim (upn,
|
||||
# a custom claim, …) — no code change needed, just this value.
|
||||
# OKTA_IDENTITY_CLAIM=preferred_username
|
||||
|
||||
# ── Okta deprovisioning sync (D18, wave 13) ────────────────────────────────────
|
||||
# A scheduled job asks Okta who is still active and disables local accounts
|
||||
# Okta no longer shows as active. It only ever DISABLES. It never re-enables.
|
||||
# If Okta cannot be reached or answers with anything unexpected, the job changes
|
||||
# NOTHING that cycle and logs the failure.
|
||||
# ── Domain authentication, D13 (REQUIRED — there is no fallback) ───────────────
|
||||
# The suite stores no passwords. Sign-in is an LDAPS simple bind against the
|
||||
# domain, so if this is misconfigured NOBODY CAN SIGN IN, admins included. There
|
||||
# is deliberately no local break-glass account (decided Aug 21 2026 — see
|
||||
# docs/waves/decisions-2026-08-21.md). Check `docker compose logs api` on startup:
|
||||
# the API logs one line saying whether LDAP is configured and reachable.
|
||||
#
|
||||
# A read-only Okta API token, created by the person who administers the Okta
|
||||
# tenant (Security > API > Tokens). This is NOT the OIDC client secret above.
|
||||
# It is a different credential with a different scope. Treat it like
|
||||
# AUTH_SECRET_KEY: never commit it, never log it. Leave it unset and the sync
|
||||
# stays off (the startup log says so).
|
||||
# OKTA_API_TOKEN=CHANGE_ME
|
||||
#
|
||||
# Second way to sign in to the Management API (D23): an Okta "API Services" app that
|
||||
# uses client authentication private_key_jwt. Set these two INSTEAD of OKTA_API_TOKEN.
|
||||
# If OKTA_API_TOKEN is also set, the token is used.
|
||||
# OKTA_SYNC_CLIENT_ID the client ID of that app (starts with 0oa)
|
||||
# OKTA_SYNC_PRIVATE_KEY its PRIVATE key as a JWK, as JSON or as base64 of that JSON.
|
||||
# In Portainer use base64: it has no quote marks to be mangled.
|
||||
# The Okta app needs the scope okta.users.read granted (Okta API Scopes tab), an admin
|
||||
# role such as Read-only Administrator assigned to it. If the app has "Require Demonstrating
|
||||
# Proof of Possession (DPoP)" switched on, the sync detects that and uses DPoP by itself. The key is a secret: never commit it or paste it
|
||||
# into chat or a ticket.
|
||||
# OKTA_SYNC_DPOP: auto (default), on, or off. auto asks for a plain Bearer token first, and
|
||||
# uses DPoP only if Okta answers invalid_dpop_proof. Set "on" to always use DPoP.
|
||||
# Set "off" to never use it. You normally set nothing.
|
||||
# OKTA_SYNC_DPOP=auto
|
||||
# OKTA_SYNC_CLIENT_ID=0oaXXXXXXXXXXXXXXXXX
|
||||
# OKTA_SYNC_PRIVATE_KEY=
|
||||
# Connect to the DOMAIN NAME, never a DC hostname and never an IP. Every DC's
|
||||
# certificate carries `prime.local` in its SAN, so the domain name both passes
|
||||
# hostname validation and round-robins across all six DCs. An IP fails with
|
||||
# `hostname mismatch` (there is no IP SAN) and the only way to force it through is
|
||||
# to disable validation, which must not happen — domain passwords cross this link.
|
||||
# LDAP_DOMAIN=prime.local
|
||||
# LDAP_HOST=prime.local
|
||||
# LDAP_PORT=636
|
||||
|
||||
# The Okta org URL that serves the Management API, e.g. https://yourorg.okta.com
|
||||
# Optional. If unset, it is the scheme and host of OKTA_ISSUER. Must be https.
|
||||
# OKTA_ORG_URL=https://your-org.okta.com
|
||||
#
|
||||
# Which Okta PROFILE attribute holds the value that matches users.username.
|
||||
# Optional. By default it follows OKTA_IDENTITY_CLAIM: preferred_username reads
|
||||
# profile.login, email reads profile.email, any other claim name reads the
|
||||
# profile attribute of the same name. Set this only if your tenant builds the
|
||||
# claim from a different attribute.
|
||||
# OKTA_SYNC_PROFILE_ATTRIBUTE=login
|
||||
#
|
||||
# How often the sync runs, in seconds. Default 900 (15 minutes), proposed and not
|
||||
# confirmed with IT. A value under 300 is raised to 300. Every api worker checks
|
||||
# once a minute and one of them wins each cycle, so raising the worker count does
|
||||
# not raise the call rate to Okta.
|
||||
# OKTA_SYNC_INTERVAL_SECONDS=900
|
||||
#
|
||||
# Dry run (D22). Set to true for the first deploy. The sync then does everything
|
||||
# except the change: it logs who it WOULD disable and writes nothing, and it writes
|
||||
# no audit rows. Read the result with: docker compose logs api | grep "Okta sync"
|
||||
# Remove it (or set it to false) to go live. Off by default.
|
||||
# OKTA_SYNC_DRY_RUN=true
|
||||
# Trust anchor: PRIME CONTROLS ROOT CA + PRIME CONTROLS ISSUING CA 1 as a PEM
|
||||
# bundle. These are PUBLIC certificates — no private key, nothing issued to this
|
||||
# app, nothing to request from IT. The repo ships a verified copy and the default
|
||||
# points at it, so you only set this to override with a mounted file.
|
||||
# LDAP_CA_FILE=/app/server/certs/prime-ca-chain.pem
|
||||
|
||||
# An AD group required to sign in. Empty means every domain account may sign in.
|
||||
# This is the INITIAL value and the fallback; the live value is set in the Admin
|
||||
# console, which refuses to save a group that does not resolve or that the saving
|
||||
# admin is not a member of. Nested groups count.
|
||||
# LDAP_REQUIRED_GROUP=WP-Suite-Users
|
||||
|
||||
# Bind/connect timeout, and how many extra CONNECT attempts to make. Retries never
|
||||
# apply to a rejected password — each failed bind counts against the domain lockout
|
||||
# policy, so guessing would lock real accounts out of Windows.
|
||||
# LDAP_TIMEOUT_SECONDS=8
|
||||
# LDAP_CONNECT_RETRIES=2
|
||||
|
||||
# ── Email notifications (optional) ─────────────────────────────────────────────
|
||||
# WP-assignment emails are OFF by default and are turned on from the Admin
|
||||
|
||||
179
server/README.md
@@ -14,12 +14,12 @@ browser → NGINX ──serves──> static site (index.html, …)
|
||||
| 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/login` | sign in (`{username, password}`) — binds against the domain, sets the session cookie |
|
||||
| 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**) |
|
||||
| POST | `/api/auth/users` | pre-create an account (**admin**) — optional; accounts self-provision on first sign-in |
|
||||
| POST | `/api/auth/users/{id}/role` | change an account's permissions role (**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 |
|
||||
@@ -40,86 +40,135 @@ fields (name, number, status, …) are promoted to columns for listing/filtering
|
||||
|
||||
---
|
||||
|
||||
## Sign-in (Okta)
|
||||
## Sign-in (domain authentication, D13)
|
||||
|
||||
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.
|
||||
**The suite stores no passwords.** Signing in performs an LDAPS **simple bind** to
|
||||
`ldaps://prime.local:636` as `<sAMAccountName>@prime.local` using the password the
|
||||
person typed — their Windows password. A successful bind is the authentication.
|
||||
See `server/ldap_auth.py`; the schema has no `password_hash` column.
|
||||
|
||||
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.
|
||||
Sign-in issues a signed JWT
|
||||
that rides in an **HttpOnly, SameSite=Lax** cookie (`wp_session`); the cookie is
|
||||
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.
|
||||
|
||||
**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.
|
||||
**The directory supplies identity; this app supplies authorization.** Roles live in
|
||||
the local `users` table and are never read from AD — so an existing admin stays an
|
||||
admin. Roles are `admin`, `project_super_user`, `project_admin`, `project_user`.
|
||||
|
||||
Roles are `admin`, `project_super_user`, `project_admin`, `project_user`
|
||||
(`html/users.js`, enforced server-side).
|
||||
**Accounts are created on first successful sign-in.** Anyone who binds successfully
|
||||
and is in the required group gets a `users` row at `project_user` with **no project
|
||||
access** — they can sign in and will see nothing until an admin grants access. That
|
||||
is least privilege, and it is deliberate; the creation is written to the audit log
|
||||
so it is visible rather than silent.
|
||||
|
||||
### Set the signing secret and the Okta app integration
|
||||
**A required AD group gates sign-in.** `LDAP_REQUIRED_GROUP` (a group name or a full
|
||||
DN; nested groups count). Empty means any domain account may sign in.
|
||||
|
||||
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()`).
|
||||
**There is no password reset and no break-glass.** The login page links to
|
||||
`https://primecontrols.okta.com/` for password self-service. If the domain is
|
||||
unreachable, or `LDAP_CA_FILE` is wrong, or the required group is misconfigured,
|
||||
**nobody can sign in, including admins** — the API logs one line at startup saying
|
||||
whether LDAP is configured and reachable, so check `docker compose logs api` first.
|
||||
|
||||
**Connect to the domain name, never a DC hostname or an IP.** Every DC certificate
|
||||
carries `prime.local` in its SAN, so the domain name both passes hostname validation
|
||||
and round-robins across all six DCs. An IP fails with `hostname mismatch` — there is
|
||||
no IP SAN — and the only way to force it through is to disable validation, which
|
||||
must never happen: domain passwords cross this link.
|
||||
|
||||
**The trust anchor is a CA certificate, not one issued to this app.** The API is the
|
||||
TLS *client*, and clients present nothing. `server/certs/prime-ca-chain.pem` holds
|
||||
`PRIME CONTROLS ROOT CA` + `PRIME CONTROLS ISSUING CA 1` — public certificates, no
|
||||
private key, nothing to request from IT. Override the path with `LDAP_CA_FILE`.
|
||||
|
||||
Diagnose the connection without touching an account (no bind, so it cannot
|
||||
contribute to a lockout):
|
||||
|
||||
```bash
|
||||
docker compose exec api openssl s_client -connect prime.local:636 -CAfile /app/server/certs/prime-ca-chain.pem </dev/null 2>&1 | grep "Verify return"
|
||||
# want: Verify return code: 0 (ok)
|
||||
```
|
||||
|
||||
### Set the signing secret
|
||||
|
||||
Add `AUTH_SECRET_KEY` to `.env` (see `.env.example`). **Required in production** —
|
||||
without it the API uses a random per-process key, so logins reset on restart.
|
||||
|
||||
```bash
|
||||
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).
|
||||
### Bootstrap the first admin
|
||||
|
||||
### 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):
|
||||
Two steps, in this order. There is no `create-admin` any more — there is no password
|
||||
to set and no account to create.
|
||||
|
||||
```bash
|
||||
python -m server.manage_users promote alice --role admin
|
||||
# 1. Sign in to the app once. That provisions your account at project_user.
|
||||
# 2. Promote it:
|
||||
docker compose exec api python -m server.manage_users promote alice
|
||||
```
|
||||
|
||||
In Docker:
|
||||
It prompts for **your** domain username and password, binds to confirm who you are,
|
||||
and prints `alice: project_user -> admin`.
|
||||
|
||||
```bash
|
||||
docker compose exec api python -m server.manage_users promote alice --role admin
|
||||
```
|
||||
Other commands: `list`, `promote <user> [--role …]`, `demote <user>`,
|
||||
`disable <user>`, `enable <user>`. After that, admins manage accounts from the Admin
|
||||
console.
|
||||
|
||||
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.
|
||||
**Every command that changes anything requires a domain bind** (D14), prompted —
|
||||
there is deliberately no `--password` flag, which would put a live domain password
|
||||
into shell history and `ps` output. `list` needs no credential so an outage stays
|
||||
diagnosable. The bind here does **not** apply the required-group gate, so a mistyped
|
||||
group cannot lock you out of the tool that fixes it.
|
||||
|
||||
**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.
|
||||
Be clear on what the bind is worth: anyone with a shell here can still write to the
|
||||
`users` table with `psql`. It is defence in depth and, mostly, **accountability** —
|
||||
every role change now writes an audit row naming a person, which shell changes
|
||||
previously did not.
|
||||
|
||||
---
|
||||
|
||||
## Local dev
|
||||
|
||||
> ### A SQLite database created before D13 will reject new sign-ins
|
||||
>
|
||||
> `Base.metadata.create_all()` creates missing tables; it never alters existing ones.
|
||||
> So a `wpsuite.db` built before D13 still has `users.password_hash` declared
|
||||
> `NOT NULL` with no default, while the current model has no such column — and an
|
||||
> INSERT that omits it is rejected:
|
||||
>
|
||||
> ```
|
||||
> IntegrityError: NOT NULL constraint failed: users.password_hash
|
||||
> ```
|
||||
>
|
||||
> Accounts already in the file keep working, so **you** can sign in and nothing looks
|
||||
> wrong. It breaks the moment a *new* person signs in, because provisioning them is an
|
||||
> INSERT — and it surfaces as an HTTP **500**, not a 401, so it reads as a server fault
|
||||
> rather than anything to do with the schema.
|
||||
>
|
||||
> Such a database also has no `alembic_version` table, so `alembic upgrade head` would
|
||||
> try to replay the baseline against tables that already exist. Stamp it first:
|
||||
>
|
||||
> ```bash
|
||||
> python -m alembic -c server/alembic.ini stamp a1b8c6d4e2f9 # the revision before the drop
|
||||
> python -m alembic -c server/alembic.ini upgrade head # runs only the drop
|
||||
> ```
|
||||
>
|
||||
> That keeps whatever is in the file. Deleting the database also works and
|
||||
> `create_all()` rebuilds a correct schema, but it throws away your test data.
|
||||
>
|
||||
> Production is unaffected: it runs Postgres and the container applies migrations at
|
||||
> start, so the column is dropped properly there.
|
||||
|
||||
|
||||
```bash
|
||||
cd server
|
||||
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
@@ -322,25 +371,25 @@ docker compose down -v
|
||||
|
||||
## Quick test
|
||||
|
||||
`/api/health` is open; every other `/api/` route needs a session cookie:
|
||||
`/api/health` is open; data routes now require a session, so log in first and
|
||||
reuse the cookie jar:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/api/health # {"ok":true} — no auth needed
|
||||
|
||||
# Sign in, saving the session cookie to a jar
|
||||
curl -c jar.txt -X POST http://127.0.0.1:8000/api/auth/login \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username":"alice","password":"<password>"}'
|
||||
|
||||
# Reuse the cookie on protected routes
|
||||
curl -b jar.txt http://127.0.0.1:8000/api/comments
|
||||
```
|
||||
|
||||
Without a session cookie, protected routes return `401 {"detail":"Not authenticated"}`.
|
||||
Without the cookie, protected routes return `401 {"detail":"Not authenticated"}`.
|
||||
|
||||
Or via the nginx proxy (replace with your hostname):
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
@@ -52,13 +52,6 @@ def run_migrations_online() -> None:
|
||||
connection=connection,
|
||||
target_metadata=target_metadata,
|
||||
compare_type=True,
|
||||
# Each migration commits on its own. One transaction for the WHOLE
|
||||
# run meant a crash at step N rolled back steps 1..N-1 while their
|
||||
# "Running upgrade" lines stayed on screen claiming they ran - the
|
||||
# 2026-08-21 outage's stamp-to-head repair trusted those lines and
|
||||
# left production missing two tables (found 2026-08-23 when the
|
||||
# locations import 500'd on a table that "had been created").
|
||||
transaction_per_migration=True,
|
||||
)
|
||||
with context.begin_transaction():
|
||||
context.run_migrations()
|
||||
|
||||
@@ -1,29 +0,0 @@
|
||||
"""drop local password (T10.4, wave 10 / D15 / D16)
|
||||
|
||||
Real deletion, not a toggle: no local password exists anymore, only Okta OIDC.
|
||||
`password_hash` was NOT NULL at the database level since the baseline schema, so
|
||||
downgrade re-adds it with server_default='' rather than leaving existing rows
|
||||
without a value — the same pattern used for the locale/timezone drop-precedent
|
||||
columns, applied in reverse.
|
||||
|
||||
Revision ID: 1d60a608bb51
|
||||
Revises: a1b8c6d4e2f9
|
||||
Create Date: 2026-09-03 00:00:00.000000
|
||||
"""
|
||||
from alembic import op
|
||||
import sqlalchemy as sa
|
||||
|
||||
|
||||
# revision identifiers, used by Alembic.
|
||||
revision = '1d60a608bb51'
|
||||
down_revision = 'a1b8c6d4e2f9'
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
op.drop_column('users', 'password_hash')
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.add_column('users', sa.Column('password_hash', sa.String(length=200), nullable=False, server_default=''))
|
||||
@@ -1,46 +0,0 @@
|
||||
"""usage events (CR-019, wave 11)
|
||||
|
||||
Append-only navigation/session activity, separate from audit_log on purpose —
|
||||
see the UsageEvent docstring in server/models.py. Retention is indefinite by
|
||||
decision (docs/waves/decisions-2026-09-17.md); nothing here schedules a purge.
|
||||
|
||||
Revision ID: 8e2cb3003f8a
|
||||
Revises: 1d60a608bb51
|
||||
Create Date: 2026-09-23 00:00:00.000000
|
||||
"""
|
||||
from alembic import op
|
||||
import sqlalchemy as sa
|
||||
|
||||
|
||||
# revision identifiers, used by Alembic.
|
||||
revision = '8e2cb3003f8a'
|
||||
down_revision = '1d60a608bb51'
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
op.create_table('usage_events',
|
||||
sa.Column('id', sa.String(length=40), nullable=False),
|
||||
sa.Column('at', sa.DateTime(timezone=True), nullable=False),
|
||||
sa.Column('username', sa.String(length=200), nullable=False),
|
||||
sa.Column('project_id', sa.String(length=40), nullable=True),
|
||||
sa.Column('tool', sa.String(length=40), nullable=False),
|
||||
sa.Column('event', sa.String(length=40), nullable=False),
|
||||
sa.Column('detail', sa.JSON(), nullable=False),
|
||||
sa.PrimaryKeyConstraint('id')
|
||||
)
|
||||
op.create_index(op.f('ix_usage_events_at'), 'usage_events', ['at'], unique=False)
|
||||
op.create_index(op.f('ix_usage_events_username'), 'usage_events', ['username'], unique=False)
|
||||
op.create_index(op.f('ix_usage_events_project_id'), 'usage_events', ['project_id'], unique=False)
|
||||
op.create_index(op.f('ix_usage_events_tool'), 'usage_events', ['tool'], unique=False)
|
||||
op.create_index(op.f('ix_usage_events_event'), 'usage_events', ['event'], unique=False)
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.drop_index(op.f('ix_usage_events_event'), table_name='usage_events')
|
||||
op.drop_index(op.f('ix_usage_events_tool'), table_name='usage_events')
|
||||
op.drop_index(op.f('ix_usage_events_project_id'), table_name='usage_events')
|
||||
op.drop_index(op.f('ix_usage_events_username'), table_name='usage_events')
|
||||
op.drop_index(op.f('ix_usage_events_at'), table_name='usage_events')
|
||||
op.drop_table('usage_events')
|
||||
@@ -32,10 +32,11 @@ def upgrade() -> None:
|
||||
sa.Column('code', sa.String(length=80), nullable=False, server_default=''),
|
||||
sa.Column('description', sa.String(length=300), nullable=False, server_default=''),
|
||||
sa.Column('unit', sa.String(length=20), nullable=False, server_default=''),
|
||||
# sa.true(), not sa.text('1'): SQLite coerces integer 1 to boolean,
|
||||
# Postgres refuses it (DatatypeMismatch) - found when this migration
|
||||
# took down the wp.controls.dev api container on 2026-08-21. The
|
||||
# location-taxonomy migration next door had it right all along.
|
||||
# sa.true(), NOT sa.text('1'). sa.text() emits raw SQL, and Postgres refuses
|
||||
# an integer default on a boolean column: "column active is of type boolean
|
||||
# but default expression is of type integer". SQLite accepts 1 happily, so
|
||||
# this passed every local test and failed only on the real engine. The
|
||||
# sibling migration e2a4c7d91b30 does the identical column correctly.
|
||||
sa.Column('active', sa.Boolean(), nullable=False, server_default=sa.true()),
|
||||
sa.Column('sort', sa.Integer(), nullable=False, server_default='0'),
|
||||
sa.Column('created_at', sa.DateTime(timezone=True), nullable=True),
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
"""drop users.password_hash — D13 / T10.3
|
||||
|
||||
Authentication moved to an LDAPS simple bind against the domain (see
|
||||
server/ldap_auth.py), so the suite no longer holds a credential of any kind.
|
||||
|
||||
THIS MIGRATION DESTROYS DATA AND CANNOT BE UNDONE IN ANY MEANINGFUL SENSE.
|
||||
`downgrade()` recreates the column, but every hash in it is gone — and even a
|
||||
restored hash would be useless, because nothing reads the column any more. The
|
||||
downgrade exists so the revision is well-formed and so an operator can step back
|
||||
past it, not because stepping back restores the old login. To actually revert to
|
||||
local passwords you have to revert the application code and reset every password
|
||||
by hand.
|
||||
|
||||
The column is recreated NULLABLE on downgrade, deliberately. The baseline schema
|
||||
declared it NOT NULL, but there are no values to put back, so a NOT NULL column
|
||||
with no server default would refuse to add itself on any table that has rows.
|
||||
|
||||
DO NOT WRAP THIS IN batch_alter_table. An earlier version of this migration did,
|
||||
and it silently deleted every row of `project_members` on SQLite.
|
||||
|
||||
Why: alembic's batch mode emulates ALTER on SQLite by rebuilding the table —
|
||||
create a new one, copy the rows, DROP the original, rename. `server/alembic/env.py`
|
||||
imports the engine from `server/db.py`, which registers a `connect` listener setting
|
||||
`PRAGMA foreign_keys=ON`, so that DROP TABLE cascades through
|
||||
`project_members.user_id`, which is declared `ondelete="CASCADE"`. Every project
|
||||
membership in the database goes with it, with no error and nothing in the log.
|
||||
|
||||
Turning the pragma off around the batch is not a fix either: `PRAGMA foreign_keys`
|
||||
is a no-op inside a transaction, and alembic runs migrations in one.
|
||||
|
||||
The real answer is that the rebuild is unnecessary. SQLite gained native
|
||||
ALTER TABLE ... DROP COLUMN in 3.35 (2021); this runtime has 3.42 and Postgres has
|
||||
always had it. A plain drop_column touches one table and cascades nowhere.
|
||||
|
||||
Revision ID: b7e4f1a20c93
|
||||
Revises: a1b8c6d4e2f9
|
||||
Create Date: 2026-08-21
|
||||
"""
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
|
||||
revision = 'b7e4f1a20c93'
|
||||
down_revision = 'a1b8c6d4e2f9'
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def upgrade():
|
||||
# Plain, un-batched, on both engines. See the docstring: batching this destroys
|
||||
# project_members on SQLite.
|
||||
op.drop_column('users', 'password_hash')
|
||||
|
||||
|
||||
def downgrade():
|
||||
op.add_column('users', sa.Column('password_hash', sa.String(length=200),
|
||||
nullable=True))
|
||||
1108
server/app.py
@@ -1,11 +1,10 @@
|
||||
"""Authentication for the Work Package Suite.
|
||||
|
||||
Identity is confirmed by Okta (OIDC authorization-code flow, see server/okta_auth.py
|
||||
and the routes in server/app.py); there is no local password anywhere in this app
|
||||
(D15, D16 — T10.4 removed the last of it). A successful sign-in issues a signed JWT
|
||||
that rides in an HttpOnly cookie (`wp_session`). Because the token is signed and
|
||||
self-validating, there is no server-side session store — every request is checked by
|
||||
verifying the cookie's signature and expiry (see `auth_gate` and `get_current_user`).
|
||||
Authentication is an LDAPS simple bind against the domain (D13); this module owns
|
||||
everything *after* that. A successful sign-in issues a signed JWT that rides in an
|
||||
HttpOnly cookie (`wp_session`). Because the token is signed and self-validating, there is no
|
||||
server-side session store — every request is checked by verifying the cookie's
|
||||
signature and expiry (see `auth_gate` and `get_current_user`).
|
||||
|
||||
Security model:
|
||||
• The real boundary is `auth_gate` (middleware in app.py): every /api/ data
|
||||
@@ -13,14 +12,14 @@ Security model:
|
||||
• The cookie is HttpOnly (JS can't read it → XSS can't steal the session),
|
||||
SameSite=Lax (blunts CSRF), and Secure whenever the request arrives over
|
||||
HTTPS (detected via X-Forwarded-Proto behind NGINX).
|
||||
• Roles are LOCAL. The directory supplies identity; this app decides what that
|
||||
identity may do, which is why an existing admin keeps admin (D13 criterion 4).
|
||||
• The signing secret comes from AUTH_SECRET_KEY. In production this MUST be
|
||||
set; if it is missing we fall back to a random per-process key (which logs a
|
||||
warning and invalidates every session on restart) so dev still works.
|
||||
|
||||
Permissions roles (`User.role`) — distinct from a person's job function on the
|
||||
project, which lives in `User.project_role` and grants nothing. Decided entirely
|
||||
locally: Okta gates WHO can authenticate at all, this app decides what an
|
||||
authenticated account may do — see D15/D16.
|
||||
project, which lives in `User.project_role` and grants nothing:
|
||||
• admin application administrator: user administration, app settings,
|
||||
and implicit access to every project.
|
||||
• project_super_user
|
||||
@@ -33,13 +32,16 @@ authenticated account may do — see D15/D16.
|
||||
modify a SOP after it has been completed, and delete projects.
|
||||
• project_user normal member: creates and edits work packages, authors a SOP
|
||||
up to completion. May NOT delete WPs or change a completed SOP.
|
||||
Also where Okta JIT provisioning (T10.3) lands a brand-new
|
||||
account — the lowest-privilege role, promoted locally from
|
||||
there by an admin (see manage_users.py for the bootstrap case).
|
||||
|
||||
The user-administration SCOPE of a super user is worked out in server/app.py
|
||||
(`managed_project_ids`, `manage_user_problem`), because it depends on project
|
||||
membership rows — this module only decides which roles carry the power at all.
|
||||
|
||||
There is no password and no password reset: D13 replaced local credentials with an
|
||||
LDAPS bind (server/ldap_auth.py). People change their password with the domain, and
|
||||
the login page points them at Okta. `token_version` survives as the
|
||||
session-revocation mechanism — a role change or a deactivation must take effect on
|
||||
sessions that have already been issued.
|
||||
"""
|
||||
import os
|
||||
import secrets
|
||||
@@ -59,10 +61,8 @@ log = logging.getLogger("wpsuite.auth")
|
||||
|
||||
COOKIE_NAME = "wp_session"
|
||||
JWT_ALG = "HS256"
|
||||
# How long a session lasts before the person must sign in again. Default 8 hours (D25).
|
||||
# One flat limit from the moment of sign-in. When T13.1 lands, the same variable becomes
|
||||
# the absolute ceiling and an idle timer is added under it.
|
||||
SESSION_HOURS = int(os.getenv("AUTH_SESSION_HOURS", "8"))
|
||||
# How long a login lasts before the user must sign in again.
|
||||
SESSION_HOURS = int(os.getenv("AUTH_SESSION_HOURS", "12"))
|
||||
|
||||
# ── permissions roles ─────────────────────────────────────────────────────────
|
||||
ROLE_ADMIN = "admin"
|
||||
@@ -121,7 +121,7 @@ def is_project_admin(user: "models.User") -> bool:
|
||||
# same question used to exist here and silently disagreed with the scoped one, which
|
||||
# locked per-project super users out of the routes they were entitled to.
|
||||
|
||||
# Paths under /api that do NOT require a session (the Okta routes themselves, health, docs).
|
||||
# Paths under /api that do NOT require a session (login itself, health, docs).
|
||||
_EXEMPT_PREFIXES = ("/api/auth/",)
|
||||
_EXEMPT_EXACT = {
|
||||
"/api/health",
|
||||
@@ -175,33 +175,14 @@ def create_token(user: "models.User") -> str:
|
||||
return jwt.encode(payload, SECRET_KEY, algorithm=JWT_ALG)
|
||||
|
||||
|
||||
# D21: a real session token is about 300 characters. Anything far larger is not
|
||||
# one of ours, and refusing it before parsing keeps a crafted cookie from making
|
||||
# the parser do work on our behalf.
|
||||
_MAX_TOKEN_CHARS = 4096
|
||||
|
||||
|
||||
def decode_token(token: str) -> Optional[dict]:
|
||||
"""Return the token claims if the signature and expiry are valid, else None.
|
||||
Session cookies only — a token of any other type is rejected.
|
||||
|
||||
D21: fails CLOSED on any error. This used to catch jwt.PyJWTError only, and
|
||||
PyJWT 2.13.0 let a RecursionError out of header parsing, so a 1.6 KB cookie
|
||||
from someone with no account produced a 500 and a stack trace instead of a
|
||||
401 (security review SEC-07). Whatever goes wrong inside the decoder, the
|
||||
answer is the same: not signed in."""
|
||||
if not token or len(token) > _MAX_TOKEN_CHARS:
|
||||
return None
|
||||
Session cookies only — a token of any other type is rejected."""
|
||||
try:
|
||||
# Every token this app issues carries exp and sub (create_token); one without them is not ours.
|
||||
claims = jwt.decode(token, SECRET_KEY, algorithms=[JWT_ALG],
|
||||
options={"require": ["exp", "sub"]})
|
||||
except Exception: # noqa: BLE001 — see docstring: every failure is "not signed in"
|
||||
claims = jwt.decode(token, SECRET_KEY, algorithms=[JWT_ALG])
|
||||
except jwt.PyJWTError:
|
||||
return None
|
||||
# No route issues a `typ`-carrying token anymore (that was the password-reset
|
||||
# token, removed in T10.4), but a session token still must never validate as
|
||||
# one — kept as a defensive check, cheap insurance against a future token type
|
||||
# riding the same cookie.
|
||||
# A password-reset token must never be usable as a session cookie.
|
||||
if claims.get("typ"):
|
||||
return None
|
||||
return claims
|
||||
|
||||
66
server/certs/prime-ca-chain.pem
Normal file
@@ -0,0 +1,66 @@
|
||||
# CN=PRIME CONTROLS ROOT CA
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIFHzCCAwegAwIBAgIQOnMIcdMiP6pELiXfh2ZmLzANBgkqhkiG9w0BAQsFADAhMR8wHQYDVQQD
|
||||
ExZQUklNRSBDT05UUk9MUyBST09UIENBMCAXDTIxMDkwOTEzMjM1OFoYDzIwNTEwOTA5MTMzMzU2
|
||||
WjAhMR8wHQYDVQQDExZQUklNRSBDT05UUk9MUyBST09UIENBMIICIjANBgkqhkiG9w0BAQEFAAOC
|
||||
Ag8AMIICCgKCAgEAri9Vkf+l3bnjGXWMEX15BYRnQTSKUStctG2NBppJ/lwj2LbHAvHf6HdkJAxx
|
||||
2lqDiG0R+D9NcGEi427XOQ78Nc9aJe4jOwip5u5Md6Szwmu4QDRjUy11dDBvRoftD550052O1WOV
|
||||
0OY5hxcZIo7bOfqDLesHG/Y74GJvrYai/4xq440uN6iTaMmsfzbIahIXP39NhuW4i4dgkQkRSfqX
|
||||
y8i3AGS8WhpViVvIlMgGXRrCcBW8MnVp32OvKE2MqQnjZI2i5f8wMT4L0J0DXlSPbV6FPLdpBXl5
|
||||
+OX+9qcEH6hI+Mv8sC/xGLAt/wwBP6E2kM2lovGGIUhBsay0UM03PJsh4r6q3HV5gpH6uYZlOgOY
|
||||
UW59pNT/VyESdZb4kfEGHNHrHy3uNb8Q71UzQxrq/UVKXnBUMN/1PszV4YA08ZaYf2EGItZoNM3v
|
||||
uTOJIifgtAo1DxaTygmglgk8CHlaN4IU8jotrzdksLYQ9MQaD5xnYADCnIf1eZ5VCF+fhpgQOCCV
|
||||
4TfJ20rR14+jy6L4yKYGgtvg8H+hvhucOOnktpV/zLv4H9pItIzbQPuxNdrEmco2i7zrsMuaNYD/
|
||||
tmbGf4mhy20zFOkdOjXGeb4cTF4HIBh3aue2T7o08vi1pkVN+8RXa7lZNbLJnpgtfTr9DKBpW2Fd
|
||||
LqAb1zN2Azorg3kCAwEAAaNRME8wCwYDVR0PBAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0O
|
||||
BBYEFMoWYtRcmyQQmB3AD4DPiau0r9XRMBAGCSsGAQQBgjcVAQQDAgEAMA0GCSqGSIb3DQEBCwUA
|
||||
A4ICAQB0XhWlrK81ZKW9bBlbQe/i6js7ciDhwObgKB0FGZJH8rqK5HFwM/wZbh9h0t+YPk/ev6oG
|
||||
BXU0rJUr1YVMERBb37c/rHBU4Bnv9r6cLhsfiTTcVGqZTM7JE9JfdmJQ10V1awSFoxU1cYMSzot9
|
||||
TyrspkZJ6JFJH2wdhZirIySQHH5WuqEOdG6g9/bDW2X27B0S62s8WNIfP+gugkTDkiHQvoUDi8GY
|
||||
/DA29lZTKPI8PhmKYZvw+fi1weqIYsFLk9pvHW21nIv6qAT7nfuGvuUR5siB7sFbw80XEX6Em8O0
|
||||
0lnP6u+vecBqLK7D34X+aupDlkZlZdPoa0EaTwvTO8pkecZCdMLcTkB2quc/fcyCmVdj4CGn3yND
|
||||
cUUR5wZbHtuCU27Rc4d3rY0gxPNpK3EXkTSOQL7BgR6EkwwNwUqeYmFb/SyXYeSqpdChvsWKgRrP
|
||||
+8n27SeJ01ezk8GMDC0YcOJAAHxXqqOAJo1IwxVvpRkoljKIAprQwHAGUNTmKy+SJXT73/LpPTX+
|
||||
RnbNTG27UfYONh5/DdkGc1wwmIp1X1a1tAb3MNRasiBGlYJ3NGDHVUwgEtmcVeVXWsj1ZhaXq2YX
|
||||
TFsDl9m1IMhFD1n8pLJTLd7AT8Exxga+OzFjMzDu0uzKw3KoAVIX/IgfybdKexVT4Z+nBCY9N+n9
|
||||
/vpujg==
|
||||
-----END CERTIFICATE-----
|
||||
# CN=PRIME CONTROLS ISSUING CA 1, DC=prime, DC=local
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIH/jCCBeagAwIBAgITdQAAAAI3j8Wt9kAshQAAAAAAAjANBgkqhkiG9w0BAQsFADAhMR8wHQYD
|
||||
VQQDExZQUklNRSBDT05UUk9MUyBST09UIENBMB4XDTIxMDkwOTE0NDUxM1oXDTM2MDkwOTE0NTUx
|
||||
M1owVDEVMBMGCgmSJomT8ixkARkWBWxvY2FsMRUwEwYKCZImiZPyLGQBGRYFcHJpbWUxJDAiBgNV
|
||||
BAMTG1BSSU1FIENPTlRST0xTIElTU1VJTkcgQ0EgMTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCC
|
||||
AgoCggIBANvhsMj7RooZ+FzAExgWLex++F1QsdDqcGkwqjaUI5AziI4yb/FMqnO93Sus60hiqql+
|
||||
hfxW/a55huBfo54kOyp5oWAjd0akfJQvFY8sXsWIGz07wiy0msvZDtHdBXy561zb0SSNpJS1Vceb
|
||||
ihyDvM5Tyc6QAzO1u76QJPkegn+v6lpWmodba0kWVvRg/P3SLCnq1LdU8oA1VhIiCkCbdry0Syop
|
||||
bVX0+evzINGmv81VbHct8ptZTBLctM11C16IwPEmntvOqVKpT166/aUO8FMqyHQQZ32ZHBp6ORNu
|
||||
WlCN/EDdgT2s7Vy9/7Hr6gy1IPjEGNYq1yYxcpth+6/RgvxFnt9SWr7B9qKtYe1rN8r+6qYVw4ne
|
||||
c0L7vRvw8HTjOJ9EQnPfID9+34Y8OQkqIHnnF80yjMGCdvh/tR/tXsUlz+Byt9m5MFdhPE22MX1x
|
||||
jyCJFug1Ufso8toAVZcavsRfX0ygeUkv+zZDZKHmF910rB8Cdb980cpKtFvx/v0BNWnzgAhgGkqO
|
||||
ttUf0PKUeGDIW6DMUKhs5JM7ED5rkepvNG5vePDVy/YidhbM4x1ph+HFVkHgT6rd1M4NeCm818C0
|
||||
MVsofXdOOdbjmkQyxPGukl9EG1ukYMfUIQpFozTbbHKNUDfqcdHu8Qm39K7opwxMOiLprXGRSgx2
|
||||
vMHI82mtAgMBAAGjggL6MIIC9jAQBgkrBgEEAYI3FQEEAwIBADAdBgNVHQ4EFgQU94Bw+7t8JXHx
|
||||
VZoWN/pFMo005ZwwGQYJKwYBBAGCNxQCBAweCgBTAHUAYgBDAEEwCwYDVR0PBAQDAgGGMA8GA1Ud
|
||||
EwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUyhZi1FybJBCYHcAPgM+Jq7Sv1dEwggEvBgNVHR8EggEm
|
||||
MIIBIjCCAR6gggEaoIIBFoaByGxkYXA6Ly8vQ049UFJJTUUlMjBDT05UUk9MUyUyMFJPT1QlMjBD
|
||||
QSxDTj1QUklNRS1ST09UQ0EsQ049Q0RQLENOPVB1YmxpYyUyMEtleSUyMFNlcnZpY2VzLENOPVNl
|
||||
cnZpY2VzLENOPUNvbmZpZ3VyYXRpb24sREM9cHJpbWUsREM9bG9jYWw/Y2VydGlmaWNhdGVSZXZv
|
||||
Y2F0aW9uTGlzdD9iYXNlP29iamVjdENsYXNzPWNSTERpc3RyaWJ1dGlvblBvaW50hklodHRwOi8v
|
||||
Y3JsLnByaW1lLWNvbnRyb2xzLmNvbS9DZXJ0RW5yb2xsL1BSSU1FJTIwQ09OVFJPTFMlMjBST09U
|
||||
JTIwQ0EuY3JsMIIBNAYIKwYBBQUHAQEEggEmMIIBIjCBuwYIKwYBBQUHMAKGga5sZGFwOi8vL0NO
|
||||
PVBSSU1FJTIwQ09OVFJPTFMlMjBST09UJTIwQ0EsQ049QUlBLENOPVB1YmxpYyUyMEtleSUyMFNl
|
||||
cnZpY2VzLENOPVNlcnZpY2VzLENOPUNvbmZpZ3VyYXRpb24sREM9cHJpbWUsREM9bG9jYWw/Y0FD
|
||||
ZXJ0aWZpY2F0ZT9iYXNlP29iamVjdENsYXNzPWNlcnRpZmljYXRpb25BdXRob3JpdHkwYgYIKwYB
|
||||
BQUHMAKGVmh0dHA6Ly9jcmwucHJpbWUtY29udHJvbHMuY29tL0NlcnRFbnJvbGwvUFJJTUUtUk9P
|
||||
VENBX1BSSU1FJTIwQ09OVFJPTFMlMjBST09UJTIwQ0EuY3J0MA0GCSqGSIb3DQEBCwUAA4ICAQAw
|
||||
2SIuBMB8JWC/YGbh3LJDt9T/z1BwEniLwEKu4SyBMfW3qJoLR0Zps8xHlCIlUjisZBSilHDNW4uW
|
||||
4891yqg104OR0dx94dQV2Y6Aw9V4tvlw+GGnWpHbUNwP3/JizlndR6ZdhdnJlIt6g7xCy4LwyXrw
|
||||
f22CibC1EWUVnsYJ8ez+LxSprWiUaEME8+bEaVuajXRitYyoG0asvtESeBhR3lwaxuzBqyAuGEfc
|
||||
P8pO/fgjigripPScXnp6opQRzZ12VSNsN8BUmtCfsqX8DK7iRsn/QLZtOKVf6kapPkorovetKwai
|
||||
wasE2mpKJweKYhGwWXdHrXZfCp6biTzG0oX4DGke7tHxdA92ArgmPR4SsNnpekUGcbUgkdpOc0sC
|
||||
mt+LXzRvFKJNd205u/FvpZlBzRZl+NQ++9OGAywyzOb4Lxli49G0yFQ5Fpq0UElqDKiLzUqUR2Ye
|
||||
qDT9nMJNTZEyP6hEjQQ+tSD9XFIlFWD83AyBHhRNKKZfPiu4mJxNYtW1ltVu5Z1EvBfbcRwc0lQa
|
||||
VKGQS23sSIx6heq2q5FqhnYZ15zSXqaAH680Up5mOkeGIfm45rMIFl/aMAJ2Fntl+Taebosf2rv5
|
||||
M/QOJs494ePbXxCJ1kzCLaqgucDXtadJ7ZV2AKhu3B9OiDrS8sv990Yn95ItlpthpVetiXxLHg==
|
||||
-----END CERTIFICATE-----
|
||||
@@ -1,66 +0,0 @@
|
||||
"""Safe HTTP responses for uploaded drawings — D19 (T16.2).
|
||||
|
||||
Security review 2026-10-01, SEC-01 and SEC-15e.
|
||||
|
||||
WHY THIS EXISTS
|
||||
Uploads accept `image/*`, which includes `image/svg+xml`. An SVG is a
|
||||
document, not a picture: it can carry <script>. GET /api/files/{id} used to
|
||||
return every file `inline` with the uploader's content type, on the app's own
|
||||
origin, so a script inside an SVG ran as whoever opened the drawing - with
|
||||
their session, and with an admin's power if an admin opened it.
|
||||
|
||||
The download name was built by hand with only `"` removed. A name outside
|
||||
Latin-1 (`Plan é.pdf`) made the header unencodable, so the download failed
|
||||
with 500; CR/LF in a name went into the header as typed.
|
||||
|
||||
THE RULE (D19, decided 2026-10-02)
|
||||
* PDF and raster images open INLINE, exactly as before. That is what the
|
||||
creator's drawing list, the printed package and Field View link to
|
||||
(CR-007), and the offline drawing cache in sw.js stores.
|
||||
* Every other type, SVG included, is an ATTACHMENT inside a sandbox: the
|
||||
browser saves it instead of rendering it on our origin, and
|
||||
`Content-Security-Policy: sandbox` strips script and same-origin access
|
||||
even if someone opens the saved response directly.
|
||||
* SVG UPLOADS STAY ACCEPTED (decided: accept, download only). The fix is on
|
||||
the way out, so SVGs already in the database are covered too.
|
||||
* `Cache-Control` is unchanged - the offline drawing cache depends on it.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from urllib.parse import quote
|
||||
|
||||
from fastapi.responses import Response
|
||||
|
||||
# Formats a browser shows as inert pixels, or in its own PDF viewer.
|
||||
INLINE_SAFE_MIME = frozenset({
|
||||
"application/pdf",
|
||||
"image/png", "image/jpeg", "image/gif", "image/webp", "image/bmp", "image/avif",
|
||||
})
|
||||
|
||||
# Control characters, and the characters that end or escape a quoted
|
||||
# header parameter. Replaced, never passed through.
|
||||
_UNSAFE_NAME = re.compile(r'[\x00-\x1f\x7f"\\;]')
|
||||
|
||||
|
||||
def content_disposition(disposition: str, name: str) -> str:
|
||||
"""A header value that is valid for ANY user-supplied file name: an ASCII
|
||||
fallback for old clients plus RFC 5987 `filename*` with the real name."""
|
||||
name = _UNSAFE_NAME.sub("_", name or "file").strip() or "file"
|
||||
ascii_name = name.encode("ascii", "replace").decode("ascii").replace("?", "_")
|
||||
return f"{disposition}; filename=\"{ascii_name}\"; filename*=UTF-8''{quote(name, safe='')}"
|
||||
|
||||
|
||||
def file_response(row) -> Response:
|
||||
"""The response for GET /api/files/{id}. `row` is a models.WpFile."""
|
||||
mime = (row.mime or "application/octet-stream").lower()
|
||||
headers = {
|
||||
"Cache-Control": "private, max-age=86400", # unchanged: sw.js caches drawings offline
|
||||
"X-Content-Type-Options": "nosniff", # NGINX adds it too; the dev server did not
|
||||
}
|
||||
if mime in INLINE_SAFE_MIME:
|
||||
headers["Content-Disposition"] = content_disposition("inline", row.name)
|
||||
else:
|
||||
headers["Content-Disposition"] = content_disposition("attachment", row.name)
|
||||
headers["Content-Security-Policy"] = "sandbox; default-src 'none'"
|
||||
return Response(content=row.data, media_type=mime, headers=headers)
|
||||
462
server/ldap_auth.py
Normal file
@@ -0,0 +1,462 @@
|
||||
"""LDAPS authentication against the Windows domain — D13, built in T10.1.
|
||||
|
||||
The suite stores no passwords. A sign-in is a **simple bind** to
|
||||
`ldaps://prime.local:636` as `<sAMAccountName>@prime.local` using the password the
|
||||
person typed; a successful bind IS the authentication. This module owns that
|
||||
conversation and nothing else — it does not touch the database, does not issue
|
||||
sessions, and does not decide what anyone is allowed to do. `server/auth.py` and
|
||||
the `login` route in `server/app.py` do that.
|
||||
|
||||
WHY `prime.local` AND NOT A DC NAME OR AN IP (this is load-bearing, do not "fix" it):
|
||||
every domain controller's certificate carries `prime.local` in its SAN alongside its
|
||||
own hostname, and the domain name round-robins in DNS across all six DCs published
|
||||
in `_ldap._tcp.prime.local`. So connecting to the domain name both passes hostname
|
||||
validation and gives failover in one move. Connecting to `192.168.3.37` instead
|
||||
fails with `hostname mismatch` — the DC certificates carry no IP SAN — and the only
|
||||
way to "fix" that is to disable the check, which is the one thing that must not
|
||||
happen here (see below).
|
||||
|
||||
THE CLIENT PRESENTS NO CERTIFICATE. This module is the TLS *client*; clients verify,
|
||||
they do not present. What it needs is a trust anchor: `PRIME CONTROLS ROOT CA` plus
|
||||
`PRIME CONTROLS ISSUING CA 1`, shipped as a PEM bundle at `server/certs/`. Those are
|
||||
public certificates — no private key, nothing secret, nothing issued to this app.
|
||||
|
||||
TWO WAYS THIS GOES CATASTROPHICALLY WRONG, both guarded here:
|
||||
|
||||
1. An EMPTY PASSWORD. In LDAP a simple bind with an empty password is an
|
||||
*anonymous* bind, and it SUCCEEDS. Without an explicit guard a blank password
|
||||
authenticates as whatever username was submitted. `verify()` therefore rejects
|
||||
an empty or whitespace-only password BEFORE `bind()` is ever called. If you are
|
||||
refactoring this file and that check looks redundant, it is not.
|
||||
|
||||
2. `validate=ssl.CERT_NONE`. It still encrypts, so it fails silently — what it
|
||||
loses is the ability to tell the real DC from someone who terminates the TLS
|
||||
session, harvests the domain password and relays the bind onward. Domain
|
||||
credentials cross this channel, so that turns an app compromise into a Windows
|
||||
compromise. `CERT_REQUIRED` with an explicit CA file is the only mode here, and
|
||||
the system trust store is deliberately NOT used: it currently trusts five other
|
||||
self-signed CAs on this estate, any of which could issue a DC-shaped cert.
|
||||
|
||||
FAILED BINDS COUNT AGAINST THE DOMAIN LOCKOUT POLICY. That is why nothing in here
|
||||
retries a rejected credential — only genuine network failures are retried, and a
|
||||
`bind()` that returns False is final. The caller throttles before it gets this far
|
||||
(T10.2); this module's job is not to make the problem worse.
|
||||
|
||||
Unconfigured is a first-class state, as it is for `MICRON_DB_URL` in `assets_db.py`:
|
||||
with no CA bundle or no `ldap3` installed, `is_configured()` is False and `verify()`
|
||||
returns `UNCONFIGURED` rather than raising. Since D13 leaves no local password
|
||||
fallback, the caller must surface that state loudly — an unconfigured deploy and a
|
||||
mistyped password look identical at the login box otherwise.
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
import re
|
||||
import ssl
|
||||
from dataclasses import dataclass
|
||||
from typing import Optional
|
||||
|
||||
log = logging.getLogger("wpsuite.ldap")
|
||||
|
||||
# ldap3 is pinned in requirements.txt. The import is guarded rather than assumed so
|
||||
# that this module — and the test suite that imports it — still loads on a checkout
|
||||
# where the dependency has not been installed. `is_configured()` reports the truth,
|
||||
# and the startup line from `describe()` says so out loud.
|
||||
try:
|
||||
from ldap3 import Server, Connection, Tls, SIMPLE, SUBTREE, NONE
|
||||
from ldap3.core.exceptions import (
|
||||
LDAPException,
|
||||
LDAPSocketOpenError,
|
||||
LDAPSessionTerminatedByServerError,
|
||||
LDAPCertificateError,
|
||||
)
|
||||
from ldap3.utils.conv import escape_filter_chars
|
||||
HAVE_LDAP3 = True
|
||||
except ImportError: # pragma: no cover
|
||||
HAVE_LDAP3 = False
|
||||
LDAPException = LDAPSocketOpenError = Exception
|
||||
LDAPSessionTerminatedByServerError = LDAPCertificateError = Exception
|
||||
|
||||
def escape_filter_chars(x, encoding=None): # type: ignore[misc]
|
||||
raise RuntimeError("ldap3 is not installed")
|
||||
|
||||
|
||||
# ── configuration ─────────────────────────────────────────────────────────────
|
||||
# Module level, matching how server/auth.py reads AUTH_SESSION_HOURS. Tests patch
|
||||
# these attributes directly rather than re-importing.
|
||||
DOMAIN = os.getenv("LDAP_DOMAIN", "prime.local")
|
||||
# Defaults to the domain name on purpose — see the module docstring. Override only
|
||||
# if you have a reason, and never with an IP address.
|
||||
HOST = os.getenv("LDAP_HOST", "") or DOMAIN
|
||||
PORT = int(os.getenv("LDAP_PORT", "636"))
|
||||
CA_FILE = os.getenv("LDAP_CA_FILE", "") or os.path.join(
|
||||
os.path.dirname(os.path.abspath(__file__)), "certs", "prime-ca-chain.pem"
|
||||
)
|
||||
TIMEOUT_SECONDS = int(os.getenv("LDAP_TIMEOUT_SECONDS", "8"))
|
||||
# Retries apply to CONNECT failures only, never to a rejected credential. Two extra
|
||||
# attempts covers the realistic case: DNS round-robin handed out a DC that is
|
||||
# rebooting for patching.
|
||||
CONNECT_RETRIES = int(os.getenv("LDAP_CONNECT_RETRIES", "2"))
|
||||
# The initial value and the fallback for the admin-console setting added in T10.5.
|
||||
REQUIRED_GROUP = os.getenv("LDAP_REQUIRED_GROUP", "")
|
||||
|
||||
# AD's "member of, transitively" extensible match. Plain `memberOf` is DIRECT
|
||||
# membership only and would wrongly refuse anyone who is in a nested child group,
|
||||
# which is how most estates actually organise access.
|
||||
NESTED_MEMBER_RULE = "1.2.840.113556.1.4.1941"
|
||||
|
||||
_USER_ATTRS = ["sAMAccountName", "mail", "displayName", "userPrincipalName"]
|
||||
|
||||
# Reason codes. Machine-readable, for logs and for the caller's branching — never
|
||||
# for a response body, because several of them would leak whether an account exists.
|
||||
OK = "ok"
|
||||
EMPTY_INPUT = "empty_input"
|
||||
UNCONFIGURED = "unconfigured"
|
||||
UNREACHABLE = "unreachable"
|
||||
UNTRUSTED = "untrusted"
|
||||
BAD_CREDENTIALS = "bad_credentials"
|
||||
NOT_IN_GROUP = "not_in_group"
|
||||
NO_DIRECTORY_ENTRY = "no_directory_entry"
|
||||
GROUP_NOT_FOUND = "group_not_found"
|
||||
GROUP_CHECK_FAILED = "group_check_failed"
|
||||
|
||||
# AD returns these as `data <code>` inside an error-49 message. Kept for the log
|
||||
# only: telling an unauthenticated caller "your password expired" confirms the
|
||||
# account exists, which `login()` goes out of its way not to do.
|
||||
_ERR49 = {
|
||||
"525": "no such user",
|
||||
"52e": "bad password",
|
||||
"530": "not permitted at this time",
|
||||
"531": "not permitted at this workstation",
|
||||
"532": "password expired",
|
||||
"533": "account disabled",
|
||||
"701": "account expired",
|
||||
"773": "must change password",
|
||||
"775": "account locked out",
|
||||
}
|
||||
_ERR49_RE = re.compile(r"data\s+([0-9a-fA-F]{3})")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LdapResult:
|
||||
"""Outcome of a bind attempt.
|
||||
|
||||
`ok` is the only field the caller should branch on for allow/deny. `reason` and
|
||||
`detail` are for logs. `sam`/`mail`/`full_name` are populated only on success and
|
||||
are what T10.4 uses to match or provision the local account.
|
||||
"""
|
||||
ok: bool
|
||||
reason: str = ""
|
||||
detail: str = ""
|
||||
sam: str = ""
|
||||
mail: str = ""
|
||||
full_name: str = ""
|
||||
upn: str = ""
|
||||
|
||||
@property
|
||||
def is_config_problem(self) -> bool:
|
||||
"""True when the failure is ours, not the user's. With no local password
|
||||
fallback (D13) these must be logged as errors and surfaced to an operator —
|
||||
otherwise a broken deploy is indistinguishable from a forgotten password."""
|
||||
return self.reason in (UNCONFIGURED, UNREACHABLE, UNTRUSTED, GROUP_NOT_FOUND,
|
||||
GROUP_CHECK_FAILED)
|
||||
|
||||
|
||||
def base_dn(domain: Optional[str] = None) -> str:
|
||||
"""`prime.local` -> `DC=prime,DC=local`."""
|
||||
d = (domain or DOMAIN or "").strip().strip(".")
|
||||
return ",".join(f"DC={part}" for part in d.split(".") if part)
|
||||
|
||||
|
||||
def is_configured() -> bool:
|
||||
"""Whether a bind could even be attempted. Deliberately does not touch the
|
||||
network — `selftest()` does that."""
|
||||
return bool(HAVE_LDAP3 and HOST and CA_FILE and os.path.isfile(CA_FILE))
|
||||
|
||||
|
||||
def describe() -> str:
|
||||
"""One line for the startup log. D13 removed the local password path, so an
|
||||
operator needs to see this in `docker compose logs api` rather than discovering
|
||||
it when the first person cannot sign in."""
|
||||
from . import ldap_fake
|
||||
if ldap_fake.is_active():
|
||||
return ("*** FAKE DIRECTORY ACTIVE — passwords come from "
|
||||
f"{ldap_fake.ENV_VAR}, NOT from the domain. Tests only. ***")
|
||||
if not HAVE_LDAP3:
|
||||
return "LDAP auth DISABLED — ldap3 is not installed. No one can sign in."
|
||||
if not CA_FILE or not os.path.isfile(CA_FILE):
|
||||
return (f"LDAP auth DISABLED — CA bundle not found at {CA_FILE!r}. "
|
||||
f"No one can sign in. Set LDAP_CA_FILE.")
|
||||
group = REQUIRED_GROUP or "(none configured — every domain account may sign in)"
|
||||
return (f"LDAP auth enabled — ldaps://{HOST}:{PORT}, domain {DOMAIN}, "
|
||||
f"CA {CA_FILE}, required group: {group}")
|
||||
|
||||
|
||||
def _tls() -> "Tls":
|
||||
"""The only TLS configuration in this module.
|
||||
|
||||
`CERT_REQUIRED` plus an explicit `ca_certs_file`. ldap3 performs the hostname
|
||||
check against the certificate's SAN itself whenever validate is not CERT_NONE,
|
||||
which is what makes connecting by IP fail instead of quietly succeeding.
|
||||
"""
|
||||
# No `version=` pin: ldap3's default negotiates the highest version both ends
|
||||
# support, which against these DCs is TLS 1.3. Pinning PROTOCOL_TLSv1_2 here
|
||||
# would silently DOWNGRADE every connection to 1.2.
|
||||
return Tls(
|
||||
ca_certs_file=CA_FILE,
|
||||
validate=ssl.CERT_REQUIRED,
|
||||
)
|
||||
|
||||
|
||||
def _server() -> "Server":
|
||||
return Server(
|
||||
HOST, port=PORT, use_ssl=True, tls=_tls(),
|
||||
connect_timeout=TIMEOUT_SECONDS, get_info=NONE,
|
||||
)
|
||||
|
||||
|
||||
def _err49(result: Optional[dict]) -> str:
|
||||
"""Human-readable AD sub-code from a bind failure, for the log only."""
|
||||
msg = ((result or {}).get("message") or "")
|
||||
m = _ERR49_RE.search(msg)
|
||||
if not m:
|
||||
return ((result or {}).get("description") or "invalid credentials")
|
||||
code = m.group(1).lower()
|
||||
return f"{code} ({_ERR49.get(code, 'unrecognised sub-code')})"
|
||||
|
||||
|
||||
def normalize_username(raw: str) -> str:
|
||||
"""Reduce whatever was typed in the login box to a `sAMAccountName`.
|
||||
|
||||
People type their email address. The mail domain here (`prime-controls.com`) is
|
||||
not the AD domain (`prime.local`), so an address is never a valid bind string —
|
||||
the local part is used instead. This assumes the mail local part equals the
|
||||
sAMAccountName, which is the norm but not guaranteed; where it differs the person
|
||||
must type their short logon name, and we log it so that is diagnosable.
|
||||
|
||||
ONE candidate is produced, never a list to try in turn: every rejected bind
|
||||
counts against the domain lockout policy, so guessing would let a handful of
|
||||
login attempts lock a real account out of Windows.
|
||||
"""
|
||||
name = (raw or "").strip()
|
||||
if not name:
|
||||
return ""
|
||||
# DOMAIN\user, as typed by anyone used to a Windows logon prompt.
|
||||
if "\\" in name:
|
||||
name = name.rsplit("\\", 1)[1].strip()
|
||||
if "@" in name:
|
||||
local, _, dom = name.partition("@")
|
||||
log.info("login input %r looks like an address; binding as sAMAccountName %r "
|
||||
"(mail domain %r is not the AD domain)", name, local.strip(), dom)
|
||||
name = local.strip()
|
||||
return name
|
||||
|
||||
|
||||
def _resolve_group_dn(conn, group: str) -> Optional[str]:
|
||||
"""Accept either a distinguished name or a plain group name, return a DN."""
|
||||
g = (group or "").strip()
|
||||
if not g:
|
||||
return None
|
||||
if "," in g and "=" in g:
|
||||
return g # already a DN
|
||||
esc = escape_filter_chars(g)
|
||||
conn.search(base_dn(), f"(&(objectClass=group)(|(cn={esc})(sAMAccountName={esc})))",
|
||||
search_scope=SUBTREE, attributes=["cn"], size_limit=2)
|
||||
if not conn.entries:
|
||||
return None
|
||||
if len(conn.entries) > 1:
|
||||
log.warning("group %r is ambiguous in the directory (%d matches); using %s",
|
||||
g, len(conn.entries), conn.entries[0].entry_dn)
|
||||
return conn.entries[0].entry_dn
|
||||
|
||||
|
||||
def member_of(conn, sam: str, group: str) -> bool:
|
||||
"""Is `sam` in `group`, counting nested membership?
|
||||
|
||||
THE RETURN VALUE OF conn.search() IS NOT OPTIONAL READING. The connection is
|
||||
built with raise_exceptions=False, so a search that FAILS returns False and
|
||||
leaves conn.entries empty — which is byte-for-byte indistinguishable from "no
|
||||
match" if you only look at conn.entries. An earlier version of this function did
|
||||
exactly that, and every failure of the extensible-match filter presented to the
|
||||
user as "you are not in the group" while they plainly were.
|
||||
|
||||
Two searches, in order, and the second one exists to catch the first being wrong:
|
||||
|
||||
1. AD's transitive matching rule (LDAP_MATCHING_RULE_IN_CHAIN). This is the
|
||||
correct query — it walks nested groups, which plain memberOf does not.
|
||||
2. If that matches nothing, a plain memberOf equality check for DIRECT
|
||||
membership.
|
||||
|
||||
If (2) matches after (1) did not, the person IS a member and is let in — refusing
|
||||
a real member is the worse error — but it is logged as a WARNING, because it means
|
||||
the transitive rule is returning nothing and NESTED membership is silently not
|
||||
working on this connection. That needs a human; it must not pass unnoticed.
|
||||
"""
|
||||
dn = _resolve_group_dn(conn, group)
|
||||
if not dn:
|
||||
log.error("required group %r does not resolve in %s — refusing the sign-in. "
|
||||
"This is a configuration fault, not a bad password.", group, base_dn())
|
||||
raise LookupError(GROUP_NOT_FOUND)
|
||||
|
||||
esc_sam, esc_dn = escape_filter_chars(sam), escape_filter_chars(dn)
|
||||
|
||||
def _search(filt: str, label: str):
|
||||
ok = conn.search(base_dn(), filt, search_scope=SUBTREE,
|
||||
attributes=["sAMAccountName"], size_limit=1)
|
||||
if not ok:
|
||||
log.error("the %s membership search FAILED (not 'no match') for %r: %s | "
|
||||
"filter=%s", label, sam, conn.result, filt)
|
||||
raise LookupError(GROUP_CHECK_FAILED)
|
||||
return bool(conn.entries)
|
||||
|
||||
if _search(f"(&(sAMAccountName={esc_sam})(memberOf:{NESTED_MEMBER_RULE}:={esc_dn}))",
|
||||
"nested"):
|
||||
return True
|
||||
|
||||
if _search(f"(&(sAMAccountName={esc_sam})(memberOf={esc_dn}))", "direct"):
|
||||
log.warning(
|
||||
"%r IS a direct member of %r, but AD's transitive matching rule "
|
||||
"(%s) returned nothing for them. Allowing the sign-in — refusing a real "
|
||||
"member is worse — but NESTED group membership is not working on this "
|
||||
"connection and needs investigating.", sam, dn, NESTED_MEMBER_RULE)
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def verify(username: str, password: str, required_group: Optional[str] = None) -> LdapResult:
|
||||
"""Authenticate against the domain. The only entry point the app should call.
|
||||
|
||||
`required_group` overrides the `LDAP_REQUIRED_GROUP` default so the admin-console
|
||||
setting (T10.5) wins. Pass an empty string to mean "no group gate"; pass None to
|
||||
use the configured default.
|
||||
"""
|
||||
sam = normalize_username(username)
|
||||
|
||||
# ── guard 1: no bind on empty input ──────────────────────────────────────
|
||||
# An empty password makes the bind below an ANONYMOUS bind, which SUCCEEDS and
|
||||
# would authenticate `sam` without proving anything at all. Must stay before
|
||||
# every return path that reaches bind().
|
||||
if not sam or not (password or "").strip():
|
||||
return LdapResult(False, EMPTY_INPUT, "empty username or password")
|
||||
|
||||
group = REQUIRED_GROUP if required_group is None else required_group
|
||||
|
||||
# Test seam (T10.7). Deliberately placed AFTER the empty-input guard above, so
|
||||
# the anonymous-bind guard covers the fake path too — a fake that re-implemented
|
||||
# it would let the real one rot without any test noticing. `is_active()` refuses
|
||||
# whenever a non-SQLite DATABASE_URL is configured; see server/ldap_fake.py.
|
||||
from . import ldap_fake
|
||||
if ldap_fake.is_active():
|
||||
ok, reason, attrs = ldap_fake.lookup(sam, password, group)
|
||||
if not ok:
|
||||
log.info("fake directory refused %r: %s", sam, reason)
|
||||
return LdapResult(False, reason, "fake directory")
|
||||
return LdapResult(True, OK, "fake directory", **attrs)
|
||||
|
||||
if not is_configured():
|
||||
return LdapResult(False, UNCONFIGURED, describe())
|
||||
|
||||
bind_user = f"{sam}@{DOMAIN}"
|
||||
last_network_error = ""
|
||||
|
||||
# Retries cover CONNECT failures only: DNS round-robin across six DCs will
|
||||
# eventually hand out one that is rebooting. A rejected credential returns
|
||||
# immediately and is never retried — each attempt counts against AD lockout.
|
||||
for attempt in range(1, max(1, CONNECT_RETRIES + 1) + 1):
|
||||
conn = None
|
||||
try:
|
||||
conn = Connection(
|
||||
_server(), user=bind_user, password=password,
|
||||
authentication=SIMPLE, read_only=True,
|
||||
receive_timeout=TIMEOUT_SECONDS, raise_exceptions=False,
|
||||
)
|
||||
if not conn.bind():
|
||||
detail = _err49(conn.result)
|
||||
log.warning("bind refused for %r: %s", sam, detail)
|
||||
return LdapResult(False, BAD_CREDENTIALS, detail)
|
||||
|
||||
# Bound as the user. AD lets an account read its own object, so no
|
||||
# service account is needed for either of the next two steps.
|
||||
conn.search(base_dn(),
|
||||
f"(&(objectClass=user)(sAMAccountName={escape_filter_chars(sam)}))",
|
||||
search_scope=SUBTREE, attributes=_USER_ATTRS, size_limit=1)
|
||||
if not conn.entries:
|
||||
log.error("bind succeeded for %r but the account has no readable "
|
||||
"directory entry under %s", sam, base_dn())
|
||||
return LdapResult(False, NO_DIRECTORY_ENTRY, "no readable directory entry")
|
||||
e = conn.entries[0]
|
||||
|
||||
def one(attr: str) -> str:
|
||||
v = getattr(e, attr, None)
|
||||
return str(v.value) if v is not None and v.value else ""
|
||||
|
||||
if group:
|
||||
try:
|
||||
if not member_of(conn, sam, group):
|
||||
log.warning("bind succeeded for %r but the account is NOT in %r",
|
||||
sam, group)
|
||||
return LdapResult(False, NOT_IN_GROUP, f"not in {group}")
|
||||
except LookupError as exc:
|
||||
reason = str(exc) or GROUP_NOT_FOUND
|
||||
return LdapResult(False, reason, f"group {group!r}: {reason}")
|
||||
|
||||
return LdapResult(
|
||||
True, OK,
|
||||
sam=one("sAMAccountName") or sam,
|
||||
mail=one("mail"),
|
||||
full_name=one("displayName"),
|
||||
upn=one("userPrincipalName"),
|
||||
)
|
||||
|
||||
except LDAPCertificateError as exc:
|
||||
# NOT retried and NOT downgraded. Either the CA bundle is wrong or
|
||||
# something is impersonating a DC; both need a human, and retrying with
|
||||
# relaxed validation is exactly the wrong instinct.
|
||||
log.error("LDAPS certificate validation FAILED against %s: %s. Refusing "
|
||||
"to continue — check LDAP_CA_FILE, and never set CERT_NONE.",
|
||||
HOST, exc)
|
||||
return LdapResult(False, UNTRUSTED, str(exc))
|
||||
except (LDAPSocketOpenError, LDAPSessionTerminatedByServerError) as exc:
|
||||
last_network_error = str(exc)
|
||||
log.warning("LDAPS connect to %s:%s failed (attempt %d): %s",
|
||||
HOST, PORT, attempt, exc)
|
||||
continue
|
||||
except LDAPException as exc:
|
||||
log.error("LDAP error for %r: %s", sam, exc)
|
||||
return LdapResult(False, UNREACHABLE, str(exc))
|
||||
finally:
|
||||
if conn is not None:
|
||||
try:
|
||||
conn.unbind()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return LdapResult(False, UNREACHABLE,
|
||||
last_network_error or f"no domain controller answered on {HOST}:{PORT}")
|
||||
|
||||
|
||||
def selftest() -> LdapResult:
|
||||
"""Open a TLS session to the domain and validate the certificate, WITHOUT binding.
|
||||
|
||||
Used by the startup check and by the admin console's diagnostics. Touches no
|
||||
account, so it cannot contribute to a lockout. Proves the three things that
|
||||
actually break a deploy: DNS resolves, a DC answers on 636, and the presented
|
||||
certificate validates against our CA bundle.
|
||||
"""
|
||||
if not is_configured():
|
||||
return LdapResult(False, UNCONFIGURED, describe())
|
||||
conn = None
|
||||
try:
|
||||
conn = Connection(_server(), receive_timeout=TIMEOUT_SECONDS, raise_exceptions=True)
|
||||
conn.open()
|
||||
return LdapResult(True, OK, f"ldaps://{HOST}:{PORT} certificate validates")
|
||||
except LDAPCertificateError as exc:
|
||||
return LdapResult(False, UNTRUSTED, str(exc))
|
||||
except LDAPException as exc:
|
||||
return LdapResult(False, UNREACHABLE, str(exc))
|
||||
finally:
|
||||
if conn is not None:
|
||||
try:
|
||||
conn.unbind()
|
||||
except Exception:
|
||||
pass
|
||||
95
server/ldap_fake.py
Normal file
@@ -0,0 +1,95 @@
|
||||
"""A fake directory, for tests only — D13 / T10.7.
|
||||
|
||||
`server/ldap_auth.py` normally opens an LDAPS connection to a domain controller.
|
||||
Tests cannot: CI has no domain, and the browser checks launch the app as a
|
||||
SUBPROCESS (`start_server` in tests/browser_check.py), so a monkeypatch in the
|
||||
test process would never reach the code doing the authenticating. The seam has to
|
||||
be configurable from the ENVIRONMENT, which is what this module is.
|
||||
|
||||
Set `WP_LDAP_FAKE_DIRECTORY` to a JSON object and `ldap_auth.verify()` answers
|
||||
from it instead of touching the network:
|
||||
|
||||
{"root": {"password": "…", "mail": "root@example.test",
|
||||
"full_name": "Root", "groups": ["WP-Suite-Users"]}}
|
||||
|
||||
`groups` is a flat list of names the account is "in". Nested groups do not exist
|
||||
here — the real `member_of` resolves a DN and uses AD's LDAP_MATCHING_RULE_IN_CHAIN,
|
||||
and faking that faithfully would mean reimplementing AD. A test that cares about
|
||||
nesting has to run against a real directory; this one is honest about being a
|
||||
string comparison.
|
||||
|
||||
THE PRODUCTION GUARD IS THE POINT OF THIS FILE.
|
||||
|
||||
An environment variable that makes any password work is exactly the kind of thing
|
||||
that escapes into production, and D13 removed every other way in — there is no
|
||||
local password to fall back on and no break-glass, so a fake directory silently
|
||||
active in production would be a total authentication bypass with nothing behind it.
|
||||
|
||||
So `is_active()` refuses whenever a real database is configured, using the same
|
||||
test `auth._load_secret` uses to refuse an ephemeral signing key: a non-SQLite
|
||||
`DATABASE_URL` means production, full stop. `ldap_auth.describe()` also shouts
|
||||
when the fake is live, so the startup line can never be mistaken for a real one.
|
||||
"""
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
from typing import Optional
|
||||
|
||||
log = logging.getLogger("wpsuite.ldap.fake")
|
||||
|
||||
ENV_VAR = "WP_LDAP_FAKE_DIRECTORY"
|
||||
|
||||
|
||||
def _raw() -> str:
|
||||
return os.getenv(ENV_VAR, "").strip()
|
||||
|
||||
|
||||
def is_active() -> bool:
|
||||
"""Whether the fake should answer. False in anything resembling production."""
|
||||
if not _raw():
|
||||
return False
|
||||
# Imported lazily: server.db reads DATABASE_URL at import, and this module is
|
||||
# imported from ldap_auth, which must stay importable on its own.
|
||||
from .db import DATABASE_URL
|
||||
if not str(DATABASE_URL).startswith("sqlite"):
|
||||
log.error(
|
||||
"%s is set but a non-SQLite DATABASE_URL is configured. REFUSING to use "
|
||||
"the fake directory — this looks like production, and D13 leaves no "
|
||||
"other way in, so honouring it would be an authentication bypass. "
|
||||
"Unset %s.", ENV_VAR, ENV_VAR)
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def directory() -> dict:
|
||||
try:
|
||||
data = json.loads(_raw())
|
||||
if not isinstance(data, dict):
|
||||
raise ValueError("top level must be an object")
|
||||
return data
|
||||
except Exception as exc: # noqa: BLE001 — a malformed fake must not look like a bad password
|
||||
log.error("%s is not valid JSON (%s); the fake directory is empty", ENV_VAR, exc)
|
||||
return {}
|
||||
|
||||
|
||||
def lookup(username: str, password: str, required_group: Optional[str]) -> tuple:
|
||||
"""Return (ok, reason, attrs). Mirrors what ldap_auth.verify() needs.
|
||||
|
||||
Deliberately does NOT re-check for an empty password: `verify()` guards that
|
||||
before it ever gets here, and duplicating the check in the fake would let the
|
||||
real guard rot without any test noticing.
|
||||
"""
|
||||
people = directory()
|
||||
who = people.get(username) or people.get(username.lower())
|
||||
if not isinstance(who, dict) or password != who.get("password"):
|
||||
return (False, "bad_credentials", {})
|
||||
if required_group:
|
||||
groups = who.get("groups") or []
|
||||
if required_group not in groups:
|
||||
return (False, "not_in_group", {})
|
||||
return (True, "ok", {
|
||||
"sam": who.get("sam") or username,
|
||||
"mail": who.get("mail", ""),
|
||||
"full_name": who.get("full_name", ""),
|
||||
"upn": who.get("upn", ""),
|
||||
})
|
||||
@@ -1,107 +1,224 @@
|
||||
"""Command-line user management for the Work Package Suite.
|
||||
|
||||
There is no local password (D15) and no local account creation from here anymore
|
||||
(D16, T10.4) — accounts are created by signing in through Okta, which JIT-
|
||||
provisions a row at the lowest-privilege role (see server/okta_auth.py,
|
||||
server/app.py's okta_callback(), wave-10.md T10.3). This tool's job is narrower
|
||||
now: change the role on an account that already exists, and do routine account
|
||||
maintenance from a shell on the server.
|
||||
Accounts are not created here any more. D13 provisions them on first successful
|
||||
sign-in, so this tool exists to do the one thing the directory cannot decide:
|
||||
assign the app's PERMISSIONS role. The directory supplies identity; this supplies
|
||||
authorization.
|
||||
|
||||
That narrower job is still how the very first admin gets named (D16): have that
|
||||
person sign in through Okta once — they land as project_user — then promote them
|
||||
from here. Promoting an existing row, rather than creating one blind, matters
|
||||
because it never has to guess the exact string Okta will send as the identity
|
||||
claim; a hand-typed username that doesn't match it exactly would just produce a
|
||||
second, orphaned account instead of the one you meant to promote.
|
||||
|
||||
Run from the PROJECT ROOT (same place you run uvicorn), so the package imports
|
||||
and .env resolve the same way the API does:
|
||||
|
||||
python -m server.manage_users promote alice --role admin
|
||||
python -m server.manage_users list
|
||||
python -m server.manage_users promote alice # -> admin
|
||||
python -m server.manage_users promote bob --role project_admin
|
||||
python -m server.manage_users demote alice # -> project_user
|
||||
python -m server.manage_users disable bob
|
||||
python -m server.manage_users enable bob
|
||||
|
||||
Run from the PROJECT ROOT (same place you run uvicorn) so the package imports and
|
||||
.env resolve the way the API does.
|
||||
|
||||
`create-admin` and `create` are GONE (D14). They were redundant once accounts
|
||||
provision themselves, and removing them closes a whole class of problem: every
|
||||
row now originates from a successful bind, so a username can no longer be typed
|
||||
in wrong and end up orphaned from the directory identity it was meant to match.
|
||||
|
||||
BOOTSTRAPPING THE FIRST ADMIN is therefore two steps, in this order:
|
||||
1. Sign in to the app once. That provisions your account at project_user.
|
||||
2. Run `promote <your-sAMAccountName>` here.
|
||||
|
||||
EVERY COMMAND THAT CHANGES ANYTHING REQUIRES A DOMAIN BIND (D14). Shell access
|
||||
alone is no longer enough to mint an admin. Be clear about what that is and is
|
||||
not worth: anyone with a shell on this container can still write to the `users`
|
||||
table directly with psql or sqlite3, so this is defence in depth and — mostly —
|
||||
ACCOUNTABILITY. Before D14 every role change made from a shell was invisible in
|
||||
the audit trail while the same change through the console was recorded. Now both
|
||||
are recorded, and both name a person.
|
||||
|
||||
The bind here deliberately does NOT apply the login group gate. If a mistyped
|
||||
required group locks everyone out of the console, this tool has to still work —
|
||||
otherwise the only way to fix the lockout is the only thing the lockout prevents.
|
||||
|
||||
`list` needs no credential, so an outage stays diagnosable.
|
||||
"""
|
||||
import argparse
|
||||
import getpass
|
||||
import sys
|
||||
import uuid
|
||||
|
||||
from .db import SessionLocal, Base, engine
|
||||
from . import models, auth
|
||||
from . import models, auth, ldap_auth
|
||||
|
||||
|
||||
def cmd_promote(args) -> None:
|
||||
role = args.role
|
||||
# 'user' is the pre-roles spelling of 'project_user', accepted here so a
|
||||
# documented one-liner from before this rework keeps working.
|
||||
if role == "user":
|
||||
role = auth.ROLE_PROJECT_USER
|
||||
if role not in auth.ROLES:
|
||||
sys.exit(f"role must be one of {', '.join(auth.ROLES)}")
|
||||
with SessionLocal() as db:
|
||||
u = auth.find_user(db, args.username)
|
||||
if not u:
|
||||
sys.exit(
|
||||
f"No user named '{args.username}'. This promotes an existing account, it "
|
||||
f"doesn't create one — they need to sign in through Okta at least once first."
|
||||
)
|
||||
old_role = u.role
|
||||
u.role = role
|
||||
# Audited the same way a role change from the web Admin Console already is
|
||||
# (server/app.py's set_user_role() -> log_event(), action "role_changed") —
|
||||
# this command changes the same field and previously left no record of who
|
||||
# ran it or what it changed (T10.10). "actor" can't name a real person here:
|
||||
# a container shell exec carries no signed-in identity to attribute it to,
|
||||
# so it's tagged as the tool itself rather than guessing. "via" mirrors JIT
|
||||
# provisioning's own tag on user_created events.
|
||||
db.add(models.AuditLog(
|
||||
id=f"ev_{uuid.uuid4().hex[:12]}",
|
||||
actor="cli:manage_users",
|
||||
action="role_changed",
|
||||
entity_type="user",
|
||||
entity_id=u.id,
|
||||
summary=u.username,
|
||||
detail={"from": old_role, "to": role, "via": "cli"},
|
||||
))
|
||||
db.commit()
|
||||
print(f"{u.username} is now {auth.ROLE_LABELS.get(role, role)}.")
|
||||
def _gen_id(prefix: str = "user") -> str:
|
||||
return f"{prefix}_{uuid.uuid4().hex[:12]}"
|
||||
|
||||
|
||||
def _audit(db, actor: str, action: str, user: "models.User", detail: dict) -> None:
|
||||
"""Append an audit row in the caller's transaction.
|
||||
|
||||
Written by hand rather than via app.py's log_event: importing that would drag
|
||||
FastAPI and the entire application into a CLI startup for one INSERT.
|
||||
"""
|
||||
db.add(models.AuditLog(
|
||||
id=_gen_id("ev"), actor=actor, action=action, entity_type="user",
|
||||
entity_id=user.id, summary=user.username, detail=detail,
|
||||
))
|
||||
|
||||
|
||||
def authenticate_operator() -> str:
|
||||
"""Prompt for a domain credential, bind, and return the operator's sAMAccountName.
|
||||
|
||||
Exits on failure — a command that changes a role must not proceed unauthenticated.
|
||||
The password is only ever read from a hidden prompt: there is no --password flag,
|
||||
because that would put a live domain password into shell history and into the
|
||||
output of `ps` for every other user on the box.
|
||||
"""
|
||||
if not ldap_auth.is_configured():
|
||||
sys.exit(f"Cannot authenticate: {ldap_auth.describe()}\n"
|
||||
f"This command needs a domain bind. Fix the LDAP configuration first.")
|
||||
who = input("Your domain username: ").strip()
|
||||
if not who:
|
||||
sys.exit("Cancelled.")
|
||||
pw = getpass.getpass("Your domain password: ")
|
||||
if not pw:
|
||||
sys.exit("Cancelled.")
|
||||
# required_group="" on purpose: see the module docstring. The login group must
|
||||
# not be able to lock an operator out of the tool that fixes the login group.
|
||||
result = ldap_auth.verify(who, pw, required_group="")
|
||||
if not result.ok:
|
||||
# SAY WHY. The /api/auth/login endpoint deliberately returns one generic
|
||||
# message so an unauthenticated caller cannot enumerate accounts; that
|
||||
# reasoning does NOT transfer here. This is a local tool, the operator is
|
||||
# the account holder, and there is nobody to leak to — so withholding the
|
||||
# AD sub-code only makes a failure undiagnosable. An earlier version of
|
||||
# this function printed "Authentication failed." and nothing else.
|
||||
print(f"Authentication failed: {result.reason} — {result.detail}", file=sys.stderr)
|
||||
print(f" bind attempted as : {ldap_auth.normalize_username(who)}@{ldap_auth.DOMAIN}",
|
||||
file=sys.stderr)
|
||||
print(f" server : ldaps://{ldap_auth.HOST}:{ldap_auth.PORT}", file=sys.stderr)
|
||||
print(f" password length : {len(pw)} characters", file=sys.stderr)
|
||||
if result.reason == ldap_auth.BAD_CREDENTIALS:
|
||||
print(" The sub-code above is AD's own reason: 52e = wrong password, "
|
||||
"775 = account locked out, 532 = password expired, "
|
||||
"533 = account disabled, 525 = no such user.", file=sys.stderr)
|
||||
print(" A 525 with a password you know is correct means the BIND NAME is "
|
||||
"wrong, not the password. This binds as <sAMAccountName>@LDAP_DOMAIN, "
|
||||
"which only works where that matches your real UPN suffix — set "
|
||||
"LDAP_DOMAIN to the UPN suffix if yours differs from the AD DNS name.",
|
||||
file=sys.stderr)
|
||||
sys.exit(1)
|
||||
print(f"Authenticated as {result.sam}.")
|
||||
return result.sam
|
||||
|
||||
|
||||
def _load(db, username: str) -> "models.User":
|
||||
u = auth.find_user(db, username)
|
||||
if not u:
|
||||
sys.exit(f"No account named '{username}'. Accounts are created on first "
|
||||
f"sign-in — has this person signed in yet? `list` shows who exists.")
|
||||
return u
|
||||
|
||||
|
||||
def cmd_list(args) -> None:
|
||||
"""Read-only, and deliberately needs no credential: during an outage this is
|
||||
how you find out what the app thinks the world looks like."""
|
||||
with SessionLocal() as db:
|
||||
rows = db.query(models.User).order_by(models.User.username).all()
|
||||
if not rows:
|
||||
print("No users yet. Accounts appear here once someone signs in through Okta.")
|
||||
print("No accounts yet. They are created on first successful sign-in.")
|
||||
return
|
||||
print(f"{'USERNAME':<24}{'ROLE':<20}{'ACTIVE':<8}{'NAME'}")
|
||||
print(f"{'USERNAME':<24}{'ROLE':<20}{'ACTIVE':<8}{'LAST LOGIN':<22}{'NAME'}")
|
||||
for u in rows:
|
||||
last = u.last_login_at.strftime("%Y-%m-%d %H:%M") if u.last_login_at else "never"
|
||||
print(f"{u.username:<24}{auth.normalize_role(u.role):<20}"
|
||||
f"{('yes' if u.is_active else 'no'):<8}{u.full_name}")
|
||||
f"{('yes' if u.is_active else 'no'):<8}{last:<22}{u.full_name}")
|
||||
|
||||
|
||||
def _set_role(username: str, role: str) -> None:
|
||||
if role not in auth.ROLES:
|
||||
sys.exit(f"role must be one of {', '.join(auth.ROLES)}")
|
||||
operator = authenticate_operator()
|
||||
with SessionLocal() as db:
|
||||
u = _load(db, username)
|
||||
old = auth.normalize_role(u.role)
|
||||
if old == role:
|
||||
print(f"{u.username} is already {role}. Nothing to do.")
|
||||
return
|
||||
# The last-admin guard, matching set_user_role in app.py: an app with no
|
||||
# admin cannot be administered, and there is no password login left to
|
||||
# recover through.
|
||||
if old == auth.ROLE_ADMIN and role != auth.ROLE_ADMIN:
|
||||
others = db.query(models.User).filter(
|
||||
models.User.role == auth.ROLE_ADMIN,
|
||||
models.User.id != u.id,
|
||||
models.User.is_active.is_(True),
|
||||
).count()
|
||||
if not others:
|
||||
sys.exit("Refusing: that is the last active admin account. Promote "
|
||||
"someone else first.")
|
||||
detail = {"from": old, "to": role, "via": "manage_users"}
|
||||
u.role = role
|
||||
# Mirrors set_user_role: an admin already reaches every project, so the
|
||||
# default-member flag would sit there doing nothing and spring back to life
|
||||
# on demotion.
|
||||
if role == auth.ROLE_ADMIN and (u.auto_add_projects or u.auto_add_role):
|
||||
u.auto_add_projects = False
|
||||
u.auto_add_role = ""
|
||||
detail["auto_add_cleared"] = True
|
||||
# NOTE: unlike the API, this permits changing your OWN role. The endpoint
|
||||
# forbids it to stop an admin locking themselves out of the console; here it
|
||||
# is the entire bootstrap path — sign in, then promote yourself.
|
||||
if u.username.lower() == operator.lower():
|
||||
detail["self"] = True
|
||||
_audit(db, operator, "role_changed", u, detail)
|
||||
db.commit()
|
||||
print(f"{u.username}: {old} -> {role}")
|
||||
|
||||
|
||||
def cmd_promote(args) -> None:
|
||||
_set_role(args.username, args.role)
|
||||
|
||||
|
||||
def cmd_demote(args) -> None:
|
||||
_set_role(args.username, auth.ROLE_PROJECT_USER)
|
||||
|
||||
|
||||
def _set_active(username: str, active: bool) -> None:
|
||||
operator = authenticate_operator()
|
||||
with SessionLocal() as db:
|
||||
u = auth.find_user(db, username)
|
||||
if not u:
|
||||
sys.exit(f"No user named '{username}'.")
|
||||
u = _load(db, username)
|
||||
if bool(u.is_active) == active:
|
||||
print(f"{u.username} is already {'enabled' if active else 'disabled'}.")
|
||||
return
|
||||
u.is_active = active
|
||||
# Disabling has to take effect on sessions already issued, and role reads go
|
||||
# through the database on every request — but token_version is what get_current_user
|
||||
# checks, so bump it to sign them out now rather than at session expiry.
|
||||
u.token_version = (u.token_version or 0) + 1
|
||||
_audit(db, operator, "user_active_changed", u,
|
||||
{"is_active": active, "via": "manage_users"})
|
||||
db.commit()
|
||||
print(f"{u.username} is now {'enabled' if active else 'disabled'}.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
# Ensure the users table exists even on a fresh database.
|
||||
# Ensure tables exist on a fresh local database (SQLite dev). Production owns
|
||||
# its schema through alembic.
|
||||
Base.metadata.create_all(bind=engine)
|
||||
|
||||
p = argparse.ArgumentParser(prog="manage_users", description="Work Package Suite user management")
|
||||
p = argparse.ArgumentParser(
|
||||
prog="manage_users",
|
||||
description="Work Package Suite user management. Accounts are created on "
|
||||
"first sign-in (D13); this assigns roles.")
|
||||
sub = p.add_subparsers(dest="cmd", required=True)
|
||||
|
||||
pr = sub.add_parser("promote", help="change an existing account's role (e.g. name the first admin)")
|
||||
pr.add_argument("username")
|
||||
pr.add_argument("--role", required=True, choices=list(auth.ROLES) + ["user"],
|
||||
help="permissions role ('user' is the legacy name for project_user)")
|
||||
sub.add_parser("list", help="list all accounts (no credential needed)")
|
||||
|
||||
sub.add_parser("list", help="list all accounts")
|
||||
pr = sub.add_parser("promote", help="raise an account's permissions role (needs a domain bind)")
|
||||
pr.add_argument("username", help="the person's sAMAccountName")
|
||||
pr.add_argument("--role", default=auth.ROLE_ADMIN, choices=list(auth.ROLES),
|
||||
help="target role (default: admin)")
|
||||
|
||||
dm = sub.add_parser("demote", help=f"set an account back to {auth.ROLE_PROJECT_USER}")
|
||||
dm.add_argument("username", help="the person's sAMAccountName")
|
||||
|
||||
dp = sub.add_parser("disable", help="disable an account (blocks sign-in)")
|
||||
dp.add_argument("username")
|
||||
@@ -109,10 +226,12 @@ def main() -> None:
|
||||
ep.add_argument("username")
|
||||
|
||||
args = p.parse_args()
|
||||
if args.cmd == "promote":
|
||||
cmd_promote(args)
|
||||
elif args.cmd == "list":
|
||||
if args.cmd == "list":
|
||||
cmd_list(args)
|
||||
elif args.cmd == "promote":
|
||||
cmd_promote(args)
|
||||
elif args.cmd == "demote":
|
||||
cmd_demote(args)
|
||||
elif args.cmd == "disable":
|
||||
_set_active(args.username, False)
|
||||
elif args.cmd == "enable":
|
||||
|
||||
@@ -142,10 +142,14 @@ class WorkPackage(Base):
|
||||
|
||||
|
||||
class User(Base):
|
||||
"""A login account. No password is stored here or anywhere else — identity is
|
||||
confirmed by Okta (OIDC), this app only decides what the account may do once
|
||||
Okta has vouched for it (see server/okta_auth.py, server/auth.py, D15/D16).
|
||||
`username` is what Okta's identity claim resolves to.
|
||||
"""A login account. NO PASSWORD IS STORED — D13 moved authentication to an
|
||||
LDAPS bind against the domain (see server/ldap_auth.py), and the
|
||||
`password_hash` column was dropped. `username` is the sAMAccountName people
|
||||
sign in with; an account is created on first successful sign-in if it does not
|
||||
already exist.
|
||||
|
||||
`is_active` is LOCAL and overrides the directory: clearing it revokes access to
|
||||
this app without touching the domain account.
|
||||
|
||||
Two independent notions of "role", deliberately separate:
|
||||
• role the PERMISSIONS role — what the account may do in the app.
|
||||
@@ -183,12 +187,14 @@ class User(Base):
|
||||
# Online-guessing throttle (see login()): consecutive failures + a lockout window.
|
||||
failed_attempts: Mapped[int] = mapped_column(Integer, default=0)
|
||||
locked_until: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
# Bumped to invalidate all existing sessions for this user (e.g. on a password
|
||||
# change). The value is embedded in the JWT and re-checked on every request.
|
||||
# Bumped to invalidate all existing sessions for this user. Password changes no
|
||||
# longer exist (D13), but a role change or a deactivation still has to take
|
||||
# effect on live sessions. The value is embedded in the JWT and re-checked on
|
||||
# every request.
|
||||
token_version: Mapped[int] = mapped_column(Integer, default=0)
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
"""Public view of a user — NEVER includes the password hash."""
|
||||
"""Public view of a user."""
|
||||
return {
|
||||
"id": self.id, "username": self.username, "email": self.email,
|
||||
"full_name": self.full_name, "role": self.role,
|
||||
@@ -337,45 +343,6 @@ class AuditLog(Base):
|
||||
}
|
||||
|
||||
|
||||
class UsageEvent(Base):
|
||||
"""CR-019: append-only record of who used the suite, when, and which tool —
|
||||
navigation/session activity, not business mutations. Deliberately a SEPARATE
|
||||
table from AuditLog rather than a new `action` value there: AuditLog answers
|
||||
"who changed what" and is read by people auditing a specific record's
|
||||
history; mixing in a `page_open` row for every authenticated page load
|
||||
would make that trail noisy for its existing purpose. This table answers a
|
||||
different question — "who is active, and on what" — and CR-019's admin
|
||||
console reads from here, not from AuditLog.
|
||||
|
||||
Not a ForeignKey to `users`, matching AuditLog's own reasoning: a user who
|
||||
is later removed should still show up in historical activity rather than
|
||||
silently vanishing from it, and `D18`'s deprovisioning sync only ever sets
|
||||
`is_active=False` — it never deletes a row — so this is defensive symmetry
|
||||
rather than a live concern today.
|
||||
|
||||
Retention is indefinite (decided 2026-09-17, `decisions-2026-09-17.md`) —
|
||||
nothing purges rows written here; that is a deliberate product decision,
|
||||
not an oversight to fix later."""
|
||||
__tablename__ = "usage_events"
|
||||
|
||||
id: Mapped[str] = mapped_column(String(40), primary_key=True)
|
||||
at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, index=True)
|
||||
username: Mapped[str] = mapped_column(String(200), default="", index=True)
|
||||
project_id: Mapped[Optional[str]] = mapped_column(String(40), nullable=True, index=True)
|
||||
# creator | wizard | field_view | dashboard | admin | directory | ...
|
||||
tool: Mapped[str] = mapped_column(String(40), default="", index=True)
|
||||
# page_open | login
|
||||
event: Mapped[str] = mapped_column(String(40), default="", index=True)
|
||||
detail: Mapped[dict] = mapped_column(JSON, default=dict)
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
return {
|
||||
"id": self.id, "at": _iso(self.at), "username": self.username,
|
||||
"project_id": self.project_id, "tool": self.tool, "event": self.event,
|
||||
"detail": self.detail or {},
|
||||
}
|
||||
|
||||
|
||||
class AppSetting(Base):
|
||||
"""Admin-editable application settings (feature flags, SMTP config, …) stored
|
||||
as key -> JSON value. Read/written via /api/settings (admin only). Secrets like
|
||||
|
||||
@@ -49,7 +49,8 @@ DEFAULTS = {
|
||||
|
||||
# Settings the app needs before anyone is signed in, or that carry no secrets and
|
||||
# are safe for any authenticated user to read (feature flags + localization
|
||||
# defaults + whether self-service password reset can work at all).
|
||||
# defaults). Self-service password reset is gone with D13 — the login page links to
|
||||
# Okta instead, so there is nothing left for the client to feature-detect.
|
||||
PUBLIC_KEYS = ("bim_enabled", "default_locale", "default_timezone")
|
||||
|
||||
|
||||
@@ -83,13 +84,9 @@ def public_settings(db: Session) -> dict:
|
||||
|
||||
|
||||
def app_flags(db: Session) -> dict:
|
||||
"""Feature flags for any signed-in user (no secrets, no SMTP detail).
|
||||
`password_reset_enabled` tells the login page whether a self-service reset can
|
||||
actually deliver mail — there's no point offering the link otherwise."""
|
||||
"""Feature flags for any signed-in user (no secrets, no SMTP detail)."""
|
||||
s = get_settings(db)
|
||||
out = {k: s.get(k) for k in PUBLIC_KEYS}
|
||||
out["password_reset_enabled"] = bool(s.get("email_enabled")) and smtp_ready(s)
|
||||
return out
|
||||
return {k: s.get(k) for k in PUBLIC_KEYS}
|
||||
|
||||
|
||||
def smtp_ready(s: dict) -> bool:
|
||||
@@ -124,22 +121,6 @@ def send_email(s: dict, to_addr: str, subject: str, body: str) -> None:
|
||||
srv.send_message(msg)
|
||||
|
||||
|
||||
def send_now(db: Session, to_addr: str, subject: str, body: str) -> bool:
|
||||
"""Send one email immediately, outside the outbox. Used for password resets —
|
||||
a reset link must never sit in a queue, and it must not be persisted in the
|
||||
notifications table where an admin could read it and take over the account.
|
||||
Returns True if it went out."""
|
||||
s = get_settings(db)
|
||||
if not (s.get("email_enabled") and smtp_ready(s) and to_addr):
|
||||
return False
|
||||
try:
|
||||
send_email(s, to_addr, subject, body)
|
||||
return True
|
||||
except Exception as e: # noqa: BLE001 — never surface SMTP detail to the caller
|
||||
log.warning("password-reset email to %s failed: %s", to_addr, e)
|
||||
return False
|
||||
|
||||
|
||||
def enqueue(db: Session, *, user: "models.User", kind: str, subject: str, body: str,
|
||||
link: str = "", wp_id: Optional[str] = None, project_id: Optional[str] = None) -> "models.Notification":
|
||||
"""Record a notification. Marked 'pending' only if email is enabled + SMTP ready +
|
||||
|
||||
@@ -1,109 +0,0 @@
|
||||
"""Okta OIDC client configuration — T10.1, wave 10 (D15).
|
||||
|
||||
This module owns the conversation with Okta and nothing else: it does not issue this
|
||||
app's own session cookie, does not touch the database, and does not decide who may sign
|
||||
in. `server/auth.py` keeps doing all of that, unchanged — a session is still a signed JWT
|
||||
in an HttpOnly cookie, roles are still local, `get_current_user` still re-reads the
|
||||
account on every request. Only how a person's identity gets confirmed changes: an Okta
|
||||
authorization-code flow, in place of the local username/password check.
|
||||
|
||||
Access gating is Okta's job, not this module's. Only accounts assigned to this app
|
||||
integration in Okta ever complete the flow at all, so there is no required-group or
|
||||
claim check layered on top here — see D15 and wave-10.md for why that is a deliberate
|
||||
difference from D13's design, not an oversight.
|
||||
|
||||
Unconfigured is a first-class state, same discipline as the LDAPS module this replaces:
|
||||
with any of the four settings below missing, `is_configured()` is False and `describe()`
|
||||
says so in the startup log, rather than the app discovering it later at the login button.
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
from typing import Optional
|
||||
|
||||
log = logging.getLogger("wpsuite.okta")
|
||||
|
||||
try:
|
||||
from authlib.integrations.starlette_client import OAuth
|
||||
HAVE_AUTHLIB = True
|
||||
except ImportError: # pragma: no cover
|
||||
HAVE_AUTHLIB = False
|
||||
OAuth = None # type: ignore[assignment]
|
||||
|
||||
# ── configuration ─────────────────────────────────────────────────────────────
|
||||
# The Okta *authorization server* issuer, e.g. https://primecontrols.okta.com/oauth2/default
|
||||
# or a custom authorization server URL. Authlib discovers the rest (authorize/token/
|
||||
# jwks endpoints) from `<issuer>/.well-known/openid-configuration` — nothing below is
|
||||
# hand-entered except this base URL, the client credentials, and our own callback.
|
||||
ISSUER = os.getenv("OKTA_ISSUER", "")
|
||||
CLIENT_ID = os.getenv("OKTA_CLIENT_ID", "")
|
||||
CLIENT_SECRET = os.getenv("OKTA_CLIENT_SECRET", "")
|
||||
# Must exactly match a Sign-in redirect URI registered on the Okta app integration.
|
||||
# e.g. https://wp.controls.dev/api/auth/okta/callback
|
||||
REDIRECT_URI = os.getenv("OKTA_REDIRECT_URI", "")
|
||||
|
||||
# Standard OIDC identity scopes only. No group/role scopes: T10.2's note above explains
|
||||
# why access gating and permissions both stay out of the token.
|
||||
SCOPES = "openid profile email"
|
||||
|
||||
# Which claim in the ID token carries this person's AD sAMAccountName equivalent, for
|
||||
# matching against the local `users` table (T10.3). Not yet confirmed by security —
|
||||
# `preferred_username` is Okta's usual default for an AD-imported user, used here as a
|
||||
# documented placeholder, NOT a verified answer. Override via env once security replies
|
||||
# so the real value can drop in without a code change.
|
||||
IDENTITY_CLAIM = os.getenv("OKTA_IDENTITY_CLAIM", "preferred_username")
|
||||
|
||||
|
||||
def is_configured() -> bool:
|
||||
"""Whether an OIDC flow could even be attempted. Deliberately does not touch the
|
||||
network — that would be a `selftest()`, added when T10.2 needs one."""
|
||||
return bool(HAVE_AUTHLIB and ISSUER and CLIENT_ID and CLIENT_SECRET and REDIRECT_URI)
|
||||
|
||||
|
||||
def describe() -> str:
|
||||
"""One line for the startup log, matching the LDAPS module's discipline: an
|
||||
unconfigured deploy must be visible in `docker compose logs api`, not discovered at
|
||||
the login button."""
|
||||
from . import okta_fake
|
||||
if okta_fake.is_active():
|
||||
return (f"*** FAKE OKTA PROVIDER ACTIVE — identities come from "
|
||||
f"{okta_fake.ENV_VAR}, NOT from Okta. Tests only. ***")
|
||||
if not HAVE_AUTHLIB:
|
||||
return "Okta auth DISABLED — authlib is not installed. No one can sign in."
|
||||
missing = [name for name, val in (
|
||||
("OKTA_ISSUER", ISSUER), ("OKTA_CLIENT_ID", CLIENT_ID),
|
||||
("OKTA_CLIENT_SECRET", CLIENT_SECRET), ("OKTA_REDIRECT_URI", REDIRECT_URI),
|
||||
) if not val]
|
||||
if missing:
|
||||
return f"Okta auth DISABLED — missing {', '.join(missing)}. No one can sign in."
|
||||
return (f"Okta auth enabled — issuer {ISSUER}, redirect {REDIRECT_URI}, "
|
||||
f"identity claim {IDENTITY_CLAIM!r}")
|
||||
|
||||
|
||||
def _build_oauth():
|
||||
"""Register the Okta client. Returns None when unconfigured so the caller (T10.2's
|
||||
routes) can fail loudly instead of Authlib raising deep inside a request.
|
||||
|
||||
Checked before `is_configured()`: the fake (T10.7) needs none of the four real
|
||||
Okta settings, and must win whenever it is legitimately active so a test run
|
||||
never has to also fill in placeholder OKTA_ISSUER/CLIENT_ID/etc. `is_active()`
|
||||
already refuses outside a SQLite-backed test database — see okta_fake.py."""
|
||||
from . import okta_fake
|
||||
if okta_fake.is_active():
|
||||
log.warning("*** FAKE OKTA PROVIDER ACTIVE (%s) — tests only ***", okta_fake.ENV_VAR)
|
||||
return okta_fake.build()
|
||||
if not is_configured():
|
||||
return None
|
||||
oauth = OAuth()
|
||||
oauth.register(
|
||||
name="okta",
|
||||
client_id=CLIENT_ID,
|
||||
client_secret=CLIENT_SECRET,
|
||||
server_metadata_url=f"{ISSUER.rstrip('/')}/.well-known/openid-configuration",
|
||||
client_kwargs={"scope": SCOPES},
|
||||
)
|
||||
return oauth
|
||||
|
||||
|
||||
# Built once at import time, same as `SECRET_KEY` in auth.py — a missing/bad config is a
|
||||
# deploy problem to catch at startup via `describe()`, not a per-request surprise.
|
||||
oauth = _build_oauth()
|
||||
@@ -1,190 +0,0 @@
|
||||
"""A fake Okta, for tests only — T10.7.
|
||||
|
||||
`server/okta_auth.py` normally hands the browser off to a real Okta authorize
|
||||
endpoint and exchanges the code with Okta's token endpoint over the network
|
||||
(Authlib discovers both from `<issuer>/.well-known/openid-configuration`). Tests
|
||||
cannot reach any of that: there is no live Okta tenant in CI, and the browser
|
||||
checks launch the app as a SUBPROCESS (`start_server` in tests/browser_check.py),
|
||||
so a monkeypatch in the test process would never reach the code doing the
|
||||
authenticating. The seam has to be configurable from the ENVIRONMENT — same
|
||||
discipline as `server/ldap_fake.py`, D13/T10.7's LDAP predecessor.
|
||||
|
||||
Set `WP_OKTA_FAKE_DIRECTORY` to a JSON object and this module stands in for the
|
||||
whole round trip — the authorize redirect, a stand-in "sign in at Okta" screen,
|
||||
and the token exchange — with no network call anywhere:
|
||||
|
||||
{"root": {"email": "root@example.test", "name": "Root Person"}}
|
||||
|
||||
The key is the identity value a real Okta ID token would carry in whichever
|
||||
claim `OKTA_IDENTITY_CLAIM` names (default `preferred_username`) — the fake
|
||||
reads `okta_auth.IDENTITY_CLAIM` at request time, so it exercises whatever claim
|
||||
name is actually configured rather than a hard-coded one.
|
||||
|
||||
WHAT THIS DOES AND DOES NOT REPLACE
|
||||
|
||||
Only the OAuth-protocol plumbing that talks to Okta over the network is faked —
|
||||
`authorize_redirect` and `authorize_access_token`, both owned by Authlib, a
|
||||
third-party library, not this app's security logic. Everything this app itself
|
||||
decides stays real and untouched in `app.py`'s `okta_login()`/`okta_callback()`:
|
||||
the `?next=` open-redirect guard (`_safe_next_path`), the disabled-account
|
||||
check, JIT provisioning, and which claim carries identity. A fake run exercises
|
||||
the actual code for all of that, not a re-implementation of it — the same
|
||||
boundary `ldap_fake.py` drew around the anonymous-bind guard.
|
||||
|
||||
THE PRODUCTION GUARD IS THE POINT OF THIS FILE.
|
||||
|
||||
An environment variable that lets anyone "sign in" as any identity by visiting a
|
||||
picker page is exactly the kind of thing that must never be reachable outside a
|
||||
test process — D16 leaves no local password fallback and no break-glass, so a
|
||||
fake provider silently active in production would be a total authentication
|
||||
bypass with a friendlier UI than most. `is_active()` refuses whenever a real
|
||||
database is configured, using the same test `auth._load_secret` and
|
||||
`ldap_fake.is_active()` already use: a non-SQLite `DATABASE_URL` means
|
||||
production, full stop. `okta_auth.describe()` also shouts when the fake is
|
||||
live, and `app.py` registers the picker/consent routes only when the fake is
|
||||
active at import time — in production they do not exist, not merely refuse.
|
||||
"""
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import secrets
|
||||
import time
|
||||
from html import escape
|
||||
from typing import Optional
|
||||
from urllib.parse import quote
|
||||
|
||||
from starlette.responses import RedirectResponse
|
||||
|
||||
log = logging.getLogger("wpsuite.okta.fake")
|
||||
|
||||
ENV_VAR = "WP_OKTA_FAKE_DIRECTORY"
|
||||
|
||||
# One-time authorization codes, in-process only. The login and the callback that
|
||||
# redeems the code both happen inside the SAME uvicorn process within one test
|
||||
# run, so this needs no more durability than that — the server restart every
|
||||
# check does between runs clears it for free. Not a cache: entries are popped on
|
||||
# first use (below) and expire on their own otherwise.
|
||||
_CODE_TTL_SECONDS = 120
|
||||
_PENDING_CODES: dict = {}
|
||||
|
||||
|
||||
def _raw() -> str:
|
||||
return os.getenv(ENV_VAR, "").strip()
|
||||
|
||||
|
||||
def is_active() -> bool:
|
||||
"""Whether the fake should answer. False in anything resembling production."""
|
||||
if not _raw():
|
||||
return False
|
||||
# Imported lazily: server.db reads DATABASE_URL at import, and this module is
|
||||
# imported from okta_auth (and app.py), which must stay importable on its own.
|
||||
from .db import DATABASE_URL
|
||||
if not str(DATABASE_URL).startswith("sqlite"):
|
||||
log.error(
|
||||
"%s is set but a non-SQLite DATABASE_URL is configured. REFUSING to use "
|
||||
"the fake Okta provider — this looks like production, and D16 leaves no "
|
||||
"other way in, so honouring it would be an authentication bypass. "
|
||||
"Unset %s.", ENV_VAR, ENV_VAR)
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def directory() -> dict:
|
||||
try:
|
||||
data = json.loads(_raw())
|
||||
if not isinstance(data, dict):
|
||||
raise ValueError("top level must be an object")
|
||||
return data
|
||||
except Exception as exc: # noqa: BLE001 — a malformed fake must not look auth-shaped
|
||||
log.error("%s is not valid JSON (%s); the fake directory is empty", ENV_VAR, exc)
|
||||
return {}
|
||||
|
||||
|
||||
def new_code(claims: dict) -> str:
|
||||
code = secrets.token_urlsafe(24)
|
||||
_PENDING_CODES[code] = {"claims": claims, "expires": time.time() + _CODE_TTL_SECONDS}
|
||||
return code
|
||||
|
||||
|
||||
def consume_code(code: str) -> Optional[dict]:
|
||||
"""Pop and return the claims for a code, or None if unknown/expired/reused.
|
||||
Popping makes the code single-use, matching a real authorization code."""
|
||||
entry = _PENDING_CODES.pop(code, None)
|
||||
if not entry or entry["expires"] < time.time():
|
||||
return None
|
||||
return entry["claims"]
|
||||
|
||||
|
||||
def picker_page(state: str, redirect_uri: str) -> str:
|
||||
"""The fake's stand-in for Okta's own sign-in screen — a plain list of the
|
||||
identities `WP_OKTA_FAKE_DIRECTORY` defines, so a browser check can click
|
||||
through a real page rather than skip the round trip with a minted cookie.
|
||||
Deliberately plain: nothing here is styled to resemble a real Okta page."""
|
||||
from . import okta_auth
|
||||
rows = []
|
||||
for username in directory():
|
||||
href = (f"/api/auth/okta/_fake_provider/consent?state={quote(state)}"
|
||||
f"&redirect_uri={quote(redirect_uri, safe='')}&username={quote(username)}")
|
||||
rows.append(
|
||||
f'<li><a id="okta-fake-identity-{escape(username)}" href="{escape(href, quote=True)}">'
|
||||
f'Continue as {escape(username)}</a></li>')
|
||||
deny_href = (f"/api/auth/okta/_fake_provider/consent?state={quote(state)}"
|
||||
f"&redirect_uri={quote(redirect_uri, safe='')}&deny=1")
|
||||
deny_href = escape(deny_href, quote=True)
|
||||
return (
|
||||
"<!doctype html><title>FAKE Okta — tests only</title>"
|
||||
"<h1>*** FAKE OKTA PROVIDER — TESTS ONLY ***</h1>"
|
||||
f"<p>Identity claim in use: <code>{escape(okta_auth.IDENTITY_CLAIM)}</code></p>"
|
||||
"<ul>" + "".join(rows) + "</ul>"
|
||||
f'<p><a id="okta-fake-deny" href="{deny_href}">Deny access</a></p>'
|
||||
)
|
||||
|
||||
|
||||
class _FakeOktaClient:
|
||||
"""Stands in for Authlib's `oauth.okta` — the same two methods `app.py`
|
||||
calls, the same async signatures, zero network calls."""
|
||||
|
||||
async def authorize_redirect(self, request, redirect_uri):
|
||||
state = secrets.token_urlsafe(24)
|
||||
# The only session write this fake makes. authorize_access_token below is
|
||||
# the only read — mirrors exactly what real Authlib does with `state`,
|
||||
# which is what T10.2's missing-SessionMiddleware bug was about: this
|
||||
# round trip is a genuine test of the same plumbing.
|
||||
request.session["_okta_fake_state"] = state
|
||||
target = redirect_uri or "/api/auth/okta/callback"
|
||||
url = (f"/api/auth/okta/_fake_provider?state={quote(state)}"
|
||||
f"&redirect_uri={quote(target, safe='')}")
|
||||
return RedirectResponse(url=url, status_code=302)
|
||||
|
||||
async def authorize_access_token(self, request):
|
||||
from authlib.integrations.base_client import OAuthError
|
||||
expected = request.session.pop("_okta_fake_state", None)
|
||||
given = request.query_params.get("state", "")
|
||||
if not expected or given != expected:
|
||||
raise OAuthError(
|
||||
error="invalid_state",
|
||||
description="fake Okta: state did not match the session (T10.7 seam)")
|
||||
err = request.query_params.get("error")
|
||||
if err:
|
||||
raise OAuthError(
|
||||
error=err,
|
||||
description=request.query_params.get("error_description", "denied"))
|
||||
code = request.query_params.get("code", "")
|
||||
claims = consume_code(code)
|
||||
if claims is None:
|
||||
raise OAuthError(error="invalid_grant",
|
||||
description="fake Okta: unknown or expired code")
|
||||
return {"userinfo": claims}
|
||||
|
||||
|
||||
class FakeOAuth:
|
||||
"""Stands in for Authlib's `OAuth()` registry. The real one exposes each
|
||||
registered client as an attribute by name; `app.py` only ever touches
|
||||
`.okta`, so that is the only attribute this needs."""
|
||||
|
||||
def __init__(self):
|
||||
self.okta = _FakeOktaClient()
|
||||
|
||||
|
||||
def build() -> "FakeOAuth":
|
||||
return FakeOAuth()
|
||||
@@ -1,815 +0,0 @@
|
||||
"""Okta Management API client - T13.2, wave 13 (D18).
|
||||
|
||||
This module asks Okta one question: who is in the org, and what is each person's
|
||||
status? It is the first half of the deprovisioning sync. It does not touch the
|
||||
database and it does not disable anyone. T13.3 does that, using the list this
|
||||
module returns.
|
||||
|
||||
Trust boundary. Sign-in uses the OIDC client (OKTA_CLIENT_ID and OKTA_CLIENT_SECRET,
|
||||
see okta_auth.py). This module uses a different credential, OKTA_API_TOKEN, a
|
||||
read-only Okta API token. The two never mix. A rotation or a leak of one does not
|
||||
touch the other.
|
||||
|
||||
Failure rule (D18, decision 4). This is the most important rule in this file:
|
||||
**an error is never an empty list.** If anything goes wrong, this module raises
|
||||
OktaSyncError. It never returns [] to mean "the call failed". T13.3 reads an empty
|
||||
list as "nobody is active", so a function that returned [] on a network error
|
||||
would disable every account on an Okta outage. The cases that raise are:
|
||||
|
||||
- the token or the org URL is not set
|
||||
- a network error or a timeout
|
||||
- any HTTP status that is not 200 (401, 403 and 429 included)
|
||||
- a body that is not a JSON list, or an item that is not shaped as expected
|
||||
- a user with no usable identity value
|
||||
- a list with no users at all (a real org is never empty; an empty list means
|
||||
the token cannot see the users)
|
||||
- a page limit reached (a cut-off list would make real users look missing)
|
||||
- a "next page" link that points to a different host
|
||||
|
||||
T13.3 (the sync job, `run_sync` below) uses that list to disable local accounts.
|
||||
Its rules are in its own docstring. In short: it only ever disables, it never
|
||||
re-enables, it writes one audit row per change, and any failure means NO change.
|
||||
|
||||
The token is read from the environment each time it is used. It is never logged,
|
||||
never put in an error message, and never returned to a browser. Errors carry the
|
||||
exception class name and the HTTP status only. httpx exceptions can include the
|
||||
request URL, so the URL is not copied into the message either.
|
||||
"""
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import re
|
||||
import threading
|
||||
import time
|
||||
import uuid
|
||||
from datetime import datetime, timedelta, timezone
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Callable, Optional
|
||||
from urllib.parse import urlparse
|
||||
|
||||
import httpx
|
||||
import jwt
|
||||
from cryptography.hazmat.primitives.asymmetric import ec
|
||||
from sqlalchemy import select, update
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from . import models, okta_auth
|
||||
|
||||
log = logging.getLogger("wpsuite.okta_sync")
|
||||
|
||||
|
||||
def _make_logs_visible() -> None:
|
||||
"""Make this module's INFO lines reach `docker compose logs api`.
|
||||
|
||||
Nothing in this app configures Python logging, and gunicorn only configures its
|
||||
own loggers. So the root logger sits at WARNING with no handler, and every
|
||||
INFO line from a `wpsuite.*` logger is dropped. Found on 2026-10-16: with the
|
||||
exact production launch command, `grep "Okta sync"` found nothing on a healthy
|
||||
start, because "configured", "scheduled" and "done" are INFO lines. Warnings
|
||||
and errors (a disable, a skipped run) showed, but the lines that say the sync
|
||||
is alive did not. An operator cannot tell "off" from "on and quiet".
|
||||
|
||||
This adds one stderr handler to THIS module's logger only, and only when the
|
||||
root logger has none, so it never doubles up if logging is configured later and
|
||||
it does not change what any other module prints. (BL-028 and the general
|
||||
question of app-wide logging are separate items.)"""
|
||||
if log.handlers or logging.getLogger().handlers:
|
||||
return
|
||||
handler = logging.StreamHandler()
|
||||
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
|
||||
log.addHandler(handler)
|
||||
log.setLevel(logging.INFO)
|
||||
|
||||
|
||||
_make_logs_visible()
|
||||
|
||||
# Okta's own page maximum for this endpoint. Asking for the maximum keeps a
|
||||
# 20-odd account org to a single call.
|
||||
PAGE_LIMIT = 200
|
||||
# A cut-off list is more dangerous than an error, so the loop is bounded and
|
||||
# raises when the bound is reached. 50 pages of 200 is 10,000 people.
|
||||
MAX_PAGES = 50
|
||||
TIMEOUT_SECONDS = 15.0
|
||||
# The whole fetch, all pages together, must finish inside this. T13.4 relies on it:
|
||||
# a run is always shorter than the shortest allowed interval, so one cycle can
|
||||
# never still be running when the next is due.
|
||||
TOTAL_DEADLINE_SECONDS = 120.0
|
||||
|
||||
# Which Okta *profile attribute* matches each OIDC claim that OKTA_IDENTITY_CLAIM
|
||||
# may name. The sign-in flow reads a claim from the ID token. This API returns
|
||||
# the profile instead. For the default claim, preferred_username, Okta's own
|
||||
# default maps it to profile.login. A claim that is not in this table is read
|
||||
# from profile[<claim>] (for example a custom attribute).
|
||||
# OKTA_SYNC_PROFILE_ATTRIBUTE overrides the whole table. Use it if the tenant
|
||||
# builds the claim from a different attribute.
|
||||
_CLAIM_TO_PROFILE = {
|
||||
"preferred_username": "login",
|
||||
"email": "email",
|
||||
}
|
||||
|
||||
|
||||
class OktaSyncError(Exception):
|
||||
"""The Okta user list could not be fetched with confidence. T13.3 must take no
|
||||
action on any account when it sees this."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OktaUser:
|
||||
identity: str # the value that matches users.username (lower case is NOT applied here)
|
||||
status: str # Okta's status, upper case: ACTIVE, SUSPENDED, DEPROVISIONED, ...
|
||||
|
||||
|
||||
# ── configuration ─────────────────────────────────────────────────────────────
|
||||
def _token() -> str:
|
||||
return os.getenv("OKTA_API_TOKEN", "").strip()
|
||||
|
||||
|
||||
def org_url() -> str:
|
||||
"""The Okta org base URL, for example https://yourorg.okta.com. The Management
|
||||
API lives here, not at the authorization server issuer. OKTA_ORG_URL wins if
|
||||
set. Otherwise it is the scheme and host of OKTA_ISSUER."""
|
||||
explicit = os.getenv("OKTA_ORG_URL", "").strip().rstrip("/")
|
||||
if explicit:
|
||||
return explicit
|
||||
issuer = (okta_auth.ISSUER or "").strip()
|
||||
parsed = urlparse(issuer)
|
||||
if parsed.scheme and parsed.netloc:
|
||||
return f"{parsed.scheme}://{parsed.netloc}"
|
||||
return ""
|
||||
|
||||
|
||||
# D23: a second way to prove who we are to Okta. Okta apps of type "API Services"
|
||||
# use OAuth 2.0 with client authentication private_key_jwt: this app holds a private
|
||||
# key (a JWK), signs a short JWT with it, trades the JWT for a one-hour access token
|
||||
# that carries only the scope okta.users.read, and sends that as a Bearer token. The
|
||||
# private key never leaves this process. An SSWS API token (OKTA_API_TOKEN) still
|
||||
# works and wins if both are set, so a deploy that has only a token behaves as before.
|
||||
OAUTH_SCOPE = "okta.users.read"
|
||||
ASSERTION_LIFETIME_SECONDS = 300
|
||||
|
||||
|
||||
def _client_id() -> str:
|
||||
return os.getenv("OKTA_SYNC_CLIENT_ID", "").strip()
|
||||
|
||||
|
||||
def _key_raw() -> str:
|
||||
return os.getenv("OKTA_SYNC_PRIVATE_KEY", "").strip()
|
||||
|
||||
|
||||
def auth_method() -> str:
|
||||
""""token" (SSWS API token), "oauth" (service app with a private key), or "" (none)."""
|
||||
if _token():
|
||||
return "token"
|
||||
if _client_id() and _key_raw():
|
||||
return "oauth"
|
||||
return ""
|
||||
|
||||
|
||||
def _parse_json_forgiving(text: str):
|
||||
"""Parse the key text as JSON, forgiving what copying does to it. Returns
|
||||
(object, None) or (None, "problem at line L column C: what"). The problem names a
|
||||
position and a rule, never any text of the key. Forgiven: line breaks and other control
|
||||
characters inside a string (a long value wrapped over several lines), curly quote
|
||||
marks, and a comma before a closing brace. Spaces inside the key's own number fields
|
||||
are removed, because those fields are base64 text."""
|
||||
attempts = [text]
|
||||
cleaned = (text.replace("\u201c", '"').replace("\u201d", '"').replace("\u2018", "'").replace("\u2019", "'"))
|
||||
cleaned = re.sub(r",\s*([}\]])", r"\1", cleaned)
|
||||
if cleaned != text:
|
||||
attempts.append(cleaned)
|
||||
last = ""
|
||||
for t in attempts:
|
||||
try:
|
||||
obj = json.loads(t, strict=False)
|
||||
except json.JSONDecodeError as exc:
|
||||
last = f"{exc.msg} at line {exc.lineno} column {exc.colno}"
|
||||
continue
|
||||
except ValueError:
|
||||
last = "unreadable"
|
||||
continue
|
||||
if isinstance(obj, dict):
|
||||
for k in ("n", "e", "d", "p", "q", "dp", "dq", "qi", "x", "y"):
|
||||
if isinstance(obj.get(k), str):
|
||||
obj[k] = re.sub(r"\s+", "", obj[k])
|
||||
return obj, None
|
||||
return None, last
|
||||
|
||||
|
||||
def _load_jwk() -> dict:
|
||||
"""OKTA_SYNC_PRIVATE_KEY is the private key as a JWK. Two forms are accepted:
|
||||
the JSON itself (it starts with "{"), or that JSON encoded as base64. Use base64
|
||||
in a Portainer environment field: it has no quote marks to be mangled.
|
||||
|
||||
The reader forgives the usual copy and paste damage: quote marks around the whole
|
||||
value, spaces and line breaks inside it, missing "=" padding, the URL-safe base64
|
||||
alphabet, a byte-order mark at the start of the file, and a JWK Set
|
||||
({"keys": [one key]}) in place of a single key. Raises OktaSyncError that says
|
||||
which step failed. A message never holds any text of the key, only counts."""
|
||||
raw = _key_raw()
|
||||
if not raw:
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY is not set")
|
||||
if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "\"'" and raw[0] not in raw[1:-1]:
|
||||
raw = raw[1:-1].strip()
|
||||
if raw.startswith(("{", '"', "-----BEGIN")):
|
||||
text = raw
|
||||
else:
|
||||
compact = re.sub(r"\s+", "", raw)
|
||||
compact += "=" * (-len(compact) % 4)
|
||||
decoded = None
|
||||
for decode in (base64.b64decode, base64.urlsafe_b64decode):
|
||||
try:
|
||||
decoded = decode(compact)
|
||||
break
|
||||
except Exception: # noqa: BLE001
|
||||
continue
|
||||
if decoded is None:
|
||||
raise _fail(f"OKTA_SYNC_PRIVATE_KEY is not valid base64 ({len(compact)} characters after "
|
||||
"removing spaces; it should be one long line of letters, digits, + / =)")
|
||||
try:
|
||||
text = decoded.decode("utf-8-sig")
|
||||
except UnicodeDecodeError:
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY decodes from base64 but the result is not text") from None
|
||||
text = text.lstrip("\ufeff").strip()
|
||||
via = "" if raw.startswith(("{", '"', "-----BEGIN")) else " after decoding base64"
|
||||
if text.startswith("-----BEGIN"):
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY holds a PEM key (-----BEGIN ...). A JWK is needed: "
|
||||
"JSON with the fields kty, kid, n, e and d")
|
||||
if text.startswith('"'):
|
||||
text = "{" + text.rstrip(",") + "}" # the fields were copied without the outer braces
|
||||
jwk, problem = _parse_json_forgiving(text)
|
||||
if problem is not None and not text.startswith("{"):
|
||||
# One more layer? A value that was encoded twice decodes to base64 text.
|
||||
try:
|
||||
squeezed = re.sub(r"\s+", "", text)
|
||||
again = base64.b64decode(squeezed + "=" * (-len(squeezed) % 4)).decode("utf-8-sig").strip()
|
||||
jwk, problem = _parse_json_forgiving(again)
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
if problem is not None:
|
||||
shape = ("starts with a brace" if text.startswith("{") else
|
||||
"starts with a letter or digit" if text[:1].isalnum() else "starts with a symbol")
|
||||
raise _fail(f"OKTA_SYNC_PRIVATE_KEY is not JSON{via} ({len(text)} characters, {shape}; {problem})")
|
||||
if isinstance(jwk, dict) and isinstance(jwk.get("keys"), list):
|
||||
if len(jwk["keys"]) != 1:
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY is a key set with more than one key; paste one key")
|
||||
jwk = jwk["keys"][0]
|
||||
if not isinstance(jwk, dict) or jwk.get("kty") not in {"RSA", "EC"}:
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY is JSON but not an RSA or EC key")
|
||||
if "d" not in jwk:
|
||||
raise _fail("OKTA_SYNC_PRIVATE_KEY holds a PUBLIC key; the private key is needed to sign")
|
||||
return jwk
|
||||
|
||||
|
||||
def _client_assertion(jwk: dict, client_id: str, audience: str) -> str:
|
||||
"""The signed JWT that proves we hold the key. Okta's rules: iss and sub are the
|
||||
client ID, aud is the token endpoint, and the lifetime is at most 60 minutes."""
|
||||
alg = jwk.get("alg") or ("RS256" if jwk["kty"] == "RSA" else "ES256")
|
||||
algorithms = jwt.algorithms.get_default_algorithms()
|
||||
if alg not in algorithms:
|
||||
raise _fail(f"the key names an algorithm that is not supported ({alg})")
|
||||
try:
|
||||
key = algorithms[alg].from_jwk(json.dumps(jwk))
|
||||
now = int(time.time())
|
||||
return jwt.encode(
|
||||
{"iss": client_id, "sub": client_id, "aud": audience, "iat": now,
|
||||
"exp": now + ASSERTION_LIFETIME_SECONDS, "jti": uuid.uuid4().hex},
|
||||
key, algorithm=alg, headers={"kid": jwk["kid"]} if jwk.get("kid") else None)
|
||||
except OktaSyncError:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise _fail(f"the key could not sign ({type(exc).__name__})") from None
|
||||
|
||||
|
||||
def _dpop_mode() -> str:
|
||||
"""OKTA_SYNC_DPOP (D24): "auto" (the default), "on" or "off".
|
||||
auto: ask for a plain Bearer token first. If Okta answers invalid_dpop_proof, the
|
||||
Okta app requires DPoP, and the sync asks again with DPoP. Nothing to set.
|
||||
on: always use DPoP.
|
||||
off: never use DPoP. A DPoP-bound token is then refused with a clear message."""
|
||||
v = os.getenv("OKTA_SYNC_DPOP", "").strip().lower()
|
||||
if v in {"1", "true", "yes", "on"}:
|
||||
return "on"
|
||||
if v in {"0", "false", "no", "off"}:
|
||||
return "off"
|
||||
return "auto"
|
||||
|
||||
|
||||
def _url_no_query(url: str) -> str:
|
||||
p = urlparse(url)
|
||||
return f"{p.scheme}://{p.netloc}{p.path}"
|
||||
|
||||
|
||||
class _Dpop:
|
||||
"""DPoP (RFC 9449): proof that the caller holds a key, sent with every request, so
|
||||
a stolen access token alone is useless. One throwaway EC key (P-256) is made for each
|
||||
run and is never stored or logged. Each request gets its own signed proof: the method
|
||||
(htm), the URL without its query (htu), a one-time id (jti), the time (iat), the
|
||||
server's latest nonce if it gave one, and for an API call a hash of the access token
|
||||
(ath). The public half of the key travels in the proof header."""
|
||||
|
||||
def __init__(self):
|
||||
self._key = ec.generate_private_key(ec.SECP256R1())
|
||||
pub = json.loads(jwt.algorithms.ECAlgorithm.to_jwk(self._key.public_key()))
|
||||
self._pub = {k: pub[k] for k in ("kty", "crv", "x", "y")}
|
||||
self.nonce: Optional[str] = None
|
||||
|
||||
def proof(self, method: str, url: str, access_token: Optional[str] = None) -> str:
|
||||
claims = {"jti": uuid.uuid4().hex, "htm": method.upper(), "htu": _url_no_query(url),
|
||||
"iat": int(time.time())}
|
||||
if self.nonce:
|
||||
claims["nonce"] = self.nonce
|
||||
if access_token:
|
||||
claims["ath"] = base64.urlsafe_b64encode(
|
||||
hashlib.sha256(access_token.encode()).digest()).rstrip(b"=").decode()
|
||||
return jwt.encode(claims, self._key, algorithm="ES256",
|
||||
headers={"typ": "dpop+jwt", "jwk": self._pub})
|
||||
|
||||
def take_nonce(self, resp: httpx.Response) -> Optional[str]:
|
||||
n = resp.headers.get("DPoP-Nonce")
|
||||
if n:
|
||||
self.nonce = n
|
||||
return n
|
||||
|
||||
|
||||
class _Credential:
|
||||
"""What is sent with each Management API call: an SSWS token, a Bearer token, or a
|
||||
DPoP-bound token with a fresh proof for every request."""
|
||||
|
||||
def __init__(self, scheme: str, token: str, dpop: Optional[_Dpop] = None):
|
||||
self.scheme, self.token, self.dpop = scheme, token, dpop
|
||||
|
||||
def headers(self, method: str, url: str) -> dict:
|
||||
h = {"Accept": "application/json"}
|
||||
if self.dpop is not None:
|
||||
h["Authorization"] = f"DPoP {self.token}"
|
||||
h["DPoP"] = self.dpop.proof(method, url, self.token)
|
||||
else:
|
||||
h["Authorization"] = f"{self.scheme} {self.token}"
|
||||
return h
|
||||
|
||||
|
||||
def _error_code(resp: httpx.Response) -> str:
|
||||
"""Okta's OAuth error code (invalid_client, invalid_scope, invalid_dpop_proof, ...).
|
||||
It tells an admin what to fix and holds no secret. Kept only if it is a short code."""
|
||||
try:
|
||||
c = resp.json().get("error", "")
|
||||
if isinstance(c, str) and re.fullmatch(r"[a-z_]{1,40}", c):
|
||||
return c
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
return ""
|
||||
|
||||
|
||||
def _access_token(client: httpx.Client, base: str) -> _Credential:
|
||||
"""Trade a signed assertion for an access token. Raises OktaSyncError for every
|
||||
failure. Neither the key, the assertion nor the token is logged or put in a message.
|
||||
Each attempt gets a new assertion, because Okta accepts an assertion id only once."""
|
||||
client_id = _client_id()
|
||||
if not client_id:
|
||||
raise _fail("OKTA_SYNC_CLIENT_ID is not set")
|
||||
endpoint = f"{base}/oauth2/v1/token"
|
||||
jwk = _load_jwk()
|
||||
mode = _dpop_mode()
|
||||
dpop: Optional[_Dpop] = _Dpop() if mode == "on" else None
|
||||
nonce_retries = 0
|
||||
resp = None
|
||||
for _ in range(4):
|
||||
headers = {"Accept": "application/json"}
|
||||
if dpop is not None:
|
||||
headers["DPoP"] = dpop.proof("POST", endpoint)
|
||||
try:
|
||||
resp = client.post(
|
||||
endpoint, headers=headers, follow_redirects=False,
|
||||
data={"grant_type": "client_credentials", "scope": OAUTH_SCOPE,
|
||||
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
|
||||
"client_assertion": _client_assertion(jwk, client_id, endpoint)})
|
||||
except httpx.HTTPError as exc:
|
||||
raise _fail(f"network error on the token request ({type(exc).__name__})") from None
|
||||
if dpop is not None:
|
||||
dpop.take_nonce(resp)
|
||||
if resp.status_code == 200:
|
||||
break
|
||||
code = _error_code(resp)
|
||||
if mode == "auto" and dpop is None and code == "invalid_dpop_proof":
|
||||
dpop = _Dpop() # the Okta app requires DPoP: ask again with it
|
||||
continue
|
||||
if dpop is not None and code == "use_dpop_nonce" and dpop.nonce and nonce_retries < 2:
|
||||
nonce_retries += 1 # Okta asks for its nonce in the proof: ask again with it
|
||||
continue
|
||||
raise _fail(f"Okta answered HTTP {resp.status_code} to the token request"
|
||||
+ (f", error {code}" if code else "")
|
||||
+ (" (DPoP was used)" if dpop is not None else ""))
|
||||
else:
|
||||
raise _fail("the token request did not succeed after retries")
|
||||
try:
|
||||
body = resp.json()
|
||||
except ValueError:
|
||||
raise _fail("the token response is not JSON") from None
|
||||
tok = body.get("access_token") if isinstance(body, dict) else None
|
||||
if not isinstance(tok, str) or not tok:
|
||||
raise _fail("the token response has no access token")
|
||||
kind = str(body.get("token_type", "")).lower()
|
||||
if kind == "dpop":
|
||||
if dpop is None:
|
||||
raise _fail("the token is DPoP-bound but OKTA_SYNC_DPOP is off")
|
||||
return _Credential("DPoP", tok, dpop)
|
||||
if kind == "bearer":
|
||||
return _Credential("Bearer", tok)
|
||||
raise _fail("the token response is neither a Bearer nor a DPoP token")
|
||||
|
||||
|
||||
def is_configured() -> bool:
|
||||
return bool(auth_method() and org_url().startswith("https://"))
|
||||
|
||||
|
||||
def describe() -> str:
|
||||
"""One line for the startup log. Never contains the token."""
|
||||
method = auth_method()
|
||||
if not method:
|
||||
return ("Okta sync DISABLED - set OKTA_API_TOKEN, or OKTA_SYNC_CLIENT_ID and "
|
||||
"OKTA_SYNC_PRIVATE_KEY. Deprovisioning is not detected.")
|
||||
base = org_url()
|
||||
if not base:
|
||||
return "Okta sync DISABLED - no OKTA_ORG_URL and OKTA_ISSUER has no host. Deprovisioning is not detected."
|
||||
if not base.startswith("https://"):
|
||||
return f"Okta sync DISABLED - org URL {base!r} is not https. The token is never sent over http."
|
||||
mode = "DRY RUN, no account is changed" if dry_run() else "live"
|
||||
how = ("API token" if method == "token"
|
||||
else f"OAuth service app (private_key_jwt), DPoP {_dpop_mode()}")
|
||||
return (f"Okta sync configured ({mode}) - org {base}, credential: {how}, "
|
||||
f"identity claim {okta_auth.IDENTITY_CLAIM!r}")
|
||||
|
||||
|
||||
def dry_run() -> bool:
|
||||
"""OKTA_SYNC_DRY_RUN (D22). When it is 1, true, yes or on, the sync does its whole
|
||||
job except the change: it logs who it WOULD disable and writes nothing. Off by
|
||||
default, so a deploy that does not set it behaves as before. Read at each run,
|
||||
so the value in force is the one the worker started with."""
|
||||
return os.getenv("OKTA_SYNC_DRY_RUN", "").strip().lower() in {"1", "true", "yes", "on"}
|
||||
|
||||
|
||||
def _profile_attribute() -> str:
|
||||
override = os.getenv("OKTA_SYNC_PROFILE_ATTRIBUTE", "").strip()
|
||||
if override:
|
||||
return override
|
||||
claim = okta_auth.IDENTITY_CLAIM
|
||||
return _CLAIM_TO_PROFILE.get(claim, claim)
|
||||
|
||||
|
||||
# ── the client ────────────────────────────────────────────────────────────────
|
||||
def _fail(reason: str) -> "OktaSyncError":
|
||||
# One place to build the error, so no call site can add a URL or a header by
|
||||
# accident.
|
||||
return OktaSyncError(f"Okta user list could not be fetched: {reason}")
|
||||
|
||||
|
||||
def _same_origin(url: str, base: str) -> bool:
|
||||
a, b = urlparse(url), urlparse(base)
|
||||
return (a.scheme, a.netloc) == (b.scheme, b.netloc)
|
||||
|
||||
|
||||
def _parse_user(item, attribute: str) -> OktaUser:
|
||||
if not isinstance(item, dict):
|
||||
raise _fail("a list item is not an object")
|
||||
status = item.get("status")
|
||||
profile = item.get("profile")
|
||||
if not isinstance(status, str) or not status.strip():
|
||||
raise _fail("a user has no status")
|
||||
if not isinstance(profile, dict):
|
||||
raise _fail("a user has no profile")
|
||||
value = profile.get(attribute)
|
||||
if not isinstance(value, str) or not value.strip():
|
||||
raise _fail(f"a user has no value for profile attribute {attribute!r}")
|
||||
return OktaUser(identity=value.strip(), status=status.strip().upper())
|
||||
|
||||
|
||||
def _get_page(client: httpx.Client, cred: _Credential, url: str, params: Optional[dict]) -> httpx.Response:
|
||||
"""One GET, with the credential's headers. With DPoP, each call has its own proof,
|
||||
and if the server answers use_dpop_nonce the call is repeated once with its nonce."""
|
||||
for attempt in (0, 1):
|
||||
resp = client.get(url, params=params, headers=cred.headers("GET", url), follow_redirects=False)
|
||||
if cred.dpop is None:
|
||||
return resp
|
||||
nonce = cred.dpop.take_nonce(resp)
|
||||
asks = resp.status_code in (400, 401) and nonce and (
|
||||
"use_dpop_nonce" in resp.headers.get("WWW-Authenticate", "") or "use_dpop_nonce" in resp.text)
|
||||
if attempt == 0 and asks:
|
||||
continue
|
||||
return resp
|
||||
return resp
|
||||
|
||||
|
||||
def fetch_users(http: Optional[httpx.Client] = None) -> "list[OktaUser]":
|
||||
"""Return every user Okta lists, as OktaUser values. Raises OktaSyncError on
|
||||
any problem; never returns an empty list. `http` is for tests (a client built
|
||||
on httpx.MockTransport). In production it is None and a short-lived client is
|
||||
made here."""
|
||||
method = auth_method()
|
||||
base = org_url()
|
||||
if not method:
|
||||
raise _fail("no Okta credential is set (OKTA_API_TOKEN, or OKTA_SYNC_CLIENT_ID and OKTA_SYNC_PRIVATE_KEY)")
|
||||
if not base.startswith("https://"):
|
||||
raise _fail("the org URL is missing or is not https")
|
||||
attribute = _profile_attribute()
|
||||
|
||||
own_client = http is None
|
||||
client = http if http is not None else httpx.Client(timeout=TIMEOUT_SECONDS)
|
||||
users: "list[OktaUser]" = []
|
||||
started = time.monotonic()
|
||||
try:
|
||||
cred = (_Credential("SSWS", _token()) if method == "token"
|
||||
else _access_token(client, base))
|
||||
url: Optional[str] = f"{base}/api/v1/users"
|
||||
params: Optional[dict] = {"limit": PAGE_LIMIT}
|
||||
for _ in range(MAX_PAGES):
|
||||
if not url:
|
||||
break
|
||||
if time.monotonic() - started > TOTAL_DEADLINE_SECONDS:
|
||||
raise _fail(f"took longer than {int(TOTAL_DEADLINE_SECONDS)} seconds in total")
|
||||
try:
|
||||
resp = _get_page(client, cred, url, params)
|
||||
except httpx.HTTPError as exc:
|
||||
# Class name only. The exception text can carry the URL.
|
||||
raise _fail(f"network error ({type(exc).__name__})") from None
|
||||
if resp.status_code != 200:
|
||||
raise _fail(f"Okta answered HTTP {resp.status_code}")
|
||||
try:
|
||||
body = resp.json()
|
||||
except ValueError:
|
||||
raise _fail("the response is not JSON") from None
|
||||
if not isinstance(body, list):
|
||||
raise _fail("the response is not a list of users")
|
||||
users.extend(_parse_user(item, attribute) for item in body)
|
||||
|
||||
nxt = resp.links.get("next", {}).get("url")
|
||||
if not nxt:
|
||||
url = None
|
||||
break
|
||||
if not _same_origin(nxt, base):
|
||||
# Never send the token to a host that the Link header names.
|
||||
raise _fail("a next-page link points to a different host")
|
||||
url, params = nxt, None # the next link already carries its query
|
||||
else:
|
||||
# The loop used every page and the last one still named a next page.
|
||||
raise _fail(f"more than {MAX_PAGES} pages; the list may be cut off")
|
||||
finally:
|
||||
if own_client:
|
||||
client.close()
|
||||
|
||||
if not users:
|
||||
raise _fail("Okta returned no users, which is not credible for a real org")
|
||||
log.info("Okta user list fetched: %d user(s)%s", len(users),
|
||||
" (with DPoP)" if cred.dpop is not None else "")
|
||||
return users
|
||||
|
||||
|
||||
# ── T13.3: the sync job ───────────────────────────────────────────────────────
|
||||
# Which Okta statuses mean "this person is gone or was blocked on purpose".
|
||||
# Decided by Matt, 2026-10-16: a literal "anything that is not ACTIVE" would also
|
||||
# catch PASSWORD_EXPIRED, LOCKED_OUT and RECOVERY, which people leave on their
|
||||
# own, and because this job never re-enables, one AD password expiry would lock a
|
||||
# person out of this app until an admin stepped in. A user who is MISSING from the
|
||||
# list disables too (Okta's default list leaves out DEPROVISIONED users).
|
||||
DISABLING_STATUSES = frozenset({"SUSPENDED", "DEPROVISIONED"})
|
||||
|
||||
SYNC_ACTOR = "system:okta_sync"
|
||||
SYNC_ACTION = "user_deprovisioned_by_sync"
|
||||
|
||||
|
||||
@dataclass
|
||||
class SyncResult:
|
||||
ok: bool # False = the run took NO action at all
|
||||
error: str = "" # why, when ok is False
|
||||
okta_users: int = 0 # size of the Okta list
|
||||
checked: int = 0 # active local accounts looked at
|
||||
disabled: "list[str]" = field(default_factory=list) # usernames disabled this run
|
||||
# (in a dry run: the ones it WOULD disable)
|
||||
dry_run: bool = False # True = nothing was changed on purpose (D22)
|
||||
|
||||
|
||||
def _gen_id(prefix: str) -> str:
|
||||
# Same shape as server/app.py gen_id. Not imported: app.py will import this
|
||||
# module (T13.4), and the reverse import would be circular.
|
||||
return f"{prefix}_{uuid.uuid4().hex[:12]}"
|
||||
|
||||
|
||||
def run_sync(db: Session, fetch: Optional[Callable[[], "list[OktaUser]"]] = None,
|
||||
dry: Optional[bool] = None) -> SyncResult:
|
||||
"""Compare the Okta user list to local accounts and disable the ones Okta no
|
||||
longer vouches for.
|
||||
|
||||
The rules, none of which may be relaxed (D18):
|
||||
|
||||
1. FAIL CLOSED. If fetching raises ANY exception, or the answer cannot be
|
||||
trusted, this function changes nothing and writes nothing. A failure is
|
||||
never read as "nobody is active". The fetch happens before the database
|
||||
is read, so there is no code path from a failed fetch to a change.
|
||||
2. ONLY DISABLE. It sets is_active to False. No input makes it set True.
|
||||
An account that is already disabled is not touched and gets no new
|
||||
audit row, so a run that finds nothing new writes nothing.
|
||||
3. One AuditLog row per disabled account, actor "system:okta_sync", so it
|
||||
is never confused with an admin's action. Rows and changes are saved in
|
||||
one transaction. If saving fails, none of it is kept.
|
||||
4. Only changes are logged. A person who is still active in Okta and still
|
||||
active here produces no row.
|
||||
|
||||
One guard beyond the rules above, inside decision 4's "anything the sync can't
|
||||
confidently parse": if there are active local accounts and NONE of them
|
||||
matches any Okta user, the identity attribute is almost certainly wrong (see
|
||||
OKTA_SYNC_PROFILE_ATTRIBUTE). That is a setup mistake, not an offboarding of
|
||||
the whole company, so the run is refused and nothing changes.
|
||||
|
||||
A local account matches an Okta user by username or by email, ignoring case,
|
||||
the same two fields auth.find_user() uses. If the Okta list holds the same
|
||||
identity twice with different statuses, the account is disabled only when
|
||||
every one of them is a disabling status.
|
||||
|
||||
DRY RUN (D22, OKTA_SYNC_DRY_RUN): every step above runs, including the fetch and
|
||||
both guards, but the account changes and the audit rows are skipped. The run logs
|
||||
who it would disable. Use it for the first deploy, to see the match count and the
|
||||
list before any account is touched.
|
||||
|
||||
`fetch` and `dry` are for tests. In production fetch is None and fetch_users() is
|
||||
used, and dry is None so the environment decides.
|
||||
"""
|
||||
fetch = fetch or fetch_users
|
||||
dry = dry_run() if dry is None else dry
|
||||
|
||||
# 1. The fetch. Nothing below runs unless it returned a list.
|
||||
try:
|
||||
okta_users = fetch()
|
||||
except Exception as exc: # an error of ANY kind, not only OktaSyncError
|
||||
msg = str(exc) if isinstance(exc, OktaSyncError) else f"unexpected {type(exc).__name__}"
|
||||
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
||||
return SyncResult(ok=False, error=msg)
|
||||
if not okta_users:
|
||||
# fetch_users() already raises on an empty list. This covers a stand-in
|
||||
# fetch (and any future change) that returns one: same rule.
|
||||
msg = "the fetch returned no users"
|
||||
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
||||
return SyncResult(ok=False, error=msg)
|
||||
|
||||
try:
|
||||
by_identity: "dict[str, list[str]]" = {}
|
||||
for u in okta_users:
|
||||
by_identity.setdefault(u.identity.strip().lower(), []).append(u.status.strip().upper())
|
||||
|
||||
locals_ = list(db.scalars(select(models.User).where(models.User.is_active.is_(True))))
|
||||
plan: "list[tuple[models.User, str]]" = []
|
||||
matched = 0
|
||||
for local in locals_:
|
||||
statuses: "list[str]" = []
|
||||
for key in {(local.username or "").strip().lower(), (local.email or "").strip().lower()}:
|
||||
if key:
|
||||
statuses.extend(by_identity.get(key, []))
|
||||
if statuses:
|
||||
matched += 1
|
||||
if all(st in DISABLING_STATUSES for st in statuses):
|
||||
plan.append((local, sorted(set(statuses))[0]))
|
||||
else:
|
||||
plan.append((local, "MISSING"))
|
||||
|
||||
if locals_ and matched == 0:
|
||||
msg = (f"none of {len(locals_)} active local account(s) matches any of "
|
||||
f"{len(okta_users)} Okta user(s); the identity attribute is probably wrong")
|
||||
log.error("Okta sync SKIPPED, no account was changed: %s", msg)
|
||||
return SyncResult(ok=False, error=msg, okta_users=len(okta_users), checked=len(locals_))
|
||||
|
||||
planned = [(local.username, status) for local, status in plan]
|
||||
checked = len(locals_)
|
||||
if not dry:
|
||||
for local, status in plan:
|
||||
local.is_active = False
|
||||
db.add(models.AuditLog(
|
||||
id=_gen_id("ev"), actor=SYNC_ACTOR, action=SYNC_ACTION,
|
||||
entity_type="user", entity_id=local.id, project_id=None,
|
||||
summary=local.username[:400],
|
||||
detail={"okta_status": status, "via": "okta_sync"},
|
||||
))
|
||||
db.commit()
|
||||
except Exception as exc:
|
||||
db.rollback()
|
||||
log.error("Okta sync FAILED, nothing was kept: unexpected %s", type(exc).__name__)
|
||||
return SyncResult(ok=False, error=f"unexpected {type(exc).__name__}")
|
||||
|
||||
if dry:
|
||||
for name, status in planned:
|
||||
log.warning("Okta sync DRY RUN would disable %r (Okta status: %s)", name, status)
|
||||
log.info("Okta sync DRY RUN done, no account was changed: %d Okta user(s), %d active "
|
||||
"local account(s) checked, %d matched, %d would be disabled",
|
||||
len(okta_users), checked, matched, len(planned))
|
||||
return SyncResult(ok=True, okta_users=len(okta_users), checked=checked,
|
||||
disabled=[name for name, _ in planned], dry_run=True)
|
||||
for name, status in planned:
|
||||
log.warning("Okta sync disabled %r (Okta status: %s)", name, status)
|
||||
log.info("Okta sync done: %d Okta user(s), %d active local account(s) checked, %d disabled",
|
||||
len(okta_users), checked, len(planned))
|
||||
return SyncResult(ok=True, okta_users=len(okta_users), checked=checked,
|
||||
disabled=[name for name, _ in planned])
|
||||
|
||||
|
||||
# ── T13.4: running it on a schedule ───────────────────────────────────────────
|
||||
# The api container runs gunicorn with 2 workers, and a later deploy may run more
|
||||
# than one container. Each worker starts its own timer thread below. Without a
|
||||
# gate, all of them would call Okta every cycle and write overlapping changes.
|
||||
# The gate is one row in app_settings (key "okta_sync"). Its updated_at is "when
|
||||
# the last run was claimed". A worker claims a run with ONE atomic conditional
|
||||
# UPDATE: it succeeds only if the last claim is older than the interval. Exactly
|
||||
# one worker wins each cycle, on SQLite and on Postgres, with no lock held.
|
||||
#
|
||||
# The row survives a restart, so a restart inside the interval does not start a
|
||||
# second run. A slow run cannot overlap the next: a fetch is bounded to
|
||||
# TOTAL_DEADLINE_SECONDS (120) and the interval can never be set below
|
||||
# INTERVAL_MIN_SECONDS (300). Inside one process the timer thread runs one cycle at
|
||||
# a time, so cycles cannot stack there either.
|
||||
CLAIM_KEY = "okta_sync"
|
||||
INTERVAL_DEFAULT_SECONDS = 900 # 15 minutes (D18, proposed, not confirmed)
|
||||
INTERVAL_MIN_SECONDS = 300
|
||||
TICK_SECONDS = 60 # how often each worker checks if a run is due
|
||||
START_DELAY_SECONDS = 10 # let the app finish starting first
|
||||
|
||||
|
||||
def interval_seconds() -> int:
|
||||
"""OKTA_SYNC_INTERVAL_SECONDS, default 900. A value that is not a number uses
|
||||
the default. A value under 300 is raised to 300 (see above for why)."""
|
||||
raw = os.getenv("OKTA_SYNC_INTERVAL_SECONDS", "").strip()
|
||||
if not raw:
|
||||
return INTERVAL_DEFAULT_SECONDS
|
||||
try:
|
||||
value = int(raw)
|
||||
except ValueError:
|
||||
log.warning("OKTA_SYNC_INTERVAL_SECONDS=%r is not a whole number; using %d",
|
||||
raw, INTERVAL_DEFAULT_SECONDS)
|
||||
return INTERVAL_DEFAULT_SECONDS
|
||||
if value < INTERVAL_MIN_SECONDS:
|
||||
log.warning("OKTA_SYNC_INTERVAL_SECONDS=%d is under the minimum; using %d",
|
||||
value, INTERVAL_MIN_SECONDS)
|
||||
return INTERVAL_MIN_SECONDS
|
||||
return value
|
||||
|
||||
|
||||
def claim(db: Session, interval: int, now: Optional[datetime] = None) -> bool:
|
||||
"""Try to claim this cycle. True for exactly one caller per interval."""
|
||||
now = now or datetime.now(timezone.utc)
|
||||
cutoff = now - timedelta(seconds=interval)
|
||||
try:
|
||||
row = db.get(models.AppSetting, CLAIM_KEY)
|
||||
if row is None:
|
||||
db.add(models.AppSetting(key=CLAIM_KEY, value={}, updated_at=now))
|
||||
db.commit() # the insert is the claim
|
||||
return True
|
||||
except IntegrityError:
|
||||
db.rollback() # another worker inserted first: it won
|
||||
return False
|
||||
db.rollback() # end the read; the UPDATE starts fresh
|
||||
result = db.execute(
|
||||
update(models.AppSetting)
|
||||
.where(models.AppSetting.key == CLAIM_KEY, models.AppSetting.updated_at <= cutoff)
|
||||
.values(updated_at=now)
|
||||
)
|
||||
db.commit()
|
||||
return result.rowcount == 1
|
||||
|
||||
|
||||
def run_if_due(session_factory: Callable[[], Session],
|
||||
fetch: Optional[Callable[[], "list[OktaUser]"]] = None,
|
||||
now: Optional[datetime] = None) -> Optional[SyncResult]:
|
||||
"""One timer tick: claim the cycle, and if it is ours, run the sync. Returns
|
||||
the SyncResult, or None when the cycle was not ours (or could not be claimed).
|
||||
Nothing here can turn a failure into a change: run_sync() owns that rule, and
|
||||
anything that goes wrong around it is logged and ends the tick."""
|
||||
try:
|
||||
with session_factory() as db:
|
||||
if not claim(db, interval_seconds(), now=now):
|
||||
return None
|
||||
with session_factory() as db:
|
||||
return run_sync(db, fetch=fetch)
|
||||
except Exception as exc:
|
||||
log.error("Okta sync tick failed, no account was changed: unexpected %s", type(exc).__name__)
|
||||
return None
|
||||
|
||||
|
||||
def start_scheduler(session_factory: Callable[[], Session]) -> "Optional[threading.Event]":
|
||||
"""Start the timer thread. Returns a stop Event (set it to end the thread), or
|
||||
None when the sync is off because OKTA_API_TOKEN or the org URL is missing.
|
||||
Logs one line either way, so an operator can see it in `docker compose logs api`."""
|
||||
log.info(describe())
|
||||
if not is_configured():
|
||||
return None
|
||||
stop = threading.Event()
|
||||
|
||||
def loop():
|
||||
if stop.wait(START_DELAY_SECONDS):
|
||||
return
|
||||
while not stop.is_set():
|
||||
run_if_due(session_factory)
|
||||
if stop.wait(TICK_SECONDS):
|
||||
return
|
||||
|
||||
threading.Thread(target=loop, name="okta-sync", daemon=True).start()
|
||||
log.info("Okta sync scheduled: every %d seconds (checked each %d s by every worker; "
|
||||
"one wins each cycle)", interval_seconds(), TICK_SECONDS)
|
||||
return stop
|
||||
@@ -17,11 +17,10 @@ pymssql==2.3.13 # read-only lookups against the Micron asset DB (SQL
|
||||
# MICRON_DB_URL to mssql+pyodbc://…?driver=ODBC+Driver+18+for+SQL+Server
|
||||
pydantic==2.13.4
|
||||
python-dotenv==1.2.2
|
||||
PyJWT==2.15.1 # signed session tokens. D21 (2026-10-02): was 2.13.0, which
|
||||
# pip-audit lists 13 advisories for (GHSA-8wjv-2p76-3863 let a
|
||||
# crafted cookie raise past decode_token). 2.15.1: none known.
|
||||
bcrypt==5.0.0 # password hashing
|
||||
PyJWT==2.13.0 # signed session tokens
|
||||
ldap3==2.9.1 # D13: LDAPS simple bind against prime.local. Pure Python,
|
||||
# so no system libldap/OpenLDAP headers in the image. The
|
||||
# trust anchor is server/certs/prime-ca-chain.pem, NOT the
|
||||
# system store — see server/ldap_auth.py.
|
||||
starlette==1.3.1 # pinned transitive (cookie / CORS handling — security-relevant)
|
||||
Authlib==1.7.2 # Okta OIDC authorization-code flow (T10.1, wave 10 / D15)
|
||||
httpx==0.28.1 # Authlib's OIDC client needs an HTTP client; explicit, not transitive
|
||||
itsdangerous==2.2.0 # signs the OAuth-state cookie SessionMiddleware sets — required by
|
||||
# Authlib's authorize_redirect/authorize_access_token, not optional
|
||||
|
||||
@@ -9,17 +9,15 @@ and to have data to inspect.
|
||||
|
||||
Every /api/ route except /api/health requires a session, so this signs in first and
|
||||
keeps the session cookie for the rest of the run — the same way server/smoketest.py
|
||||
does, reusing its opener AND its session-minting (not a second implementation).
|
||||
|
||||
There is no local password anymore (D15/D16, T10.4) — see smoketest.py's own
|
||||
AUTHENTICATION section for why and what that means: this needs to run where it can
|
||||
read the SAME AUTH_SECRET_KEY and reach the SAME database as the server under test,
|
||||
and the account must already exist (this seeds a project, not a user).
|
||||
does, reusing its opener rather than growing a second implementation of it.
|
||||
Credentials come from the environment so the password never has to appear in a
|
||||
command line or shell history:
|
||||
|
||||
export WP_SEED_USER=<admin-account> # or WP_SMOKE_USER, which is reused
|
||||
export WP_SEED_PASSWORD='…' # or WP_SMOKE_PASSWORD
|
||||
|
||||
…or pass --user. Use an admin account: seeding creates a project, and --clean
|
||||
deletes one, which needs Project Admin on it.
|
||||
…or pass --user / --password. Use an admin account: seeding creates a project, and
|
||||
--clean deletes one, which needs Project Admin on it.
|
||||
|
||||
USAGE
|
||||
python3 server/seed_demo.py https://wp-suite.company.local --insecure
|
||||
@@ -50,19 +48,16 @@ import urllib.error
|
||||
import urllib.request
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
# So `from server import auth, models` / `from server.db import SessionLocal` also
|
||||
# resolve (needed to mint a session — see AUTHENTICATION above).
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
# The session handling is smoketest.py's, imported rather than copied: one cookie
|
||||
# jar implementation, one session-minting flow, one place to fix. Importing is
|
||||
# safe — that module does its work under `if __name__ == "__main__"`.
|
||||
from smoketest import build_opener, seed_session_cookie # noqa: E402
|
||||
# jar implementation, one login flow, one place to fix. Importing is safe — that
|
||||
# module does its work under `if __name__ == "__main__"`.
|
||||
from smoketest import build_opener # noqa: E402
|
||||
|
||||
BASE = ""
|
||||
CTX = None
|
||||
# Carries the cookie jar holding the minted session (see AUTHENTICATION above).
|
||||
# This script used to call urllib.request.urlopen() directly, which has no cookie
|
||||
# Carries the cookie jar holding the session issued by /api/auth/login. This
|
||||
# script used to call urllib.request.urlopen() directly, which has no cookie
|
||||
# support, so the session was dropped and every data route answered 401 (S13).
|
||||
OPENER = None
|
||||
DEMO_NUMBER = "DEMO-001" # project number prefix used to find/clean demo data
|
||||
@@ -121,22 +116,29 @@ def main():
|
||||
ap.add_argument("--insecure", action="store_true", help="skip TLS verification")
|
||||
ap.add_argument("--clean", action="store_true", help="delete existing DEMO-* projects and exit")
|
||||
ap.add_argument("--user", default=os.getenv("WP_SEED_USER", "") or os.getenv("WP_SMOKE_USER", ""),
|
||||
help="existing account to sign in as (default: $WP_SEED_USER, then "
|
||||
"$WP_SMOKE_USER). Use an admin account.")
|
||||
help="account to sign in as (default: $WP_SEED_USER, then $WP_SMOKE_USER). "
|
||||
"Use an admin account.")
|
||||
ap.add_argument("--password",
|
||||
default=os.getenv("WP_SEED_PASSWORD", "") or os.getenv("WP_SMOKE_PASSWORD", ""),
|
||||
help="its password (default: $WP_SEED_PASSWORD, then $WP_SMOKE_PASSWORD — "
|
||||
"preferred, so it stays out of shell history)")
|
||||
args = ap.parse_args()
|
||||
BASE = args.base_url.rstrip("/")
|
||||
if args.insecure:
|
||||
CTX = ssl.create_default_context(); CTX.check_hostname = False; CTX.verify_mode = ssl.CERT_NONE
|
||||
OPENER = build_opener(CTX)
|
||||
|
||||
if not args.user:
|
||||
if not args.user or not args.password:
|
||||
missing = " and ".join(n for n, v in (("WP_SEED_USER", args.user),
|
||||
("WP_SEED_PASSWORD", args.password)) if not v)
|
||||
return abort(
|
||||
"no account — $WP_SEED_USER not set.",
|
||||
f"no credentials — {missing} not set.",
|
||||
" Every /api/ route except /api/health needs a session, so there is nothing\n"
|
||||
" this can seed without one. Set it and re-run:\n\n"
|
||||
" export WP_SEED_USER=<admin-account>\n\n"
|
||||
" Or pass --user. WP_SMOKE_USER is accepted too, so one account name serves\n"
|
||||
" this and smoketest.py.")
|
||||
" this can seed without one. Set them and re-run:\n\n"
|
||||
" export WP_SEED_USER=<admin-account>\n"
|
||||
" export WP_SEED_PASSWORD='…'\n\n"
|
||||
" Or pass --user/--password. WP_SMOKE_USER / WP_SMOKE_PASSWORD are accepted\n"
|
||||
" too, so one set of credentials serves this and smoketest.py.")
|
||||
|
||||
# health gate
|
||||
try:
|
||||
@@ -146,25 +148,18 @@ def main():
|
||||
if st != 200:
|
||||
print(f"ABORT: /api/health returned {st}"); return 1
|
||||
|
||||
# "Sign in" — mint a session directly (see AUTHENTICATION above) and seed it
|
||||
# into OPENER's jar, so it rides every request after this one.
|
||||
try:
|
||||
from server import auth as srv_auth
|
||||
from server.db import SessionLocal
|
||||
except ImportError as e:
|
||||
return abort(f"cannot import the server package to mint a session: {e}",
|
||||
" This needs to run where server/ is importable and AUTH_SECRET_KEY /\n"
|
||||
" DATABASE_URL match the target server's — see AUTHENTICATION above.")
|
||||
with SessionLocal() as db:
|
||||
user = srv_auth.find_user(db, args.user)
|
||||
if not user:
|
||||
return abort(f"no account named '{args.user}'.",
|
||||
" This signs in as an existing account, it doesn't create one — sign in\n"
|
||||
" through Okta once first, or create it from the admin console.")
|
||||
if not user.is_active:
|
||||
return abort(f"'{args.user}' is disabled.", "")
|
||||
token = srv_auth.create_token(user)
|
||||
seed_session_cookie(token, BASE)
|
||||
# Sign in. The cookie the response sets is held by OPENER's jar and rides every
|
||||
# request after this one.
|
||||
st, body = call("POST", "/api/auth/login",
|
||||
{"username": args.user, "password": args.password})
|
||||
if st != 200:
|
||||
detail = body.get("detail") if isinstance(body, dict) else body
|
||||
hint = (" The account may be locked: the API locks an account for a while after a\n"
|
||||
" few consecutive failures, so retrying with the wrong password makes this\n"
|
||||
" worse. Check the password, then wait out the lockout window."
|
||||
if st in (401, 403, 423, 429) else
|
||||
" Unexpected status from the login endpoint — check the API logs.")
|
||||
return abort(f"could not sign in as '{args.user}' (HTTP {st}): {detail}", hint)
|
||||
logged_in = True
|
||||
print(f"Signed in as {args.user}.")
|
||||
|
||||
|
||||
@@ -6,23 +6,16 @@ NGINX → FastAPI → PostgreSQL all work and that the Python logic (the AWP
|
||||
release gate, metrics, cascade delete) behaves. Stdlib only — no pip, no jq.
|
||||
|
||||
AUTHENTICATION
|
||||
There is no local password anymore (D15/D16, T10.4) — identity is Okta's job,
|
||||
and Okta requires a real browser to complete, which this stdlib script cannot
|
||||
do. So instead of signing in over HTTP the way the front end does, this script
|
||||
mints a session the same way server/app.py's okta_callback() does after Okta
|
||||
hands back an identity: auth.create_token() for an existing account, seeded
|
||||
straight into the cookie jar. That means it needs to run somewhere that can
|
||||
read the SAME AUTH_SECRET_KEY and reach the SAME database as the server under
|
||||
test — inside the api container, or locally against your dev DB. It can no
|
||||
longer sign in to an arbitrary remote URL from an unrelated workstation; if
|
||||
the target is remote, run it on that host or inside that container instead.
|
||||
Every /api/ route except /api/health requires a session (auth_gate in
|
||||
server/app.py), so the script signs in first and keeps the session cookie for
|
||||
the rest of the run. Credentials come from the environment by preference, so a
|
||||
password never has to appear in a command line or shell history:
|
||||
|
||||
export WP_SMOKE_USER=smoketest
|
||||
export WP_SMOKE_PASSWORD='…'
|
||||
python3 server/smoketest.py https://wp-suite.company.local
|
||||
|
||||
…or pass --user explicitly. The account must already exist — sign it in
|
||||
through Okta once first (or create it from the admin console) if it doesn't;
|
||||
this script promotes no one and provisions nothing.
|
||||
…or pass --user / --password explicitly.
|
||||
|
||||
Use an ADMIN account. The script creates a project and deletes it again at the
|
||||
end, and deleting one takes Project Admin on that project (require_project_admin);
|
||||
@@ -31,29 +24,26 @@ AUTHENTICATION
|
||||
discover it in the cleanup step.
|
||||
|
||||
USAGE
|
||||
# From inside the api container (has AUTH_SECRET_KEY and DATABASE_URL; hits
|
||||
# FastAPI directly):
|
||||
docker compose exec -e WP_SMOKE_USER api \
|
||||
python /app/server/smoketest.py http://localhost:8000
|
||||
# Against the deployed site (through the NGINX proxy):
|
||||
python3 server/smoketest.py https://wp-suite.company.local
|
||||
|
||||
# Local dev, against the app you're running yourself:
|
||||
export AUTH_SECRET_KEY=... DATABASE_URL=... WP_SMOKE_USER=smoketest
|
||||
python3 server/smoketest.py http://localhost:8000
|
||||
|
||||
# Self-signed / internal TLS cert on the HTTP side? skip verification:
|
||||
# Self-signed / internal TLS cert? skip verification:
|
||||
python3 server/smoketest.py https://wp-suite.company.local --insecure
|
||||
|
||||
# From inside the api container (hits FastAPI directly):
|
||||
docker compose exec -e WP_SMOKE_USER -e WP_SMOKE_PASSWORD api \
|
||||
python /app/server/smoketest.py http://localhost:8000
|
||||
|
||||
# Leave the demo project in the database so you can open it in the UI:
|
||||
python3 server/smoketest.py http://localhost:8000 --keep
|
||||
python3 server/smoketest.py https://wp-suite.company.local --keep
|
||||
|
||||
The base URL is the SITE root (no /api). Default: http://localhost:8000
|
||||
|
||||
Exit codes: 0 = all checks passed · 1 = one or more checks failed · 2 = the run
|
||||
could not start (unreachable host, missing credentials, or no account by that
|
||||
username). 2 is kept distinct on purpose: "I could not test this" is not the
|
||||
same answer as "this is broken", and conflating them is what made an
|
||||
unauthenticated version of this script report a wall of failures against a
|
||||
perfectly healthy stack.
|
||||
could not start (unreachable host, missing or rejected credentials). 2 is kept
|
||||
distinct on purpose: "I could not test this" is not the same answer as "this is
|
||||
broken", and conflating them is what made an unauthenticated version of this
|
||||
script report a wall of failures against a perfectly healthy stack.
|
||||
"""
|
||||
import argparse
|
||||
import http.cookiejar
|
||||
@@ -63,12 +53,6 @@ import ssl
|
||||
import sys
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
from urllib.parse import urlparse
|
||||
|
||||
# So `from server import auth, models` / `from server.db import SessionLocal` resolve
|
||||
# when this file is run directly (`python3 server/smoketest.py`) rather than as
|
||||
# `python -m server.smoketest` — same reasoning as the sys.path lines in tests/*.py.
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
# ── tiny colored reporter ─────────────────────────────────────────────────────
|
||||
_PASS, _FAIL = [], []
|
||||
@@ -82,40 +66,19 @@ def check(name, cond, detail=""):
|
||||
|
||||
BASE = ""
|
||||
CTX = None
|
||||
# One opener for the whole run, carrying the cookie jar that holds the session.
|
||||
# urlopen() has no cookie support, which is why the session used to be dropped on
|
||||
# the floor and every data route answered 401.
|
||||
# One opener for the whole run, carrying the cookie jar that holds the session
|
||||
# issued by /api/auth/login. urlopen() has no cookie support, which is why the
|
||||
# session used to be dropped on the floor and every data route answered 401.
|
||||
OPENER = None
|
||||
COOKIE_JAR = None
|
||||
|
||||
|
||||
def build_opener(ctx=None):
|
||||
global COOKIE_JAR
|
||||
COOKIE_JAR = http.cookiejar.CookieJar()
|
||||
handlers = [urllib.request.HTTPCookieProcessor(COOKIE_JAR)]
|
||||
handlers = [urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar())]
|
||||
if ctx is not None:
|
||||
handlers.append(urllib.request.HTTPSHandler(context=ctx))
|
||||
return urllib.request.build_opener(*handlers)
|
||||
|
||||
|
||||
def seed_session_cookie(token: str, base: str) -> None:
|
||||
"""Put a minted session into the jar directly, the same shape a Set-Cookie
|
||||
response from the old /api/auth/login would have produced — so the logout
|
||||
check below (which relies on the jar honoring logout()'s Set-Cookie that
|
||||
expires it) keeps working unchanged. `base` is explicit rather than read off
|
||||
this module's own BASE global, so seed_demo.py (which imports this function
|
||||
but has its own BASE) seeds the cookie for the host it's actually targeting."""
|
||||
host = urlparse(base).hostname or "localhost"
|
||||
COOKIE_JAR.set_cookie(http.cookiejar.Cookie(
|
||||
version=0, name="wp_session", value=token,
|
||||
port=None, port_specified=False,
|
||||
domain=host, domain_specified=True, domain_initial_dot=False,
|
||||
path="/", path_specified=True,
|
||||
secure=False, expires=None, discard=True,
|
||||
comment=None, comment_url=None, rest={"HttpOnly": None},
|
||||
))
|
||||
|
||||
|
||||
def call(method, path, body=None):
|
||||
"""Returns (status_code, parsed_body). Never raises on HTTP status."""
|
||||
url = BASE + path
|
||||
@@ -153,7 +116,10 @@ def main():
|
||||
ap.add_argument("--insecure", action="store_true", help="skip TLS verification")
|
||||
ap.add_argument("--keep", action="store_true", help="keep the demo project (don't delete)")
|
||||
ap.add_argument("--user", default=os.getenv("WP_SMOKE_USER", ""),
|
||||
help="existing account to sign in as (default: $WP_SMOKE_USER). Use an admin account.")
|
||||
help="account to sign in as (default: $WP_SMOKE_USER). Use an admin account.")
|
||||
ap.add_argument("--password", default=os.getenv("WP_SMOKE_PASSWORD", ""),
|
||||
help="its password (default: $WP_SMOKE_PASSWORD — preferred, "
|
||||
"so it stays out of shell history)")
|
||||
args = ap.parse_args()
|
||||
BASE = args.base_url.rstrip("/")
|
||||
if args.insecure:
|
||||
@@ -162,14 +128,17 @@ def main():
|
||||
|
||||
print(f"\nWork Package Suite — API smoke test\nTarget: {BASE}\n")
|
||||
|
||||
# Refuse to start without a username rather than running headlong into 401s.
|
||||
if not args.user:
|
||||
# Refuse to start without credentials rather than running headlong into 401s.
|
||||
if not args.user or not args.password:
|
||||
missing = " and ".join(
|
||||
n for n, v in (("WP_SMOKE_USER", args.user), ("WP_SMOKE_PASSWORD", args.password)) if not v)
|
||||
return abort(
|
||||
"no account — $WP_SMOKE_USER not set.",
|
||||
f"no credentials — {missing} not set.",
|
||||
" Every /api/ route except /api/health needs a session, so there is nothing\n"
|
||||
" meaningful to test without one. Set it and re-run:\n\n"
|
||||
" export WP_SMOKE_USER=<admin-account>\n\n"
|
||||
" Or pass --user. Use an admin account: the run creates a project\n"
|
||||
" meaningful to test without one. Set them and re-run:\n\n"
|
||||
" export WP_SMOKE_USER=<admin-account>\n"
|
||||
" export WP_SMOKE_PASSWORD='…'\n\n"
|
||||
" Or pass --user/--password. Use an admin account: the run creates a project\n"
|
||||
" and deletes it again, and the delete needs Project Admin on it.")
|
||||
|
||||
project_id = None
|
||||
@@ -188,29 +157,21 @@ def main():
|
||||
check("health endpoint returns ok", st == 200 and isinstance(body, dict) and body.get("ok") is True,
|
||||
f"status={st} body={body}")
|
||||
|
||||
# 2) "Sign in" — mint a session directly (see AUTHENTICATION above) and seed
|
||||
# it into OPENER's jar, so it rides every request after this one exactly the
|
||||
# way a real Set-Cookie response would have.
|
||||
try:
|
||||
from server import auth as srv_auth
|
||||
from server.db import SessionLocal
|
||||
except ImportError as e:
|
||||
return abort(f"cannot import the server package to mint a session: {e}",
|
||||
" This script now needs to run where server/ is importable and\n"
|
||||
" AUTH_SECRET_KEY / DATABASE_URL match the target server's — see\n"
|
||||
" AUTHENTICATION above.")
|
||||
with SessionLocal() as db:
|
||||
user = srv_auth.find_user(db, args.user)
|
||||
if not user:
|
||||
return abort(f"no account named '{args.user}'.",
|
||||
" This script signs in as an existing account, it doesn't create one —\n"
|
||||
" sign in through Okta once first, or create it from the admin console.")
|
||||
if not user.is_active:
|
||||
return abort(f"'{args.user}' is disabled.", "")
|
||||
token = srv_auth.create_token(user)
|
||||
seed_session_cookie(token, BASE)
|
||||
# 2) Sign in. The cookie the response sets is held by OPENER's jar and rides
|
||||
# every request after this one.
|
||||
st, body = call("POST", "/api/auth/login",
|
||||
{"username": args.user, "password": args.password})
|
||||
if st != 200:
|
||||
detail = body.get("detail") if isinstance(body, dict) else body
|
||||
hint = (" The account may be locked: the API locks an account for a while after\n"
|
||||
" a few consecutive failures (AUTH_MAX_ATTEMPTS / AUTH_LOCKOUT_MINUTES),\n"
|
||||
" so re-running with the wrong password makes this worse, not better.\n"
|
||||
" Check the password, then wait out the lockout window."
|
||||
if st in (401, 403, 423, 429) else
|
||||
" Unexpected status from the login endpoint — check the API logs.")
|
||||
return abort(f"could not sign in as '{args.user}' (HTTP {st}): {detail}", hint)
|
||||
logged_in = True
|
||||
check("session cookie seeded", bool(token))
|
||||
check("login issues a session", st == 200)
|
||||
|
||||
# 3) Prove the session actually travels — this is the check whose absence let
|
||||
# an unauthenticated version of this script look like a broken stack.
|
||||
|
||||
@@ -254,23 +254,27 @@ def main():
|
||||
if ("el.textContent = '" in ln or "el.innerHTML = '" in ln)
|
||||
and "the project" not in ln and ("✓" in ln or "⚠" in ln or "↻" in ln or "✕" in ln)])
|
||||
|
||||
print("\n7. autosave's own registration survives the retired analytics tracker")
|
||||
# This section used to also assert the per-browser usage-analytics dwell
|
||||
# listener (wp-usage.js) still fired alongside autosave, to catch autosave
|
||||
# accidentally replacing it. CR-019/T11.6 (2026-09-23) retired that tracker
|
||||
# on purpose - track() is now a documented no-op and wp-usage.js is gone -
|
||||
# so asserting it still records an event would be asserting the wrong
|
||||
# thing. What's still worth checking here is autosave's own registration,
|
||||
# which is what this section actually guards.
|
||||
print("\n7. the analytics dwell listener still fires")
|
||||
boot(page, base, tok, "/work-package-suite.html?project=projA&tab=sop")
|
||||
time.sleep(0.8)
|
||||
chk("the wizard registered autosave",
|
||||
chk("the wizard still has its analytics dwell tracker",
|
||||
page.eval("typeof trackStepDwell === 'function'"))
|
||||
chk("...and the wizard registered autosave too",
|
||||
page.eval("typeof WPAutosave === 'object' && typeof sopDraftId === 'function'"))
|
||||
chk("...and the retired dwell tracker is a harmless no-op, not missing or throwing",
|
||||
page.eval("""(() => {
|
||||
if (typeof trackStepDwell !== 'function') return false;
|
||||
try { trackStepDwell(); return true; } catch (e) { return false; }
|
||||
})()"""))
|
||||
before = page.eval("""(() => {
|
||||
try { return (JSON.parse(localStorage.getItem('wp_suite_analytics_v1')||'{}').events||[]).length; }
|
||||
catch(e){ return -1; }
|
||||
})()""")
|
||||
# trackStepDwell only records a dwell longer than 400ms, so give it one.
|
||||
time.sleep(0.9)
|
||||
page.eval("typeof trackStepDwell==='function' && trackStepDwell()")
|
||||
time.sleep(0.4)
|
||||
after_n = page.eval("""(() => {
|
||||
try { return (JSON.parse(localStorage.getItem('wp_suite_analytics_v1')||'{}').events||[]).length; }
|
||||
catch(e){ return -1; }
|
||||
})()""")
|
||||
chk("calling it records an event (it was not replaced by the guard)",
|
||||
after_n > before, "%s -> %s" % (before, after_n))
|
||||
finally:
|
||||
page.close()
|
||||
browser.close()
|
||||
|
||||
@@ -40,6 +40,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
import cdp # noqa: E402
|
||||
|
||||
PW = "CorrectHorseBattery9"
|
||||
_PASS, _FAIL = [], []
|
||||
|
||||
|
||||
@@ -150,29 +151,33 @@ def seed(db_path):
|
||||
for u in db.query(models.User).all()}
|
||||
|
||||
|
||||
# T10.7. The app authenticates through Okta, which no test can reach, and
|
||||
# start_server launches it as a SUBPROCESS — so a monkeypatch here would never
|
||||
# reach the code doing the authenticating. server/okta_fake.py reads this
|
||||
# instead, and refuses to work against a non-SQLite database.
|
||||
# D13 / T10.7. The app authenticates by binding to a domain controller, which no
|
||||
# test can reach, and start_server launches it as a SUBPROCESS — so a monkeypatch
|
||||
# here would never reach the code doing the authenticating. server/ldap_fake.py
|
||||
# reads this instead, and refuses to work against a non-SQLite database.
|
||||
#
|
||||
# Almost no check ever signs in (seed() mints tokens with auth.create_token and
|
||||
# sets the cookie directly), so this matters only where the sign-in ROUND TRIP
|
||||
# is driven — url_state_check's deep-link case. It is set for every server here
|
||||
# anyway so that a test which starts signing in later does not fail
|
||||
# mysteriously — the same reasoning the LDAP predecessor (D13/T10.7) used.
|
||||
# Most checks never sign in (seed() mints tokens with auth.create_token and sets
|
||||
# the cookie directly), so this matters only where the login FORM is driven —
|
||||
# url_state_check's deep-link-through-login case. It is set for every server here
|
||||
# anyway so that a test which starts signing in later does not fail mysteriously.
|
||||
FAKE_DIRECTORY = json.dumps({
|
||||
u: {"email": f"{u}@example.test", "name": u.title()}
|
||||
u: {"password": PW, "mail": f"{u}@example.test", "full_name": u.title(),
|
||||
"groups": ["WP-Suite-Users"]}
|
||||
for u in ("root", "sue", "pat", "mix", "bob", "sam", "legacy", "new")
|
||||
})
|
||||
|
||||
|
||||
def start_server(port, db_path, extra_env=None):
|
||||
def start_server(port, db_path):
|
||||
env = dict(os.environ)
|
||||
env["DATABASE_URL"] = "sqlite:///" + db_path.replace("\\", "/")
|
||||
env.setdefault("AUTH_SECRET_KEY", "browser-check-secret-not-for-production")
|
||||
env["WP_OKTA_FAKE_DIRECTORY"] = FAKE_DIRECTORY
|
||||
if extra_env:
|
||||
env.update(extra_env)
|
||||
env["WP_LDAP_FAKE_DIRECTORY"] = FAKE_DIRECTORY
|
||||
# SET empty, never pop: server/db.py calls load_dotenv() at import and
|
||||
# python-dotenv only skips keys already present in os.environ, so a popped
|
||||
# variable comes back from the developer's .env inside the subprocess. An empty
|
||||
# string is "present" and therefore wins. The fake grants "WP-Suite-Users" to
|
||||
# everyone; a test asserting the group gate belongs in ldap_auth_check.
|
||||
env["LDAP_REQUIRED_GROUP"] = ""
|
||||
proc = subprocess.Popen(
|
||||
[sys.executable, "-m", "uvicorn", "server.app:app", "--host", "127.0.0.1",
|
||||
"--port", str(port), "--log-level", "warning"],
|
||||
@@ -207,12 +212,9 @@ def run(page, base, tok):
|
||||
chk("auth resolved to the admin account", page.eval("(window.WP_USER||{}).role") == "admin")
|
||||
chk("the directory is visible",
|
||||
page.eval("getComputedStyle(document.getElementById('users-main')).display") != "none")
|
||||
# 10 since CR-020 (T12.2): the 9 data columns plus the row-selection column.
|
||||
chk("manager table renders 10 columns (9 + row selection)",
|
||||
page.eval("document.querySelectorAll('#users-table thead th').length") == 10,
|
||||
chk("manager table renders 9 columns",
|
||||
page.eval("document.querySelectorAll('#users-table thead th').length") == 9,
|
||||
page.eval("document.querySelectorAll('#users-table thead th').length"))
|
||||
chk("...the first is the selection column",
|
||||
page.eval("!!document.querySelector('#users-table thead th.selcell #sel-all')"))
|
||||
chk("an admin sees every account in the fixture (7)",
|
||||
page.eval("document.querySelectorAll('#users-table tbody tr').length") == 7,
|
||||
page.eval("document.querySelectorAll('#users-table tbody tr').length"))
|
||||
@@ -240,22 +242,15 @@ def run(page, base, tok):
|
||||
|
||||
# Your own row: permissions locked so you cannot demote yourself, job function
|
||||
# still editable. Asserted on the two cells, not "no select in the row".
|
||||
# The cells are found by their HEADER, not by position: CR-020's selection
|
||||
# column moved every column one to the right and these asserted r.cells[3]
|
||||
# and [4], which then read the username and the email (T12.6).
|
||||
ROW = ("const r=[...document.querySelectorAll('#users-table tbody tr')]"
|
||||
".find(r=>r.querySelector('.me-tag'));"
|
||||
"const col=n=>[...document.querySelectorAll('#users-table thead th')]"
|
||||
".findIndex(h=>h.textContent.trim().toLowerCase()===n);")
|
||||
".find(r=>r.querySelector('.me-tag'));")
|
||||
def own(q):
|
||||
return "(()=>{" + ROW + "if(!r)return false;const c=r.cells[col('permissions')];return " + q + "})()"
|
||||
return "(()=>{" + ROW + "if(!r)return false;const c=r.cells[3];return " + q + "})()"
|
||||
chk("your own permissions cell is locked, not a dropdown",
|
||||
page.eval(own("!c.querySelector('select') && !!c.querySelector('.tag')")))
|
||||
chk("...and wears the Administrator pill", page.eval(own("!!c.querySelector('.tag.admin')")))
|
||||
chk("...while your job function stays editable",
|
||||
page.eval("(()=>{" + ROW + "return !!r && !!r.cells[col('project role')].querySelector('select')})()"))
|
||||
chk("...and your own row cannot be ticked for a bulk action",
|
||||
page.eval("(()=>{" + ROW + "return !!r && !r.querySelector('input.selbox')})()"))
|
||||
page.eval("(()=>{" + ROW + "return !!r && !!r.cells[4].querySelector('select')})()"))
|
||||
|
||||
page.eval("[...document.querySelectorAll('#users-table tbody button')]"
|
||||
".find(b=>/project/i.test(b.textContent)).click()")
|
||||
@@ -465,10 +460,7 @@ def main():
|
||||
finally:
|
||||
if args.keep_server:
|
||||
print(f"\n --keep-server: still up at {base}, database at {db_path}")
|
||||
# No local password exists (D15/D16) — there's nothing to type into a login
|
||||
# form. Set the session cookie directly, the same way this script's own
|
||||
# fixture does, from the browser console on that origin:
|
||||
print(f" document.cookie = 'wp_session={tok['root']}; path=/'")
|
||||
print(" Sign in as root / " + PW)
|
||||
else:
|
||||
if server:
|
||||
# Wait for it to actually exit before deleting the database out from
|
||||
|
||||
@@ -1,326 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""CR-020 (wave 12): bulk user administration, server side.
|
||||
|
||||
python tests/bulk_users_check.py
|
||||
|
||||
Self-contained and needs NO browser: a throwaway SQLite database in a temp
|
||||
folder, the API driven in-process with FastAPI's TestClient, everything deleted
|
||||
afterward. Your real wpsuite.db is never touched.
|
||||
|
||||
What it proves is the wave's own exit criteria, measured on the server, where
|
||||
they are enforced:
|
||||
- every bulk action works on a list, row by row, with the single-user rules;
|
||||
- the caller's own account is refused on its own row, never the whole batch;
|
||||
- a super user's batch cannot reach an account or project outside their scope;
|
||||
- one AuditLog row per changed account, the same shape the single route writes;
|
||||
- a partial failure is reported row by row, never as a clean success;
|
||||
- project add/remove never touches the user's other projects or their roles;
|
||||
- the single-user routes, now built on the same functions, behave as before.
|
||||
|
||||
Exit codes: 0 all passed, 1 a check failed, 2 the run could not start.
|
||||
"""
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
import warnings
|
||||
|
||||
warnings.filterwarnings("ignore")
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
TMP = tempfile.mkdtemp(prefix="wp-bulk-users-check-")
|
||||
os.environ["DATABASE_URL"] = "sqlite:///" + os.path.join(TMP, "bulk.db").replace("\\", "/")
|
||||
os.environ["AUTH_SECRET_KEY"] = "bulk-users-check-key-bulk-users-check-0000"
|
||||
os.environ.pop("WP_OKTA_FAKE_DIRECTORY", None)
|
||||
sys.path.insert(0, ROOT)
|
||||
|
||||
try:
|
||||
from fastapi.testclient import TestClient
|
||||
from sqlalchemy import select
|
||||
from server import app as A, auth, models
|
||||
from server.db import SessionLocal
|
||||
except Exception as exc: # noqa: BLE001
|
||||
print("could not start:", exc)
|
||||
sys.exit(2)
|
||||
|
||||
RESULTS = []
|
||||
|
||||
|
||||
def check(name, ok, detail=""):
|
||||
RESULTS.append(bool(ok))
|
||||
print(f" {'PASS' if ok else 'FAIL'} {name}" + (f" ({detail})" if detail and not ok else ""))
|
||||
|
||||
|
||||
db = SessionLocal()
|
||||
|
||||
|
||||
def account(uid, role="project_user"):
|
||||
u = models.User(id=uid, username=uid[5:], role=role, email=uid[5:] + "@example.test")
|
||||
db.add(u)
|
||||
db.commit()
|
||||
return u
|
||||
|
||||
|
||||
def member(uid, pid, role=""):
|
||||
db.add(models.ProjectMember(id=f"pm_{uid}_{pid}", user_id=uid, project_id=pid, role=role))
|
||||
db.commit()
|
||||
|
||||
|
||||
def client(user):
|
||||
c = TestClient(A.app, base_url="http://127.0.0.1", raise_server_exceptions=False)
|
||||
c.cookies.set(auth.COOKIE_NAME, auth.create_token(user))
|
||||
return c
|
||||
|
||||
|
||||
def fresh():
|
||||
s = SessionLocal()
|
||||
s.expire_all()
|
||||
return s
|
||||
|
||||
|
||||
def audit(action, entity_id=None):
|
||||
s = fresh()
|
||||
q = select(models.AuditLog).where(models.AuditLog.action == action)
|
||||
if entity_id:
|
||||
q = q.where(models.AuditLog.entity_id == entity_id)
|
||||
return s.scalars(q.order_by(models.AuditLog.at)).all()
|
||||
|
||||
|
||||
def roles_of(uid):
|
||||
s = fresh()
|
||||
return {m.project_id: (m.role or "") for m in
|
||||
s.scalars(select(models.ProjectMember).where(models.ProjectMember.user_id == uid))}
|
||||
|
||||
|
||||
def by_user(resp):
|
||||
return {r["user_id"]: r for r in resp.json().get("results", [])}
|
||||
|
||||
|
||||
# ── fixture ──────────────────────────────────────────────────────────────────
|
||||
admin = account("user_admin", "admin")
|
||||
admin2 = account("user_admin2", "admin")
|
||||
superu = account("user_super") # super user on proj1 and proj4 by membership
|
||||
pu = account("user_pu") # plain project user: manages nobody
|
||||
for n in range(1, 10):
|
||||
account(f"user_u{n}")
|
||||
for pid in ("proj1", "proj2", "proj3", "proj4"):
|
||||
db.add(models.Project(id=pid, name=pid))
|
||||
db.commit()
|
||||
member("user_super", "proj1", "project_super_user")
|
||||
member("user_super", "proj4", "project_super_user")
|
||||
member("user_pu", "proj1")
|
||||
for n in (1, 2, 3, 4, 5):
|
||||
member(f"user_u{n}", "proj1")
|
||||
member("user_u6", "proj1"); member("user_u6", "proj2", "project_admin") # partly outside super's scope
|
||||
member("user_u7", "proj2") # wholly outside it
|
||||
member("user_u8", "proj1"); member("user_u8", "proj4", "project_super_user") # a role super may not grant
|
||||
ca, cs, cp = client(admin), client(superu), client(pu)
|
||||
|
||||
|
||||
def single_routes():
|
||||
print("\n0. the single-user routes still behave as before (now on the shared functions)")
|
||||
r = ca.post("/api/auth/users/user_admin/role", json={"role": "project_user"})
|
||||
check("changing your own role: 400, same words", r.status_code == 400 and "own role" in r.json()["detail"])
|
||||
r = ca.post("/api/auth/users/user_admin/active", json={"is_active": False})
|
||||
check("disabling yourself: 400, same words", r.status_code == 400 and "disable your own" in r.json()["detail"])
|
||||
r = ca.delete("/api/auth/users/user_admin")
|
||||
check("deleting yourself: 400, same words", r.status_code == 400 and "delete your own" in r.json()["detail"])
|
||||
r = cs.post("/api/auth/users/user_u6/role", json={"role": "project_admin"})
|
||||
check("a super user changing an account outside their scope: 403", r.status_code == 403)
|
||||
r = cs.put("/api/auth/users/user_u3/projects", json={"project_ids": ["proj1", "proj2"]})
|
||||
check("a super user assigning a project they don't run: 403", r.status_code == 403)
|
||||
r = ca.post("/api/auth/users/user_u9/role", json={"role": "project_admin"})
|
||||
check("a single role change still works and returns the directory row",
|
||||
r.status_code == 200 and r.json().get("role") == "project_admin")
|
||||
one = audit("role_changed", "user_u9")
|
||||
check("...and writes one role_changed row", len(one) == 1 and one[0].detail == {"from": "project_user", "to": "project_admin"},
|
||||
str([e.detail for e in one]))
|
||||
ca.post("/api/auth/users/user_u9/role", json={"role": "project_user"})
|
||||
|
||||
|
||||
def bulk_role():
|
||||
print("\n1. bulk permissions role")
|
||||
r = ca.post("/api/auth/bulk-users/role", json={
|
||||
"user_ids": ["user_u1", "user_u2", "user_admin", "user_nobody", "user_u1", "bad id!"],
|
||||
"role": "project_admin"})
|
||||
res = by_user(r)
|
||||
check("200 even though some rows fail (a partial failure is a result, not an error)", r.status_code == 200)
|
||||
check("u1 and u2 changed", res["user_u1"]["status"] == "ok" and res["user_u2"]["status"] == "ok")
|
||||
check("your own row is refused with its reason; the rest still ran",
|
||||
res["user_admin"]["status"] == "failed" and "own role" in res["user_admin"]["reason"])
|
||||
check("an unknown account is refused as 'User not found'",
|
||||
res["user_nobody"]["status"] == "failed" and res["user_nobody"]["reason"] == "User not found")
|
||||
check("a malformed id is refused, not crashed on", res["bad id!"]["status"] == "failed")
|
||||
check("a duplicated id is applied once", r.json()["requested"] == 5)
|
||||
check("counts match the rows", (r.json()["ok"], r.json()["failed"]) == (2, 3), str(r.json()))
|
||||
rows = audit("role_changed", "user_u1")
|
||||
check("one role_changed audit row per changed account, same shape as the single route",
|
||||
len(rows) == 1 and rows[0].detail == {"from": "project_user", "to": "project_admin"}
|
||||
and rows[0].actor == "admin" and rows[0].entity_type == "user", str([e.detail for e in rows]))
|
||||
r = ca.post("/api/auth/bulk-users/role", json={"user_ids": ["user_u1"], "role": "project_admin"})
|
||||
check("a row already in that role is 'unchanged' and writes no audit row",
|
||||
by_user(r)["user_u1"]["status"] == "unchanged" and len(audit("role_changed", "user_u1")) == 1)
|
||||
r = cs.post("/api/auth/bulk-users/role", json={"user_ids": ["user_u3"], "role": "admin"})
|
||||
check("a super user cannot grant admin in bulk either (grantable_roles, whole request 400)",
|
||||
r.status_code == 400)
|
||||
r = cs.post("/api/auth/bulk-users/role", json={"user_ids": ["user_u3", "user_u6", "user_u7"],
|
||||
"role": "project_admin"})
|
||||
res = by_user(r)
|
||||
check("super user: an account wholly inside their projects changes", res["user_u3"]["status"] == "ok")
|
||||
check("super user: an account also on a project they don't run is refused, with the reason",
|
||||
res["user_u6"]["status"] == "failed" and "don't administer" in res["user_u6"]["reason"],
|
||||
res["user_u6"]["reason"])
|
||||
check("super user: an account they cannot see is 'User not found' (no existence leak)",
|
||||
res["user_u7"]["status"] == "failed" and res["user_u7"]["reason"] == "User not found")
|
||||
r = ca.post("/api/auth/bulk-users/role", json={"user_ids": ["user_admin2"], "role": "project_user"})
|
||||
check("demoting another admin works while one active admin remains (the caller)",
|
||||
by_user(r)["user_admin2"]["status"] == "ok")
|
||||
|
||||
|
||||
def bulk_active():
|
||||
print("\n2. bulk activate / disable")
|
||||
r = ca.post("/api/auth/bulk-users/active", json={"user_ids": ["user_u4", "user_admin", "user_u5"],
|
||||
"is_active": False})
|
||||
res = by_user(r)
|
||||
check("u4 and u5 disabled", res["user_u4"]["status"] == "ok" and res["user_u5"]["status"] == "ok"
|
||||
and not fresh().get(models.User, "user_u4").is_active)
|
||||
check("your own account is refused on its own row",
|
||||
res["user_admin"]["status"] == "failed" and "disable your own" in res["user_admin"]["reason"])
|
||||
check("one user_disabled audit row each, same shape as the single route",
|
||||
[e.detail for e in audit("user_disabled", "user_u4")] == [{"is_active": False}])
|
||||
r = ca.post("/api/auth/bulk-users/active", json={"user_ids": ["user_u4", "user_u2"], "is_active": True})
|
||||
res = by_user(r)
|
||||
check("re-enable: u4 ok, u2 (already active) unchanged",
|
||||
res["user_u4"]["status"] == "ok" and res["user_u2"]["status"] == "unchanged")
|
||||
|
||||
|
||||
def bulk_projects():
|
||||
print("\n3. bulk project add / remove")
|
||||
r = cs.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u1", "user_u2", "user_u8"],
|
||||
"project_id": "proj1", "op": "add", "role": "project_admin"})
|
||||
res = by_user(r)
|
||||
check("add with a per-project role: every row ok", all(res[u]["status"] == "ok" for u in ("user_u1", "user_u2", "user_u8")),
|
||||
str(res))
|
||||
check("the role landed on that project", roles_of("user_u1").get("proj1") == "project_admin")
|
||||
check("the user's OTHER project and its role are untouched - even a role the caller could not grant",
|
||||
roles_of("user_u8").get("proj4") == "project_super_user", str(roles_of("user_u8")))
|
||||
rows = audit("project_access_changed", "user_u1")
|
||||
check("one project_access_changed row per account, in the single route's shape",
|
||||
len(rows) == 1 and set(rows[0].detail) == {"projects", "scope", "overrides"}
|
||||
and rows[0].detail["scope"] == "managed", str([e.detail for e in rows]))
|
||||
r = cs.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u1"], "project_id": "proj2", "op": "add"})
|
||||
check("a super user cannot add anyone to a project they don't run (403)", r.status_code == 403)
|
||||
r = cs.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u1"], "project_id": "proj1",
|
||||
"op": "add", "role": "project_super_user"})
|
||||
check("a super user cannot hand out super user on a project (400)", r.status_code == 400)
|
||||
r = ca.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u6"], "project_id": "proj3", "op": "add"})
|
||||
check("admin adds u6 to proj3; proj1 and proj2 memberships and roles stay",
|
||||
by_user(r)["user_u6"]["status"] == "ok"
|
||||
and roles_of("user_u6") == {"proj1": "", "proj2": "project_admin", "proj3": ""}, str(roles_of("user_u6")))
|
||||
r = cs.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u2", "user_u9"], "project_id": "proj1", "op": "remove"})
|
||||
res = by_user(r)
|
||||
check("remove: u2 taken off proj1", res["user_u2"]["status"] == "ok" and "proj1" not in roles_of("user_u2"))
|
||||
check("remove: someone not on it is 'User not found' to a super user who cannot see them",
|
||||
res["user_u9"]["status"] == "failed")
|
||||
r = ca.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u9"], "project_id": "proj1", "op": "remove"})
|
||||
check("remove: an admin removing someone not on the project gets 'unchanged'",
|
||||
by_user(r)["user_u9"]["status"] == "unchanged")
|
||||
r = ca.post("/api/auth/bulk-users/projects", json={"user_ids": ["user_u1"], "project_id": "proj1", "op": "replace"})
|
||||
check("only add and remove exist: no replace-the-whole-list (400)", r.status_code == 400)
|
||||
|
||||
|
||||
def bulk_delete():
|
||||
print("\n4. bulk delete")
|
||||
r = ca.post("/api/auth/bulk-users/delete", json={"user_ids": ["user_u5", "user_admin", "user_gone"]})
|
||||
res = by_user(r)
|
||||
check("u5 deleted", res["user_u5"]["status"] == "ok" and fresh().get(models.User, "user_u5") is None)
|
||||
check("your own account is refused on its own row, the others still ran",
|
||||
res["user_admin"]["status"] == "failed" and "delete your own" in res["user_admin"]["reason"])
|
||||
check("an account that no longer exists is reported, not hidden",
|
||||
res["user_gone"]["status"] == "failed" and res["user_gone"]["reason"] == "User not found")
|
||||
check("one user_deleted audit row, same shape as the single route",
|
||||
[e.detail for e in audit("user_deleted", "user_u5")] == [{"role": "project_user"}])
|
||||
check("the deleted account's memberships went with it", roles_of("user_u5") == {})
|
||||
|
||||
|
||||
def csv_resolve():
|
||||
print("\n6. CSV upload: usernames in, a line-by-line report out (T12.4)")
|
||||
text = ("username\n" # header, skipped
|
||||
"u3\n"
|
||||
"U3\n" # same person, different case: a duplicate
|
||||
"nobody\n"
|
||||
"\n" # blank lines are not rows
|
||||
"u6\n" # visible to the super user, but also on a project they don't run
|
||||
"u7\n" # not visible to the super user at all
|
||||
"super\n" # the caller themself
|
||||
"u8@example.test,extra column\n" # an email address, matched to exactly one account
|
||||
",\n") # an empty first column
|
||||
r = cs.post("/api/auth/bulk-users/resolve", json={"text": text})
|
||||
j = r.json()
|
||||
rows = {x["line"]: x for x in j["rows"]}
|
||||
check("200 with a row for every non-blank line after the header",
|
||||
r.status_code == 200 and sorted(rows) == [2, 3, 4, 6, 7, 8, 9, 10], sorted(rows))
|
||||
check("a valid username is accepted", rows[2]["status"] == "ok" and rows[2]["user_id"] == "user_u3")
|
||||
check("a repeated username is rejected as a duplicate of its first line, not applied twice",
|
||||
rows[3]["status"] == "rejected" and rows[3]["reason"] == "duplicate of line 2")
|
||||
check("an unknown username: 'User not found', with its line number", rows[4]["reason"] == "User not found")
|
||||
check("an account the caller may not change: rejected with the single route's own reason",
|
||||
rows[6]["status"] == "rejected" and "don't administer" in rows[6]["reason"], rows[6]["reason"])
|
||||
check("an account the caller cannot see: 'User not found' (a CSV leaks no more than the table)",
|
||||
rows[7]["reason"] == "User not found")
|
||||
check("the caller's own account is rejected with a clear reason", "your own account" in rows[8]["reason"])
|
||||
check("an email address resolves when exactly one account has it",
|
||||
rows[9]["status"] == "ok" and rows[9]["user_id"] == "user_u8")
|
||||
check("an empty first column is rejected, not skipped", rows[10]["reason"] == "no username in the first column")
|
||||
check("the ids handed back are exactly the accepted rows",
|
||||
j["user_ids"] == ["user_u3", "user_u8"] and (j["accepted"], j["rejected"]) == (2, 6), str(j["user_ids"]))
|
||||
r = cs.post("/api/auth/bulk-users/active", json={"user_ids": j["user_ids"] + ["user_u7"], "is_active": False})
|
||||
res = by_user(r)
|
||||
check("the CSV's ids go through the same bulk route and the same guards: an id slipped in by hand "
|
||||
"is still refused", res["user_u7"]["status"] == "failed" and res["user_u3"]["status"] == "ok")
|
||||
ca.post("/api/auth/bulk-users/active", json={"user_ids": ["user_u3", "user_u8"], "is_active": True})
|
||||
r = cp.post("/api/auth/bulk-users/resolve", json={"text": "u3"})
|
||||
check("a plain project user cannot resolve a list (403)", r.status_code == 403)
|
||||
r = cs.post("/api/auth/bulk-users/resolve", json={"text": "x" * 200_001})
|
||||
check("an oversized upload is refused (422)", r.status_code == 422)
|
||||
s = fresh()
|
||||
s.add(models.User(id="user_twin1", username="twin1", email="shared@example.test"))
|
||||
s.add(models.User(id="user_twin2", username="twin2", email="shared@example.test"))
|
||||
s.commit()
|
||||
r = ca.post("/api/auth/bulk-users/resolve", json={"text": "shared@example.test"})
|
||||
check("an email shared by two accounts matches neither", r.json()["rows"][0]["reason"] == "User not found")
|
||||
|
||||
|
||||
def gates():
|
||||
print("\n7. who may call, and how much")
|
||||
for path, body in (("role", {"role": "project_user"}), ("active", {"is_active": False}),
|
||||
("projects", {"project_id": "proj1", "op": "add"}), ("delete", {})):
|
||||
r = cp.post(f"/api/auth/bulk-users/{path}", json={"user_ids": ["user_u3"], **body})
|
||||
check(f"a plain project user is refused /bulk-users/{path} (403)", r.status_code == 403, str(r.status_code))
|
||||
anon = TestClient(A.app, base_url="http://127.0.0.1", raise_server_exceptions=False)
|
||||
check("no session: 401", anon.post("/api/auth/bulk-users/delete", json={"user_ids": ["user_u3"]}).status_code == 401)
|
||||
r = ca.post("/api/auth/bulk-users/active", json={"user_ids": [f"user_x{i}" for i in range(501)], "is_active": False})
|
||||
check("more than 500 ids in one request is refused (422)", r.status_code == 422, str(r.status_code))
|
||||
|
||||
|
||||
SECTIONS = [single_routes, bulk_role, bulk_active, bulk_projects, bulk_delete, csv_resolve, gates]
|
||||
|
||||
|
||||
def main() -> int:
|
||||
print("Wave 12 bulk user administration - server checks")
|
||||
try:
|
||||
for section in SECTIONS:
|
||||
try:
|
||||
section()
|
||||
except Exception as exc: # noqa: BLE001 - a missing route must read as FAIL, not a traceback
|
||||
check(f"section {section.__name__} ran to the end", False, f"{type(exc).__name__}: {exc}")
|
||||
finally:
|
||||
db.close()
|
||||
A.engine.dispose()
|
||||
shutil.rmtree(TMP, ignore_errors=True)
|
||||
passed = sum(RESULTS)
|
||||
print(f"\n{passed}/{len(RESULTS)} checks passed.")
|
||||
return 0 if passed == len(RESULTS) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,197 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""CR-020 (wave 12): bulk user administration in the browser, at 1440px and 390px.
|
||||
|
||||
python tests/bulk_users_ui_check.py
|
||||
|
||||
Self-contained like the other probes: a throwaway SQLite database seeded by
|
||||
browser_check.seed(), its own uvicorn, headless Edge or Chrome over CDP. Your
|
||||
real wpsuite.db is never touched. Run it alone, not back to back with another
|
||||
probe (file-map.md: chained runs exhaust the browser's ports).
|
||||
|
||||
The server rules are proven in tests/bulk_users_check.py without a browser.
|
||||
This file proves the page: selection, the toolbar, the CSV path and the typed
|
||||
delete, end to end against the real server, operable by keyboard, and holding
|
||||
together at 390px. It writes the after-screenshots CLAUDE.md asks for to
|
||||
docs/reference/baseline/wave-12/; the before-shots are the existing
|
||||
users-1440.png and after-wave9/users-390.png.
|
||||
|
||||
Exit 0 all passed, 1 a failure, 2 could not run.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import urllib.request
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
import cdp # noqa: E402
|
||||
from browser_check import seed, start_server, chk, _PASS, _FAIL # noqa: E402
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
SHOTS = os.path.join(ROOT, "docs", "reference", "baseline", "wave-12")
|
||||
READY = "!!document.querySelector('#users-table table')"
|
||||
|
||||
|
||||
def api(base, path, token):
|
||||
req = urllib.request.Request(base + path, headers={"Cookie": "wp_session=" + token})
|
||||
with urllib.request.urlopen(req, timeout=10) as r:
|
||||
return json.loads(r.read().decode())
|
||||
|
||||
|
||||
def user(base, token, username):
|
||||
return next((u for u in api(base, "/api/auth/users", token) if u["username"] == username), None)
|
||||
|
||||
|
||||
def press(page, key, code, vk):
|
||||
"""A REAL key event (Input.dispatchKeyEvent), not a synthetic KeyboardEvent:
|
||||
only a real one triggers a checkbox's native Space toggle - the lesson
|
||||
launcher_check.py records."""
|
||||
for t in ("keyDown", "keyUp"):
|
||||
page.ws.call("Input.dispatchKeyEvent", {"type": t, "key": key, "code": code,
|
||||
"windowsVirtualKeyCode": vk, "text": " " if t == "keyDown" else ""})
|
||||
time.sleep(0.3)
|
||||
|
||||
|
||||
def answer(page, ok=True, typed=None):
|
||||
time.sleep(0.4)
|
||||
if typed is not None:
|
||||
page.eval("document.getElementById('wp-dlg-input').value=%s" % json.dumps(typed))
|
||||
page.eval("document.getElementById('%s').click()" % ("wp-dlg-ok" if ok else "wp-dlg-cancel"))
|
||||
time.sleep(1.2)
|
||||
|
||||
|
||||
def tick(page, username):
|
||||
page.eval("(() => { const b=[...document.querySelectorAll('input.selbox')]"
|
||||
".find(x => x.dataset.id==='user_%s'); if(b) b.click(); })()" % username)
|
||||
time.sleep(0.2)
|
||||
|
||||
|
||||
BAR_390 = """(function(){
|
||||
var bar=document.getElementById('bulk-bar'); var out={sw:document.documentElement.scrollWidth,under:[],clipped:[],n:0};
|
||||
bar.querySelectorAll('button, select').forEach(function(el){
|
||||
var r=el.getBoundingClientRect(); if(!r.width||!r.height) return; out.n++;
|
||||
var id=el.tagName+' '+(el.textContent||el.id).trim().slice(0,20)+' '+Math.round(r.width)+'x'+Math.round(r.height);
|
||||
if(Math.min(r.width,r.height)<24) out.under.push(id);
|
||||
if(r.left<-2||r.right>392) out.clipped.push(id);
|
||||
});
|
||||
return JSON.stringify(out);
|
||||
})()"""
|
||||
|
||||
|
||||
def main():
|
||||
exe = cdp.find_browser()
|
||||
if not exe:
|
||||
print("no headless-capable browser found; set WP_BROWSER.")
|
||||
return 2
|
||||
tmpdir = tempfile.mkdtemp(prefix="wpsuite-bulkui-")
|
||||
db_path = os.path.join(tmpdir, "check.db")
|
||||
server = browser = None
|
||||
try:
|
||||
tok = seed(db_path)
|
||||
port = cdp.free_port()
|
||||
base = "http://127.0.0.1:%d" % port
|
||||
server = start_server(port, db_path)
|
||||
if server is None:
|
||||
print("server would not start")
|
||||
return 2
|
||||
browser = cdp.Browser(exe)
|
||||
page = browser.page()
|
||||
|
||||
def visit(who, width, mobile=False):
|
||||
page.clear_cookies()
|
||||
page.set_cookie("wp_session", tok[who])
|
||||
page.viewport(width, 900 if width > 500 else 844, mobile=mobile)
|
||||
page.goto(base + "/users.html", wait_for=READY)
|
||||
time.sleep(0.6)
|
||||
|
||||
print("\n1. the admin at 1440px")
|
||||
visit("root", 1440)
|
||||
page.screenshot(os.path.join(SHOTS, "users-1440.png"))
|
||||
chk("a selection column with select-all", page.eval("!!document.getElementById('sel-all')"))
|
||||
chk("no bulk bar until a row is selected", page.eval("document.getElementById('bulk-bar').hidden"))
|
||||
page.eval("document.querySelector('input.selbox[data-id=\"user_pat\"]').focus()")
|
||||
press(page, " ", "Space", 32)
|
||||
chk("Space on a focused row checkbox selects it (keyboard operable)",
|
||||
page.eval("document.querySelector('input.selbox[data-id=\"user_pat\"]').checked"))
|
||||
chk("the bar appears, reachable by keyboard",
|
||||
page.eval("!document.getElementById('bulk-bar').hidden && document.querySelector('#bulk-bar button').tabIndex >= 0"))
|
||||
tick(page, "legacy")
|
||||
chk("the bar counts the selection", page.eval("document.getElementById('bulk-count').textContent") == "2 selected")
|
||||
page.screenshot(os.path.join(SHOTS, "users-1440-selected.png"))
|
||||
page.eval("document.getElementById('bulk-role').value='project_admin';"
|
||||
"document.querySelector('[onclick=\"bulkRole()\"]').click()")
|
||||
time.sleep(0.4)
|
||||
chk("the confirm names the count", "for 2 users" in (page.eval("document.getElementById('wp-dlg-msg').textContent") or ""))
|
||||
answer(page)
|
||||
chk("both accounts changed on the server",
|
||||
user(base, tok["root"], "pat")["role"] == "project_admin" and user(base, tok["root"], "legacy")["role"] == "project_admin")
|
||||
chk("the result is announced", "2 changed" in page.eval("document.getElementById('bulk-banner').textContent")
|
||||
and page.eval("document.getElementById('bulk-banner').getAttribute('role')") in ("status", "alert"))
|
||||
tick(page, "pat")
|
||||
page.eval("const f=document.getElementById('user-filter'); f.value='active'; f.dispatchEvent(new Event('change'))")
|
||||
time.sleep(0.3)
|
||||
chk("changing the filter clears the selection, and says so",
|
||||
page.eval("document.getElementById('bulk-bar').hidden") and
|
||||
"filter changed" in page.eval("document.getElementById('sel-banner').textContent"))
|
||||
|
||||
print("\n2. the super user, a CSV with good and bad lines")
|
||||
visit("sue", 1440)
|
||||
page.eval("loadCsv(new File(['username\\npat\\nmix\\nbob\\nsue\\npat\\n'], 'list.csv', {type:'text/csv'}))")
|
||||
time.sleep(1.5)
|
||||
rep = page.eval("document.getElementById('csv-banner').textContent") or ""
|
||||
chk("only the account she may change is selected", page.eval("document.getElementById('bulk-count').textContent") == "1 selected", rep)
|
||||
chk("every bad line is reported by number and reason: another job, not found, herself, a duplicate",
|
||||
all(s in rep for s in ("Line 3 (mix)", "Line 4 (bob): User not found", "Line 5 (sue)", "Line 6 (pat): duplicate of line 2")), rep)
|
||||
page.eval("document.getElementById('bulk-project-role').value='project_admin';"
|
||||
"document.querySelector('[onclick=\"bulkProject(\\'add\\')\"]').click()")
|
||||
answer(page)
|
||||
roles = api(base, "/api/auth/users/user_pat/projects", tok["root"])["roles"]
|
||||
chk("add to project with a role landed on the server", roles.get("projA") == "project_admin", roles)
|
||||
|
||||
print("\n3. bulk delete needs the typed word")
|
||||
visit("root", 1440)
|
||||
tick(page, "bob")
|
||||
page.eval("document.querySelector('[onclick=\"bulkDelete()\"]').click()")
|
||||
time.sleep(0.4)
|
||||
chk("the dialog lists the username", "bob" in page.eval("document.getElementById('wp-dlg-msg').textContent"))
|
||||
page.eval("document.getElementById('wp-dlg-input').value='delete'; document.getElementById('wp-dlg-ok').click()")
|
||||
time.sleep(0.4)
|
||||
chk("a wrong word sends nothing", user(base, tok["root"], "bob") is not None
|
||||
and page.eval("document.getElementById('wp-dlg-overlay').classList.contains('open')"))
|
||||
answer(page, typed="DELETE")
|
||||
chk("DELETE deletes, and the report says so", user(base, tok["root"], "bob") is None
|
||||
and "1 changed" in page.eval("document.getElementById('bulk-banner').textContent"))
|
||||
|
||||
print("\n4. the gloved-hands width: 390px")
|
||||
visit("root", 390, mobile=True)
|
||||
page.screenshot(os.path.join(SHOTS, "users-390.png"))
|
||||
tick(page, "pat")
|
||||
m = json.loads(page.eval(BAR_390))
|
||||
page.screenshot(os.path.join(SHOTS, "users-390-selected.png"))
|
||||
chk("390px with the bar open: no sideways scrolling", m["sw"] <= 392, m["sw"])
|
||||
chk("390px: no bar control clipped past the screen", not m["clipped"], m["clipped"])
|
||||
chk("390px: every bar control meets the 24px floor", m["n"] > 0 and not m["under"], m["under"])
|
||||
|
||||
errs = [e for e in page.js_errors() if "beforeunload" not in e]
|
||||
chk("no JavaScript errors in the whole run", not errs, errs[:3])
|
||||
finally:
|
||||
if browser is not None:
|
||||
try:
|
||||
browser.close()
|
||||
except Exception:
|
||||
pass
|
||||
if server is not None:
|
||||
server.terminate()
|
||||
|
||||
print("\n" + "-" * 54)
|
||||
print("%d/%d checks passed." % (len(_PASS), len(_PASS) + len(_FAIL)))
|
||||
for f in _FAIL:
|
||||
print(" - " + f)
|
||||
return 1 if _FAIL else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
31
tests/cdp.py
@@ -190,26 +190,8 @@ class Browser:
|
||||
f"--user-data-dir={self.profile}", "--remote-allow-origins=*",
|
||||
"--no-first-run", "--no-default-browser-check", "--disable-gpu",
|
||||
"--disable-extensions", "--disable-sync",
|
||||
"--window-size=1400,1000"]
|
||||
# Run from an elevated (Administrator) shell, Edge and Chrome
|
||||
# "de-elevate": they relaunch themselves as a normal user through
|
||||
# Explorer and the launched process exits rc=0. The relaunch does
|
||||
# not keep the debugging port, so the port is never bound (found
|
||||
# 2026-10-02; Edge logs "Edge is running elevated: 1"). This
|
||||
# Chromium switch keeps the process we started. Ignored when the
|
||||
# shell is not elevated, and on other platforms.
|
||||
+ (["--do-not-de-elevate"] if sys.platform == "win32" else [])
|
||||
+ ["about:blank"],
|
||||
"--window-size=1400,1000", "about:blank"],
|
||||
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
|
||||
# On some Windows installs msedge.exe is a launcher: it starts the real
|
||||
# browser and exits rc=0 at once, and the real browser binds the port a
|
||||
# moment later. Giving up the instant the launched process exited
|
||||
# failed every attempt on such a machine although Edge worked when
|
||||
# started by hand (found 2026-10-02 running the wave 16 probes). An
|
||||
# rc=0 exit now gets a grace period to bind; a non-zero exit is still
|
||||
# a failure at once. Teardown is unaffected: close() sweeps by the
|
||||
# unique profile path, which also catches the handed-off process.
|
||||
exited_at = None
|
||||
for _ in range(160):
|
||||
try:
|
||||
with urllib.request.urlopen(
|
||||
@@ -217,14 +199,9 @@ class Browser:
|
||||
json.load(r)
|
||||
return
|
||||
except Exception:
|
||||
rc = self.proc.poll()
|
||||
if rc is not None:
|
||||
last = f"exited rc={rc} without binding the port"
|
||||
if rc != 0:
|
||||
break
|
||||
exited_at = exited_at or time.time()
|
||||
if time.time() - exited_at > 15:
|
||||
break
|
||||
if self.proc.poll() is not None:
|
||||
last = f"exited rc={self.proc.returncode} without binding the port"
|
||||
break
|
||||
time.sleep(0.25)
|
||||
else:
|
||||
last = "never bound the debugging port"
|
||||
|
||||
@@ -8,17 +8,9 @@ They now go through `wp-dialog.js` — the T7.9 kit extracted as a shared,
|
||||
self-injecting component (guarded so the creator's inline copy still wins on
|
||||
its own page).
|
||||
|
||||
Static half greps the counts; browser half drives the users console's dialogs
|
||||
with natives poisoned and proves they still work end to end.
|
||||
|
||||
Used to drive this via the password-reset prompt specifically, because it was
|
||||
the one place on this page exercising wp-dialog.js's PROMPT variant (text input
|
||||
+ client-side validate()) rather than its confirm variant. T10.4 (D15/D16)
|
||||
removed admin password reset entirely — there is no password to reset anymore
|
||||
— so that coverage moved with it. The prompt-with-validate() pattern itself is
|
||||
still exercised, just not on this page: see creator_dialogs_check.py for
|
||||
wp-creation-app.js's own wpPromptDialog() call sites. If users.html ever grows
|
||||
a new prompt-style dialog, it belongs back in this file.
|
||||
Static half greps the counts; browser half drives the password-reset prompt on
|
||||
the users console with natives poisoned, and proves validate() answers AT the
|
||||
input while the server round-trip completes end to end.
|
||||
|
||||
Boots its own throwaway SQLite + uvicorn + headless browser; run it alone.
|
||||
Exit 0 all passed, 1 a failure, 2 could not run.
|
||||
@@ -112,33 +104,6 @@ def main():
|
||||
chk("cancel means no: bob is still an account",
|
||||
st == 200 and any(u.get("username") == "bob" for u in (users or [])),
|
||||
ascii_([u.get("username") for u in (users or [])]))
|
||||
# CR-020 / T12.5: the bulk delete is a PROMPT-style dialog (typed DELETE),
|
||||
# the kind this file's docstring says belongs back here.
|
||||
print("\n4. bulk delete needs the typed word")
|
||||
page.eval("(() => { const b=[...document.querySelectorAll('input.selbox')]"
|
||||
".find(x => x.dataset.id==='user_bob'); b.click(); })()")
|
||||
time.sleep(0.3)
|
||||
chk("ticking a row shows the bulk bar",
|
||||
page.eval("!document.getElementById('bulk-bar').hidden"))
|
||||
page.eval("document.querySelector('[onclick=\"bulkDelete()\"]').click()")
|
||||
time.sleep(0.4)
|
||||
chk("the bulk delete asks through the kit's prompt, listing the username",
|
||||
page.eval("(() => { const o=document.getElementById('wp-dlg-overlay');"
|
||||
" return o.classList.contains('open')"
|
||||
" && document.getElementById('wp-dlg-input-wrap').style.display !== 'none'"
|
||||
" && /bob/.test(document.getElementById('wp-dlg-msg').textContent); })()"))
|
||||
page.eval("document.getElementById('wp-dlg-input').value='delete';"
|
||||
"document.getElementById('wp-dlg-ok').click()")
|
||||
time.sleep(0.3)
|
||||
chk("the wrong word keeps it open and names what to type",
|
||||
page.eval("document.getElementById('wp-dlg-overlay').classList.contains('open')"
|
||||
" && /DELETE/.test(document.getElementById('wp-dlg-err').textContent)"))
|
||||
page.eval("document.getElementById('wp-dlg-cancel').click()")
|
||||
time.sleep(0.6)
|
||||
st, users = api(base, "/api/auth/users", tok["root"])
|
||||
chk("cancel means no: bob is still an account after the bulk prompt",
|
||||
st == 200 and any(u.get("username") == "bob" for u in (users or [])))
|
||||
|
||||
errs = [e for e in page.js_errors() if "beforeunload" not in e]
|
||||
chk("no JavaScript errors, and no path reached a native dialog (they throw here)",
|
||||
not errs, ascii_(errs[:3]))
|
||||
|
||||
@@ -31,7 +31,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
import cdp # noqa: E402
|
||||
from browser_check import seed, start_server, chk, _PASS, _FAIL, _c # noqa: E402
|
||||
from browser_check import seed, start_server, chk, _PASS, _FAIL, _c, PW # noqa: E402
|
||||
|
||||
STUB = """
|
||||
window.__dialogs = [];
|
||||
|
||||
419
tests/ldap_auth_check.py
Normal file
@@ -0,0 +1,419 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does domain authentication hold its guarantees? — D13 / T10.7.
|
||||
|
||||
Covers the four things `docs/waves/decisions-2026-08-21.md` calls non-negotiable,
|
||||
plus the two provisioning rules that decide whether an existing admin survives the
|
||||
switch. These are the failure modes where the app still *looks* fine:
|
||||
|
||||
1. An empty password must not reach bind(). In LDAP a simple bind with an empty
|
||||
password is an ANONYMOUS bind and it SUCCEEDS — so without the guard, a blank
|
||||
password authenticates as whatever username was submitted.
|
||||
2. TLS must be CERT_REQUIRED with an explicit CA file. CERT_NONE still encrypts,
|
||||
so it fails silently; what it loses is the ability to tell a real DC from
|
||||
someone harvesting domain passwords.
|
||||
3. Group membership must be evaluated through AD's nested-group matching rule.
|
||||
Plain memberOf is direct membership only and wrongly refuses real people.
|
||||
4. The fake directory must be impossible to select against a real database.
|
||||
5. A refused sign-in must create no account.
|
||||
6. An existing admin must still be an admin afterwards.
|
||||
|
||||
Self-contained: throwaway SQLite + its own uvicorn. No browser, no domain — the
|
||||
fake directory (server/ldap_fake.py) stands in for the DC.
|
||||
Exit 0 all passed, 1 a failure, 2 could not run.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import ssl
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
from cdp import free_port # noqa: E402
|
||||
|
||||
_PASS, _FAIL = [], []
|
||||
PW = "CorrectHorseBattery9"
|
||||
GROUP = "WP-Suite-Users"
|
||||
SECRET = "ldap-auth-check-not-for-production"
|
||||
os.environ.setdefault("AUTH_SECRET_KEY", SECRET)
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
|
||||
def chk(label, ok, detail=""):
|
||||
(_PASS if ok else _FAIL).append(label)
|
||||
print(f" {'PASS' if ok else 'FAIL'} {label}" + ("" if ok else f" {detail}"))
|
||||
|
||||
|
||||
def post(base, path, payload):
|
||||
req = urllib.request.Request(base + path, method="POST",
|
||||
data=json.dumps(payload).encode(),
|
||||
headers={"Content-Type": "application/json"})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=10) as r:
|
||||
return r.status, json.loads(r.read().decode() or "{}")
|
||||
except urllib.error.HTTPError as e:
|
||||
try:
|
||||
return e.code, json.loads(e.read().decode() or "{}")
|
||||
except Exception:
|
||||
return e.code, {}
|
||||
|
||||
|
||||
def get(base, path, token):
|
||||
req = urllib.request.Request(base + path, headers={"Cookie": f"wp_session={token}"})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=10) as r:
|
||||
return r.status, json.loads(r.read().decode() or "{}")
|
||||
except urllib.error.HTTPError as e:
|
||||
return e.code, {}
|
||||
|
||||
|
||||
def post_as(base, path, token, payload):
|
||||
req = urllib.request.Request(base + path, method="POST",
|
||||
data=json.dumps(payload).encode(),
|
||||
headers={"Content-Type": "application/json",
|
||||
"Cookie": f"wp_session={token}"})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=10) as r:
|
||||
return r.status, json.loads(r.read().decode() or "{}")
|
||||
except urllib.error.HTTPError as e:
|
||||
return e.code, {}
|
||||
|
||||
|
||||
def start(port, db_path, fake, required_group=""):
|
||||
env = dict(os.environ)
|
||||
env["DATABASE_URL"] = "sqlite:///" + db_path.replace("\\", "/")
|
||||
env["AUTH_SECRET_KEY"] = SECRET
|
||||
env["WP_LDAP_FAKE_DIRECTORY"] = json.dumps(fake)
|
||||
# SET it empty, never pop it. server/db.py calls load_dotenv() at import, and
|
||||
# python-dotenv only skips a key that is already present in os.environ — so a
|
||||
# popped variable is helpfully restored from the developer's .env inside the
|
||||
# subprocess, and the test silently runs against the real required group.
|
||||
# An empty string counts as present, so it wins.
|
||||
env["LDAP_REQUIRED_GROUP"] = required_group or ""
|
||||
proc = subprocess.Popen(
|
||||
[sys.executable, "-m", "uvicorn", "server.app:app", "--host", "127.0.0.1",
|
||||
"--port", str(port), "--log-level", "warning"],
|
||||
env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, cwd=ROOT)
|
||||
for _ in range(160):
|
||||
try:
|
||||
with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/health", timeout=1):
|
||||
return proc
|
||||
except Exception:
|
||||
if proc.poll() is not None:
|
||||
return None
|
||||
time.sleep(0.25)
|
||||
proc.kill()
|
||||
return None
|
||||
|
||||
|
||||
def users_in(db_path):
|
||||
"""Read the users table straight out of the given file.
|
||||
|
||||
Deliberately NOT via server.db.SessionLocal: that engine is bound from
|
||||
DATABASE_URL when the module is first imported, so setting the env var later
|
||||
keeps reading whichever database was configured first. Two assertions in this
|
||||
file passed against the wrong file before that was noticed.
|
||||
"""
|
||||
import sqlite3
|
||||
con = sqlite3.connect(db_path)
|
||||
try:
|
||||
try:
|
||||
return {r[0]: r[1] for r in con.execute("select username, role from users")}
|
||||
except sqlite3.OperationalError:
|
||||
return {} # no users table yet
|
||||
finally:
|
||||
con.close()
|
||||
|
||||
|
||||
def main():
|
||||
print("1. the guards that do not need a server")
|
||||
|
||||
os.environ["DATABASE_URL"] = "sqlite:///./_ldapcheck_unit.db"
|
||||
os.environ["WP_LDAP_FAKE_DIRECTORY"] = json.dumps(
|
||||
{"root": {"password": PW, "groups": [GROUP]}})
|
||||
from server import ldap_auth
|
||||
|
||||
# 1 — the anonymous-bind guard. Connection is nulled so ANY call to bind()
|
||||
# would raise: this proves the guard returns before the transport is touched,
|
||||
# rather than merely that the result is a failure.
|
||||
saved, ldap_auth.Connection = ldap_auth.Connection, None
|
||||
try:
|
||||
for label, u, p in [("an empty password", "root", ""),
|
||||
("a whitespace-only password", "root", " "),
|
||||
("an empty username", "", PW)]:
|
||||
r = ldap_auth.verify(u, p, required_group="")
|
||||
chk(f"{label} is refused without reaching bind()",
|
||||
(not r.ok) and r.reason == ldap_auth.EMPTY_INPUT, r.reason)
|
||||
finally:
|
||||
ldap_auth.Connection = saved
|
||||
|
||||
# 2 — TLS configuration.
|
||||
tls = ldap_auth._tls()
|
||||
chk("TLS validate is CERT_REQUIRED", tls.validate == ssl.CERT_REQUIRED, tls.validate)
|
||||
chk("...with an explicit CA file, not the system store",
|
||||
bool(tls.ca_certs_file) and os.path.isfile(tls.ca_certs_file), tls.ca_certs_file)
|
||||
src = open(os.path.join(ROOT, "server", "ldap_auth.py"), encoding="utf-8").read()
|
||||
# Parse the module rather than grep it: the docstring names validate=ssl.CERT_NONE
|
||||
# in order to explain why it must never be used, and a text search cannot tell
|
||||
# that apart from an actual call. Walk every keyword argument called `validate`
|
||||
# and check what it is really set to.
|
||||
import ast as _ast
|
||||
bad = []
|
||||
for node in _ast.walk(_ast.parse(src)):
|
||||
if isinstance(node, _ast.Call):
|
||||
for kw in node.keywords:
|
||||
if kw.arg == "validate":
|
||||
name = (kw.value.attr if isinstance(kw.value, _ast.Attribute)
|
||||
else getattr(kw.value, "id", ""))
|
||||
if name != "CERT_REQUIRED":
|
||||
bad.append(f"line {node.lineno}: validate={name or '?'}")
|
||||
chk("every validate= in the module is CERT_REQUIRED (AST, not grep)",
|
||||
not bad, "; ".join(bad))
|
||||
|
||||
# 3 — nested groups. The fake cannot model AD nesting (it is a string list), so
|
||||
# what is asserted is that the REAL path builds AD's transitive matching rule
|
||||
# into its filter. A test that truly exercises nesting needs a real directory.
|
||||
chk("membership uses AD's nested matching rule, not plain memberOf",
|
||||
ldap_auth.NESTED_MEMBER_RULE == "1.2.840.113556.1.4.1941"
|
||||
and "memberOf:{NESTED_MEMBER_RULE}:=" in src,
|
||||
"the transitive matching rule is not in the search filter")
|
||||
|
||||
# 4 — the production guard on the fake, in a subprocess because DATABASE_URL is
|
||||
# read at import time.
|
||||
out = subprocess.run(
|
||||
[sys.executable, "-c",
|
||||
"from server import ldap_fake; print(ldap_fake.is_active())"],
|
||||
cwd=ROOT, capture_output=True, text=True,
|
||||
env={**os.environ,
|
||||
"DATABASE_URL": "postgresql+psycopg://u:p@localhost:5432/db",
|
||||
"AUTH_SECRET_KEY": "x",
|
||||
"WP_LDAP_FAKE_DIRECTORY": json.dumps({"root": {"password": PW}})})
|
||||
chk("the fake directory REFUSES to work against a non-SQLite database",
|
||||
out.stdout.strip() == "False", out.stdout.strip() or out.stderr[-200:])
|
||||
|
||||
print("\n2. sign-in, against a server")
|
||||
db_fd, db_path = tempfile.mkstemp(suffix=".db"); os.close(db_fd)
|
||||
port = free_port()
|
||||
fake = {"root": {"password": PW, "mail": "root@example.test",
|
||||
"full_name": "Root Person", "groups": [GROUP]},
|
||||
"outsider": {"password": PW, "mail": "outsider@example.test",
|
||||
"full_name": "Out Sider", "groups": ["SomeOtherGroup"]}}
|
||||
server = start(port, db_path, fake, required_group=GROUP)
|
||||
if server is None:
|
||||
print("the test server would not start.")
|
||||
return 2
|
||||
base = f"http://127.0.0.1:{port}"
|
||||
try:
|
||||
st, _ = post(base, "/api/auth/login", {"username": "root", "password": PW})
|
||||
chk("a correct password signs in", st == 200, st)
|
||||
chk("...and provisioned the account at project_user",
|
||||
users_in(db_path).get("root") == "project_user", users_in(db_path))
|
||||
|
||||
st, body = post(base, "/api/auth/login", {"username": "root", "password": "wrong-" + PW})
|
||||
chk("a wrong password is refused", st == 401, st)
|
||||
chk("...with a message that does not say why",
|
||||
"password" in (body.get("detail") or "").lower()
|
||||
and "expired" not in (body.get("detail") or "").lower(), body)
|
||||
|
||||
st, _ = post(base, "/api/auth/login", {"username": "root", "password": ""})
|
||||
chk("a blank password is refused at the endpoint too", st == 401, st)
|
||||
|
||||
before = set(users_in(db_path))
|
||||
st, _ = post(base, "/api/auth/login", {"username": "outsider", "password": PW})
|
||||
chk("a correct password OUTSIDE the required group is refused", st == 401, st)
|
||||
chk("...and no account was created for them",
|
||||
set(users_in(db_path)) == before, set(users_in(db_path)) - before)
|
||||
|
||||
st, _ = post(base, "/api/auth/login", {"username": "nobody", "password": PW})
|
||||
chk("an unknown account is refused and creates nothing",
|
||||
st == 401 and "nobody" not in users_in(db_path), st)
|
||||
finally:
|
||||
server.kill()
|
||||
try:
|
||||
server.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("")
|
||||
print("4. local state overrides the directory, and the throttle protects it")
|
||||
db_fd3, db3 = tempfile.mkstemp(suffix=".db"); os.close(db_fd3)
|
||||
import sqlalchemy as _sa0
|
||||
from server.db import Base as _B0
|
||||
from server import models as _m0 # noqa: F401
|
||||
eng0 = _sa0.create_engine("sqlite:///" + db3.replace("\\", "/"))
|
||||
_B0.metadata.create_all(bind=eng0)
|
||||
with eng0.begin() as con:
|
||||
con.execute(_sa0.text(
|
||||
"insert into users (id,username,email,full_name,role,is_active,"
|
||||
"failed_attempts,token_version,project_role,locale,timezone,"
|
||||
"auto_add_projects,auto_add_role,created_at,updated_at) values "
|
||||
"('user_root','root','','Root','project_user',0,0,0,'','','',0,'',"
|
||||
"datetime('now'),datetime('now'))")) # is_active = 0
|
||||
eng0.dispose()
|
||||
port3 = free_port()
|
||||
server3 = start(port3, db3, fake, required_group=GROUP)
|
||||
if server3 is None:
|
||||
print("the third test server would not start.")
|
||||
return 2
|
||||
b3 = f"http://127.0.0.1:{port3}"
|
||||
try:
|
||||
st, _ = post(b3, "/api/auth/login", {"username": "root", "password": PW})
|
||||
chk("a disabled local account is refused even though the bind succeeds",
|
||||
st == 403, st)
|
||||
|
||||
# The throttle. AUTH_MAX_ATTEMPTS is 2, and its whole purpose is that failures
|
||||
# are real domain binds counting against the AD lockout policy — so it has to
|
||||
# stop CALLING the directory, not merely refuse. Proving that: burn the budget
|
||||
# with wrong passwords, then present the CORRECT one. A 429 for a credential
|
||||
# that would otherwise succeed is only possible if the throttle runs before the
|
||||
# directory is consulted.
|
||||
codes = [post(b3, "/api/auth/login",
|
||||
{"username": "outsider", "password": "wrong"})[0] for _ in range(3)]
|
||||
chk("the attempt budget is spent and the next try is throttled",
|
||||
codes[-1] == 429, codes)
|
||||
st, _ = post(b3, "/api/auth/login", {"username": "outsider", "password": PW})
|
||||
chk("...and a CORRECT password is still refused while throttled, proving the "
|
||||
"directory is never reached", st == 429, st)
|
||||
chk("...while another account is unaffected (the budget is per-username)",
|
||||
post(b3, "/api/auth/login", {"username": "root", "password": PW})[0] == 403, "")
|
||||
finally:
|
||||
server3.kill()
|
||||
try:
|
||||
server3.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("\n3. an existing admin survives the switch")
|
||||
db_fd2, db2 = tempfile.mkstemp(suffix=".db"); os.close(db_fd2)
|
||||
# Build the schema with a NEW engine bound to this file — see users_in().
|
||||
import sqlalchemy as _sa
|
||||
from server.db import Base
|
||||
from server import models # noqa: F401
|
||||
eng2 = _sa.create_engine("sqlite:///" + db2.replace("\\", "/"))
|
||||
Base.metadata.create_all(bind=eng2)
|
||||
with eng2.begin() as con:
|
||||
con.execute(_sa.text(
|
||||
"insert into users (id,username,email,full_name,role,is_active,"
|
||||
"failed_attempts,token_version,project_role,locale,timezone,"
|
||||
"auto_add_projects,auto_add_role,created_at,updated_at) values "
|
||||
"('user_root','root','','Set By Hand','admin',1,0,0,'','','',0,'',"
|
||||
"datetime('now'),datetime('now'))"))
|
||||
eng2.dispose()
|
||||
port2 = free_port()
|
||||
server2 = start(port2, db2, fake, required_group=GROUP)
|
||||
if server2 is None:
|
||||
print("the second test server would not start.")
|
||||
return 2
|
||||
try:
|
||||
st, body = post(f"http://127.0.0.1:{port2}", "/api/auth/login",
|
||||
{"username": "root", "password": PW})
|
||||
chk("the pre-existing admin signs in", st == 200, st)
|
||||
chk("...and is STILL an admin (D13 criterion 4)",
|
||||
users_in(db2).get("root") == "admin", users_in(db2))
|
||||
chk("...and their locally-set name was not overwritten by the directory",
|
||||
(body.get("user") or {}).get("full_name") == "Set By Hand", body.get("user"))
|
||||
chk("...and no duplicate account appeared",
|
||||
len(users_in(db2)) == 1, users_in(db2))
|
||||
finally:
|
||||
server2.kill()
|
||||
try:
|
||||
server2.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("")
|
||||
print("5. the console's own routes, and what token_version actually does")
|
||||
db_fd4, db4 = tempfile.mkstemp(suffix=".db"); os.close(db_fd4)
|
||||
import sqlalchemy as _sa1
|
||||
from server.db import Base as _B1
|
||||
from server import models as _m1, auth as _auth # noqa: F401
|
||||
url4 = "sqlite:///" + db4.replace("\\", "/")
|
||||
eng1 = _sa1.create_engine(url4)
|
||||
_B1.metadata.create_all(bind=eng1)
|
||||
with eng1.begin() as con:
|
||||
for uid, un, role in [("user_boss", "root", "admin"),
|
||||
("user_pat", "pat", "project_user")]:
|
||||
con.execute(_sa1.text(
|
||||
"insert into users (id,username,email,full_name,role,is_active,"
|
||||
"failed_attempts,token_version,project_role,locale,timezone,"
|
||||
"auto_add_projects,auto_add_role,created_at,updated_at) values "
|
||||
f"('{uid}','{un}','','{un}','{role}',1,0,0,'','','',0,'',"
|
||||
"datetime('now'),datetime('now'))"))
|
||||
|
||||
class _U:
|
||||
pass
|
||||
def _tok(uid, un, role):
|
||||
u = _U(); u.id = uid; u.username = un; u.role = role; u.token_version = 0
|
||||
return _auth.create_token(u)
|
||||
boss_tok = _tok("user_boss", "root", "admin")
|
||||
pat_tok = _tok("user_pat", "pat", "project_user")
|
||||
|
||||
port4 = free_port()
|
||||
server4 = start(port4, db4, fake, required_group="")
|
||||
if server4 is None:
|
||||
print("the fourth test server would not start.")
|
||||
return 2
|
||||
b4 = f"http://127.0.0.1:{port4}"
|
||||
try:
|
||||
st, body = get(b4, "/api/auth/users", boss_tok)
|
||||
chk("an admin can list accounts", st == 200, st)
|
||||
|
||||
post(b4, "/api/auth/login", {"username": "outsider", "password": PW})
|
||||
st, body = get(b4, "/api/auth/users", boss_tok)
|
||||
rows = body if isinstance(body, list) else (body.get("users") or body.get("items") or [])
|
||||
names = [u.get("username") for u in rows if isinstance(u, dict)]
|
||||
chk("a just-provisioned account appears in the Admin console list",
|
||||
"outsider" in names, names)
|
||||
|
||||
# Exactly the request users.html sends — D13 criterion 4.
|
||||
st, _ = post_as(b4, "/api/auth/users/user_pat/role", boss_tok, {"role": "admin"})
|
||||
chk("granting admin through the console route succeeds", st == 200, st)
|
||||
chk("...and the role really changed", users_in(db4).get("pat") == "admin", users_in(db4))
|
||||
|
||||
# token_version. NOTHING in app.py bumps it any more: is_active and role are
|
||||
# re-read from the database every request, so both take effect at once without
|
||||
# it. What it still does is invalidate an ALREADY-ISSUED cookie, which is what
|
||||
# manage_users does on disable. Bump it directly and prove the effect.
|
||||
eng2 = _sa1.create_engine(url4)
|
||||
with eng2.begin() as con:
|
||||
con.execute(_sa1.text("update users set token_version = 1 where id='user_pat'"))
|
||||
eng2.dispose()
|
||||
st, _ = get(b4, "/api/auth/me", pat_tok)
|
||||
chk("bumping token_version invalidates a cookie already issued", st == 401, st)
|
||||
st, _ = get(b4, "/api/auth/me", boss_tok)
|
||||
chk("...and leaves every other session alone", st == 200, st)
|
||||
|
||||
st, body = post(b4, "/api/auth/login", {"username": "root", "password": "wrong"})
|
||||
blob = json.dumps(body).lower()
|
||||
chk("no AD sub-code leaks into a response body",
|
||||
not any(c in blob for c in ("52e", "525", "532", "533", "775", "data ")), body)
|
||||
from server import ldap_auth as _la
|
||||
chk("...though _err49 does parse one when AD sends it",
|
||||
"52e" in _la._err49({"message": "80090308: LdapErr: DSID-0C0903A9, comment: "
|
||||
"AcceptSecurityContext error, data 52e, v4563"}))
|
||||
finally:
|
||||
eng1.dispose()
|
||||
server4.kill()
|
||||
try:
|
||||
server4.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("\n" + "-" * 54)
|
||||
print(f"{len(_PASS)}/{len(_PASS) + len(_FAIL)} checks passed.")
|
||||
for f in _FAIL:
|
||||
print(" - " + f)
|
||||
return 1 if _FAIL else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
sys.exit(main())
|
||||
except Exception as exc: # noqa: BLE001
|
||||
print(f"could not run: {type(exc).__name__}: {exc}")
|
||||
sys.exit(2)
|
||||
@@ -323,13 +323,6 @@ def run(page, base, tok):
|
||||
{"text": "Probe Building One,Probe Level 1,Probe Sector B"})
|
||||
chk("the import reports it as reactivated, not created or duplicate",
|
||||
len(again["body"]["reactivated"]) == 1 and not again["body"]["created"], again["body"])
|
||||
# The 2026-08-23 production 500, pinned (locations side): Postgres-refused
|
||||
# values reject by line, on every dialect, never crash the request.
|
||||
hz = api(page, "POST", "/api/projects/projA/locations/import",
|
||||
{"text": "Probe Building One," + "Y" * 220 + ",S1", "dry_run": True})
|
||||
chk("an over-long name is a line rejection, not a 500",
|
||||
hz["status"] == 200 and hz["body"]["rejected"]
|
||||
and "200 characters" in hz["body"]["rejected"][0]["reason"], hz["body"])
|
||||
same = [n for n in api(page, "GET",
|
||||
"/api/projects/projA/locations?include_inactive=true")["body"]["nodes"]
|
||||
if n["path"] == sec["path"]]
|
||||
|
||||
@@ -54,20 +54,6 @@ def main():
|
||||
chk("locations and materials are both instances of it - not a copy beside it",
|
||||
"locList = WPListImport(" in suite and "matList = WPListImport(" in suite
|
||||
and "function locImport(dryRun){ locList.importText" in suite)
|
||||
# The 2026-08-21 outage, pinned: a Boolean server_default of sa.text('1')
|
||||
# passes on SQLite (which coerces 1) and crash-loops Postgres at deploy
|
||||
# (DatatypeMismatch). Every migration must say sa.true()/sa.false().
|
||||
import re as _re
|
||||
bad = []
|
||||
vdir = os.path.join(ROOT, "server", "alembic", "versions")
|
||||
for fn in sorted(os.listdir(vdir)):
|
||||
if not fn.endswith(".py"):
|
||||
continue
|
||||
for ln in open(os.path.join(vdir, fn), encoding="utf-8"):
|
||||
if "Boolean" in ln and "server_default" in ln and not _re.search(r"server_default=sa\.(true|false)\(\)", ln):
|
||||
bad.append("%s: %s" % (fn, ln.strip()[:90]))
|
||||
chk("no migration gives a Boolean a non-portable server_default "
|
||||
"(sa.true()/sa.false() only)", not bad, ascii_(bad[:3]))
|
||||
model = open(os.path.join(ROOT, "server", "models.py"), encoding="utf-8").read()
|
||||
mat_block = model[model.find("class MaterialItem"):model.find("class WpFile")]
|
||||
cols = re.findall(r"^\s+(\w+): Mapped", mat_block, re.M)
|
||||
@@ -105,20 +91,6 @@ def main():
|
||||
_, listing = api(base, "/api/projects/projA/materials", root)
|
||||
chk("...and nothing was written", listing["items"] == [])
|
||||
|
||||
# The 2026-08-23 production 500, pinned: what Postgres refuses (VARCHAR
|
||||
# overflow, control bytes) must come back as a per-line rejection - on
|
||||
# EVERY dialect - never crash the request.
|
||||
code, rep = api(base, "/api/projects/projA/materials/import", root, "POST",
|
||||
{"text": "Sample " + "x" * 300 + ",EA", "dry_run": True})
|
||||
chk("an over-long description is a line rejection, not a 500",
|
||||
code == 200 and rep["rejected"] and "300 characters" in rep["rejected"][0]["reason"]
|
||||
and not rep["created"], ascii_(rep))
|
||||
code, rep = api(base, "/api/projects/projA/materials/import", root, "POST",
|
||||
{"text": "Sample widget\u0000,EA", "dry_run": True})
|
||||
chk("a control byte is a line rejection, not a 500",
|
||||
code == 200 and rep["rejected"]
|
||||
and "control characters" in rep["rejected"][0]["reason"], ascii_(rep))
|
||||
|
||||
code, rep = api(base, "/api/projects/projA/materials/import", root, "POST",
|
||||
{"text": text, "dry_run": False})
|
||||
_, listing = api(base, "/api/projects/projA/materials", root)
|
||||
|
||||
@@ -1,327 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does Okta sign-in hold its guarantees? — D15/D16 / T10.7.
|
||||
|
||||
The Okta equivalent of tests/ldap_auth_check.py (D13's predecessor). Covers the
|
||||
things that would still let the app *look* fine while quietly failing:
|
||||
|
||||
1. The fake provider must be impossible to select against a real database.
|
||||
2. A one-time authorization code cannot be redeemed twice (replay).
|
||||
3. An unsolicited hit on the callback (no real login ever started) is refused,
|
||||
not a 500 — and creates no account.
|
||||
4. A denied ("Cancel") consent is refused cleanly (?error=cancelled) and
|
||||
creates no account.
|
||||
5. An unknown fake identity at consent is refused and creates no account.
|
||||
6. A correct sign-in works, and ?next= carries through to the real target —
|
||||
but only when it is a same-site path; an off-site next= is ignored.
|
||||
7. A disabled local account is refused even though Okta itself approved it —
|
||||
deprovisioning stays local (D15).
|
||||
8. An unrecognized identity is JIT-provisioned at the lowest role.
|
||||
9. An existing admin signs in and is STILL an admin, with their locally-set
|
||||
name intact — Okta never overwrites what this app already knows.
|
||||
10. OKTA_IDENTITY_CLAIM is genuinely configurable: sign-in still works with a
|
||||
non-default claim name, proving T10.3's "no hard-coded claim" promise.
|
||||
|
||||
Self-contained: throwaway SQLite + its own uvicorn. No browser, no live Okta —
|
||||
server/okta_fake.py stands in for the provider. Two layers, like its LDAP
|
||||
predecessor: guards that need no server (direct calls into okta_fake), then
|
||||
sign-in checks against a real running app.
|
||||
Exit 0 all passed, 1 a failure, 2 could not run.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
from http.cookiejar import CookieJar
|
||||
from urllib.parse import quote, urlparse
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
from cdp import free_port # noqa: E402
|
||||
|
||||
_PASS, _FAIL = [], []
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
|
||||
def chk(label, ok, detail=""):
|
||||
(_PASS if ok else _FAIL).append(label)
|
||||
print(f" {'PASS' if ok else 'FAIL'} {label}" + ("" if ok else f" {detail}"))
|
||||
|
||||
|
||||
def users_in(db_path):
|
||||
"""Read the users table straight out of the given file. Deliberately NOT
|
||||
via server.db.SessionLocal — that engine binds from DATABASE_URL at import,
|
||||
so setting the env var later keeps reading whichever file came first. The
|
||||
LDAP predecessor lost two assertions to exactly this before it was noticed."""
|
||||
import sqlite3
|
||||
con = sqlite3.connect(db_path)
|
||||
try:
|
||||
try:
|
||||
return {r[0]: (r[1], r[2], bool(r[3]))
|
||||
for r in con.execute(
|
||||
"select username, role, full_name, is_active from users")}
|
||||
except sqlite3.OperationalError:
|
||||
return {}
|
||||
finally:
|
||||
con.close()
|
||||
|
||||
|
||||
def start(port, db_path, fake, identity_claim=None):
|
||||
env = dict(os.environ)
|
||||
env["DATABASE_URL"] = "sqlite:///" + db_path.replace("\\", "/")
|
||||
env["AUTH_SECRET_KEY"] = "okta-auth-check-not-for-production"
|
||||
env["WP_OKTA_FAKE_DIRECTORY"] = json.dumps(fake)
|
||||
if identity_claim:
|
||||
env["OKTA_IDENTITY_CLAIM"] = identity_claim
|
||||
else:
|
||||
env.pop("OKTA_IDENTITY_CLAIM", None)
|
||||
proc = subprocess.Popen(
|
||||
[sys.executable, "-m", "uvicorn", "server.app:app", "--host", "127.0.0.1",
|
||||
"--port", str(port), "--log-level", "warning"],
|
||||
env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, cwd=ROOT)
|
||||
for _ in range(160):
|
||||
try:
|
||||
with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/health", timeout=1):
|
||||
return proc
|
||||
except Exception:
|
||||
if proc.poll() is not None:
|
||||
return None
|
||||
time.sleep(0.25)
|
||||
proc.kill()
|
||||
return None
|
||||
|
||||
|
||||
def opener():
|
||||
return urllib.request.build_opener(
|
||||
urllib.request.HTTPCookieProcessor(CookieJar()))
|
||||
|
||||
|
||||
def fetch(op, url):
|
||||
"""GET, auto-following redirects (urllib's default) — matches what a real
|
||||
browser does across the login -> fake-provider -> callback -> target chain.
|
||||
Returns (final_url, status, body)."""
|
||||
try:
|
||||
with op.open(url, timeout=10) as r:
|
||||
return r.geturl(), r.status, r.read().decode("utf-8", "replace")
|
||||
except urllib.error.HTTPError as e:
|
||||
return e.geturl(), e.code, e.read().decode("utf-8", "replace")
|
||||
|
||||
|
||||
def sign_in(base, op, username, next_path=None):
|
||||
"""Drive the real round trip: /api/auth/okta/login -> the fake provider's
|
||||
picker page -> consent as `username` -> okta_callback(). Every hop except
|
||||
the fake provider itself is the app's own unmodified code."""
|
||||
login_url = base + "/api/auth/okta/login"
|
||||
if next_path:
|
||||
login_url += "?next=" + quote(next_path, safe="")
|
||||
final_url, status, body = fetch(op, login_url)
|
||||
if "_fake_provider" not in final_url:
|
||||
return final_url, status, body # never reached the fake at all
|
||||
m = re.search(
|
||||
r'id="okta-fake-identity-%s" href="([^"]+)"' % re.escape(username), body)
|
||||
if not m:
|
||||
return final_url, status, body # identity not offered
|
||||
consent_url = base + m.group(1).replace("&", "&")
|
||||
return fetch(op, consent_url)
|
||||
|
||||
|
||||
def deny(base, op):
|
||||
_, _, body = fetch(op, base + "/api/auth/okta/login")
|
||||
m = re.search(r'id="okta-fake-deny" href="([^"]+)"', body)
|
||||
if not m:
|
||||
return None, None, body
|
||||
return fetch(op, base + m.group(1).replace("&", "&"))
|
||||
|
||||
|
||||
def consent_as(base, op, username, state_override=None):
|
||||
"""Reach the consent endpoint directly with an arbitrary `username` (which
|
||||
need not be one the picker actually offered) and, optionally, a `state`
|
||||
that does not match the one the login step stashed in the session — so
|
||||
'unknown identity' and 'tampered state' can be tested as the server's own
|
||||
refusal, not merely as absence from the picker's list."""
|
||||
_, _, body = fetch(op, base + "/api/auth/okta/login")
|
||||
m = re.search(r'id="okta-fake-deny" href="([^"]+)"', body)
|
||||
if not m:
|
||||
return None, None, body
|
||||
href = m.group(1).replace("&", "&").replace("deny=1", "username=" + quote(username))
|
||||
if state_override is not None:
|
||||
href = re.sub(r"state=[^&]*", "state=" + quote(state_override), href)
|
||||
return fetch(op, base + href)
|
||||
|
||||
|
||||
def main():
|
||||
print("1. the guards that do not need a server")
|
||||
|
||||
os.environ["DATABASE_URL"] = "sqlite:///./_oktacheck_unit.db"
|
||||
os.environ["WP_OKTA_FAKE_DIRECTORY"] = json.dumps({"root": {"email": "r@x.test", "name": "R"}})
|
||||
from server import okta_fake
|
||||
|
||||
chk("the fake is active against a SQLite database", okta_fake.is_active())
|
||||
|
||||
out = subprocess.run(
|
||||
[sys.executable, "-c",
|
||||
"from server import okta_fake; print(okta_fake.is_active())"],
|
||||
cwd=ROOT, capture_output=True, text=True,
|
||||
env={**os.environ,
|
||||
"DATABASE_URL": "postgresql+psycopg://u:p@localhost:5432/db",
|
||||
"AUTH_SECRET_KEY": "x",
|
||||
"WP_OKTA_FAKE_DIRECTORY": json.dumps({"root": {"email": "r@x.test"}})})
|
||||
chk("the fake provider REFUSES to work against a non-SQLite database",
|
||||
out.stdout.strip() == "False", out.stdout.strip() or out.stderr[-200:])
|
||||
|
||||
code = okta_fake.new_code({"preferred_username": "root"})
|
||||
first = okta_fake.consume_code(code)
|
||||
second = okta_fake.consume_code(code)
|
||||
chk("a fresh code redeems once", first == {"preferred_username": "root"}, first)
|
||||
chk("...and a REPLAYED code is refused the second time", second is None, second)
|
||||
|
||||
print("\n2. sign-in, against a server")
|
||||
db_fd, db_path = tempfile.mkstemp(suffix=".db"); os.close(db_fd)
|
||||
port = free_port()
|
||||
fake = {"root": {"email": "root@example.test", "name": "Root Person"},
|
||||
"newperson": {"email": "newperson@example.test", "name": "New Person"}}
|
||||
server = start(port, db_path, fake)
|
||||
if server is None:
|
||||
print("the test server would not start.")
|
||||
return 2
|
||||
base = f"http://127.0.0.1:{port}"
|
||||
try:
|
||||
# Seed one pre-existing admin and one pre-existing but disabled account,
|
||||
# the same way manage_users.py / the admin console would have left them.
|
||||
import sqlalchemy as _sa
|
||||
from server.db import Base
|
||||
from server import models # noqa: F401
|
||||
eng = _sa.create_engine("sqlite:///" + db_path.replace("\\", "/"))
|
||||
Base.metadata.create_all(bind=eng)
|
||||
with eng.begin() as con:
|
||||
con.execute(_sa.text(
|
||||
"insert into users (id,username,email,full_name,role,is_active,"
|
||||
"failed_attempts,token_version,project_role,locale,timezone,"
|
||||
"auto_add_projects,auto_add_role,created_at,updated_at) values "
|
||||
"('user_root','root','','Set By Hand','admin',1,0,0,'','','',0,'',"
|
||||
"datetime('now'),datetime('now'))"))
|
||||
con.execute(_sa.text(
|
||||
"insert into users (id,username,email,full_name,role,is_active,"
|
||||
"failed_attempts,token_version,project_role,locale,timezone,"
|
||||
"auto_add_projects,auto_add_role,created_at,updated_at) values "
|
||||
"('user_shelved','shelved','','Shelved Person','project_user',0,0,0,"
|
||||
"'','','',0,'',datetime('now'),datetime('now'))"))
|
||||
eng.dispose()
|
||||
fake["shelved"] = {"email": "shelved@example.test", "name": "Shelved Person"}
|
||||
# Restart so the running process picks up the augmented directory.
|
||||
server.kill(); server.wait(timeout=10)
|
||||
server = start(port, db_path, fake)
|
||||
if server is None:
|
||||
print("the test server would not restart with the augmented directory.")
|
||||
return 2
|
||||
|
||||
final_url, status, _ = sign_in(base, opener(), "root")
|
||||
chk("a seeded identity signs in", status == 200 and urlparse(final_url).path == "/index.html",
|
||||
(final_url, status))
|
||||
chk("...and the existing admin is STILL an admin",
|
||||
users_in(db_path).get("root", ("", "", None))[0] == "admin", users_in(db_path))
|
||||
chk("...with their locally-set name untouched by Okta",
|
||||
users_in(db_path).get("root", (None, None))[1] == "Set By Hand", users_in(db_path))
|
||||
|
||||
before = set(users_in(db_path))
|
||||
final_url, status, _ = sign_in(base, opener(), "newperson")
|
||||
chk("an unrecognized identity is JIT-provisioned", status == 200, (final_url, status))
|
||||
chk("...at the lowest role", users_in(db_path).get("newperson", ("", "", None))[0]
|
||||
== "project_user", users_in(db_path).get("newperson"))
|
||||
chk("...and only one new row appeared",
|
||||
set(users_in(db_path)) - before == {"newperson"}, set(users_in(db_path)) - before)
|
||||
|
||||
final_url, status, _ = sign_in(base, opener(), "shelved")
|
||||
chk("a disabled local account is refused despite Okta approving it",
|
||||
"error=disabled" in final_url, final_url)
|
||||
|
||||
before = set(users_in(db_path))
|
||||
final_url, status, _ = consent_as(base, opener(), "nobody-such-identity")
|
||||
# okta_callback()'s `except OAuthError` is deliberately generic (T10.5:
|
||||
# a plain-language ?error= for whatever Authlib/the provider rejected,
|
||||
# not a code-by-code breakdown) — so this lands on the same ?error=
|
||||
# cancelled as every other refusal, not a distinct "invalid_request".
|
||||
# The thing actually under test is the SERVER-side refusal, verified by
|
||||
# checking no account got created — not the display string.
|
||||
chk("consenting as an identity the fake never offered is refused BY THE SERVER"
|
||||
" (not just absent from the picker)",
|
||||
"login.html" in final_url and "error=cancelled" in final_url, final_url)
|
||||
chk("...and creates nothing", set(users_in(db_path)) == before,
|
||||
set(users_in(db_path)) - before)
|
||||
|
||||
before = set(users_in(db_path))
|
||||
final_url, status, _ = consent_as(base, opener(), "root", state_override="tampered-state")
|
||||
chk("a consent hit whose state does not match the session is refused",
|
||||
"login.html" in final_url and "error=cancelled" in final_url, final_url)
|
||||
chk("...and creates nothing", set(users_in(db_path)) == before,
|
||||
set(users_in(db_path)) - before)
|
||||
|
||||
before = set(users_in(db_path))
|
||||
final_url, status, _ = deny(base, opener())
|
||||
chk("denying consent lands back on login with a plain message",
|
||||
"login.html" in final_url and "error=cancelled" in final_url, final_url)
|
||||
chk("...and creates nothing", set(users_in(db_path)) == before,
|
||||
set(users_in(db_path)) - before)
|
||||
|
||||
cold = opener()
|
||||
final_url, status, _ = fetch(
|
||||
cold, base + "/api/auth/okta/callback?code=forged&state=forged")
|
||||
chk("an unsolicited hit on the callback (no login ever started) is refused, not a 500",
|
||||
status == 200 and "login.html" in final_url and "error=cancelled" in final_url,
|
||||
(final_url, status))
|
||||
|
||||
final_url, status, _ = sign_in(base, opener(), "root", next_path="/wp-creation-index.html?wp=x")
|
||||
chk("a same-site ?next= survives the round trip",
|
||||
urlparse(final_url).path == "/wp-creation-index.html"
|
||||
and "wp=x" in urlparse(final_url).query, final_url)
|
||||
|
||||
final_url, status, _ = sign_in(base, opener(), "root", next_path="https://evil.example.com/phish")
|
||||
chk("an off-site ?next= is ignored, not honoured",
|
||||
urlparse(final_url).path == "/index.html", final_url)
|
||||
finally:
|
||||
server.kill()
|
||||
try:
|
||||
server.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("\n3. the identity claim name is genuinely configurable (T10.3)")
|
||||
db_fd2, db2 = tempfile.mkstemp(suffix=".db"); os.close(db_fd2)
|
||||
port2 = free_port()
|
||||
server2 = start(port2, db2, {"root": {"email": "root@example.test", "name": "Root"}},
|
||||
identity_claim="upn")
|
||||
if server2 is None:
|
||||
print("the identity-claim test server would not start.")
|
||||
return 2
|
||||
try:
|
||||
base2 = f"http://127.0.0.1:{port2}"
|
||||
final_url, status, _ = sign_in(base2, opener(), "root")
|
||||
chk("sign-in works with a non-default OKTA_IDENTITY_CLAIM (upn)",
|
||||
status == 200 and urlparse(final_url).path == "/index.html", (final_url, status))
|
||||
chk("...and JIT-provisioned the account under that identity",
|
||||
users_in(db2).get("root", ("", "", None))[0] == "project_user", users_in(db2))
|
||||
finally:
|
||||
server2.kill()
|
||||
try:
|
||||
server2.wait(timeout=10)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
|
||||
print("\n" + "-" * 54)
|
||||
print(f"{len(_PASS)}/{len(_PASS) + len(_FAIL)} checks passed.")
|
||||
for f in _FAIL:
|
||||
print(" - " + f)
|
||||
return 1 if _FAIL else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
sys.exit(main())
|
||||
except Exception as exc: # noqa: BLE001
|
||||
print(f"could not run: {type(exc).__name__}: {exc}")
|
||||
sys.exit(2)
|
||||
@@ -1,252 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does the Okta Management API client keep its promises? - D18 / T13.2.
|
||||
|
||||
The one promise that matters: a failure is never an empty list. T13.3 reads an
|
||||
empty list as "nobody is active", so a client that returned [] when Okta was
|
||||
down would disable the whole org. Every failure below must raise OktaSyncError.
|
||||
|
||||
Also checked: the client uses its own credential (never the OIDC client secret),
|
||||
follows pagination, never sends the token to another host, never follows a
|
||||
redirect, and never lets the token reach a log line, an error message, or
|
||||
describe().
|
||||
|
||||
Self-contained: no server, no database, no network, no browser. httpx's
|
||||
MockTransport stands in for Okta.
|
||||
Exit 0 all passed, 1 a failure.
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
import sys
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
sys.path.insert(0, ROOT)
|
||||
|
||||
import httpx # noqa: E402
|
||||
|
||||
from server import okta_auth, okta_sync # noqa: E402
|
||||
|
||||
TOKEN = "00tok-SECRET-api-token-xyz"
|
||||
CLIENT_SECRET = "oidc-client-SECRET-abc"
|
||||
ORG = "https://example.okta.com"
|
||||
|
||||
fails = 0
|
||||
|
||||
|
||||
def chk(label, ok, extra=""):
|
||||
global fails
|
||||
print(("PASS " if ok else "FAIL ") + label + (f" [{extra}]" if (extra and not ok) else ""))
|
||||
if not ok:
|
||||
fails += 1
|
||||
|
||||
|
||||
class Capture(logging.Handler):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.lines = []
|
||||
|
||||
def emit(self, record):
|
||||
self.lines.append(record.getMessage())
|
||||
|
||||
|
||||
cap = Capture()
|
||||
logging.getLogger("wpsuite").addHandler(cap)
|
||||
logging.getLogger("wpsuite").setLevel(logging.DEBUG)
|
||||
|
||||
|
||||
def reset_env():
|
||||
os.environ["OKTA_API_TOKEN"] = TOKEN
|
||||
os.environ["OKTA_CLIENT_SECRET"] = CLIENT_SECRET
|
||||
os.environ.pop("OKTA_ORG_URL", None)
|
||||
os.environ.pop("OKTA_SYNC_PROFILE_ATTRIBUTE", None)
|
||||
okta_auth.ISSUER = f"{ORG}/oauth2/default"
|
||||
okta_auth.IDENTITY_CLAIM = "preferred_username"
|
||||
|
||||
|
||||
def user(login, status="ACTIVE", **profile):
|
||||
p = {"login": login, "email": login}
|
||||
p.update(profile)
|
||||
return {"id": "00u" + login, "status": status, "profile": p}
|
||||
|
||||
|
||||
def client(handler):
|
||||
return httpx.Client(transport=httpx.MockTransport(handler))
|
||||
|
||||
|
||||
def raises(handler, label, **kw):
|
||||
"""Run fetch_users against `handler`; it must raise OktaSyncError, and the
|
||||
message must not hold the token."""
|
||||
reset_env()
|
||||
try:
|
||||
out = okta_sync.fetch_users(http=client(handler))
|
||||
except okta_sync.OktaSyncError as exc:
|
||||
msg = str(exc)
|
||||
clean = TOKEN not in msg and CLIENT_SECRET not in msg and "example.okta.com" not in msg
|
||||
chk(f"{label}: raises, message has no token or host", clean, msg)
|
||||
return msg
|
||||
except Exception as exc: # the wrong exception type
|
||||
chk(f"{label}: raises OktaSyncError", False, f"{type(exc).__name__}: {exc}")
|
||||
return ""
|
||||
chk(f"{label}: raises (did NOT raise, returned {out!r})", False)
|
||||
return ""
|
||||
|
||||
|
||||
def ok(body):
|
||||
return lambda req: httpx.Response(200, json=body)
|
||||
|
||||
|
||||
# ── 1. a good fetch ───────────────────────────────────────────────────────────
|
||||
print("\n1. a good fetch")
|
||||
reset_env()
|
||||
seen = []
|
||||
|
||||
|
||||
def good(req):
|
||||
seen.append(req)
|
||||
return httpx.Response(200, json=[user("alice", "ACTIVE"), user("bob", "suspended")])
|
||||
|
||||
|
||||
users = okta_sync.fetch_users(http=client(good))
|
||||
chk("returns every user", [u.identity for u in users] == ["alice", "bob"])
|
||||
chk("status is upper case", [u.status for u in users] == ["ACTIVE", "SUSPENDED"])
|
||||
chk("asks the users endpoint of the org", str(seen[0].url).startswith(f"{ORG}/api/v1/users"))
|
||||
chk("asks for the page maximum", seen[0].url.params.get("limit") == "200")
|
||||
chk("authenticates with the API token (SSWS)", seen[0].headers.get("authorization") == f"SSWS {TOKEN}")
|
||||
chk("never sends the OIDC client secret", CLIENT_SECRET not in str(seen[0].headers))
|
||||
|
||||
# ── 2. pagination ─────────────────────────────────────────────────────────────
|
||||
print("\n2. pagination")
|
||||
reset_env()
|
||||
calls = []
|
||||
|
||||
|
||||
def paged(req):
|
||||
calls.append(req)
|
||||
if "after=p2" not in str(req.url):
|
||||
return httpx.Response(200, json=[user("alice")],
|
||||
headers={"Link": f'<{ORG}/api/v1/users?limit=200&after=p2>; rel="next"'})
|
||||
return httpx.Response(200, json=[user("bob")])
|
||||
|
||||
|
||||
users = okta_sync.fetch_users(http=client(paged))
|
||||
chk("follows the next link and returns both pages", [u.identity for u in users] == ["alice", "bob"])
|
||||
chk("two requests, no more", len(calls) == 2)
|
||||
chk("page 2 also carries the token", calls[1].headers.get("authorization") == f"SSWS {TOKEN}")
|
||||
|
||||
# ── 3. the failure rule: an error is never an empty list ──────────────────────
|
||||
print("\n3. every failure raises (never returns an empty list)")
|
||||
for code in (401, 403, 404, 429, 500, 502, 503):
|
||||
raises(lambda req, c=code: httpx.Response(c, json={"errorCode": "x"}), f"HTTP {code}")
|
||||
raises(lambda req: httpx.Response(302, headers={"Location": "https://evil.example/"}), "a redirect (never followed)")
|
||||
raises(lambda req: (_ for _ in ()).throw(httpx.ConnectError("boom to https://example.okta.com/api/v1/users")), "connection error")
|
||||
raises(lambda req: (_ for _ in ()).throw(httpx.ReadTimeout("slow")), "timeout")
|
||||
raises(lambda req: httpx.Response(200, text="<html>not json</html>"), "body is not JSON")
|
||||
raises(ok({"errorCode": "E0000011"}), "body is an object, not a list")
|
||||
raises(ok("a string"), "body is a string")
|
||||
raises(ok([]), "an empty list (not credible for a real org)")
|
||||
raises(ok(["alice"]), "an item that is not an object")
|
||||
raises(ok([{"profile": {"login": "a"}}]), "an item with no status")
|
||||
raises(ok([{"status": "ACTIVE"}]), "an item with no profile")
|
||||
raises(ok([{"status": "ACTIVE", "profile": {}}]), "an item with no login")
|
||||
raises(ok([{"status": "ACTIVE", "profile": {"login": " "}}]), "an item with a blank login")
|
||||
raises(ok([user("alice"), {"status": "ACTIVE", "profile": {}}]), "one bad item among good ones (never skipped)")
|
||||
|
||||
# ── 4. misconfiguration raises ────────────────────────────────────────────────
|
||||
print("\n4. misconfiguration")
|
||||
reset_env()
|
||||
os.environ["OKTA_API_TOKEN"] = ""
|
||||
try:
|
||||
okta_sync.fetch_users(http=client(good))
|
||||
chk("no token raises", False)
|
||||
except okta_sync.OktaSyncError:
|
||||
chk("no token raises", True)
|
||||
reset_env()
|
||||
okta_auth.ISSUER = ""
|
||||
try:
|
||||
okta_sync.fetch_users(http=client(good))
|
||||
chk("no org URL raises", False)
|
||||
except okta_sync.OktaSyncError:
|
||||
chk("no org URL raises", True)
|
||||
reset_env()
|
||||
os.environ["OKTA_ORG_URL"] = "http://example.okta.com"
|
||||
sent = []
|
||||
try:
|
||||
okta_sync.fetch_users(http=client(lambda r: sent.append(r) or httpx.Response(200, json=[user("a")])))
|
||||
chk("an http org URL raises", False)
|
||||
except okta_sync.OktaSyncError:
|
||||
chk("an http org URL raises", True)
|
||||
chk("...and no request was made (token never sent over http)", sent == [])
|
||||
|
||||
# ── 5. never leaks the token to another host, never loops forever ─────────────
|
||||
print("\n5. next-link safety")
|
||||
reset_env()
|
||||
hosts = []
|
||||
|
||||
|
||||
def evil_link(req):
|
||||
hosts.append(req.url.host)
|
||||
return httpx.Response(200, json=[user("alice")],
|
||||
headers={"Link": '<https://evil.example/steal>; rel="next"'})
|
||||
|
||||
|
||||
raises(evil_link, "a next link to another host")
|
||||
chk("...the other host was never contacted", hosts == ["example.okta.com"])
|
||||
|
||||
count = []
|
||||
|
||||
|
||||
def endless(req):
|
||||
count.append(1)
|
||||
return httpx.Response(200, json=[user("alice")],
|
||||
headers={"Link": f'<{ORG}/api/v1/users?after={len(count)}>; rel="next"'})
|
||||
|
||||
|
||||
raises(endless, "an endless next chain (page cap)")
|
||||
chk(f"...stops at the cap ({okta_sync.MAX_PAGES} requests)", len(count) == okta_sync.MAX_PAGES, str(len(count)))
|
||||
|
||||
# ── 6. org URL and identity attribute ─────────────────────────────────────────
|
||||
print("\n6. org URL and identity attribute")
|
||||
reset_env()
|
||||
chk("org URL is the issuer's scheme and host", okta_sync.org_url() == ORG)
|
||||
os.environ["OKTA_ORG_URL"] = "https://corp.okta.com/"
|
||||
chk("OKTA_ORG_URL wins, trailing slash removed", okta_sync.org_url() == "https://corp.okta.com")
|
||||
reset_env()
|
||||
okta_auth.IDENTITY_CLAIM = "email"
|
||||
body = [{"status": "ACTIVE", "profile": {"login": "alice", "email": "alice@x.com"}}]
|
||||
chk("claim 'email' reads profile.email", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice@x.com")
|
||||
okta_auth.IDENTITY_CLAIM = "sAMAccountName"
|
||||
body = [{"status": "ACTIVE", "profile": {"login": "alice@x.com", "sAMAccountName": "alice"}}]
|
||||
chk("a custom claim reads profile[<claim>]", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice")
|
||||
os.environ["OKTA_SYNC_PROFILE_ATTRIBUTE"] = "login"
|
||||
chk("OKTA_SYNC_PROFILE_ATTRIBUTE overrides", okta_sync.fetch_users(http=client(ok(body)))[0].identity == "alice@x.com")
|
||||
|
||||
# ── 7. the token never leaks ──────────────────────────────────────────────────
|
||||
print("\n7. the token never leaks")
|
||||
reset_env()
|
||||
chk("describe() has no token", TOKEN not in okta_sync.describe() and "configured" in okta_sync.describe())
|
||||
os.environ["OKTA_API_TOKEN"] = ""
|
||||
chk("describe() says DISABLED without a token", "DISABLED" in okta_sync.describe())
|
||||
reset_env()
|
||||
every_log = " ".join(cap.lines)
|
||||
chk("no log line holds the API token", TOKEN not in every_log)
|
||||
chk("no log line holds the client secret", CLIENT_SECRET not in every_log)
|
||||
|
||||
# ── 8. the whole fetch is time-bounded (T13.4 relies on it) ──────────────────
|
||||
print("\n8. the whole fetch is time-bounded")
|
||||
reset_env()
|
||||
saved = okta_sync.TOTAL_DEADLINE_SECONDS
|
||||
okta_sync.TOTAL_DEADLINE_SECONDS = 0.0
|
||||
|
||||
|
||||
def slow_pages(req):
|
||||
return httpx.Response(200, json=[user("alice")],
|
||||
headers={"Link": f'<{ORG}/api/v1/users?after=x>; rel="next"'})
|
||||
|
||||
|
||||
raises(slow_pages, "a fetch that runs past the total deadline")
|
||||
okta_sync.TOTAL_DEADLINE_SECONDS = saved
|
||||
chk("the real deadline is under the shortest allowed interval",
|
||||
okta_sync.TOTAL_DEADLINE_SECONDS < okta_sync.INTERVAL_MIN_SECONDS)
|
||||
|
||||
print()
|
||||
print("ALL PASSED" if not fails else f"{fails} FAILED")
|
||||
sys.exit(0 if not fails else 1)
|
||||
@@ -1,277 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does the Okta sync use DPoP correctly? - D24 / T13.10.
|
||||
|
||||
A strict fake Okta (httpx.MockTransport) checks every DPoP proof the way RFC 9449 says a
|
||||
server must: the header (typ dpop+jwt, ES256, a PUBLIC jwk only), the signature against
|
||||
that jwk, htm, htu (no query), iat, a one-time jti, the nonce when the server asked for
|
||||
one, and on an API call the ath hash of the access token and the same key as at the token
|
||||
request. Also: auto mode finds out that DPoP is required, the nonce dance at the token
|
||||
endpoint and at the API, paging, off mode, bounded retries, and no secret in any message.
|
||||
|
||||
Self-contained: no network, no server, no browser. Exit 0 all passed, 1 a failure.
|
||||
"""
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
from urllib.parse import parse_qs
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
sys.path.insert(0, ROOT)
|
||||
os.environ["DATABASE_URL"] = "sqlite://"
|
||||
for v in ("OKTA_API_TOKEN", "OKTA_SYNC_PROFILE_ATTRIBUTE", "OKTA_SYNC_DPOP"):
|
||||
os.environ.pop(v, None)
|
||||
os.environ["OKTA_ORG_URL"] = "https://example.okta.com"
|
||||
|
||||
import httpx # noqa: E402
|
||||
import jwt # noqa: E402
|
||||
from cryptography.hazmat.primitives.asymmetric import rsa # noqa: E402
|
||||
|
||||
from server import okta_sync # noqa: E402
|
||||
from server.okta_sync import OktaSyncError # noqa: E402
|
||||
|
||||
fails = 0
|
||||
|
||||
|
||||
def chk(label, ok, extra=""):
|
||||
global fails
|
||||
print(("PASS " if ok else "FAIL ") + label + (f" [{extra}]" if (extra and not ok) else ""))
|
||||
if not ok:
|
||||
fails += 1
|
||||
|
||||
|
||||
pk = rsa.generate_private_key(public_exponent=65537, key_size=2048)
|
||||
CLIENT_JWK = json.loads(jwt.algorithms.RSAAlgorithm.to_jwk(pk))
|
||||
CLIENT_JWK.update({"kid": "k1", "alg": "RS256", "use": "sig"})
|
||||
CLIENT_PUB = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps({k: CLIENT_JWK[k] for k in ("kty", "n", "e")}))
|
||||
os.environ["OKTA_SYNC_CLIENT_ID"] = "0oaCLIENT"
|
||||
os.environ["OKTA_SYNC_PRIVATE_KEY"] = json.dumps(CLIENT_JWK)
|
||||
|
||||
TOKEN_URL = "https://example.okta.com/oauth2/v1/token"
|
||||
USERS_URL = "https://example.okta.com/api/v1/users"
|
||||
ACCESS = "ACCESS-TOKEN-VALUE-123"
|
||||
|
||||
|
||||
def thumb(jwk):
|
||||
return json.dumps({k: jwk[k] for k in ("crv", "kty", "x", "y")}, sort_keys=True, separators=(",", ":"))
|
||||
|
||||
|
||||
class StrictOkta:
|
||||
def __init__(self, require_dpop=False, token_nonce=False, api_nonce=False, always_bad_proof=False,
|
||||
token_type_if_plain="Bearer", pages=1, endless_nonce=False):
|
||||
self.endless_nonce = endless_nonce
|
||||
self.require_dpop, self.token_nonce, self.api_nonce = require_dpop, token_nonce, api_nonce
|
||||
self.always_bad_proof, self.token_type_if_plain, self.pages = always_bad_proof, token_type_if_plain, pages
|
||||
self.token_calls = 0
|
||||
self.api_calls = 0
|
||||
self.problems = [] # anything the strict checks found wrong
|
||||
self.jtis = set()
|
||||
self.assertion_jtis = set()
|
||||
self.token_key = None # thumbprint of the key used at the token request
|
||||
self.api_keys = set()
|
||||
self.dpop_on_token = 0
|
||||
self.dpop_on_api = 0
|
||||
self.issued_nonce = "nonce-" + os.urandom(3).hex()
|
||||
self.api_seen = []
|
||||
|
||||
def _check_proof(self, req, url, method, ath=None, need_nonce=False):
|
||||
proof = req.headers.get("dpop")
|
||||
if not proof:
|
||||
return None, "no proof"
|
||||
try:
|
||||
hdr = jwt.get_unverified_header(proof)
|
||||
except Exception as e: # noqa: BLE001
|
||||
return None, f"unreadable header {type(e).__name__}"
|
||||
if hdr.get("typ") != "dpop+jwt" or hdr.get("alg") != "ES256":
|
||||
self.problems.append(f"bad header typ/alg {hdr.get('typ')} {hdr.get('alg')}")
|
||||
jwk = hdr.get("jwk")
|
||||
if not isinstance(jwk, dict) or "d" in jwk or jwk.get("kty") != "EC":
|
||||
self.problems.append("proof jwk missing or holds private part")
|
||||
return None, "bad jwk"
|
||||
try:
|
||||
claims = jwt.decode(proof, jwt.algorithms.ECAlgorithm.from_jwk(json.dumps(jwk)),
|
||||
algorithms=["ES256"], options={"verify_iat": False})
|
||||
except Exception as e: # noqa: BLE001
|
||||
self.problems.append(f"signature did not verify: {type(e).__name__}")
|
||||
return None, "bad signature"
|
||||
if claims.get("htm") != method:
|
||||
self.problems.append(f"htm {claims.get('htm')} != {method}")
|
||||
if claims.get("htu") != url:
|
||||
self.problems.append(f"htu {claims.get('htu')} != {url}")
|
||||
if abs(time.time() - int(claims.get("iat", 0))) > 60:
|
||||
self.problems.append("iat not current")
|
||||
if claims.get("jti") in self.jtis or not claims.get("jti"):
|
||||
self.problems.append("jti missing or reused")
|
||||
self.jtis.add(claims.get("jti"))
|
||||
if ath is not None and claims.get("ath") != ath:
|
||||
self.problems.append("ath wrong")
|
||||
if ath is None and "ath" in claims:
|
||||
self.problems.append("ath present on a token request")
|
||||
if need_nonce and claims.get("nonce") != self.issued_nonce:
|
||||
return jwk, "nonce"
|
||||
return jwk, None
|
||||
|
||||
def handler(self, req: httpx.Request):
|
||||
if req.url.path == "/oauth2/v1/token":
|
||||
self.token_calls += 1
|
||||
form = {k: v[0] for k, v in parse_qs(req.content.decode()).items()}
|
||||
try:
|
||||
a = jwt.decode(form["client_assertion"], CLIENT_PUB, algorithms=["RS256"], audience=TOKEN_URL)
|
||||
if a["jti"] in self.assertion_jtis:
|
||||
self.problems.append("client assertion jti reused")
|
||||
self.assertion_jtis.add(a["jti"])
|
||||
except Exception as e: # noqa: BLE001
|
||||
self.problems.append(f"client assertion bad: {type(e).__name__}")
|
||||
has = "dpop" in req.headers
|
||||
if has:
|
||||
self.dpop_on_token += 1
|
||||
if self.always_bad_proof:
|
||||
return httpx.Response(400, json={"error": "invalid_dpop_proof"})
|
||||
if self.require_dpop and not has:
|
||||
return httpx.Response(400, json={"error": "invalid_dpop_proof"})
|
||||
if not has:
|
||||
return httpx.Response(200, json={"token_type": self.token_type_if_plain, "access_token": ACCESS})
|
||||
jwk, bad = self._check_proof(req, TOKEN_URL, "POST", need_nonce=self.token_nonce)
|
||||
if bad == "nonce" or (self.endless_nonce and not bad):
|
||||
return httpx.Response(400, json={"error": "use_dpop_nonce"}, headers={"DPoP-Nonce": self.issued_nonce})
|
||||
if bad:
|
||||
return httpx.Response(400, json={"error": "invalid_dpop_proof"})
|
||||
self.token_key = thumb(jwk)
|
||||
return httpx.Response(200, json={"token_type": "DPoP", "access_token": ACCESS})
|
||||
if req.url.path == "/api/v1/users":
|
||||
self.api_calls += 1
|
||||
auth = req.headers.get("authorization", "")
|
||||
self.api_seen.append(auth.split(" ")[0])
|
||||
if auth.startswith("DPoP "):
|
||||
self.dpop_on_api += 1
|
||||
if auth != f"DPoP {ACCESS}":
|
||||
self.problems.append("wrong DPoP access token")
|
||||
ath = base64.urlsafe_b64encode(hashlib.sha256(ACCESS.encode()).digest()).rstrip(b"=").decode()
|
||||
jwk, bad = self._check_proof(req, USERS_URL, "GET", ath=ath, need_nonce=self.api_nonce)
|
||||
if bad == "nonce":
|
||||
return httpx.Response(401, json={"errorCode": "invalid_token"},
|
||||
headers={"DPoP-Nonce": self.issued_nonce,
|
||||
"WWW-Authenticate": 'DPoP error="use_dpop_nonce"'})
|
||||
if bad:
|
||||
return httpx.Response(401, json={})
|
||||
self.api_keys.add(thumb(jwk))
|
||||
if thumb(jwk) != self.token_key:
|
||||
self.problems.append("API proof key differs from the token request key")
|
||||
elif auth == f"Bearer {ACCESS}":
|
||||
if "dpop" in req.headers:
|
||||
self.problems.append("DPoP header sent with a plain Bearer token")
|
||||
else:
|
||||
return httpx.Response(401, json={})
|
||||
page = int(req.url.params.get("after", "0") or 0)
|
||||
body = [{"status": "ACTIVE", "profile": {"login": f"user{page}"}}]
|
||||
headers = {}
|
||||
if page + 1 < self.pages:
|
||||
headers["Link"] = f'<{USERS_URL}?after={page + 1}&limit=200>; rel="next"'
|
||||
return httpx.Response(200, json=body, headers=headers)
|
||||
return httpx.Response(404)
|
||||
|
||||
def client(self):
|
||||
return httpx.Client(transport=httpx.MockTransport(self.handler))
|
||||
|
||||
|
||||
def run(fake, mode=None):
|
||||
if mode is None:
|
||||
os.environ.pop("OKTA_SYNC_DPOP", None)
|
||||
else:
|
||||
os.environ["OKTA_SYNC_DPOP"] = mode
|
||||
try:
|
||||
return okta_sync.fetch_users(http=fake.client()), None
|
||||
except OktaSyncError as e:
|
||||
return None, str(e)
|
||||
|
||||
|
||||
# 1. auto: a plain app needs no DPoP
|
||||
f = StrictOkta()
|
||||
users, err = run(f)
|
||||
chk("auto, app without DPoP: works with one token call, Bearer", users and f.token_calls == 1 and f.dpop_on_token == 0 and f.api_seen == ["Bearer"], str(err))
|
||||
chk("no problems found by the strict checks", not f.problems, str(f.problems))
|
||||
|
||||
# 2. auto: the app requires DPoP (what your tenant answered)
|
||||
f = StrictOkta(require_dpop=True)
|
||||
users, err = run(f)
|
||||
chk("auto, app requires DPoP: plain try, then DPoP try, then users", users and f.token_calls == 2 and f.dpop_on_token == 1, f"{err} calls={f.token_calls}")
|
||||
chk("API calls carry DPoP and the access token", f.api_calls == 1 and f.dpop_on_api == 1 and f.api_seen == ["DPoP"])
|
||||
chk("API proof used the same key as the token request", len(f.api_keys) == 1 and f.api_keys == {f.token_key})
|
||||
chk("every proof and assertion id is unique, no problems", not f.problems, str(f.problems))
|
||||
|
||||
# 3. nonce at the token endpoint
|
||||
f = StrictOkta(require_dpop=True, token_nonce=True)
|
||||
users, err = run(f)
|
||||
chk("token nonce: plain, DPoP without nonce, DPoP with nonce", users and f.token_calls == 3, f"{err} calls={f.token_calls}")
|
||||
chk("token nonce: no problems", not f.problems, str(f.problems))
|
||||
|
||||
# 4. nonce at the API
|
||||
f = StrictOkta(require_dpop=True, api_nonce=True)
|
||||
users, err = run(f)
|
||||
chk("API nonce: the call is repeated once with the nonce", users and f.api_calls == 2 and f.dpop_on_api == 2, f"{err} calls={f.api_calls}")
|
||||
chk("API nonce: no problems", not f.problems, str(f.problems))
|
||||
|
||||
# 5. paging: a new proof for every page, htu without the query
|
||||
f = StrictOkta(require_dpop=True, pages=3)
|
||||
users, err = run(f)
|
||||
chk("3 pages with DPoP: 3 users, 3 API calls", users and len(users) == 3 and f.api_calls == 3, f"{err} {f.api_calls}")
|
||||
chk("3 pages: htu had no query, jti unique, same key", not f.problems, str(f.problems))
|
||||
|
||||
# 6. mode on goes straight to DPoP
|
||||
f = StrictOkta(require_dpop=True)
|
||||
users, err = run(f, "on")
|
||||
chk("mode on: DPoP from the first token call", users and f.token_calls == 1 and f.dpop_on_token == 1, f"{err} {f.token_calls}")
|
||||
f = StrictOkta()
|
||||
users, err = run(f, "true")
|
||||
chk("mode on with an app that does not need it: still works", users is not None and not f.problems, f"{err} {f.problems}")
|
||||
|
||||
# 7. mode off
|
||||
f = StrictOkta(require_dpop=True)
|
||||
users, err = run(f, "off")
|
||||
chk("mode off, app requires DPoP: stops after one call, names the error", users is None and f.token_calls == 1 and "invalid_dpop_proof" in err, str(err))
|
||||
f = StrictOkta(token_type_if_plain="DPoP")
|
||||
users, err = run(f, "off")
|
||||
chk("mode off, DPoP-bound token: clear refusal, users never called", users is None and "DPoP-bound" in err and f.api_calls == 0, str(err))
|
||||
f = StrictOkta(token_type_if_plain="mac")
|
||||
users, err = run(f)
|
||||
chk("unknown token type refused", users is None and "neither" in err, str(err))
|
||||
|
||||
# 8. bounded retries and a hopeless server
|
||||
f = StrictOkta(always_bad_proof=True)
|
||||
users, err = run(f)
|
||||
chk("a server that always rejects the proof: bounded calls, clear error", users is None and f.token_calls <= 4 and "invalid_dpop_proof" in err and "DPoP was used" in err, f"{err} {f.token_calls}")
|
||||
chk("no users call when the token failed", f.api_calls == 0)
|
||||
|
||||
f = StrictOkta(require_dpop=True, token_nonce=True, endless_nonce=True)
|
||||
users, err = run(f)
|
||||
chk("a server that asks for a nonce forever: bounded calls, clear error", users is None and f.token_calls <= 4 and "use_dpop_nonce" in err, f"{err} {f.token_calls}")
|
||||
|
||||
# 9. a new key on each run
|
||||
f1, f2 = StrictOkta(require_dpop=True), StrictOkta(require_dpop=True)
|
||||
run(f1); run(f2)
|
||||
chk("each run makes its own DPoP key", f1.token_key and f2.token_key and f1.token_key != f2.token_key)
|
||||
|
||||
# 10. secrets and startup line
|
||||
f = StrictOkta(always_bad_proof=True)
|
||||
_, err = run(f)
|
||||
chk("error holds no token, key or assertion", ACCESS not in err and CLIENT_JWK["d"][:12] not in err)
|
||||
line = okta_sync.describe()
|
||||
chk("startup line names the DPoP mode", "DPoP auto" in line, line)
|
||||
os.environ["OKTA_SYNC_DPOP"] = "on"
|
||||
chk("startup line follows the setting", "DPoP on" in okta_sync.describe())
|
||||
os.environ.pop("OKTA_SYNC_DPOP")
|
||||
|
||||
# 11. the SSWS token path is untouched
|
||||
os.environ["OKTA_API_TOKEN"] = "ssws-value"
|
||||
f = StrictOkta()
|
||||
def ssws_handler(req):
|
||||
f.api_seen.append(req.headers.get("authorization", ""))
|
||||
return httpx.Response(200, json=[{"status": "ACTIVE", "profile": {"login": "a"}}])
|
||||
users = okta_sync.fetch_users(http=httpx.Client(transport=httpx.MockTransport(ssws_handler)))
|
||||
chk("SSWS path unchanged: SSWS header, no DPoP", f.api_seen == ["SSWS ssws-value"] and users, str(f.api_seen))
|
||||
os.environ.pop("OKTA_API_TOKEN")
|
||||
|
||||
print("\nDONE" if fails == 0 else f"\n{fails} FAILED")
|
||||
sys.exit(1 if fails else 0)
|
||||
@@ -1,134 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does the Okta sync dry run change nothing? - D22 / T13.7.
|
||||
|
||||
With OKTA_SYNC_DRY_RUN on, the sync must fetch, match and apply both guards exactly
|
||||
as in a live run, report who it WOULD disable, and change no account and write no
|
||||
audit row. With it off (the default) behavior is as before.
|
||||
|
||||
Self-contained: in-memory SQLite, no server, no network, no browser.
|
||||
Exit 0 all passed, 1 a failure.
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
import sys
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
sys.path.insert(0, ROOT)
|
||||
|
||||
from sqlalchemy import create_engine, select # noqa: E402
|
||||
from sqlalchemy.orm import sessionmaker # noqa: E402
|
||||
from sqlalchemy.pool import StaticPool # noqa: E402
|
||||
|
||||
from server import models, okta_sync # noqa: E402
|
||||
from server.okta_sync import OktaSyncError, OktaUser, run_sync # noqa: E402
|
||||
|
||||
fails = 0
|
||||
|
||||
|
||||
def chk(label, ok, extra=""):
|
||||
global fails
|
||||
print(("PASS " if ok else "FAIL ") + label + (f" [{extra}]" if (extra and not ok) else ""))
|
||||
if not ok:
|
||||
fails += 1
|
||||
|
||||
|
||||
engine = create_engine("sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool)
|
||||
models.Base.metadata.create_all(engine)
|
||||
Session = sessionmaker(bind=engine, autoflush=False, future=True)
|
||||
|
||||
|
||||
def seed(names):
|
||||
with Session() as db:
|
||||
db.query(models.AuditLog).delete()
|
||||
db.query(models.User).delete()
|
||||
for n in names:
|
||||
db.add(models.User(id="u_" + n, username=n, is_active=True, email=""))
|
||||
db.commit()
|
||||
|
||||
|
||||
def state():
|
||||
with Session() as db:
|
||||
return ({u.username: u.is_active for u in db.scalars(select(models.User))},
|
||||
db.query(models.AuditLog).count())
|
||||
|
||||
|
||||
def okta(*pairs):
|
||||
return lambda: [OktaUser(identity=i, status=s) for i, s in pairs]
|
||||
|
||||
|
||||
class Capture(logging.Handler):
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.lines = []
|
||||
|
||||
def emit(self, r):
|
||||
self.lines.append(r.getMessage())
|
||||
|
||||
|
||||
cap = Capture()
|
||||
logging.getLogger("wpsuite.okta_sync").addHandler(cap)
|
||||
|
||||
# 1. Flag parsing
|
||||
for v, want in [("", False), ("false", False), ("0", False), ("true", True), ("TRUE", True),
|
||||
("1", True), ("yes", True), ("on", True), (" on ", True), ("maybe", False)]:
|
||||
os.environ["OKTA_SYNC_DRY_RUN"] = v
|
||||
chk(f"OKTA_SYNC_DRY_RUN={v!r} -> {want}", okta_sync.dry_run() is want)
|
||||
os.environ.pop("OKTA_SYNC_DRY_RUN")
|
||||
chk("unset -> live", okta_sync.dry_run() is False)
|
||||
|
||||
# 2. Dry run reports the plan and changes nothing
|
||||
seed(["alice", "bob", "carol", "dan"])
|
||||
before = state()
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=okta(("alice", "ACTIVE"), ("bob", "SUSPENDED"), ("carol", "DEPROVISIONED")), dry=True)
|
||||
after = state()
|
||||
chk("dry run ok", res.ok and res.dry_run)
|
||||
chk("dry run lists bob, carol and dan (missing)", sorted(res.disabled) == ["bob", "carol", "dan"], str(res.disabled))
|
||||
chk("dry run changed no account", before == after, f"{before} {after}")
|
||||
chk("dry run wrote no audit row", after[1] == 0)
|
||||
chk("log says DRY RUN would disable", any("DRY RUN would disable 'bob'" in l for l in cap.lines))
|
||||
chk("summary line says no account was changed and counts 3 matched, 3 would be disabled",
|
||||
any("DRY RUN done, no account was changed" in l and "3 matched" in l and "3 would be disabled" in l
|
||||
for l in cap.lines))
|
||||
|
||||
# 3. The environment decides when no argument is given
|
||||
os.environ["OKTA_SYNC_DRY_RUN"] = "true"
|
||||
seed(["alice", "bob"])
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=okta(("alice", "ACTIVE"), ("bob", "SUSPENDED")))
|
||||
chk("env on -> dry run", res.dry_run and state()[0]["bob"] is True and state()[1] == 0)
|
||||
|
||||
# 4. Guards still apply in a dry run
|
||||
seed(["alice", "bob"])
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=okta(("zed", "ACTIVE")))
|
||||
chk("zero-match guard still refuses in a dry run", (not res.ok) and "probably wrong" in res.error)
|
||||
|
||||
|
||||
def boom():
|
||||
raise OktaSyncError("down")
|
||||
|
||||
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=boom)
|
||||
chk("fetch failure still fails closed in a dry run", (not res.ok) and state() == ({"alice": True, "bob": True}, 0))
|
||||
|
||||
# 5. Live run (flag off) is unchanged
|
||||
os.environ.pop("OKTA_SYNC_DRY_RUN")
|
||||
seed(["alice", "bob"])
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=okta(("alice", "ACTIVE"), ("bob", "SUSPENDED")))
|
||||
st = state()
|
||||
chk("live run disables and logs one audit row", (not res.dry_run) and st[0]["bob"] is False and st[1] == 1)
|
||||
|
||||
# 6. Startup line names the mode
|
||||
os.environ["OKTA_API_TOKEN"] = "tok-secret-9f3a"
|
||||
os.environ["OKTA_ORG_URL"] = "https://example.okta.com"
|
||||
os.environ["OKTA_SYNC_DRY_RUN"] = "true"
|
||||
chk("startup line says DRY RUN", "DRY RUN" in okta_sync.describe())
|
||||
os.environ.pop("OKTA_SYNC_DRY_RUN")
|
||||
chk("startup line says live", "(live)" in okta_sync.describe())
|
||||
chk("startup line never holds the token", "tok-secret-9f3a" not in okta_sync.describe())
|
||||
|
||||
print("\nDONE" if fails == 0 else f"\n{fails} FAILED")
|
||||
sys.exit(1 if fails else 0)
|
||||
@@ -1,218 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Does the Okta deprovisioning sync fail closed? - D18 / T13.3.
|
||||
|
||||
The rule that must never be skipped or weakened: when Okta cannot be asked, or
|
||||
its answer cannot be trusted, the sync changes NO account and writes NO audit
|
||||
row. Treating "could not reach Okta" as "nobody is active" would lock the whole
|
||||
company out on one bad afternoon.
|
||||
|
||||
Also checked: the sync only ever disables (it never re-enables, under any
|
||||
input), writes one audit row per change with a non-human actor, leaves an
|
||||
already-disabled account alone, logs only changes, and keeps temporary Okta
|
||||
states (PASSWORD_EXPIRED, LOCKED_OUT, RECOVERY) from disabling anyone.
|
||||
|
||||
Self-contained: its own in-memory SQLite, no server, no network, no browser.
|
||||
Exit 0 all passed, 1 a failure.
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
sys.path.insert(0, ROOT)
|
||||
|
||||
import httpx # noqa: E402
|
||||
from sqlalchemy import create_engine, select # noqa: E402
|
||||
from sqlalchemy.orm import sessionmaker # noqa: E402
|
||||
from sqlalchemy.pool import StaticPool # noqa: E402
|
||||
|
||||
from server import models, okta_auth, okta_sync # noqa: E402
|
||||
from server.okta_sync import OktaSyncError, OktaUser, run_sync # noqa: E402
|
||||
|
||||
fails = 0
|
||||
|
||||
|
||||
def chk(label, ok, extra=""):
|
||||
global fails
|
||||
print(("PASS " if ok else "FAIL ") + label + (f" [{extra}]" if (extra and not ok) else ""))
|
||||
if not ok:
|
||||
fails += 1
|
||||
|
||||
|
||||
engine = create_engine("sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool)
|
||||
models.Base.metadata.create_all(engine)
|
||||
Session = sessionmaker(bind=engine, autoflush=False, future=True)
|
||||
|
||||
|
||||
def seed(rows):
|
||||
"""rows: list of (username, is_active[, email]). Wipes users and audit rows first."""
|
||||
with Session() as db:
|
||||
db.query(models.AuditLog).delete()
|
||||
db.query(models.User).delete()
|
||||
for r in rows:
|
||||
name, active = r[0], r[1]
|
||||
db.add(models.User(id="u_" + name, username=name, is_active=active,
|
||||
email=(r[2] if len(r) > 2 else "")))
|
||||
db.commit()
|
||||
|
||||
|
||||
def state():
|
||||
with Session() as db:
|
||||
users = {u.username: u.is_active for u in db.scalars(select(models.User))}
|
||||
audits = [a.to_dict() for a in db.scalars(select(models.AuditLog))]
|
||||
return users, audits
|
||||
|
||||
|
||||
def fixed(*pairs):
|
||||
return lambda: [OktaUser(identity=i, status=s) for i, s in pairs]
|
||||
|
||||
|
||||
# ── 1. the failure rule ───────────────────────────────────────────────────────
|
||||
print("\n1. FAIL CLOSED: a failed or untrusted fetch changes nothing")
|
||||
BASE = [("alice", True), ("bob", True), ("carol", True)]
|
||||
|
||||
|
||||
def boom(exc):
|
||||
def f():
|
||||
raise exc
|
||||
return f
|
||||
|
||||
|
||||
failing = [
|
||||
("OktaSyncError (auth failure)", boom(OktaSyncError("HTTP 401"))),
|
||||
("RuntimeError", boom(RuntimeError("boom"))),
|
||||
("ConnectionError", boom(ConnectionError("down"))),
|
||||
("TimeoutError", boom(TimeoutError("slow"))),
|
||||
("ValueError", boom(ValueError("bad"))),
|
||||
("KeyError", boom(KeyError("x"))),
|
||||
("fetch returns an empty list", lambda: []),
|
||||
("fetch returns None", lambda: None),
|
||||
("fetch returns garbage (strings)", lambda: ["alice", "bob"]),
|
||||
("fetch returns garbage (dicts)", lambda: [{"identity": "alice"}]),
|
||||
]
|
||||
for label, fetch in failing:
|
||||
seed(BASE)
|
||||
before = state()
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=fetch)
|
||||
after = state()
|
||||
chk(f"{label}: ok is False", res.ok is False)
|
||||
chk(f"{label}: zero accounts changed", after[0] == before[0] == {"alice": True, "bob": True, "carol": True})
|
||||
chk(f"{label}: zero audit rows", after[1] == [] and res.disabled == [])
|
||||
|
||||
print("\n ...and through the real client, not a stand-in")
|
||||
okta_auth.ISSUER = "https://example.okta.com/oauth2/default"
|
||||
os.environ["OKTA_API_TOKEN"] = "tok"
|
||||
for code in (401, 403, 429, 500):
|
||||
seed(BASE)
|
||||
c = httpx.Client(transport=httpx.MockTransport(lambda r, k=code: httpx.Response(k, json={})))
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=lambda c=c: okta_sync.fetch_users(http=c))
|
||||
u, a = state()
|
||||
chk(f"real client, HTTP {code}: nothing changed, no audit rows",
|
||||
(not res.ok) and all(u.values()) and a == [])
|
||||
seed(BASE)
|
||||
os.environ["OKTA_API_TOKEN"] = ""
|
||||
with Session() as db:
|
||||
res = run_sync(db) # fetch=None: the default path, no token set
|
||||
u, a = state()
|
||||
chk("default fetch with no token: nothing changed, no audit rows", (not res.ok) and all(u.values()) and a == [])
|
||||
|
||||
print("\n ...and when saving fails")
|
||||
seed(BASE)
|
||||
with Session() as db:
|
||||
real_commit = db.commit
|
||||
|
||||
def bad_commit():
|
||||
raise RuntimeError("disk full")
|
||||
|
||||
db.commit = bad_commit
|
||||
res = run_sync(db, fetch=fixed(("alice", "ACTIVE"))) # bob and carol would be disabled
|
||||
u, a = state()
|
||||
chk("a failed commit keeps no change and no audit row", (not res.ok) and all(u.values()) and a == [])
|
||||
|
||||
print("\n ...and when no local account matches any Okta user (wrong identity attribute)")
|
||||
seed(BASE)
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=fixed(("zed@x.com", "ACTIVE"), ("yan@x.com", "ACTIVE")))
|
||||
u, a = state()
|
||||
chk("zero matches is refused, not read as 'everyone left'", (not res.ok) and all(u.values()) and a == [])
|
||||
chk("...and the error says why", "identity attribute" in res.error)
|
||||
|
||||
# ── 2. what it does disable ───────────────────────────────────────────────────
|
||||
print("\n2. a good run disables the right accounts")
|
||||
seed([("alice", True), ("bob", True), ("carol", True), ("dave", True),
|
||||
("erin", True), ("frank", True), ("gina", True), ("hank", True)])
|
||||
okta = fixed(("alice", "ACTIVE"), ("bob", "SUSPENDED"),
|
||||
# carol is MISSING from the list
|
||||
("dave", "DEPROVISIONED"), ("erin", "PASSWORD_EXPIRED"),
|
||||
("frank", "LOCKED_OUT"), ("gina", "RECOVERY"), ("hank", "ACTIVE"))
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=okta)
|
||||
users, audits = state()
|
||||
chk("run is ok", res.ok, res.error)
|
||||
chk("missing, SUSPENDED and DEPROVISIONED are disabled",
|
||||
sorted(res.disabled) == ["bob", "carol", "dave"] and
|
||||
[users[n] for n in ("bob", "carol", "dave")] == [False, False, False])
|
||||
chk("ACTIVE stays active", users["alice"] is True and users["hank"] is True)
|
||||
chk("PASSWORD_EXPIRED, LOCKED_OUT and RECOVERY do NOT disable (temporary states)",
|
||||
users["erin"] is True and users["frank"] is True and users["gina"] is True)
|
||||
chk("one audit row per disabled account", len(audits) == 3, str(len(audits)))
|
||||
row = next(a for a in audits if a["summary"] == "bob")
|
||||
chk("audit actor is the sync job, not a person", {a["actor"] for a in audits} == {"system:okta_sync"})
|
||||
chk("audit action is user_deprovisioned_by_sync", {a["action"] for a in audits} == {"user_deprovisioned_by_sync"})
|
||||
chk("audit row names the user and the Okta status found",
|
||||
row["entity_type"] == "user" and row["entity_id"] == "u_bob" and row["detail"].get("okta_status") == "SUSPENDED")
|
||||
chk("a missing user is recorded as MISSING",
|
||||
next(a for a in audits if a["summary"] == "carol")["detail"].get("okta_status") == "MISSING")
|
||||
|
||||
print("\n ...run it again: only changes are logged")
|
||||
with Session() as db:
|
||||
res2 = run_sync(db, fetch=okta)
|
||||
users2, audits2 = state()
|
||||
chk("second run is ok, disables nobody", res2.ok and res2.disabled == [])
|
||||
chk("second run writes no new audit rows (no duplicates)", len(audits2) == 3)
|
||||
chk("accounts unchanged by the second run", users2 == users)
|
||||
|
||||
# ── 3. never re-enables, never touches a disabled account ─────────────────────
|
||||
print("\n3. never re-enables, never touches an already-disabled account")
|
||||
seed([("alice", True), ("hank", False), ("gina", False)])
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=fixed(("alice", "ACTIVE"), ("hank", "ACTIVE"))) # gina missing
|
||||
users, audits = state()
|
||||
chk("a disabled account that is ACTIVE in Okta stays disabled", users["hank"] is False)
|
||||
chk("a disabled account that is missing from Okta stays as it is", users["gina"] is False)
|
||||
chk("no audit row for either (nothing changed)", audits == [] and res.disabled == [])
|
||||
src = open(os.path.join(ROOT, "server", "okta_sync.py")).read()
|
||||
chk("no assignment of is_active to True anywhere in okta_sync.py",
|
||||
"is_active = True" not in src and "is_active=True" not in src.replace("is_active.is_(True)", ""))
|
||||
|
||||
# ── 4. matching ───────────────────────────────────────────────────────────────
|
||||
print("\n4. matching")
|
||||
seed([("ALICE", True), ("bob", True, "Bob@X.com"), ("carol", True)])
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=fixed(("alice", "ACTIVE"), ("bob@x.com", "ACTIVE"), ("carol", "SUSPENDED")))
|
||||
users, _ = state()
|
||||
chk("username match ignores case", users["ALICE"] is True)
|
||||
chk("email match works, ignoring case", users["bob"] is True)
|
||||
chk("a matching SUSPENDED user is disabled", users["carol"] is False)
|
||||
|
||||
seed([("alice", True), ("bob", True), ("carol", True)])
|
||||
with Session() as db:
|
||||
run_sync(db, fetch=fixed(("alice", "ACTIVE"), ("bob", "ACTIVE"), ("bob", "SUSPENDED"),
|
||||
("carol", "SUSPENDED"), ("carol", "DEPROVISIONED")))
|
||||
users, _ = state()
|
||||
chk("an identity listed twice, one entry active: stays active", users["bob"] is True)
|
||||
chk("an identity listed twice, every entry disabling: disabled", users["carol"] is False)
|
||||
|
||||
# ── 5. the secret never reaches the audit row or the result ───────────────────
|
||||
print("\n5. no secret in what is stored or returned")
|
||||
seed(BASE)
|
||||
os.environ["OKTA_API_TOKEN"] = "SECRET-TOKEN-123"
|
||||
c = httpx.Client(transport=httpx.MockTransport(lambda r: httpx.Response(401, json={})))
|
||||
with Session() as db:
|
||||
res = run_sync(db, fetch=lambda: okta_sync.fetch_users(http=c))
|
||||
chk("the failure message has no token", "SECRET-TOKEN-123" not in res.error and "example.okta.com" not in res.error)
|
||||
|
||||
print()
|
||||
print("ALL PASSED" if not fails else f"{fails} FAILED")
|
||||
sys.exit(0 if not fails else 1)
|
||||