Phase 5 — Accounts, Auth and Keys (`apps/dashboard-api`)
Goal: the dashboard backend:
- sign-up and sign-in with every decided method and hardening
- orgs, workspaces, members and roles
- the key lifecycle, synced to the gateway
- the read APIs the dashboard screens need
- staff accounts and read-only impersonation
Done when: in staging, a new user can sign up, get an org and a Default workspace, create a key (synced to Bifrost and shown once) and make a charged API call with it (after a hand-seeded balance; payments come in phase 6), and the auth conformance suite passes in CI.
| ID | Task | Who | Needs | Status |
|---|---|---|---|---|
| P5.01 | Better Auth: sign-up, sign-in, email | Agent | P1.02, P0.05 | todo |
| P5.02 | Two-factor, passkeys, sessions | Agent | P5.01 | todo |
| P5.03 | Session hardening and response headers | Agent | P5.01 | merged — code #44 |
| P5.04 | Orgs, workspaces, roles and permissions | Agent | P5.01 | merged — through the integration branch, code #65 (#24 closed); audit events for every org and workspace change code #75 |
| P5.05 | Invitations and members | Agent | P5.04 | merged — code #33 (invitation email sends once P0.05 gives the domain) |
| P5.06 | Consent and the content-logging setting | Agent | P5.04, P4.07 | merged — code #32 (the consent record and the content-logging setting) |
| P5.07 | Key lifecycle with gateway sync | Agent | P5.04, P0.10, P0.13 | merged — code #31, with the reviewer’s fixes (audited, race-safe lifecycle); gateway: Bifrost adapter code #71 in production, mock code #69 in staging |
| P5.08 | Usage, logs and overview read APIs | Agent | P4.01, P5.04 | merged — code #32 |
| P5.09 | Stored-content read | Agent | P5.08, P4.07 | merged — code #32 (needs the R2 CONTENT binding) |
| P5.10 | Low-balance alerts and notification settings | Agent | P5.04, P4.02 | merged — code #32, settings only; the alert job waits for P0.05 |
| P5.11 | Staff accounts and the admin route group | Agent | P5.02 | merged — code #34, code #35; exact staff credit moves code #74 |
| P5.12 | Impersonation (view as customer) | Agent | P5.11, P4.07 | merged — code #43 |
| P5.13 | Auth conformance suite in CI | Agent | P5.03, P5.12 | merged — code #44 |
P5.01 — Better Auth: sign-up, sign-in, email
Section titled “P5.01 — Better Auth: sign-up, sign-in, email”Who: Agent · Needs: P1.02, P0.05
Better Auth on Hono in apps/dashboard-api:
- Sign-in methods: email and password (with a known-breach check), Google, GitHub and GitLab.
- Account flows: email verification, password reset, and linking only on a verified email.
- Abuse protection: Turnstile on sign-up, sign-in and reset; auth rate limits stored in the database.
- Email: Resend templates for verify and reset.
- Spec: decisions log, Dashboard auth model, Login methods and Better Auth plugins, Transactional email: Resend;
../architecture/auth-security.mdsections 3 and 4 - Done when: every sign-in method works in staging, a breached password is refused, and sign-in returns one generic error for every failure.
P5.02 — Two-factor, passkeys, sessions
Section titled “P5.02 — Two-factor, passkeys, sessions”Who: Agent · Needs: P5.01
- Two-factor: an authenticator app, with backup codes.
- Passkeys.
- Sessions: list active sessions, revoke one, and log out everywhere. A password reset revokes all sessions.
- Profile: change name, and change email with re-verification of the new address (screen 29).
- Spec:
../architecture/auth-security.md3.2;../product/build-inventory.mdscreen 30 - Done when: each flow works in staging, and a reset kills existing sessions (test).
P5.03 — Session hardening and response headers
Section titled “P5.03 — Session hardening and response headers”Who: Agent · Needs: P5.01
- Cookies:
__Host-cookies per audience, or the fallback recorded in P1.01. SeparateBETTER_AUTH_SECRET_APP/_ADMIN. - CSRF: the
Origin/Sec-Fetch-Sitecheck on every non-GET. - CORS: scoped to one origin.
- Caching:
Cache-Control: no-storeandVary: Cookieon every response, plus Cloudflare cache bypass rules. - Page headers: CSP and HSTS via a Pages
_headersfile. - Spec:
../architecture/auth-security.md3.1–3.4 - Done when: the header test (conformance items 8 and 18) passes against staging, and a dashboard cookie pasted into the admin origin is refused.
P5.04 — Orgs, workspaces, roles and permissions
Section titled “P5.04 — Orgs, workspaces, roles and permissions”Who: Agent · Needs: P5.01
- On sign-up: create the org and a Default workspace, with its currency preselected from the user’s country.
- Roles: Owner, Admin and Member, checked in one place. Members see only the workspaces they’re added to; only Owners and Admins pay and transfer.
- Workspace currency: changeable until the first top-up, then fixed.
- Workspace deletion: the balance must be moved out first, and the last workspace can’t be deleted.
- Org deletion (screen 31): Owner only, after every workspace’s balance is moved out or zero; revokes the org’s keys; soft delete (
deleted_at). - Suspended org: every dashboard write is refused with a notice, and top-ups and transfers are blocked (decisions log, Org suspension).
- URLs: org and workspace ids in every route.
- Spec:
../product/build-inventory.mdFeatures;../architecture/db-schema.md4.1 - Done when: a permission test matrix (role × action) passes, a Member is refused every workspace they’re not in, and a suspended org’s members get read-only access.
P5.05 — Invitations and members
Section titled “P5.05 — Invitations and members”Who: Agent · Needs: P5.04
- Invitations: invite by email via Resend, an expiring link, resend and revoke; acceptance applies the workspaces granted in the invite.
- Members: change role, and remove a member, with a prompt to revoke or reassign their keys.
- Org: transfer ownership.
- Spec:
../product/build-inventory.mdscreens 7 and 26–28, 31;../architecture/api-key-security.mdsection 3 - Done when: the invite → accept → access flow works in staging, an expired link fails, and removing a member handles their keys.
P5.06 — Consent and the content-logging setting
Section titled “P5.06 — Consent and the content-logging setting”Who: Agent · Needs: P5.04, P4.07
- At sign-up: record the consent timestamp and terms version.
- Per workspace: a content-logging flag, on by default.
- Changes: every toggle is audit-logged, and opting out stops future capture only.
- Spec: backlog #17 Backend; decisions log, Audit trail & prompt/response retention
- Done when: an opted-out workspace writes no R2 objects (verified with P3.07), and the toggle history is in the audit log.
P5.07 — Key lifecycle with gateway sync
Section titled “P5.07 — Key lifecycle with gateway sync”Who: Agent · Needs: P5.04, P0.10, P0.13
The adapter’s create, update and delete methods, through the management binding with the Bifrost admin credential. On top of them:
- Create: a
pendingrow → a gateway credential (value encrypted intoapi_key_gateway_credentials) →active→ show the key once. Any failure rolls back both sides. - Update: caps, models, expiry, and rate limits from the org, kept in sync.
- Rotate: same row, new hash, no overlap.
- Revoke: Postgres first, then delete on the gateway with retry.
- Also: list, detail, spend against cap, and the onboarding default key.
- Spec: decisions log, API key ↔ Bifrost virtual key mapping, Key ↔ Bifrost sync and failure path, Spend cap authority, Gateway management route allow-list;
../architecture/api-key-security.mdsections 2–4 - Done when:
- every path works in staging
- a Bifrost failure mid-create shows no key and leaves no live credential
- the “virtual key alone can’t call a management route” test passes
P5.08 — Usage, logs and overview read APIs
Section titled “P5.08 — Usage, logs and overview read APIs”Who: Agent · Needs: P4.01, P5.04
Endpoints behind screens 8–11 and 19–20:
-
the balance and 24-hour spend
-
usage by model, provider, key and member, read from the rollups; never summing credits across currencies
-
logs with filters and time bounds, and the log detail
-
transactions
-
this workspace’s current rates
-
Spec:
../product/build-inventory.mdscreens 8–11, 19–20;../architecture/db-schema.md4.5 (time-bounded queries) -
Done when: every query is time-bounded and uses an index (
EXPLAINin the PR), and the “all workspaces” view never adds different currencies together.
P5.09 — Stored-content read
Section titled “P5.09 — Stored-content read”Who: Agent · Needs: P5.08, P4.07
Read a request’s stored prompt and response from R2 for customer Owners and Admins, and for staff Admins. Never Members, Support or impersonated sessions. The content.read audit event is written before the content is returned.
- Spec:
../architecture/backend-scope.mdsection 4 Stored-content read; backlog #17 Access control - Done when: a test proves each forbidden role is refused, and no audit write means no content.
P5.10 — Low-balance alerts and notification settings
Section titled “P5.10 — Low-balance alerts and notification settings”Who: Agent · Needs: P5.04, P4.02
A per-workspace threshold in credits and a recipient. A scheduled job sends the Resend low-balance email once per crossing, not on every run.
- Spec:
../product/build-inventory.mdscreen 33, Low-balance alerts - Done when: crossing the threshold in staging sends one email.
P5.11 — Staff accounts and the admin route group
Section titled “P5.11 — Staff accounts and the admin route group”Who: Agent · Needs: P5.02
- Staff identity: a staff flag, separate from org roles, with two staff roles: Admin (full) and Support (read-only plus a few actions).
- Middleware: two-factor required before any admin route works; a reason required for money and access changes.
- Session: its own admin cookie and audience.
- Spec:
../product/build-inventory.mdStaff access, Staff roles, Staff two-factor;../architecture/auth-security.mdsection 1 - Done when: a staff user without two-factor is refused every admin route, and Support is refused every write except its allowed actions.
P5.12 — Impersonation (view as customer)
Section titled “P5.12 — Impersonation (view as customer)”Who: Agent · Needs: P5.11, P4.07
- Who: staff Admin only.
- Start: a reason is required; a single-use token carries the session from
admin.toapp., with a 30-minute limit. - While active: every non-GET route and every stored-content read is rejected, and a “Viewing as” banner shows.
- Audit: start, end and every event are logged with
impersonated_by. - Spec: decisions log, Impersonation;
../architecture/db-schema.md8.2 item 1; backlog #18 Impersonation - Done when: the test proving an impersonated session can’t call any non-GET route or read content passes.
P5.13 — Auth conformance suite in CI
Section titled “P5.13 — Auth conformance suite in CI”Who: Agent · Needs: P5.03, P5.12
The remaining items of the 20-item suite not covered in P3.10, run in the PR gates and on every auth dependency bump.
- Spec:
../architecture/auth-security.mdsection 6;../architecture/cicd.mdsection 2 - Done when: all 20 items pass in CI, and the automated dependency PR runs them.