Role-gated admin surface to rotate member Fastmail app passwords and designate the shared calendar, on a new v1.1 DB foundation. 4 plans, executed as a sequential wave chain.
What shipped
10-01 — v1.1 DB foundation: additive generate+migrate migration (0001_famous_mad_thinker.sql) adding users.is_admin, member_credentials.provider_type + unique(user_id), calendar_events.reminder_lead_minutes, and an app_config table. Dev-bypass user id=1 seeded admin in e2e global-setup.
10-03 — Admin API surface (TDD):adminRouter (requireAdmin-gated) members/credential-rotation/calendars/shared-designation; member self-service POST /api/me/credential; one shared validateEncryptAndStoreCredential helper (400-no-echo, session-userId only); broker resync helpers promoted to exports.
10-04 — PWA admin surfaces: gated /admin route + conditional nav (AppNav/BottomTabBar), shared CredentialSheet, SetupBanner, e2e/admin.spec.ts. Client isAdmin is UX-only; server 403 is the boundary (D-03).
Code review + fix
Code review (10-REVIEW.md) found 1 BLOCKER (CR-01), fixed in this PR (2f347cb): PUT /api/admin/calendars/:id/shared cleared the current shared calendar then set the target in two non-transactional UPDATEs without checking the target exists — a bad/stale id silently wiped the family shared lane. Now verifies the target inside a transaction and returns 404 otherwise (regression test added, RED→GREEN).
Verification
gsd-verifier: 12/12 must-haves PASS.
Local: api 271/271, pwa unit 191/191, e2e admin.spec.ts 5/5 (desktop Chromium); typecheck (both apps) + builds clean; lint / format:check / md:lint / frozen-lockfile all green.
Live dev MariaDB confirmed to hold all v1.1 columns/table via real query (not just tsc).
Follow-ups (deferred, non-blocking)
WR-01 first-login-wins bootstrap is a non-atomic count-then-insert race — deferred to Phase 12, which reworks this bootstrap.
WR-02/api/me coalesces missing OIDC iss/sub to '' (defense-in-depth).
WR-03 the additive unique(user_id) would error 1062 on a prod env already holding duplicate credential rows (deploy-time check).
Audit gap (IN-01):apps/api/src/broker/credentialSync.ts and apps/pwa/src/components/CredentialSheet.tsx sit in a sandbox-denied dir and were not directly read in review; their encrypt-at-rest + no-echo contracts are covered by passing integration tests. Recommend a crypto re-audit with full read access.
Migration deviation (10-01): local db:migrate hit a legacy __drizzle_migrations journal-hash mismatch (local dev-DB artifact), so DDL was applied directly + the hash recorded; fresh CI DB applies 0000+0001 cleanly.
## Phase 10 — Admin Role & Settings (ADMIN-01/02/03)
Role-gated admin surface to rotate member Fastmail app passwords and designate the shared calendar, on a new v1.1 DB foundation. 4 plans, executed as a sequential wave chain.
### What shipped
- **10-01 — v1.1 DB foundation:** additive generate+migrate migration (`0001_famous_mad_thinker.sql`) adding `users.is_admin`, `member_credentials.provider_type` + `unique(user_id)`, `calendar_events.reminder_lead_minutes`, and an `app_config` table. Dev-bypass user id=1 seeded admin in e2e global-setup.
- **10-02 — Server admin primitives (TDD):** DB-backed `requireAdmin` middleware, first-login-wins `is_admin` bootstrap, `/api/me` exposing `isAdmin` + `needsProviderSetup` (dev-bypass + OIDC paths).
- **10-03 — Admin API surface (TDD):** `adminRouter` (requireAdmin-gated) members/credential-rotation/calendars/shared-designation; member self-service `POST /api/me/credential`; one shared `validateEncryptAndStoreCredential` helper (400-no-echo, session-userId only); broker resync helpers promoted to exports.
- **10-04 — PWA admin surfaces:** gated `/admin` route + conditional nav (AppNav/BottomTabBar), shared `CredentialSheet`, `SetupBanner`, `e2e/admin.spec.ts`. Client `isAdmin` is UX-only; server 403 is the boundary (D-03).
### Code review + fix
Code review (10-REVIEW.md) found **1 BLOCKER (CR-01)**, fixed in this PR (2f347cb): `PUT /api/admin/calendars/:id/shared` cleared the current shared calendar then set the target in two non-transactional UPDATEs **without checking the target exists** — a bad/stale id silently wiped the family shared lane. Now verifies the target inside a transaction and returns 404 otherwise (regression test added, RED→GREEN).
### Verification
- gsd-verifier: **12/12 must-haves PASS**.
- Local: api 271/271, pwa unit 191/191, e2e admin.spec.ts 5/5 (desktop Chromium); typecheck (both apps) + builds clean; lint / format:check / md:lint / frozen-lockfile all green.
- Live dev MariaDB confirmed to hold all v1.1 columns/table via real query (not just tsc).
### Follow-ups (deferred, non-blocking)
- **WR-01** first-login-wins bootstrap is a non-atomic count-then-insert race — deferred to Phase 12, which reworks this bootstrap.
- **WR-02** `/api/me` coalesces missing OIDC iss/sub to '' (defense-in-depth).
- **WR-03** the additive `unique(user_id)` would error 1062 on a prod env already holding duplicate credential rows (deploy-time check).
- **Audit gap (IN-01):** `apps/api/src/broker/credentialSync.ts` and `apps/pwa/src/components/CredentialSheet.tsx` sit in a sandbox-denied dir and were not directly read in review; their encrypt-at-rest + no-echo contracts are covered by passing integration tests. Recommend a crypto re-audit with full read access.
- **Migration deviation (10-01):** local `db:migrate` hit a legacy `__drizzle_migrations` journal-hash mismatch (local dev-DB artifact), so DDL was applied directly + the hash recorded; fresh CI DB applies 0000+0001 cleanly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
- Generated via drizzle-kit generate from updated schema.ts
- SQL is additive-only: CREATE TABLE app_config + ALTER TABLE ADD COLUMN (3x) + ADD CONSTRAINT UNIQUE
- Applied to live dev MariaDB via direct SQL execution (drizzle-kit migrate journal hash mismatch
with legacy migration tracking; DDL applied + hash recorded in __drizzle_migrations manually)
- Verified: MIGRATION OK via live DB SHOW COLUMNS / SHOW TABLES query
- No DROP/TRUNCATE statements in generated SQL (grep returns 0)
- INSERT INTO users (id=1, is_admin=true) ON DUPLICATE KEY UPDATE is_admin=true (idempotent)
- Supplies placeholder non-null oidc_iss='dev-bypass', oidc_sub='dev-user-1', color='#4A90D9'
- requireAdmin (Plan 02) does a DB lookup for the bypass user; without this seed it would 403
- Existing calendar/event/list seeds unchanged (INSERT IGNORE INTO calendars, Seeded Test Event)
- 403 for non-admin user (is_admin=false in DB)
- next() called for admin user (is_admin=true in DB)
- 403 when no user on context (no DB query)
- 403 when context user spoofs isAdmin=true but DB has is_admin=false (T-10-04)
- reads users.isAdmin from DB (never trusts context user's isAdmin claim)
- 403 with { error: 'Forbidden' } for non-admins and missing user
- side-effect import of devBypass.js for ContextVariableMap augmentation
- bypass path skips OIDC only, not the DB check (T-10-04/T-10-05)
- first user with zero admins → is_admin=true in INSERT values
- subsequent user with admin present → is_admin=false in INSERT values
- existing user re-upsert → is_admin unchanged (early-return path, no insert)
- update existing color tests to accommodate new 4-select flow order
- zero-admin COUNT check before INSERT: first user gets is_admin=true
- subsequent users (admin already exists) get is_admin=false
- existing-user early-return path unchanged (is_admin not modified)
- Phase-12 hook comment: tighten to first login after app_config.setup_complete
- adds 'import { sql }' from drizzle-orm
- dev-bypass path: isAdmin from DB (not hardcoded), needsProviderSetup from member_credentials
- needsProviderSetup=true when no member_credentials row exists
- needsProviderSetup=false when member_credentials row exists
- dev-bypass path: DB lookup for users.isAdmin (T-10-05 bypass skips OIDC not DB)
- OIDC path: same resolveAdminAndSetupStatus helper after upsertUser
- needsProviderSetup: true when no member_credentials row, false when one exists
- no /api/me/credential POST added here (Plan 03)
RED phase: all admin.test.ts tests fail (404 — routes/mounts not yet created).
Tests cover:
- T-10-08 Pitfall 9: 403 for non-admin on every /api/admin/* route
- T-10-09 Pitfall 7: 400 with no echoed password for all credential failure modes
(PROPFIND/auth failure, createFastmailClient throw, network error, schema mismatch)
- T-10-11: valid credential stores encrypted (AES-256-GCM), not plaintext
- ADMIN-02: PUT /api/admin/calendars/:id/shared — exclusive is_shared=1
- T-10-12 Pitfall 6: POST /api/me/credential ignores body userId, writes to session user
- D-07: non-admin member can POST /api/me/credential (no requireAdmin on self-service)
- SUMMARY.md for Plan 04 (AdminPage, CredentialSheet, SetupBanner, nav gating)
- STATE.md: plan advanced to last, progress 100%, decisions recorded
- ROADMAP.md: Phase 10 marked Complete (4/4 summaries)
PUT /api/admin/calendars/:id/shared cleared the current shared calendar then
set the target in two non-transactional UPDATEs without checking the target
exists — a bad/stale id wiped the family shared lane and still returned ok.
Verify the target inside a transaction; return 404 when absent. Adds a
regression test (RED→GREEN).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Phase 10 — Admin Role & Settings (ADMIN-01/02/03)
Role-gated admin surface to rotate member Fastmail app passwords and designate the shared calendar, on a new v1.1 DB foundation. 4 plans, executed as a sequential wave chain.
What shipped
0001_famous_mad_thinker.sql) addingusers.is_admin,member_credentials.provider_type+unique(user_id),calendar_events.reminder_lead_minutes, and anapp_configtable. Dev-bypass user id=1 seeded admin in e2e global-setup.requireAdminmiddleware, first-login-winsis_adminbootstrap,/api/meexposingisAdmin+needsProviderSetup(dev-bypass + OIDC paths).adminRouter(requireAdmin-gated) members/credential-rotation/calendars/shared-designation; member self-servicePOST /api/me/credential; one sharedvalidateEncryptAndStoreCredentialhelper (400-no-echo, session-userId only); broker resync helpers promoted to exports./adminroute + conditional nav (AppNav/BottomTabBar), sharedCredentialSheet,SetupBanner,e2e/admin.spec.ts. ClientisAdminis UX-only; server 403 is the boundary (D-03).Code review + fix
Code review (10-REVIEW.md) found 1 BLOCKER (CR-01), fixed in this PR (
2f347cb):PUT /api/admin/calendars/:id/sharedcleared the current shared calendar then set the target in two non-transactional UPDATEs without checking the target exists — a bad/stale id silently wiped the family shared lane. Now verifies the target inside a transaction and returns 404 otherwise (regression test added, RED→GREEN).Verification
Follow-ups (deferred, non-blocking)
/api/mecoalesces missing OIDC iss/sub to '' (defense-in-depth).unique(user_id)would error 1062 on a prod env already holding duplicate credential rows (deploy-time check).apps/api/src/broker/credentialSync.tsandapps/pwa/src/components/CredentialSheet.tsxsit in a sandbox-denied dir and were not directly read in review; their encrypt-at-rest + no-echo contracts are covered by passing integration tests. Recommend a crypto re-audit with full read access.db:migratehit a legacy__drizzle_migrationsjournal-hash mismatch (local dev-DB artifact), so DDL was applied directly + the hash recorded; fresh CI DB applies 0000+0001 cleanly.🤖 Generated with Claude Code
- reads users.isAdmin from DB (never trusts context user's isAdmin claim) - 403 with { error: 'Forbidden' } for non-admins and missing user - side-effect import of devBypass.js for ContextVariableMap augmentation - bypass path skips OIDC only, not the DB check (T-10-04/T-10-05)- zero-admin COUNT check before INSERT: first user gets is_admin=true - subsequent users (admin already exists) get is_admin=false - existing-user early-return path unchanged (is_admin not modified) - Phase-12 hook comment: tighten to first login after app_config.setup_complete - adds 'import { sql }' from drizzle-ormcredentialSync.ts: - validateEncryptAndStoreCredential(userId, email, appPassword, providerType) — single shared validate→encrypt→store→initial-sync path used by BOTH admin and self-service - createFastmailClient + fetchCalendars wrapped in ONE try/catch: any failure throws CredentialValidationError (routes map to { error: 'Invalid request' } 400) - appPassword never logged or echoed (T-10-10) - encryptPassword (AES-256-GCM) applied before DB write (T-10-11) - fire-and-forget initial sync via loadClientForUser + syncCalendar (Pitfall 5) admin.ts: - adminRouter.use('*', requireAdmin) FIRST (Pitfall 9 / T-10-08) - GET /members: users LEFT JOIN member_credentials → hasCredential boolean - POST /credentials: noEchoHook + validateEncryptAndStoreCredential (T-10-09) - GET /calendars: calendar list (UI-SPEC Surface 5) - PUT /calendars/:id/shared: exclusive is_shared update (ADMIN-02, D-06) index.ts: - app.route('/api/admin', adminRouter) mounted in route block me.ts: - POST /credential: member self-service, always currentUserId (Pitfall 6 / T-10-12) - meCredentialSchema (no userId field), meNoEchoHook, calls shared helper - All 17 new admin tests pass; 270 total pass; tsc --noEmit clean