Compare commits

..

27 Commits

Author SHA1 Message Date
e50a05a1e0 T12.6: wave 12 closed - browser_check passes after the re-point
Matt reran tests/browser_check.py on the re-pointed probe: all
passed. Every T12 done-when and every wave 12 exit criterion is now
checked in wave-12.md.
2026-10-06 14:05:43 -07:00
912cf75027 T12.6: browser results, screenshots, browser_check re-pointed
Matt's run (Edge/Chrome, one at a time): bulk_users_ui_check 19/19,
console_dialogs_check 16/16, mobile_check 24/24, a11y_check 22/22.

browser_check 67/71: its four failures asserted column POSITIONS
(9 columns; r.cells[3]/[4] for Permissions/Project role). CR-020's
selection column comes first, so those read Username and Email. The
probe now expects 10 columns with the selection column first, finds
the cells by header name, and checks your own row has no selection
box. Verified on the real page in the DOM harness; rerun to close.

After-screenshots committed in docs/reference/baseline/wave-12/.
BL-061 logged: the pre-existing sync badge covers a control for ~2 s
after load (pointer-events:none, so never blocks a click); belongs
with wave 14's badge work.
2026-10-06 11:18:39 -07:00
d04a0ff414 T12.6: wave 12 verification record, browser probe, BL-060
- tests/bulk_users_ui_check.py (new): selection, keyboard Space on a
  row box, toolbar role change, super-user CSV with good and bad lines,
  add-to-project with a role, typed DELETE, all end to end against a
  real server; 390px bar layout; writes after-screenshots to
  docs/reference/baseline/wave-12/. Needs a browser: to be run on
  Matt's machine.
- tests/cdp.py: --do-not-de-elevate and the rc=0 grace, the same
  change as wave 16 T16.4 (identical content, merges cleanly), so the
  probes start from an elevated shell on this branch too.
- Verification record in wave-12.md: bulk_users_check 61/61 (main
  7/18), single-user routes identical before/after on 16 calls, DOM
  harness 48/48, jsdom against a real server 13/13, smoke 27/27,
  seed_demo OK. Server-checkable done-when boxes ticked; the browser,
  screenshot and full-suite boxes stay open until run on Edge.
- BL-060 logged: a super user's refusal reason promises a project
  access change neither the dialog nor the bulk route allows. Needs
  Nick; not fixed here (scope).
- file-map.md: wave 12's two new checks.
2026-10-06 11:08:03 -07:00
1c4d1bbccb T12.5: CR-020 bulk delete with typed confirmation
'Delete selected…' in the bulk bar. The dialog lists every affected
username (scrolling inside the dialog for a long list), says the
delete cannot be undone and offers disable instead, and sends nothing
until the word DELETE is typed in capitals, whatever the count
(confirmed 2026-10-06). Wrong words keep the dialog open with the
reason; cancel sends nothing.

Your own account cannot be selected; if it ever reached the request,
the server refuses that row and the report names it with the reason.

The bulk delete is a prompt-style dialog, so it is covered in
tests/console_dialogs_check.py (its docstring asks for exactly this):
new section 4 drives it in the browser with native dialogs poisoned.
DOM harness: 48/48.
2026-10-06 11:05:01 -07:00
74d3bc4af7 T12.4: CR-020 CSV upload (usernames only)
POST /api/auth/bulk-users/resolve reads a list of usernames (first
column; comma, semicolon or tab; header skipped) and answers line by
line, the CR-005 validate-and-report pattern. A line is rejected, with
its number and reason, when it names nobody the caller can see ('User
not found', as everywhere else), an account they may not change (the
single route's own reason), their own account, or a username already
listed (duplicate of line N). An email address resolves only when
exactly one account has it. Nothing is changed by this route.

The console's 'Select from CSV' turns the accepted accounts into the
ordinary selection (filter reset so every selected row is visible) and
lists every rejected line. The action, confirm and per-row report are
the checkbox ones, through the same T12.1 routes, which re-check each
row: a CSV cannot reach an account a checkbox could not.
Usernames only, action in the toolbar (decided 2026-10-06). Files over
1 MB are refused before upload; FileReader fallback for browsers
without Blob.text().

bulk_users_check.py: 61/61. DOM harness: 40/40.
2026-10-06 11:04:01 -07:00
681048197a T12.3: CR-020 bulk-action toolbar
Role change, enable/disable, and project add/remove on the selected
rows, wired to the T12.1 endpoints. Delete is T12.5.

- The toolbar offers only what the caller may do: grantable roles,
  managed projects (archived last, marked), grantable per-project roles.
- Every action confirms through wpConfirmDialog naming the exact count
  (and for projects, the project and role) before anything is sent.
- The result lists every failed row with the server's reason, plus the
  changed / already-set counts; a partial failure is a warning, an
  all-failed batch an alert, a server error says nothing was changed.
  Never a blanket success. Announced through the live-region banner.
- The directory reloads afterwards, which clears the selection.

DOM harness (jsdom, real page and scripts, mocked API): 30/30 with
T12.2.
2026-10-06 11:02:09 -07:00
cf46b3ce42 T12.2: CR-020 row selection in the User Directory
- A checkbox per row the caller may change; select-all covers only the
  rows the current filter and search show, and is indeterminate on a
  partial selection.
- Your own row and rows you cannot change show a disabled box whose
  label gives the reason.
- Changing the filter or the search clears the selection and says so
  in a live region (decided 2026-10-06), so no hidden row stays
  selected.
- The bulk bar appears at one or more selected rows and is hidden (out
  of the tab order) at zero. Actions arrive in T12.3.
- Selection is updated in place, not by re-rendering, so focus stays on
  the checkbox just used. One delegated listener; no ids in inline
  handlers.
- The email-width rule now targets td.ell, not nth-child(3), which the
  new column would have shifted.

Checked in a DOM harness (jsdom) against the real page and scripts:
14/14; against main the selection checks fail. Browser probe at
390px/1440px follows in T12.6.
2026-10-06 11:01:02 -07:00
0e79e17a57 T12.1: CR-020 bulk user endpoints
POST /api/auth/bulk-users/{active,role,projects,delete} take a list of
user ids (max 500) and run each row through the same guards and audit
as the single-user route: the rules now live once, in guard_target and
apply_user_{active,role,delete,projects}, which the single-user routes
call too.

- A refused row is reported with its reason; the rest still run; the
  response counts ok / unchanged / failed. Never a blanket success.
- The caller's own account is refused only on its own row.
- One AuditLog row per changed account, same action and shape as the
  single route. A row already in the requested state is 'unchanged'
  and writes no audit row.
- Project assignment is add/remove to ONE project with a per-project
  role (confirmed 2026-10-06); roles on the user's other projects are
  carried over as stored.
- Routes sit under /api/auth/bulk-users/ because /api/auth/users/bulk/
  would match {user_id}='bulk'.

New tests/bulk_users_check.py (no browser): 47/47. Against main: the
7 single-route checks pass, every bulk check fails.
Single-user routes compared before/after on 16 calls (200/400/403/404):
identical responses, audit rows and memberships. Smoke test 27/27.
2026-10-06 10:57:48 -07:00
286e629782 wave 12: plan for CR-020 on a branch from main; details confirmed
Brings docs/waves/wave-12.md and decisions-2026-09-17.md across from
feat/waves-11-13 (planning docs only, no wave 11 or 13 code), so the
PR into main is wave 12 alone.

Confirmed 2026-10-06 by Matt Mabrey: typed DELETE for bulk delete;
project assignment is add/remove per project; changing the filter
clears the selection; the CSV holds usernames only.
2026-10-06 10:53:29 -07:00
df20b8f18d wave-10: close out claim mapping and redirect URI, live in production
Confirmed by an actual live Okta sign-in after main (cc64c88) deployed: preferred_username is the right identity claim, and the redirect URI works. Matt matched his existing pre-Okta admin account rather than getting JIT-provisioned as a duplicate. Two deploy-time snags recorded, both Case B (config, not data): OKTA_CLIENT_ID/SECRET/ISSUER left empty in Portainer at first (caught cleanly by is_configured()), then OKTA_ISSUER missing its https:// scheme (surfaced as httpx.UnsupportedProtocol, not a deliberate app error - BL-028 still stands). Neither needed the backup. BTG pilot group now includes Cody and Cameron, awaiting Adrian.
2026-09-09 13:34:32 -07:00
cc64c88c3e T10.10: audit manage_users.py promote
cmd_promote() changed a user's role with no audit trail, unlike the
identical change from the web Admin Console (set_user_role() ->
log_event(), action "role_changed"). Not a new privilege - anyone
with container-exec access already has DB access directly, D16's own
trust-tier reasoning - but there was no record of who ran it or what
changed.

Now writes an AuditLog row matching set_user_role()'s shape, tagged
via:cli (mirrors JIT provisioning's via:okta_jit) since a container
shell exec carries no signed-in identity to attribute the change to.

Verified against a scratch SQLite db: audit row lands correctly, role
change persists, the no-such-user refusal still exits 1 clean.
2026-09-03 16:27:13 -07:00
dc13f9b0e3 T10.8: verification (390px/1440px, full suite, per-task done-when)
Walked T10.1-T10.5's claims against the actual code (env vars, routes,
JIT provisioning, the password-removal sweep, login.html) rather than
re-trusting this file's own prose. No drift found.

Full suite via the Docker runner: 39/41 files clean. token_check.py's
exit 2 is a harness mismatch (needs --out/--compare, not a bare run),
not a failure. generalinfo_check.py is 48/49 - the one failure is a
pre-existing rgba() shadow literal from the D11 Micron-assets merge,
confirmed via git show HEAD to predate this wave; logged as BL-031,
not fixed here. okta_auth_check.py re-run fresh: 22/22.

390px/1440px: baseline_shots.py captured all fourteen shots. Visually
confirmed login.html and users.html show the Okta-only sign-in and the
password-free admin UI at both widths.

Wave 10 complete.
2026-09-03 15:22:03 -07:00
d6eae0d846 T10.9: rollback-aware deploy runbook for the Okta cutover
New DEPLOY-runbook-2026-09-03.md, separate from the 2026-08-04 runbook.
Names the five new OKTA_* env vars, treats the pre-deploy backup as the
only way back once 1d60a608bb51 (drop_local_password) commits since its
downgrade() restores the column but not the data, and splits Rollback
into the fixable case (Okta app integration misconfigured, fix and
redeploy api, no data at risk) versus the severe case (abandoning Okta
for local-password code, which only a destructive backup restore can
reach). States D16's no-break-glass posture plainly.

D17 records the decision and why: staged-deploy-sequence docs and
backlog-only were both considered and declined in favor of the runbook.

Logged to backlog.md rather than fixed here: okta_auth.describe() has
no caller (BL-028), users.failed_attempts/locked_until are vestigial
(BL-029), DEPLOY-login-portal.md is fully stale (BL-030).
2026-09-03 14:25:18 -07:00
d7d1e93dd8 T10.6 - record what was built in wave-10.md 2026-09-03 13:48:08 -07:00
f023192b74 T10.6 - deployment docs and env var reference describe Okta, not the never-shipped LDAP config
D13 never shipped, so DEPLOYMENT.md, server/.env.example and server/README.md
still described the original local-password system as of this task starting -
POST /api/auth/login, bcrypt password_hash, create-admin with a prompted
password, self-service reset-password email flow, AUTH_RESET_MINUTES /
AUTH_RESET_COOLDOWN_SECONDS. All of that is gone as of T10.4; these three files
now describe what actually runs.

server/.env.example and DEPLOYMENT.md's env block both gain the five OKTA_*
variables (ISSUER, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, IDENTITY_CLAIM),
explained the same way AUTH_SECRET_KEY already was - what it does, where to
get it, what happens if it's missing.

Also updated, not originally named in T10.6's bullet but required for the
documented vars to actually reach a running container: docker-compose.yml's
api service sets environment: as an explicit allowlist, not env_file, so the
four new OKTA_* entries had to be added there too or .env would document
something that silently does nothing. OKTA_IDENTITY_CLAIM specifically is NOT
${OKTA_IDENTITY_CLAIM:-} - compose setting an env var to an empty string is
not the same as leaving it unset, and server/okta_auth.py's own default
(preferred_username) only kicks in when the var is truly unset. Mirrored the
same default in the compose file instead, or every deployment that leaves the
optional line commented out in .env would 503 on every sign-in looking for a
claim literally named "".

server/README.md: replaced the login-portal section with the Okta flow
(access gating is Okta's job, not this app's - roles/authorization stay
local), replaced "create the first admin" with the promote-not-create
bootstrap path (D16) and its no-break-glass posture, replaced the curl-based
login example in Quick Test with a pointer to smoketest.py's own
session-minting technique (there is nothing left to curl - Okta requires a
real browser).

DEPLOYMENT.md: same treatment for its own copies of the env block, the
Portainer var list, the users table's password_hash column, the auth
endpoints summary, the smoke-test walkthrough (WP_SMOKE_USER only, must run
inside the api container or local dev sharing AUTH_SECRET_KEY/DATABASE_URL -
no longer targetable from an arbitrary remote workstation), the entire
"Self-service password reset" section (replaced with "Sign-in and admin
bootstrap (Okta)"), and the project_super_user role description / exclusive-
scope bullet, both of which named "reset passwords" as something that no
longer exists.

Left alone, logged rather than fixed here per CLAUDE.md scope discipline:
- users.failed_attempts / locked_until columns are still in the schema and
  still reset to 0/None on every Okta sign-in, but nothing increments them
  anymore since local login() is gone - vestigial, not documented as active
  lockout behavior in either doc now, but not migrated away either.
- server/README.md's "Production - Docker Compose" section (### 1-5) is a
  self-contained alternate quickstart that already duplicated and diverged
  from the real root docker-compose.yml before this task; it uses env_file
  rather than an explicit allowlist so it isn't broken by this change, but
  it's still a second source of truth nobody asked this task to reconcile.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-03 13:47:48 -07:00
78d1942a0e T10.7 - add an explicit validation note (22/22, 26/26, 71/71) 2026-09-03 13:34:30 -07:00
45aff9c423 T10.7 - record the real browser-suite verification
url_state_check.py and browser_check.py both need a real headless browser via
tests/cdp.py, which the dev sandbox T10.7 was built in does not have and
cannot install (no sudo, network egress allowlisted against every route tried
- apt, a user-space Playwright Chromium download, Docker Hub). Documented as
an open gap in that commit rather than claimed as done.

Run for real since, on a machine with Docker, through a small general-purpose
tool kept deliberately outside this repo (headless-py-test-runner - it has no
idea what repo it is pointed at, so it does not belong in a Work Package Suite
PR). url_state_check.py 26/26, including scenario 2's actual click-through of
the fake-Okta round trip this task built; browser_check.py 71/71. Gap closed -
wave-10.md now says so instead of leaving the question open.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-03 13:33:17 -07:00
290c9b078c T10.7 - a fake-OIDC-provider test seam, mirroring ldap_fake.py
Only two calls actually touch the network: Authlib's authorize_redirect and
authorize_access_token. server/okta_fake.py stands in for both, dispatched from
okta_auth._build_oauth() before the real Okta config is even considered, and
production-refusing the same way ldap_fake.is_active() does - a non-SQLite
DATABASE_URL means production, full stop, no matter what WP_OKTA_FAKE_DIRECTORY
says. Everything this app itself decides stays real: the ?next= open-redirect
guard, the disabled-account check, JIT provisioning, and which claim carries
identity all run unmodified in app.py's okta_login()/okta_callback().

The fake needed one thing ldap_fake.py never did: something to actually redirect
the browser to and back, since Okta's real flow leaves the site and LDAP's never
did. Two routes stand in for Okta's own sign-in screen - a plain picker listing
whatever WP_OKTA_FAKE_DIRECTORY defines, and a consent step that hands back an
authorization code (or an error) at okta_callback, exactly the shape a real Okta
redirect would carry. Both are registered in app.py only when the fake is active
at import time, so in production they do not exist at all, not merely refuse a
request - confirmed by starting the app with the env var unset and checking
app.routes directly.

tests/browser_check.py's start_server() takes an optional extra_env now (no
existing caller passes a third positional arg, so none of the ~40 files that
import it needed touching) and sets WP_OKTA_FAKE_DIRECTORY unconditionally,
same reasoning the LDAP predecessor used: almost nothing signs in (seed() mints
tokens directly), but the one check that does should not fail mysteriously.

tests/url_state_check.py scenario 2, SKIPPED since T10.4, is un-skipped and now
drives the real round trip: login.html's own button, the fake picker page, the
fake consent redirect, okta_callback(). Carries forward the LDAP predecessor's
own bug fix too - asserting the app actually LEFT login.html, not just that
wp-creation-index.html appears somewhere in the URL (which the ?next= parameter
alone would satisfy).

tests/okta_auth_check.py is new, mirroring ldap_auth_check.py's two-layer shape:
guards that need no server (the production refusal, single-use/replay on the
authorization code), then a real running app for sign-in itself - an existing
admin surviving unchanged, JIT provisioning at the lowest role, a disabled
account refused despite Okta approving it, an unsolicited callback hit refused
without a 500, a tampered state refused, a denied consent refused, an unknown
identity refused BY THE SERVER (not just absent from the picker), a same-site
next= surviving and an off-site one ignored, and OKTA_IDENTITY_CLAIM genuinely
working under a non-default claim name. 22/22.

One thing this could not verify in this environment: url_state_check.py and
browser_check.py both need a headless Edge/Chrome via cdp.py, and this sandbox
has neither installed and no way to install one (no sudo). Confirmed the failure
is the tests' own designed-for exit 2 ("no headless-capable browser found; set
WP_BROWSER"), not a crash, and separately confirmed start_server() itself boots
cleanly with the fake wired in - health check, the picker page rendering with
the seeded identities, login.html all responding correctly - so the only gap is
the DOM-level click-through, not the server-side mechanism url_state_check
exercises (which okta_auth_check.py covers directly via HTTP instead).

wave-10.md's T10.7 bullet records the shape of what got built and the 22/22
result.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-03 12:11:24 -07:00
72b10283fc T10.5: login becomes an Okta redirect, not a form
server/app.py:
- okta_login(): validates and stashes ?next= (same-site path only) in the
  OAuth-state session before redirecting to Okta, so a deep link an assignment
  email carried (X1/CR-011/CR-014) survives the round trip instead of always
  landing on /index.html.
- okta_callback(): reads that stashed next= back (re-validated on the way out
  too - belt and suspenders against a crafted value) and redirects there on
  success. The two failure paths that used to raise a raw HTTPException -
  OAuthError (sign-in cancelled/failed) and a locally-disabled account - now
  redirect to /login.html?error=... instead: this route is reached by a full
  page browser navigation from Okta, not a fetch() call, so a JSON error body
  just looks like a broken page to whoever is signing in.

html/login.html + html/login.js: rebuilt as a single "Sign in with Okta" link,
replacing the username/password form and the forgot/reset-password views
(gone entirely - no local password exists to reset, per D15/D16/T10.4). Kept
the accessible error/ok banner pattern (role=alert / role=status) byte-for-
byte, since CLAUDE.md names this file as the reference other pages copy for
that pattern. login.js reads ?next= off its own URL (auth-guard.js's
goToLogin() already builds this, unchanged) and forwards it to
/api/auth/okta/login, and shows a plain-language message for ?error=disabled
/ ?error=cancelled, clearing the code from the address bar once shown. Sign-
out (auth-guard.js's wpLogout()) already redirected to login.html - untouched,
already satisfied "lands back on the app's own login page."

Uses a real <a href> rather than a JS-driven navigation, so it's a working
link even before login.js runs, and needs no keyboard/touch handling beyond
what a link gets for free (C1 accessibility).

Also fixed in passing (not a separate commit - this is what exposed it):
_safe_next_path() on the server and safeNext() in login.js enforce the exact
same rule (same-site path only, reject '//' and scheme URLs) so a crafted
?next= can't become an open redirect through a real Okta sign-in.

Verified: a fake-Okta-client round trip against the real app (SessionMiddleware
fix from the prior commit) confirms next= is honored end to end, a malicious
next= is rejected and falls back to /index.html, OAuthError redirects to
?error=cancelled, and a disabled account redirects to ?error=disabled. The
JS-side safeNext() was checked against the same cases directly in Node and
matches the server's validation exactly. login.js passes `node --check`;
login.html parses cleanly. Live 390px/1440px screenshots were NOT captured
this session - the environment's browser pane isn't signed in to view a
published preview of it, so that check needs to happen when this branch is
actually run and opened by a signed-in browser; the layout risk is low since
.card/.brand/.error/.ok/.foot are unchanged from the already-shipped file and
the only new CSS is one simple full-width block link.

wave-10.md T10.5 / D15 / D16
2026-09-03 11:27:26 -07:00
77f8f9f800 Fix T10.2: install SessionMiddleware, required by Authlib
okta_login() and okta_callback() (T10.2) both crash with a 500
(AssertionError: SessionMiddleware must be installed to access
request.session) against a real Okta client, because Authlib's
authorize_redirect() and authorize_access_token() both store/read OIDC
state and nonce in request.session. Never caught by T10.2's or T10.3's
own verification because every prior test mocked authorize_redirect /
authorize_access_token directly, bypassing Authlib's real implementation
entirely. Found while starting T10.5 and reproducing the real flow.

Adds starlette.middleware.sessions.SessionMiddleware, on its own cookie
(wp_oauth_state, distinct from the app's real session cookie wp_session)
with a short 10-minute lifetime and same_site=lax so it survives the
top-level redirect back from Okta. This cookie carries nothing but
ephemeral per-attempt OAuth state — no identity, no long-term secret —
so it reuses auth.SECRET_KEY rather than adding a new required config
knob. Reused in T10.5 to carry the post-login redirect target across
the same round trip.

Adds itsdangerous to requirements.txt — SessionMiddleware's hard
dependency, not previously needed anywhere in this app.

Verified: reproduced the crash against server.app with a fake (network-
bypassed) Authlib client and no SessionMiddleware, confirmed the
AssertionError, then confirmed the same request succeeds (302 to the
authorize URL, wp_oauth_state cookie set) once the middleware is added.

wave-10.md T10.2 (bug fix)
2026-09-03 11:13:28 -07:00
73da684b99 T10.4: remove the local password path entirely
Real deletion (D15's 'full replacement'), not a toggle. Okta is now the only
credential this app accepts anywhere.

Backend:
- server/models.py: drop User.password_hash.
- server/alembic/versions/1d60a608bb51_...: matching migration (op.drop_column,
  same plain-drop precedent as project_role/locked_until/etc.; downgrade re-adds
  it with server_default='').
- server/auth.py: remove hash_password/verify_password/password_problem/
  MIN_PASSWORD_LEN/_COMMON_PASSWORDS, create_reset_token/decode_reset_token/
  RESET_MINUTES, the bcrypt import. Roles/tokens/cookies/get_current_user
  untouched.
- server/app.py: remove login(), the whole self-service reset-password block
  (forgot-password/reset-available/reset-password), and change_password()
  (POST /api/auth/password). Rework create_user() to drop the password field
  (with a docstring note: the username must exactly match the eventual Okta
  identity claim, or a later sign-in provisions a second account instead of
  matching this one). Remove admin_reset_password() outright - nothing left to
  reset. Fixes a bug this task's own predecessor left behind: okta_callback()'s
  JIT provisioning (T10.3) was still setting password_hash="", which would have
  raised TypeError the moment the column was actually dropped.

Admin bootstrap (D16): server/manage_users.py moves from creating accounts
(create/create-admin/reset-password, all password-based) to a single 'promote
<username> --role <role>' command that changes the role on a row Okta's JIT
provisioning already created - the documented path for naming the first admin.
list/disable/enable unchanged.

Frontend: html/users.js drops the password field and validation from
createUser(), removes resetPw() and its button (nothing left to reset).
html/users.html drops the #nu-password input, adds a tooltip on username
explaining the exact-match-to-Okta requirement. html/auth-guard.js removes the
wpChangePassword dialog; html/wp-sidenav.js removes the 'Password' menu item
that opened it.

Tests: tests/browser_check.py and tests/launcher_check.py stop hashing a
password to seed fixture rows (and the --keep-server hint now prints a
ready-to-use cookie-setting snippet instead of a dead username/password).
tests/pipeline_check.py and tests/token_check.py drop an unused PW import.
tests/console_dialogs_check.py: the admin password-reset dialog it drove no
longer exists, so that scenario is removed - the prompt-with-validate() UI
pattern it exercised is still covered via creator_dialogs_check.py's
wp-creation-app.js call sites, noted in this file's docstring so the coverage
move isn't silent. tests/url_state_check.py: the "next= survives a real sign-in
via login" scenario is explicitly marked SKIPPED (not deleted, not faked) -
that promise is specific to the login FORM this task removed and can't be
honestly re-proven until T10.5 rebuilds it as an Okta redirect; a minted-token
cookie now stands in as setup only, so scenarios 3-6 in that file still get a
signed-in page to run against.

server/smoketest.py and server/seed_demo.py: switched from POST /api/auth/login
to minting a session the same way okta_callback() does (auth.create_token(),
seeded into the cookie jar) rather than waiting on T10.7. This is a real
operational change, documented in both files' own AUTHENTICATION sections: they
now need to run where AUTH_SECRET_KEY and the database match the target
server's (inside the api container, or local dev) - they can no longer sign in
to an arbitrary remote URL from an unrelated workstation, because Okta requires
a real browser and these are stdlib scripts. The account must already exist;
neither script creates or promotes one.

server/requirements.txt: bcrypt dropped, nothing imports it anymore.

Verified: full Alembic chain (baseline through this migration) upgrades and
downgrades cleanly against a throwaway SQLite DB. okta_callback() JIT
provisioning re-tested against the post-migration schema (would have thrown
before the password_hash="" fix above). create_user() verified via a live HTTP
call with no password field. manage_users.py promote verified end to end
(seed a JIT-shaped row at project_user, promote to admin, list). smoketest.py
and seed_demo.py both run to completion against a live uvicorn instance using
the new minted-session path - 25/25 checks, including logout actually
invalidating the session (proving the cookie-jar seeding didn't just fake the
sign-in, it preserved the real expiry mechanics).

wave-10.md T10.4 / D15 / D16
2026-09-03 10:58:28 -07:00
c74289aa0d D16: Okta admin bootstrap and break-glass posture; correct T10.4 scope
Decision, raised during T10.4 hazard review:

- Admin bootstrap: manage_users.py moves from creating an admin account to
  promoting an existing one, by username, on a row Okta's JIT provisioning
  (T10.3) already created. Rejected blind account creation — the exact
  OKTA_IDENTITY_CLAIM format is still unconfirmed by security, and a
  hand-typed username that doesn't match it produces an orphaned second
  account instead of promoting the real one. Ongoing (non-bootstrap) admin
  naming needs no new work: html/users.js's existing role dropdown already
  handles it.
- Break glass: none, by design, matching the precedent already on record
  for the abandoned LDAPS design (D13/D14) rather than assumed to carry
  over untested. If Okta is unreachable, the app is unreachable for
  everyone until Okta is restored. Rejected a toggleable emergency local
  login — it would reintroduce the stored credential D15 exists to
  eliminate.

Also corrects T10.4's scope in wave-10.md: hazard review found real call
sites of hash_password/verify_password/password_problem the original
bullet didn't name (create_user(), admin_reset_password(), users.js's
admin forms, browser_check.py/launcher_check.py fixtures), plus a
verification-gate ordering problem (smoketest.py and seed_demo.py
authenticate via POST /api/auth/login, which T10.4 removes, and both are
named explicitly in CLAUDE.md's verification section). Fixed by having
T10.4 switch both scripts to mint a session with auth.create_token()
directly, the same technique browser_check.py already uses, rather than
waiting on T10.7.

D16
2026-09-03 10:35:58 -07:00
7ed3cbec4c T10.3: identity matching and JIT provisioning for Okta sign-in
okta_callback() now completes the sign-in instead of stopping at the claim:

- Matches the OKTA_IDENTITY_CLAIM value to a local account via
  auth.find_user() (username or email, case-insensitive) — the same lookup
  login() already uses, so an account whose username mirrors its AD
  identity needs no migration.
- No match: JIT-provisions a new account at the lowest-privilege role
  (project_user), no project membership, no password hash. Access beyond
  that is still granted locally by an admin/project super user, same as
  any account created by hand via create_user(). Logs a user_created audit
  event (via: okta_jit) for parity with that route.
- Match found but is_active is False: blocked with the same 403 'Account
  is disabled' login() raises today. Okta granting the challenge does not
  override an account this app has disabled locally (D15: 'roles stay
  local').
- On success: issues the same session cookie login() does (auth.create_
  token / auth.set_session_cookie), then redirects the browser to
  /index.html — this route is reached by a full-page navigation from
  Okta's redirect, not a fetch call, so a redirect is required rather than
  the JSON body login() returns.

Verified with a fake Okta client against a throwaway SQLite DB: new
identity provisions correctly (role/email/name/no-password), a repeat
sign-in matches the existing row without duplicating it or touching a
role an admin has since changed, a locally-disabled account is blocked
despite a valid Okta claim, and a missing identity claim is rejected
before touching the database.

wave-10.md T10.3 / D15
2026-09-03 10:16:50 -07:00
a9e5ee3892 T10.2: Okta login-redirect and callback routes
Adds GET /api/auth/okta/login (redirect to Okta's authorize endpoint) and
GET /api/auth/okta/callback (exchange code, validate ID token, pull the
identity claim) to server/app.py, using the oauth.okta client from
okta_auth.py (T10.1).

Access gating is Okta's job, not this route's: only accounts assigned to
the app integration in Okta ever reach the callback, so there is no
app-side group/claim check layered on top (D15, wave-10.md T10.2).

Stops at NotImplementedError once the identity claim is in hand. Matching
that claim to a local account and issuing the session cookie is T10.3, kept
separate per the one-task-per-PR rule.

wave-10.md T10.2 / D15
2026-09-03 10:11:49 -07:00
0ee35ae4ed T10.1: Okta OIDC client dependency and config (wave 10) 2026-09-03 09:57:55 -07:00
044862acba Wave 10: task breakdown for the Okta OIDC build 2026-09-02 17:38:35 -07:00
31c548318b D15: retire D13/D14 (LDAPS, never deployed), move straight to Okta OIDC 2026-09-02 17:20:01 -07:00
56 changed files with 4151 additions and 1017 deletions

View File

@@ -0,0 +1,355 @@
# 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.

View File

@@ -52,27 +52,44 @@ POSTGRES_DB=wpsuite
POSTGRES_USER=wpsuite
POSTGRES_PASSWORD=<strong-random-password>
# REQUIRED — signs login session cookies. If unset, `docker compose up` errors
# out and the API refuses to start. Generate once and keep it stable:
# 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:
# 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 + 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.
# 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.
# SMTP_PASSWORD=<smtp-app-password>
# OPTIONAL — password-reset link lifetime (minutes) and the per-account send
# cooldown (seconds). Defaults shown; both only matter once email is enabled.
# AUTH_RESET_MINUTES=60
# AUTH_RESET_COOLDOWN_SECONDS=120
```
The API builds its own DB connection string from the `POSTGRES_*`
@@ -87,6 +104,7 @@ 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.
These are the only credentials in the system, and they never appear in the
@@ -151,25 +169,34 @@ 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. 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.
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.
```bash
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 \
# 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 \
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 / --password override the environment if you'd rather be explicit.
# --user overrides $WP_SMOKE_USER if you'd rather be explicit.
```
Exit codes: **0** all checks passed · **1** one or more checks failed · **2** the run
@@ -257,7 +284,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`, `password_hash` (bcrypt), `role`, `full_name`, `email`, `is_active`, `auto_add_projects` + `auto_add_role` (default membership on new projects), login-lockout + `token_version` fields |
| `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` |
| `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) |
@@ -275,8 +302,9 @@ 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 `POST /api/auth/login` / `logout`, `GET /api/auth/me`, admin user management
under `/api/auth/users` (including `POST /api/auth/users/{id}/auto-add`) ·
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`) ·
Admin-only `GET/PUT /api/settings`,
`POST /api/settings/test-email`, `GET /api/notifications`,
`GET /api/projects/{id}/members`.
@@ -350,27 +378,31 @@ 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.
### Self-service password reset
### Sign-in and admin bootstrap (Okta)
Turning email on also enables **Forgot password** on the login page. Until then the
link explains that an admin must reset it (`server/manage_users.py`, or the Admin
console's **Reset password** button).
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.
- The emailed link carries a short-lived signed token — `AUTH_RESET_MINUTES`
(default 60). It is **single-use**: completing a reset bumps the account's
`token_version`, which both burns the link and signs out that user's other
sessions. A completed reset also clears any login lockout.
- `/api/auth/forgot-password` answers **identically for unknown accounts**, so it
can't be used to discover usernames. Misses are recorded in the audit log
(`password_reset_miss`) instead.
- One reset mail per account+client per `AUTH_RESET_COOLDOWN_SECONDS` (default 120)
so the form can't be used to flood someone's inbox. The throttle is per worker
and in-memory; the token expiry is the real control.
- Reset mails are sent **immediately, not through the notifications outbox** — a
reset link must never be persisted where an admin could read it and take over an
account.
- Set `app_base_url` in the admin card, or the emailed link will be relative and
therefore useless.
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:
```bash
docker compose exec api python -m server.manage_users promote alice --role admin
```
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).
## Permissions roles
@@ -382,7 +414,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**: create accounts, reset passwords, set permissions, grant project access |
| `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_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 |
@@ -399,9 +431,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.** 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
* **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
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

View File

@@ -27,10 +27,28 @@ services:
POSTGRES_HOST: db
# Optional full-URL override (must be URL-encoded if used).
DATABASE_URL: ${DATABASE_URL:-}
# 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).
# 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).
AUTH_SECRET_KEY: ${AUTH_SECRET_KEY:?set AUTH_SECRET_KEY in .env (see server/.env.example)}
AUTH_SESSION_HOURS: ${AUTH_SESSION_HOURS:-12}
# 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}
# 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.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 296 KiB

After

Width:  |  Height:  |  Size: 382 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 243 KiB

After

Width:  |  Height:  |  Size: 315 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 340 KiB

After

Width:  |  Height:  |  Size: 193 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 299 KiB

After

Width:  |  Height:  |  Size: 135 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 82 KiB

After

Width:  |  Height:  |  Size: 132 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 81 KiB

After

Width:  |  Height:  |  Size: 123 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 116 KiB

After

Width:  |  Height:  |  Size: 136 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 80 KiB

After

Width:  |  Height:  |  Size: 98 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

View File

@@ -316,6 +316,17 @@ 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

View File

@@ -594,3 +594,105 @@ deliberately deferred.
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).
### BL-028 — `okta_auth.describe()` is never called
- **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.
### BL-029 — `users.failed_attempts` / `users.locked_until` are vestigial
- **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.
### BL-031 — A raw `rgba()` shadow survives in the creator's stylesheet
- **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.

View File

@@ -0,0 +1,75 @@
# 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.

View File

@@ -0,0 +1,122 @@
# 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`.

View File

@@ -0,0 +1,355 @@
# 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`.

233
docs/waves/wave-10.md Normal file
View File

@@ -0,0 +1,233 @@
# Wave 10 — Okta OIDC authentication
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.
Depends only on `main` as it stands after `D15`. Not sequenced behind any other wave.
## Tasks
- **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`.
- **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.
- **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.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.
- **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).
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.
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.
- **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.
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.
**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.
- **T10.8 — Verification.** 390px and 1440px, full suite, done-when checks per task,
matching the rigor D13 was held to.
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.
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.
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.
- **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.
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.
- **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.
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.
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
- 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.
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.
**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.

263
docs/waves/wave-12.md Normal file
View File

@@ -0,0 +1,263 @@
# 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.

View File

@@ -60,62 +60,10 @@
.then(function () { window.location.replace('login.html'); });
};
// Change-password dialog (uses POST /api/auth/password, which requires the
// current password). Available from the top-right pill on any page.
window.wpChangePassword = function () {
if (document.getElementById('wp-pw-modal')) return;
var ov = document.createElement('div');
ov.id = 'wp-pw-modal';
ov.style.cssText = 'position:fixed;inset:0;background:rgba(20,30,50,.5);display:flex;align-items:center;' +
'justify-content:center;z-index:10002;padding:20px;font:14px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;';
var inp = 'width:100%;padding:9px 10px;margin-bottom:12px;border:1px solid var(--cds-border-strong);border-radius:4px;font-size:14px;';
var lbl = 'display:block;font-size:12px;color:var(--cds-text-secondary);margin-bottom:4px;';
ov.innerHTML =
'<div style="background:var(--cds-layer);color:var(--cds-text-primary);border-radius:10px;max-width:380px;width:100%;box-shadow:0 12px 40px rgba(20,30,50,.3);overflow:hidden;">' +
'<div style="padding:14px 18px;border-bottom:1px solid var(--cds-border-subtle);font-weight:700;">Change password</div>' +
'<div style="padding:16px 18px;">' +
'<div id="wp-pw-msg" style="display:none;font-size:12.5px;padding:8px 10px;border-radius:6px;margin-bottom:12px;"></div>' +
'<label style="' + lbl + '">Current password</label>' +
'<input id="wp-pw-cur" type="password" autocomplete="current-password" style="' + inp + '">' +
'<label style="' + lbl + '">New password (at least 12 characters)</label>' +
'<input id="wp-pw-new" type="password" autocomplete="new-password" style="' + inp + '">' +
'<label style="' + lbl + '">Confirm new password</label>' +
'<input id="wp-pw-new2" type="password" autocomplete="new-password" style="' + inp + 'margin-bottom:0;">' +
'</div>' +
'<div style="padding:12px 18px;border-top:1px solid var(--cds-border-subtle);display:flex;gap:8px;justify-content:flex-end;">' +
'<button type="button" id="wp-pw-cancel" style="padding:8px 14px;border:1px solid var(--cds-border-strong);background:var(--cds-layer);border-radius:6px;cursor:pointer;font-weight:600;">Cancel</button>' +
'<button type="button" id="wp-pw-save" style="padding:8px 14px;border:none;background:var(--cds-interactive-01);color:var(--cds-text-on-color);border-radius:6px;cursor:pointer;font-weight:600;">Update password</button>' +
'</div>' +
'</div>';
function close() { var m = document.getElementById('wp-pw-modal'); if (m) m.remove(); }
function msg(text, ok) {
var el = document.getElementById('wp-pw-msg');
el.style.display = 'block'; el.textContent = text;
el.style.background = ok ? 'var(--wp-status-success-bg)' : 'var(--wp-status-error-bg)'; el.style.color = ok ? 'var(--wp-status-success-text)' : 'var(--cds-support-error)';
}
ov.addEventListener('click', function (e) { if (e.target === ov) close(); });
document.body.appendChild(ov);
document.getElementById('wp-pw-cancel').onclick = close;
document.getElementById('wp-pw-cur').focus();
document.getElementById('wp-pw-save').onclick = function () {
var cur = document.getElementById('wp-pw-cur').value;
var n1 = document.getElementById('wp-pw-new').value;
var n2 = document.getElementById('wp-pw-new2').value;
if (!cur || !n1) { msg('Please fill in every field.', false); return; }
if (n1.length < 12) { msg('New password must be at least 12 characters.', false); return; }
if (n1 !== n2) { msg('New passwords do not match.', false); return; }
fetch('/api/auth/password', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ current_password: cur, new_password: n1 })
})
.then(function (r) { return r.json().catch(function () { return null; }).then(function (j) { return { ok: r.ok, status: r.status, j: j }; }); })
.then(function (res) {
if (res.ok) { msg('Password updated.', true); setTimeout(close, 1200); }
else { msg((res.j && res.j.detail) || ('Could not update (HTTP ' + res.status + ').'), false); }
})
.catch(function () { msg('Could not reach the server.', false); });
};
};
// 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
@@ -171,7 +119,8 @@
// 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 two items that were only here: Language & time, and Password.
// 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.)
//
// Nothing replaces it. Every signed-in page mounts the drawer, so there is no page
// left that would need a floating fallback pill.

View File

@@ -31,34 +31,23 @@
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; }
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 {
.btn {
display: block;
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;
}
button:hover:not(:disabled) { background: var(--cds-hover-primary); }
button:disabled { background: var(--cds-disabled-02); cursor: not-allowed; }
.btn:hover { background: var(--cds-hover-primary); }
.btn:focus-visible { outline: 2px solid var(--cds-focus); outline-offset: 2px; }
.error {
display: none;
background: var(--wp-status-error-bg);
@@ -69,7 +58,6 @@
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);
@@ -80,15 +68,7 @@
margin-bottom: 1.25rem;
}
.ok.show { display: block; }
.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; }
.foot { margin-top: 1.5rem; font-size: 0.75rem; color: var(--cds-text-helper); text-align: center; }
</style>
</head>
<body>
@@ -99,61 +79,10 @@
<div id="error" class="error" role="alert"></div>
<div id="ok" class="ok" role="status"></div>
<!-- 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>
<button id="submit" type="submit">Sign in</button>
</form>
<p class="center"><a href="#" id="forgot-link" class="link">Forgot password?</a></p>
</section>
<!-- FORGOT PASSWORD (email reset) -->
<section id="view-forgot" style="display:none">
<h1>Reset password</h1>
<p class="sub">We'll email you a link to set a new one.</p>
<div id="forgot-unavailable" class="note" style="display:none">
Password reset by email isn't switched on yet. Contact your project admin and
they'll set a new password for you. Once you're signed in you can change it
yourself from the menu in the top-right corner.
</div>
<form id="forgot-form" autocomplete="on">
<div class="field">
<label for="forgot-username">Username or email</label>
<input id="forgot-username" type="text" autocomplete="username" required>
</div>
<button id="forgot-submit" type="submit">Email me a reset link</button>
</form>
<p class="center"><a href="#" id="back-to-login" class="link">← Back to sign in</a></p>
</section>
<!-- SET A NEW PASSWORD (arrived from the emailed link) -->
<section id="view-reset" style="display:none">
<h1>Set a new password</h1>
<p class="sub">Choose a password you don't use anywhere else.</p>
<form id="reset-form" autocomplete="on">
<div class="field">
<label for="new-password">New password</label>
<input id="new-password" type="password" autocomplete="new-password" autofocus required>
</div>
<div class="hint">At least 12 characters.</div>
<div class="field">
<label for="new-password2">Confirm new password</label>
<input id="new-password2" type="password" autocomplete="new-password" required>
</div>
<button id="reset-submit" type="submit">Set password &amp; sign in</button>
</form>
<p class="center"><a href="#" id="reset-to-login" class="link">← Back to sign in</a></p>
</section>
<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>
<p class="foot">Authorized use only · BTG / Pilot</p>
</main>

View File

@@ -1,26 +1,16 @@
/* Login page logic for the Work Package Suite.
Three views on one page:
• sign in posts to /api/auth/login. On success the server sets an
HttpOnly session cookie (not readable here — that's the
point) and we redirect to ?next= or the home page.
• forgot password posts to /api/auth/forgot-password, which emails a
single-use link. Only offered when the server reports
email is actually configured (/api/auth/reset-available);
otherwise we say to ask an admin.
• set a new password shown when the page is opened as login.html?reset=<token>
from that email. Posts to /api/auth/reset-password.
The reset token stays in the URL only until it's used; on success we strip it
from the address bar so it isn't left in history or copied out of the bar. */
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). */
(function () {
'use strict';
var errorBox = document.getElementById('error');
var okBox = document.getElementById('ok');
var signinLink = document.getElementById('okta-signin');
function show(el) { if (el) el.style.display = ''; }
function hide(el) { if (el) el.style.display = 'none'; }
function byId(id) { return document.getElementById(id); }
function showError(msg) {
@@ -28,188 +18,38 @@
errorBox.textContent = msg;
errorBox.classList.add('show');
}
function showOk(msg) {
errorBox.classList.remove('show');
okBox.textContent = msg;
okBox.classList.add('show');
}
function clearBanners() {
errorBox.classList.remove('show');
okBox.classList.remove('show');
}
// 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() {
// 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() {
try {
var next = new URLSearchParams(location.search).get('next') || '';
if (next && next.charAt(0) === '/' && next.charAt(1) !== '/') return next;
} catch (e) {}
return 'index.html';
return '';
}
function resetToken() {
try { return new URLSearchParams(location.search).get('reset') || ''; } catch (e) { return ''; }
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;
}
function view(which) {
clearBanners();
['login', 'forgot', 'reset'].forEach(function (v) {
(which === v ? show : hide)(byId('view-' + v));
});
}
// ── sign in ────────────────────────────────────────────────────────────────
var form = byId('login-form');
var submitBtn = byId('submit');
// Guarded because a cached older login.html may not have the reset views; an
// unguarded addEventListener on null would break sign-in itself.
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.'));
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';
});
});
// ── forgot password ────────────────────────────────────────────────────────
var resetAvailable = null; // null = not checked yet
function checkResetAvailable() {
if (resetAvailable !== null) return Promise.resolve(resetAvailable);
return fetch('/api/auth/reset-available')
.then(function (r) { return r.ok ? r.json() : null; })
.then(function (j) { resetAvailable = !!(j && j.enabled); return resetAvailable; })
.catch(function () { resetAvailable = false; return false; });
}
(byId('forgot-link') || {addEventListener: function(){}}).addEventListener('click', function (e) {
e.preventDefault();
view('forgot');
// Prefill from the sign-in box so nobody types their username twice.
var u = byId('username').value.trim();
if (u) byId('forgot-username').value = u;
checkResetAvailable().then(function (enabled) {
// With email off there's nothing to submit — say so and hide the form.
(enabled ? hide : show)(byId('forgot-unavailable'));
(enabled ? show : hide)(byId('forgot-form'));
if (enabled) byId('forgot-username').focus();
});
});
(byId('back-to-login') || {addEventListener: function(){}}).addEventListener('click', function (e) {
e.preventDefault();
view('login');
});
var forgotForm = byId('forgot-form') || document.createElement('form');
var forgotBtn = byId('forgot-submit') || document.createElement('button');
forgotForm.addEventListener('submit', function (e) {
e.preventDefault();
clearBanners();
var who = byId('forgot-username').value.trim();
if (!who) { showError('Enter your username or email.'); return; }
forgotBtn.disabled = true;
forgotBtn.textContent = 'Sending…';
postJson('/api/auth/forgot-password', { username: who })
.then(function (res) {
if (res.status === 503) {
showError(detail(res, "Password reset by email isn't available. Ask an administrator."));
} else if (res.ok) {
// Deliberately the same message whether or not the account exists.
showOk('If that account exists, a reset link is on its way. The link expires in an hour.');
hide(forgotForm);
} else {
showError(detail(res, 'Could not send the reset email (HTTP ' + res.status + ').'));
}
forgotBtn.disabled = false;
forgotBtn.textContent = 'Email me a reset link';
})
.catch(function () {
showError('Could not reach the server. Check your connection and try again.');
forgotBtn.disabled = false;
forgotBtn.textContent = 'Email me a reset link';
});
});
// ── set a new password (from the emailed link) ──────────────────────────────
(byId('reset-to-login') || {addEventListener: function(){}}).addEventListener('click', function (e) {
e.preventDefault();
view('login');
});
var resetForm = byId('reset-form') || document.createElement('form');
var resetBtn = byId('reset-submit') || document.createElement('button');
resetForm.addEventListener('submit', function (e) {
e.preventDefault();
clearBanners();
var token = resetToken();
var pw = byId('new-password').value;
var pw2 = byId('new-password2').value;
if (!token) { showError('This reset link is incomplete. Request a new one.'); return; }
if (pw !== pw2) { showError('The two passwords do not match.'); return; }
if (pw.length < 12) { showError('Password must be at least 12 characters.'); return; }
resetBtn.disabled = true;
resetBtn.textContent = 'Saving…';
postJson('/api/auth/reset-password', { token: token, new_password: pw })
.then(function (res) {
if (res.ok) {
// Take the token out of the URL before anything else — it's spent.
try { history.replaceState(null, '', 'login.html'); } catch (err) {}
view('login');
showOk('Password updated. Sign in with your new password.');
byId('username').focus();
return;
}
showError(detail(res, 'Could not set your password (HTTP ' + res.status + ').'));
resetBtn.disabled = false;
resetBtn.textContent = 'Set password & sign in';
})
.catch(function () {
showError('Could not reach the server. Check your connection and try again.');
resetBtn.disabled = false;
resetBtn.textContent = 'Set password & sign in';
});
});
// Arriving from the reset email opens straight into the new-password view.
if (resetToken()) view('reset');
(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) {}
})();
})();

View File

@@ -24,11 +24,11 @@
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. */
#users-table table td:nth-child(3){ max-width:230px; overflow:hidden; text-overflow:ellipsis; }
/* 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-banner:not(:empty), #scope-banner:not(:empty){ margin-bottom:var(--s3); }
/* The create form is a lot of fields; give the password one room to breathe and
let the project picker take a full row of its own. */
#nu-password{ flex:1 1 200px; }
#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,6 +36,45 @@
#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>
@@ -66,15 +105,33 @@
<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="renderUsers()">
<select id="user-filter" onchange="renderUsers()">
<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">
<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>
@@ -83,12 +140,12 @@
<h2>Add a user</h2>
<div class="sub" id="create-sub"></div>
<div class="urow">
<input id="nu-username" placeholder="Username *" autocomplete="off">
<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-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>
<select id="nu-project-role" title="Job function on the project"></select>
<input id="nu-password" type="password" placeholder="Password (min 12)" autocomplete="new-password">
</div>
<div id="nu-projects">
<div class="note" id="nu-projects-label" style="margin-bottom:var(--s1)"></div>

View File

@@ -23,6 +23,10 @@
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(){
@@ -40,6 +44,7 @@ async function boot(){
renderScope();
}
renderCreateForm();
renderBulkActions();
loadUsers();
}
@@ -90,11 +95,309 @@ 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();
@@ -116,7 +419,8 @@ 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>';
if(!list.length){ wrap.innerHTML = count+'<div class="note">Nothing matches.</div>'; return; }
_shownSelectable = list.filter(selectable).map(u => u.id);
if(!list.length){ wrap.innerHTML = count+'<div class="note">Nothing matches.</div>'; updateSelectionUI(); return; }
const head = manages()
? ['Username','Name','Email',
@@ -130,9 +434,16 @@ 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>'+ths+
wrap.innerHTML = count+'<div class="tscroll"><table class="grid"><thead><tr>'+selTh+ths+
'</tr></thead><tbody>'+rows+'</tbody></table></div>'+legend();
updateSelectionUI();
}
function legend(){
@@ -183,14 +494,13 @@ function managerRow(u){
: projRoleReadonly(u, can, why);
const actions = [];
if(can && !me) actions.push('<button class="mini" onclick="resetPw(\''+uid+'\',\''+uname+'\')">Reset password</button>');
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>');
if(me) actions.push('<button class="mini" disabled title="Use the Password link in the top bar to change your own">—</button>');
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
@@ -254,19 +564,6 @@ function projAccessCell(u){
// ── row actions ───────────────────────────────────────────────────────────────
// Each one reloads on failure so a control can never sit there showing a value the
// server refused.
async function resetPw(id, username){
// The min-12 rule was stated in the prompt label and enforced only by the
// server round-trip; the kit's validate() answers AT the input instead.
const pw = await wpPromptDialog({title:'Reset password',
message:'Set a new password for "'+username+'". Their existing sessions are signed out.',
label:'New password (min 12 characters)',
validate:v => (v && v.length >= 12) ? '' : 'At least 12 characters.'});
if(pw === null) return;
const { status, json } = await api('POST','/api/auth/users/'+id+'/password',{new_password:pw});
if(status === 200) toast('Password reset for '+username+'. Their existing sessions are signed out.');
else wpAlertDialog({title:'Reset failed', message:'Could not reset the password: '+apiError(status, json)});
}
async function toggleActive(id, makeActive){
const { status, json } = await api('POST','/api/auth/users/'+id+'/active',{is_active:makeActive});
if(status === 200) loadUsers();
@@ -344,25 +641,27 @@ 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 password = val('nu-password');
const project_ids = [...document.querySelectorAll('#nu-project-list input[type=checkbox]:checked')]
.map(c => c.value);
const say = (color, text) => { msg.style.color = color; msg.textContent = text; };
if(!username){ say('var(--red)','Username is required.'); return; }
if(password.length < 12){ say('var(--red)','Password must be at least 12 characters.'); return; }
if(_scope.scope !== 'all' && !project_ids.length){
say('var(--red)','Pick at least one project — you administer users per project.'); return;
}
say('var(--muted)','Creating…');
const { status, json } = await api('POST','/api/auth/users',{
username, password, project_ids,
username, project_ids,
full_name: val('nu-fullname').trim(), email: val('nu-email').trim(),
role: val('nu-role'), project_role: val('nu-project-role'),
});
if(status === 200){
say('var(--green)','✓ Created '+username+'.');
['nu-username','nu-fullname','nu-email','nu-password'].forEach(id => document.getElementById(id).value = '');
['nu-username','nu-fullname','nu-email'].forEach(id => document.getElementById(id).value = '');
loadUsers();
} else {
say('var(--red)','✕ '+apiError(status, json, 'Could not create the account'));

View File

@@ -53,7 +53,6 @@
{ section: 'Account' },
{ action: 'wpPreferences', icon: '◷', label: 'Language & time',
sub: 'Dates, numbers and time zone' },
{ action: 'wpChangePassword', icon: '⚿', label: 'Password', sub: 'Change your password' },
];
function esc(v) {

View File

@@ -12,15 +12,49 @@ DATABASE_URL=postgresql+psycopg://wpsuite:CHANGE_ME@localhost:5432/wpsuite
# CORS_ORIGINS=http://localhost:5500
# ── Authentication ────────────────────────────────────────────────────────────
# 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:
# 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:
# 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 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
# ── Email notifications (optional) ─────────────────────────────────────────────
# WP-assignment emails are OFF by default and are turned on from the Admin
# console (Notifications & email card), where the SMTP host/port/from-address

View File

@@ -14,12 +14,12 @@ browser → NGINX ──serves──> static site (index.html, …)
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/health` | liveness check (unauthenticated) |
| POST | `/api/auth/login` | sign in (`{username, password}`) — sets the session cookie |
| GET | `/api/auth/okta/login` | redirects the browser to Okta's authorize endpoint (`?next=` optional) |
| GET | `/api/auth/okta/callback` | Okta redirects back here with the auth code; signs the person in |
| POST | `/api/auth/logout` | clear the session cookie |
| GET | `/api/auth/me` | the logged-in user |
| POST | `/api/auth/password` | change your own password |
| GET | `/api/auth/users` | list accounts (**admin**) |
| POST | `/api/auth/users` | create an account (**admin**) |
| POST | `/api/auth/users` | pre-create an account by username (**admin**) |
| DELETE | `/api/auth/users/{id}` | delete an account (**admin**) |
| POST | `/api/sops` | create/update a SOP (upsert by `id`) |
| GET | `/api/sops` | list SOP summaries |
@@ -40,50 +40,81 @@ fields (name, number, status, …) are promoted to columns for listing/filtering
---
## Login portal (user accounts)
## Sign-in (Okta)
The suite is gated by a username/password login. 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.
There is no local password anywhere in this app (D15/D16) — Okta OIDC is the
only way in. `login.html` is a single "Sign in with Okta" button; the actual
exchange is `server/okta_auth.py` (the Okta client config) and the two routes
in `server/app.py`: `okta_login()` sends the browser to Okta's authorize
endpoint, `okta_callback()` exchanges the code, matches the ID token's identity
claim against `users.username`, and signs the person in.
Sign-in still ends the same way it always did: a signed JWT in an **HttpOnly,
SameSite=Lax** cookie (`wp_session`), marked **Secure** automatically whenever
the request arrives over HTTPS (via NGINX's `X-Forwarded-Proto`). There is no
server-side session store — each request is validated by checking the cookie's
signature and expiry. Okta only confirms *who* someone is; this app still
decides *what* they may do — roles, project membership, everything below stays
local and unchanged by Okta.
**The real security boundary is the API:** every `/api/` data route is refused
with `401` unless a valid session cookie is present (see `auth_gate` in
`app.py`). The static pages additionally include `auth-guard.js`, which redirects
to `login.html` when there's no session — that's for UX, not protection.
Passwords are stored only as **bcrypt** hashes (`server/auth.py`). Roles are
`admin` (may manage users) and `user`.
**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.
### Set the signing secret
Roles are `admin`, `project_super_user`, `project_admin`, `project_user`
(`html/users.js`, enforced server-side).
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.
### Set the signing secret and the Okta app integration
Add `AUTH_SECRET_KEY` and the five `OKTA_*` variables to `.env` — see
`.env.example` for what each one is and where it comes from. `AUTH_SECRET_KEY`
is **required in production**: without it the API uses a random per-process
key, so logins reset on restart. The `OKTA_*` variables are not a hard-fail the
same way — the API starts without them, it just refuses every sign-in and says
so in the startup log (`okta_auth.describe()`).
```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).
### Create the first admin
The `/api/auth/users` endpoint needs an existing admin, so bootstrap one from a
shell (run from the **project root**, like uvicorn):
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):
```bash
python -m server.manage_users create-admin alice --name "Alice Smith"
# prompts for a password (min 8 chars)
python -m server.manage_users promote alice --role admin
```
In Docker:
```bash
docker compose exec api python -m server.manage_users create-admin alice --name "Alice Smith"
docker compose exec api python -m server.manage_users promote alice --role admin
```
Other commands: `create <user> --role user`, `list`, `reset-password <user>`,
`disable <user>`, `enable <user>`. After that, admins can add users through the
API (or you can keep using the CLI).
Other commands: `list`, `disable <user>`, `enable <user>`. After the first
admin exists, they can promote others through the User Directory page (or keep
using the CLI) — no shell access needed for anyone after the first.
**No break-glass path.** If Okta is unreachable or misconfigured, the app is
unreachable for everyone, including admins, until Okta is restored (D16) — this
is a deliberate choice, the same one the abandoned LDAPS design made, not an
oversight.
---
@@ -291,25 +322,25 @@ docker compose down -v
## Quick test
`/api/health` is open; data routes now require a session, so log in first and
reuse the cookie jar:
`/api/health` is open; every other `/api/` route needs a session cookie:
```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 the cookie, protected routes return `401 {"detail":"Not authenticated"}`.
Without a session 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.

View File

@@ -0,0 +1,29 @@
"""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=''))

View File

@@ -9,24 +9,27 @@ Run (prod): gunicorn -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000 serve
Interactive docs: http://<host>/api/docs
"""
import base64
import logging
import os
import re
import uuid
from datetime import timedelta, timezone
from time import monotonic
from typing import Any, Optional
from urllib.parse import urlparse
from authlib.integrations.base_client import OAuthError
from fastapi import FastAPI, Depends, HTTPException, Query, Request, Response, BackgroundTasks
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from fastapi.responses import JSONResponse, RedirectResponse
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel, ConfigDict, Field
from sqlalchemy import select, delete, func
from sqlalchemy.orm import Session
from starlette.middleware.sessions import SessionMiddleware
from .db import Base, engine, get_db
from . import models, auth, notify, assets_db
from . import models, auth, notify, assets_db, okta_auth, okta_fake
log = logging.getLogger("wpsuite.app")
# Schema management:
# • Local dev (SQLite) auto-creates tables for a zero-config run.
@@ -56,6 +59,22 @@ if _origins:
allow_methods=["*"], allow_headers=["*"], expose_headers=["X-Total-Count"],
)
# Authlib's Okta client needs request.session to carry the OIDC state/nonce (and,
# below, our own post-login redirect target) across the round trip to Okta and
# back — it raises an AssertionError without this. Bug found in T10.2 (those
# routes never crashed in testing because every prior check mocked
# authorize_redirect/authorize_access_token directly, bypassing Authlib's real
# implementation); fixed here rather than reworking already-shipped T10.2 code.
#
# This is NOT the app's session cookie — wp_session (auth.py) still carries the
# actual signed-in identity, unchanged. This cookie holds nothing but ephemeral,
# per-attempt OAuth state, so it gets a short lifetime and a plain secret reuse
# (auth.SECRET_KEY) rather than its own required config knob.
app.add_middleware(
SessionMiddleware, secret_key=auth.SECRET_KEY, session_cookie="wp_oauth_state",
same_site="lax", https_only=False, max_age=600,
)
# ── Authentication gate ────────────────────────────────────────────────────────
# Every /api/ data route requires a valid session cookie. Login, health, and the
@@ -605,14 +624,8 @@ def health():
# ── Authentication ─────────────────────────────────────────────────────────────
class LoginIn(BaseModel):
username: str
password: str
class NewUserIn(BaseModel):
username: str
password: str
full_name: str = ""
email: str = ""
role: str = auth.ROLE_PROJECT_USER # permissions role — see auth.ROLES
@@ -634,24 +647,6 @@ class PreferencesIn(BaseModel):
timezone: Optional[str] = None
class ForgotPasswordIn(BaseModel):
username: str = "" # username or email
class ResetPasswordIn(BaseModel):
token: str
new_password: str
class PasswordChangeIn(BaseModel):
current_password: str
new_password: str
class AdminPasswordIn(BaseModel):
new_password: str
class ActiveIn(BaseModel):
is_active: bool
@@ -674,160 +669,143 @@ class AutoAddIn(BaseModel):
role: str = ""
LOGIN_MAX_ATTEMPTS = int(os.getenv("AUTH_MAX_ATTEMPTS", "5"))
LOGIN_LOCKOUT_MINUTES = int(os.getenv("AUTH_LOCKOUT_MINUTES", "15"))
@app.post("/api/auth/login")
def login(body: LoginIn, request: Request, response: Response, db: Session = Depends(get_db)):
"""Verify credentials and, on success, set the HttpOnly session cookie.
Throttles online password guessing: after LOGIN_MAX_ATTEMPTS consecutive
failures an account is locked for LOGIN_LOCKOUT_MINUTES."""
user = auth.find_user(db, body.username)
now = models.utcnow()
# Always run the hash comparison first — even for missing or locked accounts —
# so response timing doesn't leak which usernames exist. verify_password
# tolerates an empty hash.
valid = auth.verify_password(body.password, user.password_hash if user else "")
locked = user.locked_until if user else None
if locked is not None and locked.tzinfo is None:
locked = locked.replace(tzinfo=timezone.utc) # SQLite returns naive datetimes; normalize to UTC
if locked is not None and locked > now:
raise HTTPException(status_code=429, detail="Too many failed attempts. Try again later.")
if not user or not valid:
if user:
user.failed_attempts = (user.failed_attempts or 0) + 1
if user.failed_attempts >= LOGIN_MAX_ATTEMPTS:
user.locked_until = now + timedelta(minutes=LOGIN_LOCKOUT_MINUTES)
user.failed_attempts = 0
log_event(db, user.username, "login_locked", "user", user.id, summary=user.username,
detail={"minutes": LOGIN_LOCKOUT_MINUTES})
db.commit()
raise HTTPException(status_code=401, detail="Invalid username or password")
if not user.is_active:
raise HTTPException(status_code=403, detail="Account is disabled")
user.failed_attempts = 0
user.locked_until = None
user.last_login_at = now
db.commit()
token = auth.create_token(user)
auth.set_session_cookie(response, request, token)
return {"user": user.to_dict()}
@app.post("/api/auth/logout")
def logout(response: Response):
auth.clear_session_cookie(response)
return {"ok": True}
# ── Self-service password reset (needs email switched on) ──────────────────────
RESET_COOLDOWN_SECONDS = int(os.getenv("AUTH_RESET_COOLDOWN_SECONDS", "120"))
# In-process throttle: one reset mail per (account, client) per cooldown. Enough to
# stop someone using the form to spam a colleague's inbox. Per-worker and lost on
# restart — deliberately simple; the token expiry is the real control.
_reset_last: dict[str, float] = {}
# ── Okta OIDC sign-in (T10.2, wave 10 / D15) ────────────────────────────────────
# Access gating is Okta's job: only accounts assigned to this app integration in Okta
# can complete authorize_redirect at all. No app-side group/claim check is layered on
# top here — see okta_auth.py's docstring and wave-10.md T10.2 for why.
def _safe_next_path(raw: str) -> str:
"""A same-site path only — same rule login.js's own nextTarget() enforces
client-side. Rejects absolute/scheme URLs ('//evil.com', 'https://evil.com')
so a crafted ?next= can't turn a real Okta sign-in into an open redirect."""
raw = (raw or "").strip()
if raw and raw.startswith("/") and not raw.startswith("//"):
return raw
return ""
def _reset_throttled(request: Request, username: str) -> bool:
now = monotonic()
key = f"{(username or '').strip().lower()}|{request.client.host if request.client else ''}"
prev = _reset_last.get(key)
if prev is not None and (now - prev) < RESET_COOLDOWN_SECONDS:
return True
_reset_last[key] = now
if len(_reset_last) > 5000: # bound the dict on a long-lived worker
cutoff = now - RESET_COOLDOWN_SECONDS
for k in [k for k, t in _reset_last.items() if t < cutoff]:
_reset_last.pop(k, None)
return False
@app.get("/api/auth/okta/login")
async def okta_login(request: Request):
"""Send the browser to Okta's authorize endpoint. Where to land afterward
(?next=, e.g. from a deep link an assignment email carried — X1/CR-011/CR-014)
rides in the OAuth-state session cookie alongside Authlib's own state/nonce,
since nothing else survives the round trip to Okta and back."""
if not okta_auth.oauth:
raise HTTPException(status_code=503, detail="Sign-in is temporarily unavailable. Contact IT.")
next_path = _safe_next_path(request.query_params.get("next", ""))
if next_path:
request.session["post_login_redirect"] = next_path
return await okta_auth.oauth.okta.authorize_redirect(request, okta_auth.REDIRECT_URI)
def reset_body(user: "models.User", link: str, minutes: int) -> str:
# No account detail beyond the username, and no customer data — same rule as
# the assignment mail. The link is the only sensitive thing in here.
who = user.full_name or user.username
return (
f"Hi {who},\n\n"
f"A password reset was requested for your Work Package Suite account "
f"({user.username}).\n\n"
f"Set a new password:\n{link}\n\n"
f"The link expires in {minutes} minutes and can only be used once. "
f"If you didn't request this, you can ignore this email — your current "
f"password still works.\n"
)
@app.get("/api/auth/okta/callback")
async def okta_callback(request: Request, db: Session = Depends(get_db)):
"""Exchange the authorization code for tokens, validate the ID token, and sign the
person in. T10.3: matches the identity claim to a local account, or JIT-provisions
one, then issues the same session cookie login() does today.
Failure paths land back on the login page with a plain-language ?error= instead
of a raw HTTPException — this route is reached by a full-page browser navigation
from Okta, not a fetch() call, so a JSON error body is just a broken-looking page
to whoever is sitting at the keyboard (T10.5)."""
if not okta_auth.oauth:
raise HTTPException(status_code=503, detail="Sign-in is temporarily unavailable. Contact IT.")
try:
token = await okta_auth.oauth.okta.authorize_access_token(request)
except OAuthError as exc:
log.warning("Okta callback rejected: %s", exc)
return RedirectResponse(url="/login.html?error=cancelled", status_code=303)
claims = token.get("userinfo") or {}
identity = (claims.get(okta_auth.IDENTITY_CLAIM) or "").strip()
if not identity:
log.error("Okta ID token had no %r claim — check OKTA_IDENTITY_CLAIM", okta_auth.IDENTITY_CLAIM)
raise HTTPException(status_code=503, detail="Sign-in is temporarily unavailable. Contact IT.")
@app.get("/api/auth/reset-available")
def reset_available(db: Session = Depends(get_db)):
"""Whether the login page should offer 'Forgot password'. Self-service reset
depends entirely on outbound email, so it's off unless email is enabled AND
SMTP is configured — otherwise the only route is an admin reset."""
s = notify.get_settings(db)
return {"enabled": bool(s.get("email_enabled")) and notify.smtp_ready(s)}
@app.post("/api/auth/forgot-password")
def forgot_password(body: ForgotPasswordIn, request: Request, db: Session = Depends(get_db)):
"""Email a reset link. Always returns the same 200 response whether or not the
account exists — this endpoint is unauthenticated, so it must not become a
username/email oracle. Failures are recorded in the audit log instead."""
s = notify.get_settings(db)
if not (s.get("email_enabled") and notify.smtp_ready(s)):
raise HTTPException(
status_code=503,
detail="Password reset by email isn't available. Ask an administrator to reset it for you.",
user = auth.find_user(db, identity)
if user is None:
# JIT provisioning (D15). Okta is the only gate on WHO can reach this route
# at all — this app still decides what a first-time sign-in may do. A new
# account gets the lowest-privilege role and no project membership; an admin
# or project super user grants access afterward, same as any account created
# by hand today (create_user() above). No password field exists at all —
# Okta is the only credential (D15/D16, real deletion as of T10.4).
user = models.User(
id=gen_id("user"),
username=identity,
email=(claims.get("email") or "").strip(),
full_name=(claims.get("name") or "").strip(),
role=auth.ROLE_PROJECT_USER,
)
if _reset_throttled(request, body.username):
# Same shape as the success response — no oracle, no mail bomb.
return {"ok": True, "message": "If that account exists, a reset link is on its way."}
user = auth.find_user(db, body.username)
if user and user.is_active and user.email:
base = (s.get("app_base_url") or "").rstrip("/")
token = auth.create_reset_token(user)
link = f"{base}/login.html?reset={token}" if base else f"/login.html?reset={token}"
sent = notify.send_now(
db, user.email,
"Work Package Suite — reset your password",
reset_body(user, link, auth.RESET_MINUTES),
)
log_event(db, user.username, "password_reset_requested", "user", user.id,
summary=user.username, detail={"emailed": bool(sent)})
db.commit()
else:
# Log the miss for the admin's benefit; the caller can't tell the difference.
log_event(db, "(anonymous)", "password_reset_miss", "user", "",
summary=(body.username or "")[:200],
detail={"reason": "no account, inactive, or no email on file"})
db.commit()
return {"ok": True, "message": "If that account exists, a reset link is on its way."}
db.add(user)
db.flush()
log_event(db, user.username, "user_created", "user", user.id, summary=user.username,
detail={"role": user.role, "via": "okta_jit"})
elif not user.is_active:
# Deprovisioning stays local (D15's "roles stay local"): Okta letting someone
# through does not override an account this app has disabled. Same rule
# login() enforced today, now surfaced as a login-page banner (T10.5)
# instead of a raw 403 body, for the reason in this route's docstring.
return RedirectResponse(url="/login.html?error=disabled", status_code=303)
@app.post("/api/auth/reset-password")
def reset_password(body: ResetPasswordIn, db: Session = Depends(get_db)):
"""Complete a reset using the emailed token. The token carries the user's
token_version, and finishing a reset bumps it — so the link is single-use and
every existing session for that account is signed out."""
claims = auth.decode_reset_token(body.token or "")
if not claims:
raise HTTPException(status_code=400, detail="This reset link is invalid or has expired. Request a new one.")
user = db.get(models.User, claims.get("sub"))
if not user or not user.is_active:
raise HTTPException(status_code=400, detail="This reset link is no longer valid.")
if (claims.get("ver", 0) or 0) != (user.token_version or 0):
raise HTTPException(status_code=400, detail="This reset link has already been used. Request a new one.")
problem = auth.password_problem(body.new_password, user.username, user.email)
if problem:
raise HTTPException(status_code=400, detail=problem)
user.password_hash = auth.hash_password(body.new_password)
user.token_version = (user.token_version or 0) + 1 # burns the link + all sessions
# A completed reset also clears any login lockout — the person has proven
# control of the mailbox, so there's nothing left to throttle.
user.failed_attempts = 0
user.locked_until = None
log_event(db, user.username, "password_reset", "user", user.id, summary=user.username)
user.last_login_at = models.utcnow()
db.commit()
return {"ok": True}
db.refresh(user)
tok = auth.create_token(user)
target = _safe_next_path(request.session.pop("post_login_redirect", "")) or "/index.html"
redirect = RedirectResponse(url=target, status_code=303)
auth.set_session_cookie(redirect, request, tok)
return redirect
# ── Fake Okta test seam (T10.7) ──────────────────────────────────────────────
# Registered ONLY when the fake is active — checked once, at import time, same
# timing okta_auth.oauth itself is built at. In production these two routes do
# not exist at all, not merely refuse a request: see server/okta_fake.py's
# docstring for why that distinction matters given D16 leaves no other way in.
if okta_fake.is_active():
@app.get("/api/auth/okta/_fake_provider")
async def okta_fake_provider(request: Request):
"""Stands in for Okta's own sign-in screen. A plain list of the
identities WP_OKTA_FAKE_DIRECTORY defines, so a browser check drives a
real page through a real round trip rather than skipping it."""
state = request.query_params.get("state", "")
redirect_uri = request.query_params.get("redirect_uri") or "/api/auth/okta/callback"
from fastapi.responses import HTMLResponse
return HTMLResponse(okta_fake.picker_page(state, redirect_uri))
@app.get("/api/auth/okta/_fake_provider/consent")
async def okta_fake_consent(request: Request):
"""What clicking an identity (or Deny) on the fake picker does: hands
back an authorization code (or an error) at okta_callback, exactly the
shape a real Okta redirect would carry. Everything after this — the
state check, JIT provisioning, the disabled-account and open-redirect
guards — is the real okta_callback() above, unmodified."""
state = request.query_params.get("state", "")
redirect_uri = request.query_params.get("redirect_uri") or "/api/auth/okta/callback"
if request.query_params.get("deny"):
return RedirectResponse(
url=f"{redirect_uri}?error=access_denied&error_description=denied+by+fake+user&state={state}",
status_code=303)
username = request.query_params.get("username", "")
entry = okta_fake.directory().get(username)
if not isinstance(entry, dict):
return RedirectResponse(
url=f"{redirect_uri}?error=invalid_request&error_description=unknown+fake+identity&state={state}",
status_code=303)
claims = {okta_auth.IDENTITY_CLAIM: username,
"email": entry.get("email", ""), "name": entry.get("name", "")}
code = okta_fake.new_code(claims)
return RedirectResponse(url=f"{redirect_uri}?code={code}&state={state}", status_code=303)
@app.get("/api/auth/me")
@@ -883,22 +861,6 @@ def set_preferences(body: PreferencesIn, user: models.User = Depends(auth.get_cu
return {"user": user.to_dict()}
@app.post("/api/auth/password")
def change_password(body: PasswordChangeIn, request: Request, response: Response, user: models.User = Depends(auth.get_current_user), db: Session = Depends(get_db)):
if not auth.verify_password(body.current_password, user.password_hash):
raise HTTPException(status_code=400, detail="Current password is incorrect")
problem = auth.password_problem(body.new_password, user.username, user.email)
if problem:
raise HTTPException(status_code=400, detail=problem)
user.password_hash = auth.hash_password(body.new_password)
user.token_version = (user.token_version or 0) + 1 # invalidate all OTHER existing sessions
db.commit()
db.refresh(user)
# Keep this session logged in by re-issuing a cookie carrying the new version.
auth.set_session_cookie(response, request, auth.create_token(user))
return {"ok": True}
# ── User administration ─────────────────────────────────────────────────────────
# Two kinds of caller reach these routes: an app admin, who manages every account,
# and a Project Super User, who manages the accounts on the projects they administer.
@@ -986,9 +948,14 @@ def user_scope(user: models.User = Depends(auth.get_current_user), db: Session =
@app.post("/api/auth/users")
def create_user(body: NewUserIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
problem = auth.password_problem(body.password, body.username, body.email)
if problem:
raise HTTPException(status_code=400, detail=problem)
"""Create an account ahead of its first Okta sign-in — e.g. to put it on
projects or hand it a role before anyone has ever signed in as them.
`body.username` MUST match what Okta's identity claim will send for this
person exactly (see OKTA_IDENTITY_CLAIM, server/okta_auth.py) — auth.find_user()
is how a later Okta sign-in locates this row (T10.3). A mismatch doesn't
fail loudly; it silently produces a second, JIT-provisioned account instead
of signing this person into the one just created here."""
allowed = grantable_roles(actor)
if body.role not in allowed:
raise HTTPException(status_code=400, detail=f"role must be one of {', '.join(allowed)}")
@@ -1020,7 +987,6 @@ def create_user(body: NewUserIn, actor: models.User = Depends(require_user_manag
username=body.username.strip(),
email=body.email.strip(),
full_name=body.full_name.strip(),
password_hash=auth.hash_password(body.password),
role=body.role,
project_role=body.project_role.strip()[:120],
)
@@ -1047,34 +1013,100 @@ def create_user(body: NewUserIn, actor: models.User = Depends(require_user_manag
return directory_entry(db, u, actor)
@app.post("/api/auth/users/{user_id}/password")
def admin_reset_password(user_id: str, body: AdminPasswordIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
u = load_target_user(db, user_id)
# ── One account-level change, used by the single-user routes AND the bulk routes ──
# CR-020 (T12.1): a bulk action is the single-user action, once per row. So each
# rule lives in exactly one function below, and both kinds of route call it: a
# bulk request cannot reach further than a one-at-a-time request, because there
# is no second copy of the rules for it to reach through. Every function checks
# all of its guards BEFORE it changes anything, so a row that is refused leaves
# nothing half-written, and writes its AuditLog row the way the single route
# always has. None of them commits; the route owns the transaction.
def guard_target(db: Session, actor: "models.User", u: "models.User") -> None:
"""The two checks every account change starts with: may the caller see this
account (404 if not, so existence does not leak), and may they change it."""
require_see_user(db, actor, u)
require_manage_user(db, actor, u)
problem = auth.password_problem(body.new_password, u.username, u.email)
if problem:
raise HTTPException(status_code=400, detail=problem)
u.password_hash = auth.hash_password(body.new_password)
u.token_version = (u.token_version or 0) + 1 # revoke the user's existing sessions
# An administrative password reset was the one user-account change that left no
# trace; it is the most impersonation-adjacent thing on this page, so it logs.
log_event(db, actor, "password_reset", "user", u.id, summary=u.username,
detail={"by": "administrator"})
db.commit()
return {"ok": True}
def apply_user_active(db: Session, actor: "models.User", u: "models.User", is_active: bool) -> None:
if u.id == actor.id and not is_active:
raise HTTPException(status_code=400, detail="You cannot disable your own account")
u.is_active = is_active
log_event(db, actor, "user_enabled" if is_active else "user_disabled", "user", u.id,
summary=u.username, detail={"is_active": bool(is_active)})
def apply_user_role(db: Session, actor: "models.User", u: "models.User", role: str) -> None:
"""The role guards: never your own role, never the last active admin. The
grantable-roles check is the caller's, made once per request before this."""
if u.id == actor.id:
raise HTTPException(status_code=400, detail="You cannot change your own role")
if auth.is_admin(u) and role != auth.ROLE_ADMIN:
other_admins = db.scalars(
select(models.User.id).where(
(models.User.role == auth.ROLE_ADMIN)
& (models.User.id != u.id)
& (models.User.is_active.is_(True))
)
).all()
if not other_admins:
raise HTTPException(status_code=400, detail="Can't remove the last admin account")
old_role = u.role
u.role = role
detail = {"from": old_role, "to": role}
# Promoting someone to admin retires their default-member flag: an admin already
# reaches every project, so the flag would do nothing except sit there invisibly
# (the console shows admins no controls) and come back to life the day they are
# demoted. Same reasoning as clearing the role in set_user_auto_add.
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
log_event(db, actor, "role_changed", "user", u.id, summary=u.username, detail=detail)
def apply_user_delete(db: Session, actor: "models.User", u: "models.User") -> None:
if u.id == actor.id:
raise HTTPException(status_code=400, detail="You cannot delete your own account")
log_event(db, actor, "user_deleted", "user", u.id, summary=u.username, detail={"role": u.role})
db.delete(u)
def apply_user_projects(db: Session, actor: "models.User", u: "models.User",
managed: Optional[set], valid: set, roles: dict) -> None:
"""Replace the caller's slice of `u`'s memberships with `valid`, each carrying
its role from `roles` ('' = inherit). `valid` must already be checked to exist
and to sit inside `managed`."""
# Rebuild only the rows this caller owns. Scoping the DELETE is the whole of the
# "leave other jobs alone" guarantee — get it wrong and a super user's save
# silently revokes access everywhere else.
doomed = delete(models.ProjectMember).where(models.ProjectMember.user_id == u.id)
if managed is not None:
# in_() on an empty set is a valid always-false predicate, so a caller who
# administers nothing deletes nothing (require_manage_user already refused them).
doomed = doomed.where(models.ProjectMember.project_id.in_(managed))
db.execute(doomed)
for pid in valid:
db.add(models.ProjectMember(id=gen_id("pm"), user_id=u.id, project_id=pid,
role=roles.get(pid, "")))
log_event(db, actor, "project_access_changed", "user", u.id, summary=u.username,
detail={"projects": len(valid),
"scope": "all" if managed is None else "managed",
"overrides": {p: r for p, r in roles.items() if p in valid}})
def project_scoped_grantable(actor: "models.User") -> tuple:
"""Per-project roles `actor` may hand out. Only an app admin can make someone a
super user on a project. user_scope and get_user_projects still spell the same
rule inline for the console; left as they are to keep this diff to CR-020."""
return auth.PROJECT_SCOPED_ROLES if auth.is_admin(actor) else (auth.ROLE_PROJECT_ADMIN, auth.ROLE_PROJECT_USER)
@app.post("/api/auth/users/{user_id}/active")
def set_user_active(user_id: str, body: ActiveIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
u = load_target_user(db, user_id)
require_see_user(db, actor, u)
require_manage_user(db, actor, u)
if u.id == actor.id and not body.is_active:
raise HTTPException(status_code=400, detail="You cannot disable your own account")
u.is_active = body.is_active
log_event(db, actor, "user_enabled" if body.is_active else "user_disabled", "user", u.id,
summary=u.username, detail={"is_active": bool(body.is_active)})
guard_target(db, actor, u)
apply_user_active(db, actor, u, body.is_active)
db.commit()
return directory_entry(db, u, actor)
@@ -1091,32 +1123,8 @@ def set_user_role(user_id: str, body: RoleIn, actor: models.User = Depends(requi
if body.role not in allowed:
raise HTTPException(status_code=400, detail=f"role must be one of {', '.join(allowed)}")
u = load_target_user(db, user_id)
require_see_user(db, actor, u)
require_manage_user(db, actor, u)
if u.id == actor.id:
raise HTTPException(status_code=400, detail="You cannot change your own role")
if auth.is_admin(u) and body.role != auth.ROLE_ADMIN:
other_admins = db.scalars(
select(models.User.id).where(
(models.User.role == auth.ROLE_ADMIN)
& (models.User.id != u.id)
& (models.User.is_active.is_(True))
)
).all()
if not other_admins:
raise HTTPException(status_code=400, detail="Can't remove the last admin account")
old_role = u.role
u.role = body.role
detail = {"from": old_role, "to": body.role}
# Promoting someone to admin retires their default-member flag: an admin already
# reaches every project, so the flag would do nothing except sit there invisibly
# (the console shows admins no controls) and come back to life the day they are
# demoted. Same reasoning as clearing the role in set_user_auto_add.
if body.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
log_event(db, actor, "role_changed", "user", u.id, summary=u.username, detail=detail)
guard_target(db, actor, u)
apply_user_role(db, actor, u, body.role)
db.commit()
db.refresh(u)
return directory_entry(db, u, actor)
@@ -1173,12 +1181,8 @@ def set_user_auto_add(user_id: str, body: AutoAddIn, admin: models.User = Depend
@app.delete("/api/auth/users/{user_id}")
def delete_user(user_id: str, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
u = load_target_user(db, user_id)
require_see_user(db, actor, u)
require_manage_user(db, actor, u)
if u.id == actor.id:
raise HTTPException(status_code=400, detail="You cannot delete your own account")
log_event(db, actor, "user_deleted", "user", u.id, summary=u.username, detail={"role": u.role})
db.delete(u)
guard_target(db, actor, u)
apply_user_delete(db, actor, u)
db.commit()
return {"deleted": user_id}
@@ -1231,8 +1235,7 @@ def set_user_projects(user_id: str, body: ProjectAssignIn, actor: models.User =
exactly as they were, because a payload that simply omits them would otherwise cut
someone off from a job the caller can't even see."""
u = load_target_user(db, user_id)
require_see_user(db, actor, u)
require_manage_user(db, actor, u)
guard_target(db, actor, u)
requested = [p for p in dict.fromkeys(body.project_ids) if p]
for pid in requested:
check_id(pid)
@@ -1245,28 +1248,227 @@ def set_user_projects(user_id: str, body: ProjectAssignIn, actor: models.User =
# A super user may hand out the project-scoped roles below their own; only an app
# admin can make someone a super user on a project. Anything unrecognised falls
# back to inheriting the account's own role.
allowed = auth.PROJECT_SCOPED_ROLES if auth.is_admin(actor) else (auth.ROLE_PROJECT_ADMIN, auth.ROLE_PROJECT_USER)
allowed = project_scoped_grantable(actor)
roles = {pid: r for pid, r in (body.roles or {}).items() if r in allowed}
# Rebuild only the rows this caller owns. Scoping the DELETE is the whole of the
# "leave other jobs alone" guarantee — get it wrong and a super user's save
# silently revokes access everywhere else.
doomed = delete(models.ProjectMember).where(models.ProjectMember.user_id == user_id)
if managed is not None:
# in_() on an empty set is a valid always-false predicate, so a caller who
# administers nothing deletes nothing (require_manage_user already refused them).
doomed = doomed.where(models.ProjectMember.project_id.in_(managed))
db.execute(doomed)
for pid in valid:
db.add(models.ProjectMember(id=gen_id("pm"), user_id=user_id, project_id=pid,
role=roles.get(pid, "")))
log_event(db, actor, "project_access_changed", "user", u.id, summary=u.username,
detail={"projects": len(valid),
"scope": "all" if managed is None else "managed",
"overrides": {p: r for p, r in roles.items() if p in valid}})
apply_user_projects(db, actor, u, managed, valid, roles)
db.commit()
return {"assigned": sorted(valid), "roles": {p: roles.get(p, "") for p in sorted(valid)}}
# ── Bulk user administration — CR-020 (T12.1) ─────────────────────────────────
# Four actions over a list of accounts: activate/disable, permissions role,
# project add/remove (with the per-project role), delete. Each row runs exactly
# the guards and the audit of the single-user route, through the same apply_*
# function above. Rules, decided 2026-09-17 and confirmed 2026-10-06:
# * a row that is refused is reported with its reason and the rest still run;
# a batch is never reported as a success when part of it failed;
# * one AuditLog row per changed account, the same as the single route writes -
# never one opaque "bulk" entry;
# * the caller's own account is refused only on its own row (disable, demote,
# delete), never by failing the whole batch;
# * project assignment adds to or removes from ONE project; it never replaces a
# user's whole project list.
# A row already in the requested state is reported "unchanged" and writes no
# audit row: nothing changed, so there is nothing to audit.
#
# The routes live under /api/auth/bulk-users/ rather than /api/auth/users/bulk/,
# because POST /api/auth/users/{user_id}/active would otherwise match "bulk" as
# a user id.
BULK_MAX_USERS = 500
class BulkUsersIn(BaseModel):
user_ids: list[str] = Field(default_factory=list, max_length=BULK_MAX_USERS)
class BulkActiveIn(BulkUsersIn):
is_active: bool
class BulkRoleIn(BulkUsersIn):
role: str
class BulkProjectIn(BulkUsersIn):
project_id: str
op: str # "add" | "remove"
role: str = "" # per-project role on add; '' = inherit the account's own
def run_bulk(db: Session, actor: "models.User", user_ids: list[str], action: str, apply) -> dict:
"""Run `apply(u)` once per distinct id, in the order given. `apply` returns
"ok" or "unchanged", or raises HTTPException with the reason the single-user
route would have given. The flush after every row matters: the session does
not autoflush, and a later row's guard (the last-admin count, for one) has to
see what an earlier row already changed."""
results = []
for uid in dict.fromkeys(i for i in user_ids if i):
row = {"user_id": uid, "username": "", "status": "", "reason": ""}
try:
check_id(uid)
u = load_target_user(db, uid)
row["username"] = u.username
guard_target(db, actor, u)
row["status"] = apply(u)
db.flush()
except HTTPException as exc:
row["status"] = "failed"
row["reason"] = exc.detail if isinstance(exc.detail, str) else str(exc.detail)
results.append(row)
db.commit()
counts = {s: sum(1 for r in results if r["status"] == s) for s in ("ok", "unchanged", "failed")}
return {"action": action, "requested": len(results), **counts, "results": results}
@app.post("/api/auth/bulk-users/active")
def bulk_set_active(body: BulkActiveIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
def apply(u):
if bool(u.is_active) == bool(body.is_active):
return "unchanged"
apply_user_active(db, actor, u, body.is_active)
return "ok"
return run_bulk(db, actor, body.user_ids, "enable" if body.is_active else "disable", apply)
@app.post("/api/auth/bulk-users/role")
def bulk_set_role(body: BulkRoleIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
allowed = grantable_roles(actor)
if body.role not in allowed:
raise HTTPException(status_code=400, detail=f"role must be one of {', '.join(allowed)}")
def apply(u):
# Compared as stored: a legacy 'user' row moved to 'project_user' is a real
# change of the stored value, so it is applied and audited, as one at a time.
if u.role == body.role:
return "unchanged"
apply_user_role(db, actor, u, body.role)
return "ok"
return run_bulk(db, actor, body.user_ids, "role", apply)
@app.post("/api/auth/bulk-users/projects")
def bulk_set_project(body: BulkProjectIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
"""Add every listed account to one project (with a per-project role), or remove
them from it. Implemented as the single route's replace of the caller's slice,
computed per user, so the audit row is the same shape the dialog writes."""
if body.op not in ("add", "remove"):
raise HTTPException(status_code=400, detail="op must be 'add' or 'remove'")
check_id(body.project_id)
if not db.get(models.Project, body.project_id):
raise HTTPException(status_code=404, detail="Project not found")
managed = managed_project_ids(db, actor)
if managed is not None and body.project_id not in managed:
raise HTTPException(status_code=403, detail="You don't administer the users of that project")
role = (body.role or "").strip()
if body.op == "add" and role and role not in project_scoped_grantable(actor):
raise HTTPException(
status_code=400,
detail=f"role must be '' (inherit) or one of {', '.join(project_scoped_grantable(actor))}")
pid = body.project_id
def apply(u):
mine = [m for m in db.scalars(select(models.ProjectMember)
.where(models.ProjectMember.user_id == u.id)).all()
if managed is None or m.project_id in managed]
current = {m.project_id: (m.role or "") for m in mine}
if body.op == "add":
if current.get(pid) == role:
return "unchanged"
current[pid] = role
else:
if pid not in current:
return "unchanged"
current.pop(pid)
# Roles on the caller's OTHER projects are carried over exactly as stored -
# adding someone to one job must never reset their role on another.
apply_user_projects(db, actor, u, managed, set(current),
{p: r for p, r in current.items() if r})
return "ok"
return run_bulk(db, actor, body.user_ids, "project_" + body.op, apply)
class BulkResolveIn(BaseModel):
text: str = Field(default="", max_length=200_000)
_CSV_HEADER_WORDS = ("username", "user", "login", "email", "user name")
@app.post("/api/auth/bulk-users/resolve")
def bulk_resolve(body: BulkResolveIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
"""CR-020 (T12.4): turn an uploaded list of usernames into the account ids a
bulk action will run on - a second way IN to the same four bulk routes, not a
third copy of their rules. The CSV holds usernames only (decided 2026-10-06);
the action is chosen in the console and applies to every accepted row.
Validate and report, the CR-005 pattern: every line is either accepted or
rejected WITH ITS LINE NUMBER and a reason - never silently skipped. A line is
rejected when it names nobody this caller can see (the same 'not found' a
hidden account gets everywhere else), an account they may not change (with
the same reason the single route would give), their own account, or a
username already listed on an earlier line. Nothing is changed here; the
bulk route the console calls next re-checks every row anyway."""
rows = []
seen: dict[str, int] = {}
visible = visible_user_ids(db, actor)
cache: dict = {}
for line_no, raw in enumerate((body.text or "").splitlines(), start=1):
line = raw.strip().lstrip("")
if not line:
continue
cell = re.split(r"[,;\t]", line, maxsplit=1)[0].strip().strip('"').strip()
if not cell:
rows.append({"line": line_no, "text": line[:120], "status": "rejected",
"reason": "no username in the first column"})
continue
if line_no == 1 and cell.lower() in _CSV_HEADER_WORDS:
continue # header row
row = {"line": line_no, "text": cell[:120], "status": "rejected", "reason": "",
"user_id": None, "username": ""}
if any(ord(ch) < 32 for ch in cell) or len(cell) > 120:
row["reason"] = "not a valid username"
rows.append(row)
continue
key = cell.lower()
if key in seen:
row["reason"] = f"duplicate of line {seen[key]}"
rows.append(row)
continue
seen[key] = line_no
u = db.scalars(select(models.User).where(func.lower(models.User.username) == key)).first()
if u is None:
# An offboarding list usually carries email addresses. Accepted only
# when exactly one account has that address, so a shared or reused
# address can never pick the wrong person.
by_mail = db.scalars(select(models.User).where(func.lower(models.User.email) == key)).all()
u = by_mail[0] if len(by_mail) == 1 else None
if u is None or (visible is not None and u.id not in visible):
row["reason"] = "User not found"
elif u.id == actor.id:
row["reason"] = "your own account - change it one setting at a time"
else:
problem = manage_user_problem(db, actor, u, cache)
if problem:
row["reason"] = problem
else:
row.update(status="ok", user_id=u.id, username=u.username)
rows.append(row)
accepted = [r for r in rows if r["status"] == "ok"]
return {"read": len(rows), "accepted": len(accepted), "rejected": len(rows) - len(accepted),
"user_ids": [r["user_id"] for r in accepted], "rows": rows}
@app.post("/api/auth/bulk-users/delete")
def bulk_delete(body: BulkUsersIn, actor: models.User = Depends(require_user_manager), db: Session = Depends(get_db)):
"""Hard delete, the same as DELETE /api/auth/users/{id} (decided 2026-09-17:
no soft delete invented for the bulk case). The console asks for the typed
word DELETE first; the server's guard is the per-row rules, as for one."""
def apply(u):
apply_user_delete(db, actor, u)
return "ok"
return run_bulk(db, actor, body.user_ids, "delete", apply)
# ── Projects ─────────────────────────────────────────────────────────────────
@app.post("/api/projects")
def upsert_project(body: ProjectIn, user: models.User = Depends(auth.get_current_user), db: Session = Depends(get_db)):

View File

@@ -1,10 +1,11 @@
"""Authentication for the Work Package Suite.
A self-contained username/password login. Passwords are stored only as bcrypt
hashes; a successful login 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`).
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`).
Security model:
• The real boundary is `auth_gate` (middleware in app.py): every /api/ data
@@ -17,7 +18,9 @@ Security model:
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:
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.
• admin application administrator: user administration, app settings,
and implicit access to every project.
• project_super_user
@@ -30,15 +33,13 @@ project, which lives in `User.project_role` and grants nothing:
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.
Password reset: a short-lived signed token (see `create_reset_token`) is emailed
to the account's address. It is single-use by construction — it embeds the user's
`token_version`, which is bumped when the password changes, so a used or
superseded link stops validating.
"""
import os
import secrets
@@ -46,7 +47,6 @@ import logging
from datetime import datetime, timedelta, timezone
from typing import Optional
import bcrypt
import jwt
from fastapi import Depends, HTTPException, Request, Response, status
from sqlalchemy import select, func
@@ -59,10 +59,8 @@ log = logging.getLogger("wpsuite.auth")
COOKIE_NAME = "wp_session"
JWT_ALG = "HS256"
# How long a login lasts before the user must sign in again.
# How long a session lasts before the person must sign in again.
SESSION_HOURS = int(os.getenv("AUTH_SESSION_HOURS", "12"))
# How long an emailed password-reset link stays valid.
RESET_MINUTES = int(os.getenv("AUTH_RESET_MINUTES", "60"))
# ── permissions roles ─────────────────────────────────────────────────────────
ROLE_ADMIN = "admin"
@@ -121,30 +119,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.
# Password policy (shared by the API and the CLI).
MIN_PASSWORD_LEN = int(os.getenv("AUTH_MIN_PASSWORD_LEN", "12"))
_COMMON_PASSWORDS = {
"password", "password1", "password123", "passw0rd", "12345678", "123456789",
"1234567890", "qwerty123", "letmein123", "changeme", "admin123", "welcome123",
"iloveyou1", "abc12345", "qwertyuiop",
}
def password_problem(pw: str, username: str = "", email: str = "") -> Optional[str]:
"""Return a human-readable reason the password is unacceptable, or None if OK.
Shared by the API endpoints and the CLI so the policy is enforced everywhere."""
if len(pw) < MIN_PASSWORD_LEN:
return f"Password must be at least {MIN_PASSWORD_LEN} characters."
low = pw.lower()
if username and low == username.strip().lower():
return "Password must not be the same as the username."
if email and low == email.strip().lower():
return "Password must not be the same as the email."
if low in _COMMON_PASSWORDS:
return "That password is too common — choose something less guessable."
return None
# Paths under /api that do NOT require a session (login itself, health, docs).
# Paths under /api that do NOT require a session (the Okta routes themselves, health, docs).
_EXEMPT_PREFIXES = ("/api/auth/",)
_EXEMPT_EXACT = {
"/api/health",
@@ -184,22 +159,6 @@ def _load_secret() -> str:
SECRET_KEY = _load_secret()
# ── password hashing ──────────────────────────────────────────────────────────
def hash_password(plain: str) -> str:
# bcrypt operates on at most 72 bytes; longer inputs are truncated by the
# algorithm. Encode explicitly so non-ASCII passwords hash consistently.
return bcrypt.hashpw(plain.encode("utf-8")[:72], bcrypt.gensalt()).decode("ascii")
def verify_password(plain: str, hashed: str) -> bool:
if not hashed:
return False
try:
return bcrypt.checkpw(plain.encode("utf-8")[:72], hashed.encode("ascii"))
except (ValueError, TypeError):
return False
# ── tokens ──────────────────────────────────────────────────────────────────
def create_token(user: "models.User") -> str:
now = datetime.now(timezone.utc)
@@ -221,39 +180,15 @@ def decode_token(token: str) -> Optional[dict]:
claims = jwt.decode(token, SECRET_KEY, algorithms=[JWT_ALG])
except jwt.PyJWTError:
return None
# A password-reset token must never be usable as a session cookie.
# 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.
if claims.get("typ"):
return None
return claims
def create_reset_token(user: "models.User") -> str:
"""Short-lived, single-use token for an emailed password-reset link.
Single-use falls out of `ver`: completing a reset bumps the user's
token_version, so the link (and any older link) no longer validates."""
now = datetime.now(timezone.utc)
payload = {
"typ": "pwreset",
"sub": user.id,
"ver": user.token_version or 0,
"iat": now,
"exp": now + timedelta(minutes=RESET_MINUTES),
}
return jwt.encode(payload, SECRET_KEY, algorithm=JWT_ALG)
def decode_reset_token(token: str) -> Optional[dict]:
"""Claims for a valid, unexpired reset token, else None."""
try:
claims = jwt.decode(token, SECRET_KEY, algorithms=[JWT_ALG])
except jwt.PyJWTError:
return None
if claims.get("typ") != "pwreset":
return None
return claims
# ── cookie helpers ────────────────────────────────────────────────────────────
def _is_https(request: Request) -> bool:
# Behind NGINX, TLS is terminated at the proxy and forwarded as plain HTTP,

View File

@@ -1,24 +1,28 @@
"""Command-line user management for the Work Package Suite.
Use this to create the FIRST admin account (the /api/auth/users endpoint needs an
existing admin, so you have to bootstrap one here), and for occasional account
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.
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 create-admin alice --name "Alice Smith"
python -m server.manage_users create bob --role user --name "Bob Jones"
python -m server.manage_users promote alice --role admin
python -m server.manage_users list
python -m server.manage_users reset-password alice
python -m server.manage_users disable bob
python -m server.manage_users enable bob
If --password is omitted you'll be prompted (input is hidden). Passwords must be
at least 8 characters.
"""
import argparse
import getpass
import sys
import uuid
@@ -26,53 +30,48 @@ from .db import SessionLocal, Base, engine
from . import models, auth
def _gen_id() -> str:
return f"user_{uuid.uuid4().hex[:12]}"
def _prompt_password(provided: str | None, username: str = "") -> str:
pw = provided
if not pw:
pw = getpass.getpass("New password: ")
confirm = getpass.getpass("Confirm password: ")
if pw != confirm:
sys.exit("Passwords do not match.")
problem = auth.password_problem(pw, username)
if problem:
sys.exit(problem)
return pw
def cmd_create(args, role: str | None = None) -> None:
role = role or args.role
# 'user' is the pre-roles spelling of 'project_user' and is still accepted so the
# documented one-liners keep working; anything else has to be a current role.
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)}")
pw = _prompt_password(getattr(args, "password", None), args.username)
with SessionLocal() as db:
if auth.find_user(db, args.username):
sys.exit(f"A user named '{args.username}' already exists.")
u = models.User(
id=_gen_id(),
username=args.username.strip(),
full_name=(args.name or "").strip(),
email=(args.email or "").strip(),
password_hash=auth.hash_password(pw),
role=role,
)
db.add(u)
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"Created {role}: {u.username} (id={u.id})")
print(f"{u.username} is now {auth.ROLE_LABELS.get(role, role)}.")
def cmd_list(args) -> None:
with SessionLocal() as db:
rows = db.query(models.User).order_by(models.User.username).all()
if not rows:
print("No users yet. Create one with: create-admin <username>")
print("No users yet. Accounts appear here once someone signs in through Okta.")
return
print(f"{'USERNAME':<24}{'ROLE':<20}{'ACTIVE':<8}{'NAME'}")
for u in rows:
@@ -80,17 +79,6 @@ def cmd_list(args) -> None:
f"{('yes' if u.is_active else 'no'):<8}{u.full_name}")
def cmd_reset_password(args) -> None:
pw = _prompt_password(getattr(args, "password", None), args.username)
with SessionLocal() as db:
u = auth.find_user(db, args.username)
if not u:
sys.exit(f"No user named '{args.username}'.")
u.password_hash = auth.hash_password(pw)
db.commit()
print(f"Password reset for {u.username}.")
def _set_active(username: str, active: bool) -> None:
with SessionLocal() as db:
u = auth.find_user(db, username)
@@ -108,39 +96,23 @@ def main() -> None:
p = argparse.ArgumentParser(prog="manage_users", description="Work Package Suite user management")
sub = p.add_subparsers(dest="cmd", required=True)
def add_create(name, help_):
sp = sub.add_parser(name, help=help_)
sp.add_argument("username")
sp.add_argument("--password", help="set non-interactively (otherwise prompted)")
sp.add_argument("--name", default="", help="full name")
sp.add_argument("--email", default="")
return sp
add_create("create-admin", "create an admin account")
c = add_create("create", "create an account")
c.add_argument("--role", choices=list(auth.ROLES) + ["user"], default=auth.ROLE_PROJECT_USER,
help="permissions role ('user' is the legacy name for project_user)")
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")
rp = sub.add_parser("reset-password", help="reset a user's password")
rp.add_argument("username")
rp.add_argument("--password", help="set non-interactively (otherwise prompted)")
dp = sub.add_parser("disable", help="disable an account (blocks login)")
dp = sub.add_parser("disable", help="disable an account (blocks sign-in)")
dp.add_argument("username")
ep = sub.add_parser("enable", help="re-enable an account")
ep.add_argument("username")
args = p.parse_args()
if args.cmd == "create-admin":
cmd_create(args, role="admin")
elif args.cmd == "create":
cmd_create(args)
if args.cmd == "promote":
cmd_promote(args)
elif args.cmd == "list":
cmd_list(args)
elif args.cmd == "reset-password":
cmd_reset_password(args)
elif args.cmd == "disable":
_set_active(args.username, False)
elif args.cmd == "enable":

View File

@@ -142,8 +142,10 @@ class WorkPackage(Base):
class User(Base):
"""A login account. Passwords are never stored in the clear — only a bcrypt
hash (see server/auth.py). `username` is what people sign in with.
"""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.
Two independent notions of "role", deliberately separate:
• role the PERMISSIONS role — what the account may do in the app.
@@ -159,7 +161,6 @@ class User(Base):
username: Mapped[str] = mapped_column(String(120), unique=True, index=True)
email: Mapped[str] = mapped_column(String(200), default="")
full_name: Mapped[str] = mapped_column(String(200), default="")
password_hash: Mapped[str] = mapped_column(String(200), default="")
role: Mapped[str] = mapped_column(String(20), default="project_user") # permissions role
# Job function on the project — free text, offered from a suggested list.
project_role: Mapped[str] = mapped_column(String(120), default="")

109
server/okta_auth.py Normal file
View File

@@ -0,0 +1,109 @@
"""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()

190
server/okta_fake.py Normal file
View File

@@ -0,0 +1,190 @@
"""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()

View File

@@ -17,6 +17,9 @@ 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
bcrypt==5.0.0 # password hashing
PyJWT==2.13.0 # signed session tokens
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

View File

@@ -9,15 +9,17 @@ 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 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:
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).
export WP_SEED_USER=<admin-account> # or WP_SMOKE_USER, which is reused
export WP_SEED_PASSWORD='…' # or WP_SMOKE_PASSWORD
…or pass --user / --password. Use an admin account: seeding creates a project, and
--clean deletes one, which needs Project Admin on it.
…or pass --user. 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
@@ -48,16 +50,19 @@ 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 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
# 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
BASE = ""
CTX = None
# 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
# Carries the cookie jar holding the minted session (see AUTHENTICATION above).
# 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
@@ -116,29 +121,22 @@ 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="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)")
help="existing account to sign in as (default: $WP_SEED_USER, then "
"$WP_SMOKE_USER). Use an admin account.")
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 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)
if not args.user:
return abort(
f"no credentials — {missing} not set.",
"no account — $WP_SEED_USER not set.",
" Every /api/ route except /api/health needs a session, so there is nothing\n"
" 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.")
" 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.")
# health gate
try:
@@ -148,18 +146,25 @@ def main():
if st != 200:
print(f"ABORT: /api/health returned {st}"); return 1
# 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)
# "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)
logged_in = True
print(f"Signed in as {args.user}.")

View File

@@ -6,16 +6,23 @@ 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
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:
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.
export WP_SMOKE_USER=smoketest
export WP_SMOKE_PASSWORD='…'
python3 server/smoketest.py https://wp-suite.company.local
…or pass --user / --password explicitly.
…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.
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);
@@ -24,26 +31,29 @@ AUTHENTICATION
discover it in the cleanup step.
USAGE
# Against the deployed site (through the NGINX proxy):
python3 server/smoketest.py https://wp-suite.company.local
# 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 \
# 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
# 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:
python3 server/smoketest.py https://wp-suite.company.local --insecure
# Leave the demo project in the database so you can open it in the UI:
python3 server/smoketest.py https://wp-suite.company.local --keep
python3 server/smoketest.py http://localhost:8000 --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 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.
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.
"""
import argparse
import http.cookiejar
@@ -53,6 +63,12 @@ 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 = [], []
@@ -66,19 +82,40 @@ def check(name, cond, detail=""):
BASE = ""
CTX = None
# 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.
# 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.
OPENER = None
COOKIE_JAR = None
def build_opener(ctx=None):
handlers = [urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar())]
global COOKIE_JAR
COOKIE_JAR = http.cookiejar.CookieJar()
handlers = [urllib.request.HTTPCookieProcessor(COOKIE_JAR)]
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
@@ -116,10 +153,7 @@ 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="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)")
help="existing account to sign in as (default: $WP_SMOKE_USER). Use an admin account.")
args = ap.parse_args()
BASE = args.base_url.rstrip("/")
if args.insecure:
@@ -128,17 +162,14 @@ def main():
print(f"\nWork Package Suite — API smoke test\nTarget: {BASE}\n")
# 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)
# Refuse to start without a username rather than running headlong into 401s.
if not args.user:
return abort(
f"no credentials — {missing} not set.",
"no account — $WP_SMOKE_USER not set.",
" Every /api/ route except /api/health needs a session, so there is nothing\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"
" 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"
" and deletes it again, and the delete needs Project Admin on it.")
project_id = None
@@ -157,21 +188,29 @@ 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. 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)
# 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)
logged_in = True
check("login issues a session", st == 200)
check("session cookie seeded", bool(token))
# 3) Prove the session actually travels — this is the check whose absence let
# an unauthenticated version of this script look like a broken stack.

View File

@@ -26,6 +26,7 @@ browser found, or the server would not start). 2 is distinct on purpose: "I coul
not test this" is not the same answer as "this is broken".
"""
import argparse
import json
import os
import subprocess
import sys
@@ -39,7 +40,6 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import cdp # noqa: E402
PW = "CorrectHorseBattery9"
_PASS, _FAIL = [], []
@@ -86,7 +86,7 @@ def seed(db_path):
def mk(username, role):
db.add(models.User(id="user_" + username, username=username,
email=f"{username}@example.test", full_name=username.title(),
password_hash=auth.hash_password(PW), role=role))
role=role))
mk("root", auth.ROLE_ADMIN)
mk("sue", auth.ROLE_PROJECT_SUPER) # super user on Job A
@@ -150,10 +150,29 @@ def seed(db_path):
for u in db.query(models.User).all()}
def start_server(port, db_path):
# 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.
#
# 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.
FAKE_DIRECTORY = json.dumps({
u: {"email": f"{u}@example.test", "name": u.title()}
for u in ("root", "sue", "pat", "mix", "bob", "sam", "legacy", "new")
})
def start_server(port, db_path, extra_env=None):
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)
proc = subprocess.Popen(
[sys.executable, "-m", "uvicorn", "server.app:app", "--host", "127.0.0.1",
"--port", str(port), "--log-level", "warning"],
@@ -188,9 +207,12 @@ 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")
chk("manager table renders 9 columns",
page.eval("document.querySelectorAll('#users-table thead th').length") == 9,
# 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,
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"))
@@ -218,15 +240,22 @@ 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'));")
".find(r=>r.querySelector('.me-tag'));"
"const col=n=>[...document.querySelectorAll('#users-table thead th')]"
".findIndex(h=>h.textContent.trim().toLowerCase()===n);")
def own(q):
return "(()=>{" + ROW + "if(!r)return false;const c=r.cells[3];return " + q + "})()"
return "(()=>{" + ROW + "if(!r)return false;const c=r.cells[col('permissions')];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[4].querySelector('select')})()"))
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("[...document.querySelectorAll('#users-table tbody button')]"
".find(b=>/project/i.test(b.textContent)).click()")
@@ -436,7 +465,10 @@ def main():
finally:
if args.keep_server:
print(f"\n --keep-server: still up at {base}, database at {db_path}")
print(" Sign in as root / " + PW)
# 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=/'")
else:
if server:
# Wait for it to actually exit before deleting the database out from

326
tests/bulk_users_check.py Normal file
View File

@@ -0,0 +1,326 @@
#!/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())

View File

@@ -0,0 +1,197 @@
#!/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())

View File

@@ -190,8 +190,26 @@ 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", "about:blank"],
"--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"],
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(
@@ -199,9 +217,14 @@ class Browser:
json.load(r)
return
except Exception:
if self.proc.poll() is not None:
last = f"exited rc={self.proc.returncode} without binding the port"
break
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
time.sleep(0.25)
else:
last = "never bound the debugging port"

View File

@@ -8,9 +8,17 @@ 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 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.
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.
Boots its own throwaway SQLite + uvicorn + headless browser; run it alone.
Exit 0 all passed, 1 a failure, 2 could not run.
@@ -91,31 +99,6 @@ def main():
chk("the console booted with a user table",
page.eval("!!document.querySelector('table')"))
page.eval("void resetPw('user_pat','pat')")
time.sleep(0.4)
chk("the reset prompt is the kit's modal, open, focused at the input",
page.eval("(() => { const o=document.getElementById('wp-dlg-overlay');"
" return !!o && o.classList.contains('open')"
" && document.activeElement.id==='wp-dlg-input'; })()"))
page.eval("document.getElementById('wp-dlg-input').value='short';"
"document.getElementById('wp-dlg-ok').click()")
chk("a short password is refused AT the input - dialog stays, error says why",
page.eval("(() => { const o=document.getElementById('wp-dlg-overlay');"
" return o.classList.contains('open')"
" && /12 characters/.test(document.getElementById('wp-dlg-err').textContent); })()"))
page.eval("document.getElementById('wp-dlg-input').value='CorrectHorseBattery10';"
"document.getElementById('wp-dlg-ok').click()")
time.sleep(1.2)
chk("a good answer closes the dialog and the server accepts it",
page.eval("!document.getElementById('wp-dlg-overlay').classList.contains('open')"))
chk("...announced through the kit's toast (role=status)",
page.eval("(() => { const t=document.getElementById('toast');"
" return !!t && t.getAttribute('role')==='status'"
" && /Password reset for pat/.test(t.textContent); })()"))
st, _ = api(base, "/api/auth/login", "x", "POST",
{"username": "pat", "password": "CorrectHorseBattery10"})
chk("...and the new password actually works", st == 200, st)
print("\n3. destroy needs a real yes")
page.eval("void deleteUser('user_bob','bob')")
time.sleep(0.4)
@@ -129,6 +112,33 @@ 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]))

View File

@@ -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, PW # noqa: E402
from browser_check import seed, start_server, chk, _PASS, _FAIL, _c # noqa: E402
STUB = """
window.__dialogs = [];
@@ -55,8 +55,7 @@ def seed_empty(db_path):
Base.metadata.create_all(bind=engine)
with SessionLocal() as db:
db.add(models.User(id="user_new", username="new", email="new@example.test",
full_name="New Starter", password_hash=auth.hash_password(PW),
role=auth.ROLE_ADMIN))
full_name="New Starter", role=auth.ROLE_ADMIN))
db.commit()
return {u.username: auth.create_token(u) for u in db.query(models.User).all()}

327
tests/okta_auth_check.py Normal file
View File

@@ -0,0 +1,327 @@
#!/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("&amp;", "&")
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("&amp;", "&"))
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("&amp;", "&").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)

View File

@@ -33,7 +33,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, PW # noqa: E402
from browser_check import seed, start_server, chk, _PASS, _FAIL, _c # noqa: E402
READY = "!!document.querySelector('#pipeline-strip .pipe-cell, #pipeline-strip .pipe-empty, " \
"#pipeline-strip .pipe-error')"

View File

@@ -47,7 +47,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, PW # noqa: E402,F401
from browser_check import seed, start_server # noqa: E402
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
HTML = os.path.join(ROOT, "html")

View File

@@ -7,7 +7,13 @@ the suite, so no work package had an address. This checks the promise those emai
will rest on.
1. a URL identifying a work package opens that work package
2. the same URL works for a SIGNED-OUT user, via login, landing on the target
2. the same URL works for a SIGNED-OUT user, via the real Okta sign-in round
trip (T10.7's fake provider stands in for Okta itself — see
server/okta_fake.py — but the app's own login.html, the redirect to
/api/auth/okta/login, the state round trip through SessionMiddleware, and
okta_callback()'s handling of ?next= are all real, unmodified code).
Landing on the requested target, not the home page, doubles as setup for
scenarios 3-6 below.
3. refresh preserves project, package, tab and view
4. Back and Forward move through states without a reload or a broken view
5. the URL survives being copied to a second browsing context
@@ -27,7 +33,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, PW # noqa: E402
from browser_check import seed, start_server, chk, _PASS, _FAIL, _c # noqa: E402
def settle(page, seconds=1.4):
@@ -168,7 +174,7 @@ def main():
finally:
page2.close()
print("\n2. the same URL works for a signed-out user, via login")
print("\n2. the same URL works for a signed-out user, via the real Okta round trip")
page.clear_cookies()
page.goto(deep)
settle(page, 1.6)
@@ -177,19 +183,44 @@ def main():
nxt = page.eval("new URLSearchParams(location.search).get('next')||''")
chk("...carrying the requested target, package id and all",
"wp-creation-index.html" in nxt and "wp=wpA1" in nxt, "next=%r" % nxt)
page.eval("document.getElementById('username').value=%r" % "root")
page.eval("document.getElementById('password').value=%r" % PW)
page.eval("document.querySelector('form').requestSubmit"
"? document.querySelector('form').requestSubmit()"
": document.querySelector('form').submit()")
for _ in range(40):
if "wp-creation-index.html" in page.eval("location.href"):
# Drive the actual button, not a shortcut to it — its href already
# carries ?next= (login.js's safeNext()); this is the same click a
# person makes.
signin_href = page.eval(
"(document.getElementById('okta-signin')||{}).getAttribute('href')||''")
chk("the sign-in link itself carries ?next=", "next=" in signin_href, signin_href)
page.goto(base + signin_href)
for _ in range(30):
if "_fake_provider" in page.eval("location.href"):
break
time.sleep(0.3)
settle(page, 1.2)
chk("the app hands off to the (fake) Okta provider",
"_fake_provider" in page.eval("location.href"), page.eval("location.href"))
# The fake provider's own picker page — a real page, not a shortcut.
# See server/okta_fake.py: only the network-touching Authlib calls are
# faked, not app.py's own login/callback/JIT/guard code.
identity_href = page.eval(
"(document.getElementById('okta-fake-identity-root')||{}).getAttribute('href')||''")
chk("the fake provider offers the seeded 'root' identity", bool(identity_href),
page.eval("document.body.innerHTML"))
page.goto(base + identity_href)
for _ in range(30):
href = page.eval("location.href")
if "login.html" not in href and "_fake_provider" not in href:
break
time.sleep(0.3)
settle(page, 1.0)
# NOT `"wp-creation-index.html" in location.href` alone — that string
# is in the ?next= parameter too, so this would pass while still
# sitting on login.html with the sign-in rejected (the same mistake
# D13/T10.7's LDAP predecessor caught and fixed here). Assert we
# actually LEFT the login page.
href = page.eval("location.href")
chk("signing in continues to the requested page, not the home page",
"wp-creation-index.html" in page.eval("location.href"),
page.eval("location.href"))
"login.html" not in href and "wp-creation-index.html" in href
and "wp=wpA1" in href, href)
for _ in range(30):
if page.eval("!!window.wpCreatorReady"):
break