auth

The Auth submodule manages every phase of the user identity lifecycle: credential exchange, session token issuance, multi-factor authentication challenges, password recovery, and session termination. It is the entry point for all user-facing authentication and the guardian of every protected resource in the platform.

Login returns a short-lived JWT access token used in the Authorization: Bearer header for protected endpoints, and optionally a long-lived refresh token. The refresh token can be exchanged for a new access/refresh pair without re-authentication, enabling seamless session continuity across browser sessions and mobile apps. Logout invalidates the refresh token server-side, ensuring the session ends even if the access token has not yet expired naturally.

HedHog supports three MFA channels. TOTP works with any standards-compliant authenticator app (Google Authenticator, Authy, 1Password). Email OTP sends a six-digit code to the user's verified email address. WebAuthn uses the Web Authentication API to leverage hardware security keys, Face ID, Touch ID, or Windows Hello. When MFA is enabled, the standard login flow responds with a pending mfaToken instead of a full session — the client must submit the correct code through the matching verification endpoint to receive the final access token. Recovery codes provide a backup when the primary MFA device is unavailable.

The forgot-password flow is two-step: a time-limited, single-use code is sent to the registered email (POST /auth/forgot), and that code is then submitted alongside the new password (POST /auth/forgot-reset). The WebAuthn assertion ceremony follows the same two-step model — generate options, then verify the signed response from the authenticator.

Self-registration via POST /auth/signup is available for open-registration platforms. For invite-only or admin-provisioned deployments, this endpoint can be locked down through route-level permissions without changing code.