# Shared-device switching (PIN)

Design decisions for children sharing a family computer/tablet — recorded
2026-09-11. Implements: multi-session cookies, `pins` collection, profile
picker, and the idle lock.

## Model

- **The PIN is NOT a login.** It selects among sessions that already exist on
  the device. A PIN alone mints nothing on a fresh device; a stolen cookie
  alone selects nothing without the PIN. Threat model: sibling mischief on a
  family device (devtools-level bypass is explicitly accepted — data is
  family-scoped and actions are reversible).
- Per-device state lives in cookies:
  - `pb_token_<userId>` — one httpOnly cookie per child with a session on
    this device (the "device is logged into both accounts" property).
  - `pb_active` — which child session is currently active.
  - `pb_token` — unchanged single session for parents (and legacy children).
    Parent login supersedes kid mode by clearing `pb_active`; a kid switch
    shadows (but does not delete) a parent session; resolving order is
    `pb_active` first, then `pb_token`.
- Sessions are never the security boundary: the OTP gate still guards each
  child's first-ever join on a device, and switching re-mints an expired token
  server-side via the derived password (never exposed to the client).

## `pins` collection

- Superuser-only rules (like `otp`); all reads/writes via server endpoints
  with session-role checks. Plaintext 3-digit PIN — deliberately recoverable
  so a parent can read it out (Q1: View, not reset). Child changes their own
  PIN in Preferences (requires current PIN).
- Fields: `famId` (rel), `userId` (rel), `pin` (text).

## Switch flow

`POST /api/switch-user { userId, pin }`:

1. Request must carry `pb_token_<userId>` (the profile must be on this
   device). No session required — the picker is reachable with no active user.
2. PIN verified server-side via superuser (children must NOT be able to read
   each other's pins, so collection rules can't be the check).
3. In-memory rate limit: 5 fails → 30s lockout per userId (3-digit space).
4. Refresh the device cookie's token; if expired, re-auth with the derived
   password (heals sessions on switch).
5. Set `pb_token_<userId>` + `pb_active`; client full-reloads to that child's
   dashboard URL (`/famSlug/handle`).

Per-profile removal: `POST /api/device/remove { userId }` — deletes that
cookie (+ `pb_active` if it was active). No session required (device-local
cookie surgery only).

## Picker

One component (`SharedPicker`) used everywhere:

- TopNav switcher button (always visible when the device has child sessions).
- Idle-lock return (overlay).
- `/{famSlug}/switch` — standalone landing when the device has child sessions
  but no active session (e.g. after per-profile logout). The fam layout
  redirects unauthenticated device requests to it. Links: "Add a child with a
  code" → `/{famSlug}/join`, "Parent login" → `/login`.

Every pick (including "resume" as the current kid) requires the PIN.

## Idle lock

- Default 10 min; parent-adjustable in Family Settings: `Off / 2 / 10`
  (`settings.lockMins`, 0 = off; `shared-device.md` settled default 10).
- Client-side only, child sessions only (parent sessions never lock).
- **Only fires when shared-computer mode is ON for the device** (see below) —
  a personal device never locks, even with lockMins set.
- `localStorage['fam_last_active']` updated on click/key/touch (throttled
  10s) and force-written on `pagehide` — survives browser close, sleep and
  restarts. Next launch compares elapsed time; past the timeout → picker.
  Live timer (15s interval) does the same mid-session.
- Resets: join wizard and picker switch write a fresh timestamp before
  navigating, so freshly-activated sessions don't instantly lock.

## Shared-computer toggle (TopNav)

- **Storage: localStorage, NOT the DB.** Shared-ness is a property of *this
  browser* — a DB flag on `fams`/`settings` would force PIN mode on every
  device including a parent's phone. `localStorage['fam_shared_device']`
  is the source of truth; a plain `fam_shared_device=1` cookie mirrors it
  so server loads see it (`data.sharedDevice`). Neither is a security
  boundary — the PIN + device session cookies remain the gate.
- **Location:** monitor icon in the TopNav (fam layout children slot, next
  to the profile switcher). Rendered for any role, even logged out —
  whoever holds the device can mark it shared. Active state: indigo fill.
- **What it gates:**
  - Profile switcher (`kid-switch`) button — only shown when shared mode
    is ON and the device holds child sessions.
  - Idle lock — only fires for child sessions on shared devices.
  - (Server `/switch` redirect unchanged — the picker is harmless on
  - non-shared devices and the server can't do better without the cookie.)
- **PIN reminders on enable** (`GET /api/pins/status`, set/unset only —
  values never leave the server except via the settings `revealPin`
  action):
  - Parent toggling sees the roster: who still needs a PIN (→ Settings →
    Members) vs who is ready (→ read the PINs out to them).
  - A child toggling sees only their own state: "remember your PIN" or
  - "ask a parent to set one up" (no PIN → picker shows "ask a parent").
- Client flag helpers: `lib/client/shared-device.ts`
  (`isSharedDevice` / `setSharedDevice`, writes the cookie mirror too).

## Join flow (child)

After OTP redeem:

1. If the device already has other child sessions → PIN setup (required).
2. Else ask "Will this computer be shared with a sibling?" — yes → PIN setup;
   no → skip (PIN can be added later in Preferences; parents can set it in
   Family Settings).
3. Land on the child's dashboard.

Parents keep the existing join (set own password, single session).

## Edge cases

- Two tabs share the timestamp → the active tab keeps the other from locking.
- Tab switches don't lock (kids alt-tab constantly).
- Expired sessions: the picker still shows the profile; switching re-mints.
- No PIN set on a profile → picker shows "ask a parent to set it up".