Wave 10: task breakdown for the Okta OIDC build

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/waves/decisions-2026-09-02.md

@@ -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.

docs/waves/wave-10.md

@@ -0,0 +1,55 @@
+# 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`, remove the
+  bcrypt-based `login()`, remove the username/password form. Real deletion, matching
+  `D15`'s "full replacement," not a toggle or a fallback.
+
+- **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).
+
+- **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.
+
+- **T10.8 — Verification.** 390px and 1440px, full suite, done-when checks per task,
+  matching the rigor D13 was held to.
+
+## Still open
+
+- The OIDC claim mapping (`T10.3`).
+- Final confirmation of the redirect/callback URI (`https://wp.controls.dev/api/auth/okta/callback`
+  proposed, pending security).
+- The `Business Technology Group` pilot assignment in Okta.