# principal — Auth/RBAC + Token page + Filtered Excel export

**Date:** 2026-08-27
**Request:** (1) Users with roles to log into the portal; (2) an API-token creation page;
(3) save tickets to Excel honoring the active filters.

## 1. Roles & capability model

Internal role keys (hierarchy `viewer < pm < lead < admin`), display labels:

| key | label | Tasks (board/tickets/closed) | Reports (stats/insights) | Add users | API tokens |
|---|---|:--:|:--:|:--:|:--:|
| `viewer` | Viewer | ✓ | — | — | — |
| `pm` | PM | ✓ | ✓ | — | — |
| `lead` | Project Leadership | ✓ | ✓ | ✓ | — |
| `admin` | Admin | ✓ | ✓ | ✓ | ✓ |

- `/api/config` + `/api/stats` stay viewer-accessible (board needs colours/colleagues/counts).
- `/api/sync` stays token-only (extension), unchanged.
- Server enforces per-route via `requireRole(min)`; client hides nav/pages a role can't use
  (defense-in-depth; the server is the gate).
- Seeded `AUTH_USER` account is forced to role `admin` (bootstrap).

## 2. Route → minimum role

| Route | Min role |
|---|---|
| `GET /api/tickets`, `/api/tickets/:number`, `/api/stats`, `/api/config` | viewer |
| `GET /api/analytics/*`, `/api/insights` | pm |
| `GET/POST /api/users` (list/create) | lead |
| `GET/POST /api/tokens` (list/create) | admin |

## 3. Token page
Admin-only page: list existing tokens (label, id, created, last-used, expiry, revoked) +
create (returns the raw `fg_…` once) + revoke. Replaces the `x-admin-key` HTTP gate with the
admin session role; the `mint-token` CLI stays.

## 4. Filtered Excel export
Board/tickets "Export Excel" button → exports the CURRENTLY FILTERED rows client-side via
`write-excel-file` (the Husky template's dep). Columns: Number, State, Assignee, Group, Brand,
Market, Requester, Lifetime(d), Days-in-state, Last activity, Jira status, Cost, Link.

## Plan / routing
- dba/engineer — `app_users.role` (additive), user CRUD, `requireRole`, route gating.
- security — audit the authz before merge (public domain).
- engineer — Admin page (Users + Tokens tabs), export util, role-gated nav.
- verifier — gate the result.

## Next
engineer — implement server RBAC + user/token endpoints, then the client Admin page + export.