docs(auth-model): explain authn model

1. Identity model — email is the identity, three optional credential slots (username, password_hash, oidc_subject), the @-in-username ban that makes namespaces provably disjoint.
  2. Login dispatcher — @-in-input decides the path. Single DB lookup.
  3. Login paths — four ways in (username+password, email+password, email+magic-link, OIDC redirect) with their pre-conditions.
  4. Magic-link eligibility ladder — the three-branch table with OIDC unconditional reject, password flag-gated, no-credential allowed.
  5. Registration paths — four ways (/api/auth/register with full creds, email-only, grant-by-email invitation, OIDC JIT).
  6. Anti-enumeration — per-endpoint table showing what each surface returns and why; explicit note that instance-wide policy stays visible.
  7. Security trade-offs — mailbox-as-bypass (lenient vs strict), no native MFA, magic-link as bearer token, enumeration via timing.
  8. Rate limits — the five caps from PR 12 + classic auth, with env knobs.
  9. Audit events — table of 12 event names with reason keys; every entry verified grep-able in src/.
  10. Migration path — what existing instances see when PR 16-20 land (forward-only, non-destructive).
  11. Future direction — login_strategy — the seven-row matrix sketch as the explicit-policy north star.
  12. Out of scope — TOTP/WebAuthn, external→internal promotion, session_kind, differentiated session TTL, OCM, email-verified gates (PR 23), device-bound tokens (PR 22), anti-enum timing parity, per-user opt-out, login_strategy implementation.
  13. Related documents — cross-refs to magic-link-auth, ReBAC, share-integration, env-vars.

docs/.vitepress/config.mts

@@ -116,6 +116,7 @@ export default defineConfig({
             { text: "File and Blob lifecycle", link: "/architecture/file-and-blob-lifecycle" },
             { text: "ReBAC & Authorization", link: "/architecture/rebac-authorization" },
             { text: "User lifecycle", link: "/architecture/user-lifecycle" },
+            { text: "Authentication model", link: "/architecture/auth-model" },
             { text: "Magic-link auth", link: "/architecture/magic-link-auth" },
           ],
         },