# src/lib/ — AGENTS.md

Server-side business logic, configuration loaders, and utilities.

## Key subdirectories

- `auth/` — Core auth logic: `hazo_get_auth.server.ts` (the main auth utility), session token validation, OAuth helpers, auth cache, scope cache, rate limiter.
- `config/` — Config loaders: `config_loader.server.ts` (hazo_config-based, handles all 18+ INI sections), `hazo_auth_core_config.ts` (hazo_core loadConfig overlay for critical sections with Zod validation).
- `services/` — Business logic: `login_service.ts`, `registration_service.ts`, `password_reset_service.ts`, `session_token_service.ts`, `scope_service.ts`, `invitation_service.ts`, `email_service.ts`, etc.
- `auto_test/` — hazo_auth's internal test runner (server-side). This is the original test infrastructure that inspired `hazo_ui/test-harness`. Executes scenario definitions via API calls; the runner is invoked through `/api/hazo_auth/auto_test`.
- `utils/` — Utilities: `api_route_helpers.ts` (re-exports `get_filename`/`get_line_number` from hazo_logs), `sanitize_error_for_user.ts`.
- `legal/` — Legal docs management (acceptance tracking, versioned docs).
- `schema/` — Zod schemas for request validation.

## Error handling (Wave 2)

Server-side `throw new Error(...)` replaced with `HazoError` subclasses from `hazo_core`:
- `HazoAuthError(HAZO_AUTH_FORBIDDEN)` — authentication required or permission denied
- `HazoAuthError(HAZO_AUTH_INVALID_TOKEN)` — invalid session token
- `HazoNotFoundError(HAZO_AUTH_USER_NOT_FOUND)` — user not found
- `HazoRateLimitError(HAZO_AUTH_RATE_LIMITED)` — rate limit exceeded
- `HazoConfigError(HAZO_AUTH_CONFIG)` — missing/invalid config or env vars

## Logging

All logging via `create_app_logger()` from `app_logger.ts`, which returns `createLogger('hazo_auth')` from `hazo_core`. Log calls use structured format: `logger.info('event.name', { fields })`.
