Auth Module

The auth module owns every touch point around user identity: registration, login, and session lifecycle. When you need to change how accounts are created, how tokens are minted or validated, or how third‑party logins work, this is the place to start.

Overview

• Config (config.rs) – Centralizes runtime configuration for email rules, JWT token parameters, and OAuth providers. Look here when wiring new environment variables or tuning token TTLs.
• Entities (entities/) – Typed models for Redis and database records used during authentication, such as session IDs and magic links. Extending persistence schemas happens here.
• Services (services/) – Stateless services that implement registration flows, session issuance, and password utilities. Application code should depend on these instead of hand‑rolling auth logic.
• RPC (rpc/) – Public gRPC/HTTP endpoints that expose authentication capabilities to other services. If you are adding a new feature, start by defining or updating the RPCs.
• OAuth (oauth/) – Provider integrations, OpenID helpers, and challenge storage. Any new provider or OpenID tweak belongs here.
• Cron (cron.rs) – Housekeeping jobs that prune expired challenges, OTPs, and sessions. Whenever you add a new time‑bound artifact, ensure a cleanup job exists.
• Hooks & Events (hooks/, events/) – Event emission and subscriber glue for cross‑module reactions (e.g., notifying other modules about new signups).
• Password (password.rs) – Hashing strategy and password policy helpers. Adjust this when requirements change.

Typical Extension Workflow

1. Start with configuration – Introduce config structs or fields in config.rs, then surface them through ConfigProvider so deployments can set them.
2. Update domain logic – Modify the relevant service in services/ to implement the new behaviour. Use existing entity types or create new ones inside entities/.
3. Expose interfaces – Adjust RPC handlers under rpc/ (and optionally events/ or hooks/) so callers can access the new functionality.
4. Keep maintenance in mind – Schedule cleanups in cron.rs and emit events where downstream consumers expect them.

Usage Notes

• Always reuse the JWT helpers in config::JwtConfig when issuing tokens so validation rules stay consistent.
• When introducing a new OAuth provider, add its configuration to config.rs, implement the client under oauth/, and register it through the provider registry.
• Prefer high‑level service APIs for authentication operations inside other modules; they encapsulate hashing, validation, and side effects.
• Tests live under modules/auth/tests/. Mirror the high‑level flows there to keep regressions visible.

Keep this document in sync with structural changes so future maintainers know where to find the pieces they need.