Authentication & OTP Security

Security in Flockbase combines strong password policies, adaptive two-factor authentication, device trust fingerprinting, and cryptographic refresh token rotation.

The Login Flow

1. Client POST /auth/login (email + password)
               │
               ▼
      Verify Credentials
               │
      Is device recognized?
       ┌───────┴───────┐
      YES              NO
       │               │
       ▼               ▼
 Issue JWTs      Dispatch Termii SMS OTP
 (Access +       Return { requiresOtp: true, reference }
  Refresh)             │
                       ▼
                 2. Client POST /auth/verify-otp
                       │
                       ▼
                 Verify 6-digit OTP
                 Mark device as trusted
                 Issue JWTs (Access + Refresh)

Step 1: Initial Authentication (POST /auth/login)

{
  "email": "pastor@church.org",
  "password": "SecurePassword123!"
}

• Trusted Device Response (200 OK):

  {
    "requiresOtp": false,
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "48b6f3c1-..."
  }

• Unrecognized Device Response (200 OK):

  {
    "requiresOtp": true,
    "reference": "ref_9f28a381cd..."
  }

Step 2: OTP Verification (POST /auth/verify-otp)

{
  "reference": "ref_9f28a381cd...",
  "code": "849201",
  "trustDevice": true
}

Upon success, the API returns the access/refresh token pair and sets an encrypted HTTP-only cookie marking the current device as trusted.

Termii SMS Delivery & Cost Management

Flockbase integrates with Termii for SMS OTP delivery across Nigerian and international networks.

Production Environment

• Requires valid TERMII_API_KEY and approved TERMII_SENDER_ID (default: Flockbase).
• Sends a 6-digit one-time PIN valid for 5 minutes.

Zero-Cost Developer Mode (Local / Staging)

To avoid burning Termii SMS credits during local testing and development:

1. Leave TERMII_API_KEY blank in your local .env.
2. When the key is unset, the backend uses the local OTP stub (logs to database only; no external SMS call).
3. Furthermore, when NODE_ENV !== 'production', the /auth/login endpoint automatically includes the generated PIN in the response body:

   {
     "requiresOtp": true,
     "reference": "ref_local_123",
     "devOtpCode": "123456"
   }

4. Engineers can immediately copy the code from DevTools Network tab or console without touching a phone.

Device Trust & Re-verification

To minimize friction for regular users while safeguarding church data:

• Trust Token: When a user checks "Trust this device" during OTP verification, an HMAC-signed device cookie is issued with a 30-day lifespan.
• Automatic Re-verification: Even if a cookie is present, an OTP is prompted if:
  • The login originates from an anomalous IP range.
  • The browser user-agent changes significantly.
  • The user's account status or role was elevated.

Session Token Rotation & Password Changes

• Access Token: Short-lived JWT (15-minute expiration). Carries userId, email, role, and unitId.
• Refresh Token: Stored as a hashed token in PostgreSQL with a 7-day expiration.
• Rotation: Every time POST /auth/refresh is called, the old refresh token is revoked and a new one is issued.

Password Change Invalidation

Users can update their password via PATCH /users/me/password:

• Requires currentPassword and newPassword.
• Upon successful update, all other active refresh tokens for this user are instantly revoked across all devices, protecting against unauthorized persistence.

Brute-Force Rate Limiting

• 5 consecutive failed attempts lock the account for 15 minutes (LOGIN_MAX_ATTEMPTS = 5, LOGIN_LOCKOUT_MINUTES = 15).
• Account lockout is tracked with timestamps in the user record and automatically resets after the cool-down window.