Chapter 2.2 — Authentication

1. Purpose

Authentication is the gateway to every other module in travoBooks. This chapter defines how identities are proved — for human users, partner-employee logins, customer self-service accounts, and machine-to-machine API consumers — and how sessions are issued, validated, and revoked. It also defines password policy, multi-factor enrolment, lockout behaviour, and personal-access-token (PAT) lifecycle.

Authorisation — what an authenticated principal is allowed to do — is covered in Chapter 2.1 (Users, Roles & RBAC) and Chapter 2.3 (Permission Catalog).

2. Why it matters in modern travel accounting

A travel-accounting platform sits on top of irreplaceable financial state: a single compromised accountant session can post fraudulent journal entries that take weeks to unwind. The platform also issues real airline tickets — each one a regulated, settled financial obligation with the BSP. Authentication failures translate directly into financial loss, ADM exposure, and customer trust damage.

Industry-specific pressure on auth design: - Agents work from mobile devices on public Wi-Fi. - Mid-office staff at large agencies use shared workstations. - Corporate clients expect SSO into their identity provider. - API integration partners need long-lived, scoped credentials. - IATA / BSP audits require demonstrable identity assurance.

3. Industry relevance

The travoBooks auth model aligns with NIST SP 800-63B Authenticator Assurance Level 2 for staff users handling financial postings, and Level 3 for partner-admin operations (high-impact configuration changes, payouts). Customer self-service accounts default to Level 1 with optional MFA upgrade.

4. Compliance considerations

• PCI DSS 8.x — strong authentication for all access to systems handling cardholder data (travoBooks does not store PANs, but the gateway-token paths still require strong auth).
• GDPR Art. 32 — appropriate technical measures including authentication strength proportional to data sensitivity.
• SOC 2 CC6 — logical access controls; documented authentication mechanisms.
• IATA Resolution 818g — agent identity controls for IATA-accredited members.
• Local data-protection laws (Bangladesh DPA, India DPDP, EU GDPR) — record of consent, breach-notification triggers.

5. Business logic

5.1 Authentication factors supported

5.2 Password policy

Passwords are never logged, returned in API responses, or written to disk outside the hashed password_hash column.

5.3 Session model

Sessions are server-side, identified by an opaque session ID in a __Host-travoBooks-Session cookie.

Session records also store a risk_score updated by signals (geo change, new device, unusual timing) — high-risk sessions trigger step-up MFA.

5.4 Multi-factor authentication

MFA enrolment is mandatory for: - Any role with is_financial = TRUE (accountant, partner_admin, approver, cashier) - Any user with API key creation permission - Any user in a partner with mfa_required = TRUE policy

MFA enrolment is optional but recommended for all other users.

MFA enrolment flow: 1. User logs in with password. 2. System prompts MFA enrolment (TOTP QR code or WebAuthn registration). 3. User scans QR / registers passkey. 4. User enters one current OTP to confirm enrolment. 5. System generates 10 single-use backup codes, shown once, stored hashed. 6. Enrolment is recorded in user_mfa_methods with enrolled_at.

MFA verification flow at login: 1. Password verified → MFA challenge issued. 2. User submits OTP / passkey assertion. 3. On success, full session is established. 4. On 3 consecutive MFA failures within 5 minutes, lock the account.

5.5 Personal Access Tokens (PAT)

PATs let users and machine identities authenticate to the API without a session.

5.6 SSO (Phase 2)

For partners with enterprise IdPs: - OIDC (preferred) — travoBooks acts as relying party. - SAML 2.0 — for legacy IdPs. - JIT provisioning — first-time SAML/OIDC users get a viewer role; partner_admin must elevate. - SCIM 2.0 — automatic user lifecycle sync (Phase 3).

6. Inputs → processing → outputs

Login (password + MFA)

Input: {partner_slug, email, password, mfa_code?}

Processing: 1. Resolve partner_id from slug. 2. Look up user by (partner_id, email). 3. Bcrypt-compare password against password_hash. 4. Apply rate-limit (Redis sliding window keyed by (partner_id, email) and by source IP). 5. If MFA required, issue or verify challenge. 6. Create session record in Redis. 7. Set session cookie. 8. Emit auth.login.success audit event.

Output: Redirect to dashboard; cookie set.

API call with PAT

Input: HTTP request with Authorization: Bearer tvb_live_<token>

Processing: 1. Parse token, look up by prefix in personal_access_tokens. 2. Argon2id verify the suffix against stored hash. 3. Check expires_at, revoked_at. 4. Check IP allow-list if configured. 5. Load associated user + permission set. 6. Attach principal to request context. 7. Increment pat.usage_count; update last_used_at. 8. Emit auth.pat.used audit event.

Output: Request proceeds to controller with authenticated principal.

7. Module dependencies

8. Security & permissions

• Authentication endpoints have stricter rate-limits than other routes.
• Failed login attempts emit telemetry that feeds the WAF and abuse-detection system.
• Account-takeover signals trigger automatic forced password reset and notification.
• Tokens are never returned twice — if lost, they must be recreated.
• The last_password_change_at timestamp is tracked; downstream PATs older than this timestamp can optionally be force-rotated by policy.

9. Validation rules

10. Error handling

The login API never distinguishes between "user does not exist" and "password incorrect" — both return AUTH_INVALID_CREDENTIALS. The MFA challenge response never reveals whether MFA is enrolled until the password phase succeeds. Lockout messages do not disclose lockout duration to the requester (they are logged for support, not shown to attacker).

For PAT failures, the response is 401 Unauthorized with no body discriminator — observability is internal.

11. Real-world examples

Example A — Accountant logs in from new device

1. Accountant [email protected] (partner beta-travel) logs in.
2. Password validates.
3. Geo-IP shows session originating from Singapore; last 30 days of logins were from Bangladesh.
4. Risk score elevated → MFA challenge issued plus email notification "New login from Singapore".
5. Ria enters TOTP → session established.
6. auth.login.success audit event recorded with risk_score=0.62, mfa_method=totp.

Example B — API key for booking automation

1. Beta Corp dev creates a PAT tvb_live_a1b2... with scope bookings.read.partner, bookings.create.partner and IP allow-list 198.51.100.0/24.
2. Dev integrates into their corporate booking bot.
3. Bot calls POST /api/v1/bookings from 198.51.100.45 with the bearer token.
4. Auth layer verifies token, IP, scope → request proceeds.
5. Usage metrics are visible in the partner UI; rate-limit headers tell the bot when to back off.

Example C — Session hijack attempt detected

1. Attacker steals session cookie via XSS in third-party widget (hypothetical — travoBooks' CSP prevents it).
2. Attacker replays cookie from a different IP / User-Agent.
3. Session-binding mismatch raises risk_score to 0.95.
4. Session is force-terminated; original user notified by email.
5. auth.session.suspicious_replay audit event recorded.

12. Step-by-step workflow

13. Database tables touched

14. Future scalability

• WebAuthn / Passkeys — Phase 2, becomes the preferred MFA factor; passwords retained as a recovery mechanism only.
• Risk-based adaptive auth — Phase 2, ML-scored risk that adjusts MFA frequency.
• Step-up auth API — Phase 2, exposes require_mfa(action) to controllers so individual high-risk actions (large refund, payout) can demand fresh MFA regardless of session state.
• Hardware-token (FIDO2) support for enterprise partners — Phase 3.
• SCIM 2.0 for SSO partner lifecycle — Phase 3.

15. Common pitfalls

• ⚠️ Don't expose user-existence via differing error messages. Always return the same generic message on credential failure.
• ⚠️ Don't make MFA bypass-able via "remember this device". travoBooks' policy is per-session — no persistent MFA-skip cookie for financial roles.
• 🔒 PATs are bearer tokens — treat them like cash. UI must mask, transport must be TLS, storage must be hashed.
• 🔒 Never log Authorization headers. Sanitisation must happen at the structured-logging layer before serialisation.
• ⚠️ Don't tie session lifetime to "Remember Me" without re-checking permission cache. Permission changes must invalidate stale sessions via role_set_version (see Ch 2.1).