Authentication Service

The Authentication Service is the gatekeeper of the Nodesify Admin platform. It handles user identity, session management, and security context establishment.

Login Flow (/auth/login)

The login process is a multi-step secure workflow:

1. Credential Validation: The system verifies the username and password against the database (using bcrypt hashing).
2. MFA Check:
   • If the user has MFA enabled, the server returns a specific mfaRequired response. No tokens are issued yet.
   • The client must then call /auth/mfa/verify to complete the login.
3. Token Issuance:
   • Access Token: A short-lived JWT (JSON Web Token) returned in the response body. Used for API Authorization Bearer header.
   • Refresh Token: A long-lived, rotating token set as an HttpOnly cookie. Used to renew access tokens.
4. CSRF Protection: A Double-Submit Cookie pattern is used. The server sets a csrf_token cookie and expects a matching header in subsequent state-changing requests.

Session Management

To maintain security while providing a smooth user experience, we use a robust session management strategy known as Refresh Token Rotation with Reuse Detection.

Token Refresh Mechanism (/auth/token/refresh)

This endpoint is called automatically by the frontend interceptors when an Access Token expires (typically every 15-30 minutes).

1. Rotation (One-Time Usage):

   • Every time a Refresh Token is used to get a new Access Token, the Refresh Token itself is also replaced.
   • The server invalidates the old Refresh Token and issues a new one in the response cookie.
   • This ensures that if a Refresh Token is stolen, it is likely valid for only a short window or already invalid.

2. Reuse Detection (Theft Protection):

   • Scenario: An attacker steals a user's Refresh Token. The legitimate user uses it first (rotating it). The attacker then tries to use the old stolen token.
   • Detection: The system recognizes that an already used/revoked token is being presented.
   • Action: This is treated as a security breach. The system revokes the entire Token Family.
     • The legitimate user's active session is killed (they are logged out).
     • The attacker's access is blocked.
   • Result: Both parties are forced to re-authenticate, ensuring the legitimate owner regains control.

3. Token Family:

   • A "Family" links a chain of rotated tokens to a single root session login.
   • Revoking a family invalidates all tokens (past, present, and future) associated with that specific login event.

Active Sessions (/auth/sessions)

Users and Admins can view and manage active login sessions.

• Get Sessions (GET /auth/sessions): Lists all active sessions for the current user, including Device (User-Agent), IP, and Last Active time.
• Revoke Session (DELETE /auth/sessions/:id): Terminates a specific session. The refresh token for that session becomes invalid immediately.
• Revoke All Others: A security feature to "Log out of all other devices".

MFA Management (/auth/mfa)

Multi-Factor Authentication (TOTP) can be enabled by any user for added security.

• Setup (GET /auth/mfa/setup): Generates a new TOTP secret and returns the QR code URL.
• Enable (POST /auth/mfa/enable): Confirms the setup by verifying a code and activating MFA on the account.
• Disable (POST /auth/mfa/disable): Turns off MFA (requires current password).
• Recovery Codes: When MFA is enabled, a set of one-time use recovery codes is generated for emergency access.

Account Security

Password Change (/auth/password)

• Endpoint: PUT /auth/password
• Requirement: Users must provide their oldPassword to set a newPassword.
• Effect: Changing the password automatically revokes all other sessions to ensure that if an account was compromised, the attacker loses access.

Impersonation (/auth/impersonate/:id)

Permission Required: System:Auth:Impersonate

This feature allows Super Admins to log in as another user to troubleshoot issues.

• Mechanism: The server issues a new, temporary session for the target user.
• Safety: The session has a short duration (2 hours).
• Audit: The operation is logged with a clear "Impersonated by [Admin]" context.