The first OIDC login AFTER app_config.setup_complete='true' claims the single unclaimed local user (oidc_iss IS NULL AND claimed=false), populating oidc_iss/oidc_sub and setting claimed=true
The claimed user keeps its is_admin and credential — no new admin row is created
The claim NEVER keys on email — match is by oidc_iss IS NULL AND claimed=false only (D-10)
Existing OIDC users (claimed=true from the Plan-01 backfill) are matched by identity as before and never re-claimed
When setup_complete is not yet true (or no unclaimed user exists), upsertUser falls through to the normal new-user insert path
path
provides
contains
apps/api/src/auth/user.ts
upsertUser with the first-login-claims branch (repurposed first-login-wins)
Rework `upsertUser` in `apps/api/src/auth/user.ts` to implement first-login-claims (D-08): the first
OIDC login after `app_config.setup_complete='true'` claims the single unclaimed pre-OIDC local user
(provisioned by the wizard in Plan 02) instead of minting a fresh admin. This repurposes the Phase 10
first-login-wins bootstrap — the WR-01 rework the code comment at user.ts l.114 explicitly defers to
Phase 12. TDD plan: claim behavior tests are written before/with the logic change.
Purpose: Without this, the wizard-created local user (oidc_iss NULL, is_admin=true, holding the
validated credential) would be orphaned and the first OIDC login would create a second admin. SETUP-01's
"first run → guided bootstrap" only closes the loop once the operator's OIDC identity adopts that local user.
Output: A claim-aware upsertUser that preserves the identity model (no email keying) and the credential + admin status.
upsertUser first-login-claims branch in apps/api/src/auth/user.ts:
reads app_config.setup_complete
when true, claims the unclaimed local user (WHERE oidc_iss IS NULL AND claimed=false LIMIT 1), sets oidc_iss/oidc_sub/claimed=true, preserves is_admin + credential
shouldBeAdmin for the normal insert path becomes setup_complete !== 'true' && admin count === 0
apps/api/tests/auth/user.test.ts — D-08 claim test cases (turning the Plan-01 scaffolds green)
Task 1: First-login-claims branch in upsertUser (D-08)
apps/api/src/auth/user.ts, apps/api/tests/auth/user.test.ts
- apps/api/src/auth/user.ts (the file being modified — identity lookup l.76-97, first-login-wins block l.112-123, insert path l.125-141)
- apps/api/tests/auth/user.test.ts (existing upsertUser tests + the Plan-01 D-08 scaffold)
- .planning/phases/12-initial-setup-wizard/12-PATTERNS.md §auth/user.ts (the exact replacement pattern, import additions, claim query)
- .planning/phases/12-initial-setup-wizard/12-RESEARCH.md §Pattern 4 + Pitfall 4 (no email keying) + §Migration backfill (claimed=true for existing OIDC users)
- Existing identity match (oidc_iss+oidc_sub present) → returns/updates that row as today (unchanged); never re-claims
- setup_complete='true' AND an unclaimed user exists (oidc_iss IS NULL AND claimed=false) → claim it: set oidc_iss, oidc_sub, claimed=true, keep is_admin; return the claimed row
- setup_complete='true' AND no unclaimed user → normal insert path, NOT auto-admin (an admin already exists from the claim model)
- setup_complete !== 'true' → existing first-login-wins behavior preserved (shouldBeAdmin = admin count === 0)
- Claim query uses isNull(users.oidcIss) AND eq(users.claimed,false) — asserts NO claims.email / no email column lookup
Per PATTERNS.md §auth/user.ts: add `isNull` to the drizzle-orm import and `appConfig` to the
schema import. After the existing identity lookup (step 1, l.76-97) and before the insert (step 4),
read `app_config.setup_complete`. If its value === 'true', select the single unclaimed user
`WHERE isNull(users.oidcIss) AND eq(users.claimed, false) LIMIT 1`; if found, `db.update(users).set({
oidcIss, oidcSub, claimed: true, displayName: displayName ?? unclaimed.displayName }).where(eq(
users.id, unclaimed.id))` and return `{ ...unclaimed, oidcIss, oidcSub, claimed: true }` (is_admin
preserved — not overwritten). Replace the `shouldBeAdmin = Number(count) === 0` line with
`shouldBeAdmin = flagRow?.value !== 'true' && Number(count) === 0` so the normal insert path no
longer self-promotes once setup is complete. MUST NOT introduce any email-keyed matching (D-10 /
Pitfall 4). Turn the Plan-01 D-08 scaffolds GREEN and add: claim success (fields + is_admin
preserved), no-double-claim (a claimed user is not re-claimed), no-email-key (assert the query path
references no email), and the setup_complete-false fallthrough.
- source: `grep -c "isNull(users.oidcIss)" apps/api/src/auth/user.ts` returns >= 1
- source: claim path reads setup_complete (`grep -c "setup_complete" apps/api/src/auth/user.ts` >= 1)
- source: NO email keying in the claim — `grep -Ec "claims\.email|users\.email|eq\(.*email" apps/api/src/auth/user.ts` returns 0
- source: shouldBeAdmin gated on setup_complete (`grep -Ec "value !== 'true'.*count|flagRow.*shouldBeAdmin|shouldBeAdmin =.*!= 'true'" apps/api/src/auth/user.ts` >= 1)
- source: the claim sets claimed=true (`grep -c "claimed: true" apps/api/src/auth/user.ts` >= 1)
- test: user.test.ts D-08 cases pass (claim success/admin-preserved, no-double-claim, fallthrough)
cd apps/api && pnpm test -- user && pnpm typecheck
upsertUser claims the unclaimed local user after setup_complete, preserves is_admin, never keys on email, and falls through correctly when setup is incomplete; user.test.ts green.
<threat_model>
Trust Boundaries
Boundary
Description
Authelia OIDC callback → upsertUser
claims supplied by the IdP drive the claim/merge of a pre-existing local user
STRIDE Threat Register
Threat ID
Category
Component
Disposition
Mitigation Plan
T-12-10
Spoofing
first-login-claims claiming the wrong user
accept
Claim query is oidc_iss IS NULL AND claimed=false LIMIT 1; exactly one pending user exists in a 2-person household; OIDC reach requires Authelia household membership (documented claim-window assumption, D-08)
T-12-11
Elevation of Privilege
unexpected auto-admin after setup
mitigate
shouldBeAdmin gated to setup_complete !== 'true' — once setup completes, new logins do not self-promote; admin comes only from the claimed local user
T-12-12
Tampering
email-keyed identity coupling
mitigate
Acceptance gate forbids claims.email/users.email lookups (D-10 / Pitfall 4); match is identity-null + claimed-false only
T-12-SC
Tampering
npm/pip/cargo installs
accept
Zero new packages this plan — no legitimacy checkpoint needed
</threat_model>
- `pnpm --filter @familysync/api test -- user` green (claim, no-double-claim, no-email-key, fallthrough)
- `cd apps/api && pnpm typecheck` green
- Source greps: isNull(users.oidcIss) present; no email keying; shouldBeAdmin gated on setup_complete
<success_criteria>
D-08 first-login-claims: first OIDC login after setup_complete claims the unclaimed local user, preserving is_admin + credential
No email coupling; existing OIDC users (backfilled claimed=true) never re-claimed
Normal insert path no longer auto-promotes admin once setup is complete
</success_criteria>
Create `.planning/phases/12-initial-setup-wizard/12-03-SUMMARY.md` when done
