user auth documentation changes

2026-05-27 09:12:45 -05:00
parent 97be2d2908
commit 08401afd28
4 changed files with 116 additions and 31 deletions
@@ -9,7 +9,7 @@
      html, body { margin: 0; padding: 0; height: 100%; }
      #root { height: 100%; }
    </style>
-    <script type="module" crossorigin src="/assets/index-CkShUZiL.js"></script>
+    <script type="module" crossorigin src="/assets/index-C1XYfYmx.js"></script>
    <link rel="stylesheet" crossorigin href="/assets/index-BoQf6yV_.css">
  </head>
  <body>
@@ -83,6 +83,33 @@ Internal tool for CPAS violation documentation, workforce standing management, a

 ---

+## Authentication & User Accounts
+
+The application is protected by a login screen. Every page and every API action requires a valid signed-in session — unauthenticated visitors cannot view or edit any CPAS data.
+
+### Signing in
+
+Open the app and enter your username and password in the login popup. A session lasts **7 days**, after which you'll be asked to sign in again. Use the **Logout** button in the top-right of the nav bar to end your session immediately.
+
+### The bootstrap admin
+
+A single admin account is created automatically from the container's environment variables (\`ADMIN_USERNAME\` / \`ADMIN_PASSWORD\`). Notes:
+
+- Its password is **owned by the Docker environment** — it re-syncs on every container start. To rotate it, change \`ADMIN_PASSWORD\` in the container settings and restart. It cannot be changed from the UI (a UI change would be overwritten on the next restart).
+- Set a strong \`ADMIN_PASSWORD\` at deploy time. The image ships with a placeholder default that must be overridden.
+
+### Managing users (admin only)
+
+Admins see a **Users** button in the nav bar that opens the user-management panel. From there you can:
+
+- **Add a user** — username, password (min 6 characters), and a role of **User** or **Admin**.
+- **Reset a password** for any account.
+- **Delete a user** — they lose access immediately. You cannot delete your own account.
+
+Roles: **Admin** can manage users plus everything a User can do; **User** can view and edit CPAS data but cannot manage accounts. Login attempts and all account changes are written to the audit log.
+
+---
+
 ## How Scoring Works

 Every violation carries a **point value** set at the time of submission. Points count toward an employee's score only within a **rolling 90-day window** — once a violation is older than 90 days it automatically drops off and the score recalculates.
@@ -264,6 +291,7 @@ Toasts auto-dismiss after a few seconds (errors persist longer). Each toast has
 - Acknowledgment signature field — employee name + date on form and PDF
 - Toast notification system — global feedback for all user actions
 - Backfill Snapshots — per-employee repair tool that rebuilds the prior-points snapshot on every violation when older PDFs drift from current data
+- Authentication — login screen gating all routes, env-bootstrapped admin account, and admin-managed user accounts with admin/user roles

 ---

@@ -272,7 +300,7 @@ Toasts auto-dismiss after a few seconds (errors persist longer). Each toast has
 These are well-scoped additions that fit the current architecture without major changes.

 - **CSV export** — one endpoint returning violations or dashboard data as a downloadable CSV for payroll or external reporting.
- **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments without requiring full auth.
+- **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments.

 ---

@@ -291,7 +319,7 @@ Larger features that require more design work or infrastructure.

 These require meaningful infrastructure additions and should be evaluated against actual operational need before committing.

- **Multi-user auth** — role-based login (admin, supervisor, read-only). Currently the app assumes a trusted internal network with no authentication layer.
+- **Expanded roles** — finer-grained permissions beyond the current admin/user split (e.g. supervisor-scoped or read-only roles).
 - **Tier escalation alerts** — email or in-app notification when an employee crosses into Tier 2+, automatically routed to their supervisor.
 - **Scheduled digest** — weekly email summary to supervisors showing their employees' current standings and any approaching thresholds.
 - **Automated DB backup** — scheduled snapshot of the database to a mounted backup volume or remote destination.