# Auth, Admin, And Learning Hub Logic

This doc summarizes the current auth/admin/Learning Hub responsibilities. The
source of truth is `server.js`, `src/routes/*.js`, and the focused top-level
docs.

## Auth

- Local auth uses argon2id for new password hashes and bcrypt fallback/rehash
  for legacy rows.
- Web sessions use the `ped_auth` httpOnly cookie.
- Mobile sessions use secure token storage and `Authorization: Bearer`.
- `user_sessions` is the authoritative session registry.
- OIDC uses Authorization Code + PKCE through `src/routes/oidc.js`.
- 2FA uses TOTP plus one-time backup codes.

See [`../authentication.md`](../authentication.md) for details.

## Admin Panel

Admin routes live under `/api/admin` and require admin middleware unless the
specific route is explicitly public (for example public config reads used by the
login screen). Admin responsibilities include:

- user management and role changes
- settings and feature flags
- model allowlist/defaults/custom models
- prompt overrides
- SMTP/OIDC/security settings
- health/log views
- milestone management
- admin docs browser

## Learning Hub

Learning Hub has two surfaces:

- learner/user-facing routes under `/api/learning`
- moderator/admin CMS routes under `/api/admin/learning`

Content types include articles, pearls, quizzes, and presentations. AI content
generation can use topic text, uploaded files, or connected Nextcloud/WebDAV
sources. Semantic search uses pgvector embeddings on `learning_content` when an
embedding provider is configured.

See [`../learning-hub.md`](../learning-hub.md) and
[`../embeddings-setup.md`](../embeddings-setup.md).

## Security Rules

- Never expose raw secrets in admin health/config responses.
- Keep OIDC issuer validation and SSRF protections intact.
- Keep login, password reset, 2FA, and session endpoints rate-limited.
- Treat Learning Hub uploads as untrusted input and keep file-type checks.
- Sanitize rendered Learning Hub content.

## Change Checklist

1. Check the relevant route and frontend module together.
2. Preserve role middleware order.
3. Run `node --check` on touched JS files.
4. Run `npm test`.