# ADR-011: Employee Authentication Uses PIN, Not Passwords or OAuth

## Status

Accepted, 2026-06-25.

## Status History

```yaml
status_history:
  - date: 2026-06-25
    status: Proposed
    changed_by: hkl
    reason: Formalising foundational auth decision in force since day one
    changed_via: adr-kit (360lm)
  - date: 2026-06-25
    status: Accepted
    changed_by: hkl
    reason: All 20 PWAs use PIN auth; no exceptions
    changed_via: adr-kit (360lm)
```

## Context

360lm is used by field workers, installation crews, and office staff — many of whom are not technically literate. The system must be usable on shared devices (Android phones passed between workers) without personal accounts or email addresses. Users range from the owner (Harish) to peons (Sachin). A traditional username+password system would require each employee to remember credentials, reset passwords via email, and manage individual accounts — none of which fits the operational context. OAuth (Google/Microsoft) would require every employee to have a personal Google/Microsoft account linked to the company, which is not the case.

## Decision

All 360lm employee-facing authentication uses a 4–6 digit numeric PIN assigned by an admin (harish/pramod) via the Admin PWA. The PIN is stored hashed in the database. Login is: select name from a list (or type employee ID) → enter PIN → session created. No email, no password, no OAuth for employee-facing PWAs.

**Decision Maker:** hkl

## Alternatives Considered

- **Username + password.** Rejected: field workers cannot reliably remember or manage passwords; no email infrastructure for resets; shared devices make password security hygiene impractical.
- **OAuth (Google/Microsoft SSO).** Rejected: requires every employee to have a personal Google/Microsoft account; adds external dependency; inappropriate for daily-wage field workers without corporate email.
- **Biometric (fingerprint/face).** Rejected: requires device-specific APIs, inconsistent across the Android device fleet; shared devices make per-user biometric enrollment impossible. // ponytail: upgrade trigger=company issues dedicated personal devices to all staff
- **QR code / NFC tap.** Rejected: requires physical token management infrastructure; adds hardware dependency for a software problem.

## Consequences

**Positive:**
- Extremely low friction — field workers can log in in under 5 seconds.
- Works on any shared Android device with no per-device setup.
- PIN reset is instant via Admin PWA (harish/pramod).
- No dependency on external auth providers.

**Negative / Trade-offs:**
- PIN is a weaker credential than a password — shoulder-surfing risk in the field.
- If a PIN is shared between employees, there is no audit trail distinguishing who acted.
- No multi-factor authentication.

**Risks and mitigations:**
- PIN brute force: mitigated by rate limiting in PostgREST + short PIN length only used for low-stakes operations; no financial transactions are PIN-gated alone.
- Shared PIN: acceptable risk for the current workforce size and operational context; admin can reassign PINs at any time.

## Related Decisions

- ADR-012 (Hub as SSO gateway) — PIN auth is mediated through hub.
- ADR-006 (verify_pin response format) — the API contract for PIN verification.

## References

- `memory/project_arch.md` — org hierarchy and roles
- `admin/index.html` — PIN assignment UI
- `hub/index.html` — PIN login flow