Phase 4: Security Perimeter & Authentication

This document details the multi-layered security architecture of the Itinera API. The system relies on a perimeter defense model: throttling brute-force at the edge, authenticating identities via JWT, validating email states, and enforcing fine-grained RBAC before business logic is executed.

1. Edge Defense: The Rate Limit Matrix

The application does not rely on a single, global rate limit. Instead, AppServiceProvider registers 9 granular, context-aware sliding windows based on route expense and vulnerability.

Limiter	Limit	Key	Purpose / Justification
`api_authenticated`	60 / min	`user_id` or IP	General API consumption for authenticated users (SEC-16).
`login`	5 / min	`IP` + `email`	Prevents credential stuffing. Keys on both IP and the targeted email account.
`register`	5 / min	`IP`	Prevents mass account creation / spam bots.
`ai`	Dynamic / day	`user_id` or IP	Controlled by `config('ai.rate_limit_per_day')`. Prevents burning expensive Groq/Llama tokens.
`maps`	10 / min	`IP`	Protects the expensive Overpass/Mapbox fan-out endpoints.
`weather`	30 / min	`IP`	Protects public external Open-Meteo fetches (SEC-03).
`checkout`	5 / min	`user_id` or IP	Prevents spamming order creation and Paymob Payment Intent exhaustion (SEC-08).
`contacts`	5 / min	`IP`	Prevents spamming the public contact database (SEC-03).
`newsletter`	5 / min	`user_id` or IP	Prevents email subscription bombing (NEWS-01).

2. Authentication: The JWT Lifecycle

Itinera utilizes stateless JSON Web Tokens (via tymon/jwt-auth) to verify identity without maintaining server-side sessions.

Issuance: Tokens are issued exclusively via /api/auth/login and /api/auth/register (using the auth:api guard).

Expiry: Bearer tokens expire strictly after 1 hour.

Rotation & Blacklisting: Users hit /api/auth/refresh to obtain a new token. When refreshed or when the user calls /api/auth/logout, the old token is explicitly Blacklisted in the database/cache. It cannot be used again, severely limiting the window for stolen token abuse.

Refresh Throttling: Token refreshing is implicitly bound to the api_authenticated limiter to prevent excessive token generation.

3. Email Verification Gate

Before users can access premium resources or finalize agency profiles, they must verify their email.

The Gate: Routes are protected by the verified middleware (pointing to MustVerifyEmail).

Security Rules:

Signed URLs: Verification links are cryptographically signed.

Expiry: Links expire within a strict window (default 60 mins).

No Auto-Trust: Even users signing in via OAuth providers (if enabled) must pass explicit verification if the provider doesn't guarantee the email.

Resend Throttling: To prevent SMS/Email bombing, the /email/verification-notification endpoint is hard-throttled at 1 email per 60 seconds.

4. Authorization: Spatie RBAC Matrix

Authorization logic is decoupled from Controllers via spatie/laravel-permission.

Roles

The system operates on four strict roles:

super_admin (Bypasses all Gates implicitly)

admin

agency

user

The Super Admin Override

In AppServiceProvider::boot(), we register a global Gate::before interceptor. This guarantees that super_admin can always execute actions without needing explicit permission assignments, reducing DB queries and configuration drift:

Route-Level Enforcement

Permissions are enforced at the routing layer, completely isolating the business logic from authorization concerns. For example:

This guarantees that a standard user can never execute agency functions, even if they manipulate client-side routing.

Phase 4: Security Perimeter &amp; Authentication

1. Edge Defense: The Rate Limit Matrix#

2. Authentication: The JWT Lifecycle#

3. Email Verification Gate#

4. Authorization: Spatie RBAC Matrix#

Roles#

The Super Admin Override#

Route-Level Enforcement#

5. Security Architecture Map#