diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 72db5ba..12dca2f 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -404,6 +404,72 @@ Directory page — no shell access needed. unreachable for everyone, including admins, until Okta is restored — the same posture the abandoned LDAPS design took, carried forward deliberately (D16). +### Accounts the Okta sync disabled (D18) + +**Who this is for:** app admins, and project super users who manage accounts. + +When `OKTA_API_TOKEN` is set, the `api` container asks Okta every 15 minutes +(`OKTA_SYNC_INTERVAL_SECONDS`) who is still active. It **disables** a local +account when the person is missing from Okta's list, or when Okta shows the +status SUSPENDED or DEPROVISIONED. A password expiry, a lockout, or a recovery +in progress does not disable anyone. With no token set, the sync is off and the +startup log says `Okta sync DISABLED`. + +The sync only ever disables. **It never re-enables an account.** A person comes +back only when an admin enables the account by hand. + +**How to see what the sync did** + +1. Open the **Admin Console** (`admin.html`). Find the **Activity log** card. +2. Click **Refresh**. Search for `okta_sync`, or set the type to **User accounts**. +3. A row from the sync reads: Who `system:okta_sync`, Action `user deprovisioned + by sync`, Item the username, Detail `okta_status: SUSPENDED` (or `MISSING` if + the person was not in Okta's list at all). + +Only app admins see these rows. They belong to no project. + +**How to re-enable a person** + +1. **Fix the person in Okta first.** Ask the Okta admin to make the person ACTIVE + again (or to restore them, for a rehire). If you skip this step, the next sync + cycle (up to 15 minutes later) disables the account again. +2. Open the **User Directory** (`users.html`). +3. Find the person. A disabled account shows the **Enable** button on its row. + Click it. +4. The person can sign in on their next attempt. The app writes a `user enabled` + row to the Activity log under your name. + +**Who may do step 3** + +* An **app admin** may enable any account. +* A **project super user** may enable an account only if every project the person + belongs to is a project that super user administers. If the person is also on a + project that the super user does not administer, the row is read-only and shows + the reason. An app admin must make the change. +* Nobody can change their own account. + +**If no admin can sign in** (for example, a bad sync run disabled every admin), +use the shell on the host. Replace `alice` with the username: + +```bash +docker compose exec api python -m server.manage_users list +docker compose exec api python -m server.manage_users enable alice +``` + +**If the sync disabled the wrong people** + +1. Turn the sync off. Remove `OKTA_API_TOKEN` from `.env` and restart the api + (`docker compose up -d api`). The sync starts only when the token is set. +2. Find the cause before you turn it on again. The usual cause is that the Okta + profile attribute does not match `users.username`. See + `OKTA_SYNC_PROFILE_ATTRIBUTE` in `server/.env.example`. +3. Enable the people who were disabled by mistake (steps above). +4. Set the token again and restart. + +If the sync cannot reach Okta, or Okta gives an answer the sync cannot trust, the +sync changes **no** account in that cycle and writes a line to the api log: +`docker compose logs api | grep "Okta sync"`. + ## Permissions roles `User.role` is the **permissions** role; `User.project_role` is the person's **job diff --git a/docker-compose.yml b/docker-compose.yml index ac06ed1..f2d5628 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -49,6 +49,18 @@ services: # here instead, so an operator who leaves .env's copy commented out gets # the real default, not a broken one. OKTA_IDENTITY_CLAIM: ${OKTA_IDENTITY_CLAIM:-preferred_username} + # Okta deprovisioning sync (D18, wave 13). OFF until OKTA_API_TOKEN is set; the + # startup log says which. The token is a read-only Okta API token, NOT the OIDC + # client secret above. Empty values here mean "unset" to the code, so the + # ${VAR:-} form is safe for all four (unlike OKTA_IDENTITY_CLAIM above, whose + # code default only applies when the variable is absent). + # Reaching Okta needs outbound https. The `outbound` network the api service + # already joins is an ordinary bridge with a gateway, so no new network is + # needed; the host firewall must allow https to the Okta org. + OKTA_API_TOKEN: ${OKTA_API_TOKEN:-} + OKTA_ORG_URL: ${OKTA_ORG_URL:-} + OKTA_SYNC_PROFILE_ATTRIBUTE: ${OKTA_SYNC_PROFILE_ATTRIBUTE:-} + OKTA_SYNC_INTERVAL_SECONDS: ${OKTA_SYNC_INTERVAL_SECONDS:-} # 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. diff --git a/docs/reference/baseline/admin-1440.png b/docs/reference/baseline/admin-1440.png index aa3ba41..2746893 100644 Binary files a/docs/reference/baseline/admin-1440.png and b/docs/reference/baseline/admin-1440.png differ diff --git a/docs/reference/baseline/admin-390.png b/docs/reference/baseline/admin-390.png index a5d4e4c..d5c9738 100644 Binary files a/docs/reference/baseline/admin-390.png and b/docs/reference/baseline/admin-390.png differ diff --git a/docs/reference/baseline/creator-1440.png b/docs/reference/baseline/creator-1440.png index 97da56d..8b0840e 100644 Binary files a/docs/reference/baseline/creator-1440.png and b/docs/reference/baseline/creator-1440.png differ diff --git a/docs/reference/baseline/creator-390.png b/docs/reference/baseline/creator-390.png index 7f8b12a..8593b18 100644 Binary files a/docs/reference/baseline/creator-390.png and b/docs/reference/baseline/creator-390.png differ diff --git a/docs/reference/baseline/sop-1440.png b/docs/reference/baseline/sop-1440.png index 49fdcca..9127e3d 100644 Binary files a/docs/reference/baseline/sop-1440.png and b/docs/reference/baseline/sop-1440.png differ diff --git a/docs/reference/baseline/sop-390.png b/docs/reference/baseline/sop-390.png index d4adcb2..eb011d6 100644 Binary files a/docs/reference/baseline/sop-390.png and b/docs/reference/baseline/sop-390.png differ diff --git a/docs/reference/file-map.md b/docs/reference/file-map.md index 17667ab..a113866 100644 --- a/docs/reference/file-map.md +++ b/docs/reference/file-map.md @@ -283,7 +283,9 @@ python tests/triage_check.py # A6 - the sidebar answers the stand-up python tests/qa_gate_check.py # CR-014/D2/D9/D10 - QA gate + capture sink 41 checks python tests/files_check.py # CR-007/D8 - drawings upload + real offline 36 checks python tests/sticky_bar_check.py # B6 - save reachable on every wizard step 12 checks -python tests/usage_check.py # D5 - one analytics core, admin report 15 checks +# tests/usage_check.py (D5) removed at T11.6 - it tested the per-browser +# analytics core and admin report, both retired in favour of CR-019's +# server-side Activity & usage card (see docs/waves/decisions-2026-09-17.md). python tests/creator_dialogs_check.py # S1 creator - 0 natives, errors at fields 20 checks ``` diff --git a/docs/waves/backlog.md b/docs/waves/backlog.md index ddb0758..f3f0390 100644 --- a/docs/waves/backlog.md +++ b/docs/waves/backlog.md @@ -696,3 +696,124 @@ deliberately deferred. - **Suggested wave or follow-up:** wave 14, alongside T14.1's badge changes: do not show the badge on pages with nothing to sync, and keep it clear of page controls. + +<<<<<<< ours +### BL-069 - The sync has no cap on one run and no last-admin guard + +- **Found during:** T13.3 (D18) +- **Where:** `server/okta_sync.py` `run_sync()` +- **What:** a run disables every account the rules select, however many. If the + identity attribute is partly wrong (it matches some accounts and not others), + one run can disable most of the company, including every admin. The + zero-match guard only stops the case where nothing matches. Disabled accounts + cannot sign in, so re-enabling needs an admin who is still active, or the + `manage_users.py` command line on the host. +- **Why not now:** D18 does not ask for it, and the right limit is a product + call: a count, a share of accounts, a rule that the last active admin never + disables, or all three. +- **Suggested wave or follow-up:** before the first live run, or in T13.6 if + Matt decides. Needs Matt. + +======= +## Future build: mobile app and scaling + +Logged 2026-10-12 from the meeting with Nick. The answers are in +`docs/waves/decisions-2026-10-12.md` (Q2 to Q14). The path from here to a +mobile version outside the VPN, across projects, is in +`docs/waves/roadmap-mobile-scaling.md`. These are features for a future +build. They have no wave and no `CR-`/`D-` id yet. Give each one an id when a +wave is planned. Items marked "to confirm" have an open question listed in the +decision file ("Still open"). Do not build them until it is answered. + +Follow-up answers from Matt on 2026-10-12 are folded into the entries below. + +Server work is needed for BL-062 to BL-066 (CLAUDE.md, "Frontend and backend +boundary"). Do not use `localStorage` as the store of record. + +### BL-062 - Offline Field View for crews + +- **From:** Q2, Q3 +- **What:** Field View opens offline for up to **7 days** after the last sign-in + (today: 12 hours). Only crews in Field View work offline. The creator has no + offline mode. When the app opens online again and the account is disabled, + wipe that account's local data. +- **Why not now:** new scope. It needs an id, and it follows the outbox work in + wave 14 (T14.1 to T14.3). +- **Suggested wave or follow-up:** future mobile wave. Check it against the D18 + session rules (idle timeout, absolute ceiling): a 7 day offline window and a + session ceiling must agree on what "signed in" means. + +### BL-063 - Offline edit conflicts: merge, notify, log + +- **From:** Q4 +- **What:** When an offline edit meets a newer server version, the app merges + the two, shows a notification to the crew, writes a log entry, and updates the + owner. If both sides changed the same field, **the field value wins**, and the + app keeps a **history of changes**. This replaces the earlier default (keep + both, crew chooses). +- **To confirm:** who "the owner" is, how long the history is kept, and who can + read it. See the decision file, "Still open" item 2. +- **Suggested wave or follow-up:** same wave as BL-062. + +### BL-064 - Field photo limits + +- **From:** Q5 +- **What:** a limit of **5 MB per photo**. This equals the D8 limit that the + server already enforces for drawings (`FILE_MAX_BYTES`), so photos can use the + same upload path and the same D19 download headers. +- **To confirm:** the count per package, and whether the app resizes a photo + before upload (phone photos are often 3 MB to 8 MB). Decision file, "Still + open" item 1. +- **Suggested wave or follow-up:** same wave as BL-062. + +### BL-065 - Batch print and merged PDF + +- **From:** Q6, Q7, Q8, Q9 +- **What:** print many packages in one PDF. + - Limit: **25 packages on phones**. On desktop the user can scale the filter + up to 50 or 100. Open: who sets the larger value (each user, or an admin + setting). Decision file, "Still open" item 5. + - Drawings go **after the form**, in **upload order**, **scaled to fit**. + - SVG drawings are **left out**. A page names each file that was left out. + - Every page shows the **package number, the print date, and page X of Y**. +- **Related:** BL-000d (merge or list attachments on export) asked the same + question for CR-008. This entry answers the layout part of it. +- **Suggested wave or follow-up:** future print wave. + +### BL-066 - Keep drawings when a package is deleted + +- **From:** Q13 +- **What:** deleting a package no longer deletes its drawings. Keep them for + data retention. **The storage quota is freed** when the package is deleted. + Storage will move to cloud storage in a future deployment. This replaces the + earlier default (delete with the package). +- **Today:** drawing bytes live in the Postgres `wp_files` table (CR-007, D8). + The 2 GB per project limit counts them. Kept files must not count toward that + limit, so the count has to change. +- **To confirm:** retention period, who can delete for good, who can recover. + See the decision file, "Still open" item 3. +- **Suggested wave or follow-up:** roadmap Phase 3 (object storage). It affects + D19 (safe download) paths too: recovered files must keep the attachment and + sandbox headers. + +### BL-067 - Ready for QA progress weight is 0.85 + +- **From:** Q12 +- **What:** change the progress weight for Ready for QA from 0 to **0.85**. + Today a package falls from 75% to 0% when it reaches Ready for QA. +- **Why not now:** it changes a shipped number on dashboards and roll-ups. Use + its own item id and re-run the roll-up checks. +- **Suggested wave or follow-up:** future wave. Small task. + +### BL-068 - One cost-code list, kept in the SOP + +- **From:** Q14 +- **What:** the creator has 38 cost codes, the SOP has 39, and 13 differ. Keep + **one list, in the SOP**, and make the creator read it. +- **Blocked on:** the correct codes. The **PM** supplies them (decided + 2026-10-12). The date is not set. This is a data question and not a code + question. +- **Related:** BL-019 (closed) made a stored code that has left the list stay + as an option. Keep that behavior when the list changes. +- **Suggested wave or follow-up:** future wave, after the codes arrive. +>>>>>>> theirs diff --git a/docs/waves/context-handoff-2026-10-12.md b/docs/waves/context-handoff-2026-10-12.md new file mode 100644 index 0000000..26c4a9c --- /dev/null +++ b/docs/waves/context-handoff-2026-10-12.md @@ -0,0 +1,97 @@ +# Context handoff: Work Package Suite + +> Update 2026-10-16: waves 11 and 13 (T13.2 to T13.5) are on the release branch `release/waves-11-13-okta-sync`, with T13.1 held back. The branch and wave status tables below describe 2026-10-12. See `docs/waves/wave-13.md` for the current state. + +Date: 2026-10-12 +Purpose: Give a new chat the facts about waves 11, 12, 13, and 16. +This file is a handoff note. It is not a spec. The spec files stay the source of truth (`IMPLEMENTATION.md`, `docs/waves/*`, `CLAUDE.md`). +It was checked against `git` on 2026-10-12. Earlier chat summaries about this repo are out of date. Use this file. + +## 1. Branch state + +| Branch | State | +|---|---| +| `main` | At `d42ae0c` (2026-10-06). Contains wave 12 (CR-020, bulk user editing) and wave 16 (D19, D20, D21), both merged by PR. | +| `feat/waves-11-13` | Local and `origin` are the same commit, `da1325c`. It is pushed. It is not merged. It is 13 commits ahead of `main` and 19 behind. | +| `notes/cr019-usage-metrics-d18-deprovisioning` | Holds the same wave 11 work plus the session notes. | + +Correction to an earlier statement: the Gitea push is no longer blocked. The branch is on `origin`. + +Merge rule from `wave-12.md`: T13.1 (idle timeout) must not reach `main` before T14.1. Do not merge `feat/waves-11-13` into `main` as a whole without a decision from the user. Wave 11 and T13.1 are on the same branch. + +Working tree on `main` (2026-10-12) has two untracked files: `WorkPackageSuite_Consolidated_Change_Request_R2.docx` and `docs/waves/decisions-2026-08-25.md`. Do not delete them. + +## 2. What is on `feat/waves-11-13` + +| Commit | Task | Item | +|---|---|---| +| `75ac930` | Planning docs for CR-019, CR-020, D18 | CR-019, CR-020, D18 | +| `0652fa7` | T11.1 UsageEvent model and migration | CR-019 | +| `850b789` | T11.2 capture usage events | CR-019 | +| `3584695`, `6cde6e3` | T13.1 idle timeout with an absolute ceiling | D18 | +| `8e863ae` | T11.3 aggregation endpoint with filters | CR-019 | +| `2de76d5` | T11.4 usage export (raw and sanitized CSV) | CR-019 | +| `a6c3fbf`, `0b5ab59` | T11.5 admin console "Activity & usage" card, checked at 390px and 1440px | CR-019 | +| `b2a083a` | T11.6 retire the per-browser Usage report | CR-019 | +| `2842ec9` | Session notes for 2026-09-23 | none | +| `4f3a94b` | T11.6 follow-up: fix `tests/autosave_check.py` | CR-019 | +| `da1325c` | T11.7 full verification pass. Wave 11 closed on 2026-09-24. | CR-019 | + +Notes: +- `html/wp-usage.js` and `tests/usage_check.py` were deleted in T11.6. The `track()` functions in `wp-creation-app.js` and `work-package-suite-app.js` are now documented no-ops. About 45 call sites stay. +- T11.7 found a real regression that T11.6 caused. `tests/autosave_check.py` still expected the retired tracker to write to `localStorage`. The test was fixed. It now passes 33 of 33. The cause was that T11.6 ran only `tests/baseline_shots.py`, not the full suite. Run the full suite for any frontend task. + +## 3. T11.7 verification results (2026-09-24) + +- Alembic: upgrade, downgrade, upgrade on SQLite passed. The SQL render for Postgres was clean (this catches SQLite-only DDL, the "BL-027 class" of defect). +- Test scripts: 38 of 39 passed after the autosave fix. +- Two known failures that are not regressions: + - `token_check.py` exits 2. This is a CLI usage detail. + - `generalinfo_check.py` finds an old color-literal gap in `wp-creation-styles.css`. + +## 4. Wave status + +| Wave | Items | Status | +|---|---|---| +| 10 | Okta OIDC sign-in (D15, D16) | Done. In production. | +| 11 | CR-019 usage and activity metrics | Done on `feat/waves-11-13`. Not on `main`. | +| 12 | CR-020 bulk user editing | Done. Merged to `main` on 2026-10-06 (T12.1 to T12.6). | +| 13 | D18 Okta/AD deprovisioning sync | T13.1 done on `feat/waves-11-13`. T13.2 and later are not started. T13.3 must fail closed. Do not relax that. | +| 14, 15 | Not checked in this handoff | T14.1 must land before T13.1 reaches `main`. Read the wave files before you plan. | +| 16 | D19 safe downloads, D20 one SOP per project, D21 session decode fails closed | Done. Merged to `main` on 2026-10-06. | + +Wave 16 decisions (`docs/waves/decisions-2026-10-02.md`): SEC-06 (session revocation) waits for the AWS work. Other SEC findings stay as backlog drafts in `docs/reference/security-review/backlog-drafts.md`. + +## 5. Rules that apply here (`CLAUDE.md`) + +- Every change traces to an item ID (`CR-`, `F`, `S`, `A`, `B`, `C`, `D`, task `T.`). New scope gets a new ID. +- One task per PR. Put the task ID and item IDs in the commit message and PR title. +- Do not fix other problems that you see. Log them in `docs/waves/backlog.md`. +- Do not reorder waves. Do not start a wave before the previous wave is merged, unless the task says it is independent. +- Server work is needed for CR-004, CR-018, CR-007, CR-011, CR-014, CR-013, and B4. Do not use `localStorage` for these. +- Do not change: Actual Hours in Closeout (CR-017), localization (A7), uppercase card headers in `console.css` (A5), the logged-override path `confirmEarlyRelease()` (A1), or hidden-not-deleted fields (CR-002, CR-016). +- Token rule: one place defines color, spacing, and type. Do not add raw hex values to page stylesheets. +- Accessibility (C1): use real `'; - }); - box.innerHTML = html; -} - // ── access control: admins only ───────────────────────────────────────────────── // auth-guard.js requires a login and sets window.WP_USER (firing 'wp-auth-ready'). // Show the console for admins; otherwise show the "Admins only" notice. diff --git a/html/auth-guard.js b/html/auth-guard.js index 6d55683..1fb3f9f 100644 --- a/html/auth-guard.js +++ b/html/auth-guard.js @@ -125,12 +125,40 @@ // Nothing replaces it. Every signed-in page mounts the drawer, so there is no page // left that would need a floating fallback pill. + // ── CR-019: usage ping ─────────────────────────────────────────────────── + // One page_open event per authenticated load, sent from exactly ONE place + // (here) rather than from each page's own script - the shared-chrome lesson + // S4 and the token-drift lesson S5 both taught this codebase the hard way. + // Fire-and-forget: never blocks reveal(), never retries, never surfaces an + // error to the person using the app - a missed usage ping is not something + // anyone here should notice happening. + var TOOL_BY_PAGE = { + 'index.html': 'launcher', + 'work-package-suite.html': 'wizard', + 'wp-creation-index.html': 'creator', + 'field.html': 'field_view', + 'admin.html': 'admin', + 'users.html': 'directory' + }; + function pingUsage() { + var page = (location.pathname.split('/').pop() || 'index.html'); + var tool = TOOL_BY_PAGE[page] || page.replace(/\.html$/, ''); + try { + fetch('/api/usage/ping', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ tool: tool }) + }).catch(function () {}); + } catch (e) {} + } + function proceed(user) { clearTimeout(safety); window.WP_USER = user; reveal(); if (window.WP_USER) { window.wpFlags(); // start the feature-flag fetch; pages await it as needed + pingUsage(); try { document.dispatchEvent(new CustomEvent('wp-auth-ready', { detail: window.WP_USER })); } catch (e) {} } } diff --git a/html/work-package-suite-app.js b/html/work-package-suite-app.js index 4829511..34af900 100644 --- a/html/work-package-suite-app.js +++ b/html/work-package-suite-app.js @@ -2207,20 +2207,18 @@ function loadStepComments(){ } } -// ── USAGE ANALYTICS ───────────────────────────────────────────────────────── -// Lightweight usage analytics stored in localStorage so the tool owner can review -// engagement over time. No field VALUES are stored (field-edit events record only -// the field id), keeping captured data non-sensitive. -// D5 / T7.10: the analytics implementation lives in wp-usage.js and the report -// on the admin console. The wizard's own copy of showAnalytics() never had a -// caller here - the button lived on the creator - and once B7 dissolved the -// frame the duplicate sat in the same document as five colliding globals. -// This page only records; dwell tracking keeps its page-local state below. +// ── USAGE ANALYTICS (retired, T11.6) ──────────────────────────────────────── +// This used to write to wp-usage.js's per-browser localStorage log (D5/T7.10), +// read back by the admin console's old "Usage logs" panel. CR-019 replaced +// both with real, server-side, per-user activity (UsageEvent + the Activity & +// usage card) - see decisions-2026-09-17.md for why this per-browser data was +// never a source the new report could adopt. track() is now a no-op; kept +// (rather than deleting its handful of call sites, including the dwell-timer +// plumbing below) so this stays a one-line change instead of touching every +// caller for the same outcome. let _stepEnter = Date.now(); -function track(event, detail){ - WPUsage.track(WPUsage.KEYS.wizard, event, detail); -} +function track(event, detail){ /* retired, T11.6 — see comment above */ } function trackStepDwell(){ const ms = Date.now() - _stepEnter; if(ms > 400 && ms < 1000*60*60) track('step_dwell', {step: currentStep, ms}); diff --git a/html/work-package-suite.html b/html/work-package-suite.html index 29146de..cbd53d1 100644 --- a/html/work-package-suite.html +++ b/html/work-package-suite.html @@ -11,7 +11,6 @@ - diff --git a/html/wp-creation-app.js b/html/wp-creation-app.js index 61c3797..40f762d 100644 --- a/html/wp-creation-app.js +++ b/html/wp-creation-app.js @@ -3993,11 +3993,17 @@ function openSopModal(){ document.getElementById('sop-modal').classList.add('open'); track('view_sop'); } function closeSopModal(){ document.getElementById('sop-modal').classList.remove('open'); } -// D5 / T7.10: the analytics implementation lives in wp-usage.js - ONE copy for -// the whole suite - and its report lives on the admin console, where an -// operator-facing readout belongs. This page only records. Same key, same -// event shape: everything recorded before the move is still readable after it. -function track(event,detail){ if(devMode) return; WPUsage.track(WPUsage.KEYS.creator, event, detail); } +// CR-019 / T11.6 (2026-09-23): this used to write to wp-usage.js's per-browser +// localStorage log (D5/T7.10). Retired along with the admin console's old +// "Usage logs" panel, its only reader - real, server-side, per-user activity +// now exists (UsageEvent, the Activity & usage card, T11.1-T11.5) and this +// data was never reliably tied to a real identity anyway, so it was not a +// source the new report could adopt (decisions-2026-09-17.md). track() stays +// as a no-op rather than deleting its ~35 call sites throughout this file: +// removing every call individually is a much larger, riskier diff for the +// same outcome, and a call site here still documents the moment worth +// recording if usage analytics are ever rebuilt server-side. +function track(event,detail){ /* retired, T11.6 — see comment above */ } // ── COMMENTS ───────────────────────────────────────────────────────────────── const COMMENTS_KEY='wp_iwp_comments_v1'; diff --git a/html/wp-creation-index.html b/html/wp-creation-index.html index 6483cbf..3da788b 100644 --- a/html/wp-creation-index.html +++ b/html/wp-creation-index.html @@ -11,7 +11,6 @@ -