Authentication and Authorization¶

This page documents the authentication and authorization mechanisms identified in the WhiteLotusAI REST API gateway source. It describes the JWT lifecycle, protected routes, role-based access control (RBAC), identity propagation, and outstanding security verification items.

1. Overview¶

WhiteLotusAI uses JSON Web Tokens (JWTs) to authenticate API requests at the REST API gateway. The gateway issues access and refresh tokens following successful authentication operations, validates access tokens on protected routes, and maintains refresh-token records in Redis.

The implementation separates authentication from authorization:

• Authentication establishes the identity associated with a valid token.
• Authorization determines whether the authenticated identity is permitted to perform an operation.
• Identity propagation passes user and tenant context to downstream services, where applicable.

2. Authentication architecture¶

2.1 Source components¶

The principal gateway implementation files are:

2.2 Request and token lifecycle¶

The following diagram represents the documented source-level flow. It is a logical overview, not a runtime trace.

flowchart TB
    USER(["User or API Client"])

    subgraph AUTH["Authentication Operations"]
        direction TB
        LOGIN["Registration or Login"]
        USERSVC["User Service"]
        ISSUE["Issue Access and Refresh Tokens"]
        REFRESH["Refresh Token Request"]
        CACHE["Redis Refresh-Token Cache"]
    end

    subgraph PROTECTED["Protected API Requests"]
        direction TB
        REQUEST["Request with Bearer Token"]
        VALIDATE["JWTBearer Validation"]
        PERMISSION["Route Permission Check"]
        HANDLER["Route Handler"]
        DOWNSTREAM["Downstream Service"]
    end

    USER --> LOGIN
    LOGIN --> USERSVC
    USERSVC -->|"Successful response"| ISSUE
    ISSUE -->|"Tokens returned"| USER
    ISSUE --> CACHE

    USER --> REQUEST
    REQUEST --> VALIDATE
    VALIDATE -->|"Valid access token"| PERMISSION
    PERMISSION -->|"Allowed by configured policy"| HANDLER
    HANDLER --> DOWNSTREAM

    USER --> REFRESH
    REFRESH --> CACHE
    CACHE -.->|"Token lookup and rotation"| REFRESH
    REFRESH -->|"Replacement tokens, when successful"| USER

    classDef client fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:2px
    classDef auth fill:#d1fae5,stroke:#059669,color:#064e3b,stroke-width:2px
    classDef security fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px
    classDef service fill:#ede9fe,stroke:#7c3aed,color:#4c1d95,stroke-width:2px

    class USER client
    class LOGIN,USERSVC,ISSUE,REFRESH,CACHE auth
    class REQUEST,VALIDATE,PERMISSION security
    class HANDLER,DOWNSTREAM service

    style AUTH fill:transparent,stroke:#059669,stroke-width:1.5px
    style PROTECTED fill:transparent,stroke:#d97706,stroke-width:1.5px

3. Authentication endpoints¶

The authentication router is defined in rest_api/package/app/api/auth.py, with the default API prefix /api.

The endpoint descriptions reflect the inspected implementation. Confirm the effective HTTP status codes and request/response schemas against the registered routes and tests.

3.1 Registration¶

The registration handler forwards the submitted registration details to the user service. When the service reports success, the gateway creates access and refresh tokens and returns them with the user profile.

The handler also provides responses for duplicate-email and general registration-failure cases.

Verification checklist

• Confirm request validation and required fields.
• Verify duplicate-account handling and appropriate HTTP status codes.
• Confirm that tokens are issued only after successful registration.
• Verify that sensitive registration data is not written to logs.
• Confirm the returned user profile excludes sensitive authentication data.

3.2 Login¶

The login handler forwards the submitted email and password to the user service. If the service reports success, the gateway creates access and refresh tokens.

The response includes the access token, refresh token, bearer token type, and user profile.

When the user service does not report success, the handler returns an invalid-credentials message. The exact HTTP status depends on the response handling and status supplied by the service.

3.3 Refresh-token rotation¶

The inspected refresh handler performs the following operations:

1. Decodes the supplied refresh token.
2. Checks the token against the refresh-token cache.
3. Deletes the existing refresh-token record.
4. Retrieves the associated user through the user service.
5. Creates replacement access and refresh tokens if the user lookup succeeds.

The handler returns 401 Unauthorized when the refresh token is invalid, expired, or absent from the cache. A separate user-not-found response is also defined.

The precise behavior for concurrent requests, Redis failures, and downstream service errors remains unverified.

3.4 Logout¶

The logout route declares JWTBearer as a dependency. It obtains the user identifier from the validated access-token payload and requests deletion of the submitted refresh-token record.

The handler returns a success message after the deletion call completes.

4. JWT structure and configuration¶

Token creation and decoding are implemented in rest_api/package/app/auth/auth_handler.py.

4.1 Illustrative token payload¶

The following is a fictional, non-secret example to illustrate the documented claim names. It is not a captured token or a guarantee of the complete payload schema.

{
  "sub": "example-user-id",
  "kind": "access",
  "role": "MEMBER",
  "tenant_id": "example-tenant",
  "exp": 1790000000
}

The example includes a tenant claim for illustration. Verify the exact tenant claim name, required claims, and expiration handling against the implementation before using this example as an API contract.

Security requirements:

• Use a securely generated signing secret and a deliberate rotation policy.
• Explicitly allow only approved signing algorithms during token validation.
• Validate token type, expiration, and required claims.
• Prevent refresh tokens from being accepted as access tokens.
• Never commit actual signing secrets or internal service credentials.
• Keep token lifetimes consistent with the approved deployment policy.

5. Access-token validation¶

The JWTBearer dependency is implemented in rest_api/package/app/auth/auth_bearer.py.

The inspected dependency:

1. Extracts HTTP bearer credentials.
2. Rejects missing or invalid authorization headers.
3. Decodes and validates the access token.
4. Rejects tokens that cannot be validated as access tokens.
5. Checks the route permission entry when a matching entry is found in AUTH_ROUTES.
6. Attaches the decoded payload to request.credentials and request.state.credentials.

Route handlers commonly obtain the authenticated user identifier from:

request.state.credentials["sub"]

This snippet illustrates access to the decoded subject claim; it is not a standalone authentication implementation.

5.1 Expected response categories¶

6. Role-based access control¶

The authorization table is defined in rest_api/package/app/auth/auth_routes.py.

The table supports:

• all — any authenticated user, according to the configured mapping.
• A list of role names, such as ["ADMIN"] — the specified roles are permitted by that mapping.

The inspected table includes ADMIN restrictions for these user-management handlers:

The table also defines permissions for several profile, session, chat, RAG, and integration handlers.

6.1 Authorization decision model¶

flowchart TD
    A["Request with Valid Access Token"]
    B["Resolve Route Tag and Handler"]
    C{"Matching Permission Entry?"}
    D{"Role Allowed?"}
    E["Continue to Handler"]
    F["Return 403"]
    G["Review Missing Mapping"]

    A --> B --> C
    C -->|Yes| D
    C -->|No| G
    D -->|Yes| E
    D -->|No| F

    classDef input fill:#e8eaf6,stroke:#5c6bc0,color:#20243a
    classDef decision fill:#fff3e0,stroke:#ef8c22,color:#633b0b
    classDef allowed fill:#e0f2f1,stroke:#00897b,color:#173b38
    classDef denied fill:#ffebee,stroke:#d9534f,color:#6d2020
    classDef review fill:#fce4ec,stroke:#ad4775,color:#5b2340

    class A,B input
    class C,D decision
    class E allowed
    class F denied
    class G review

The diagram's missing-mapping branch is a recommended review outcome, not a claim that the current implementation returns that outcome.

6.2 Route-policy verification¶

For each registered endpoint, confirm:

• The route is registered under the expected prefix and router.
• The intended authentication dependency is active.
• The route tag and handler name match the authorization table.
• The required roles are enforced.
• Missing mappings are rejected or handled by an explicitly approved policy.
• Both allowed and denied requests are covered by automated tests.

7. Protected route families¶

The following routers declare JWTBearer as a router-level dependency in the inspected source.

The logout endpoint declares the dependency directly on the route. Registration, login, and refresh serve separate authentication purposes.

This inventory documents declared dependencies, not proof of effective authorization. Check the actual route registrations, permission mappings, and downstream access controls.

8. Identity, ownership, and tenant isolation¶

The gateway passes user identifiers to downstream services for several operations. For example, session handlers derive the user identifier from the validated JWT payload and pass it to the session service.

The RAG router derives user, role, and tenant values from the token payload, with a configured default tenant fallback.

The following controls require verification for every resource-bearing endpoint:

• Trusted identity: derive the caller identity from validated authentication context.
• Resource ownership: prevent access to another user's resources by changing request identifiers.
• Tenant isolation: enforce tenant boundaries within the responsible service and data-access layer.
• Role enforcement: apply authorization consistently across gateway and downstream operations.
• Internal authentication: prevent unauthorized internal requests from forging or overriding trusted identity context.
• Context integrity: ensure downstream services cannot mistake caller-controlled values for verified claims.

9. Security requirements and operational guidance¶

The following are security requirements and verification criteria, not a declaration that all controls are implemented.

9.1 Example verification matrix¶

Use the following matrix when implementing or reviewing authentication tests.

The table describes expected security outcomes and test cases. It is not evidence that these tests currently exist or pass.

10. Open verification findings¶

The following findings were recorded during source inspection. No application code was changed as part of this documentation update.

10.1 Recommended remediation order¶

The following is a suggested prioritization for engineering review, not a statement of confirmed exploitability.

1. Authorization enforcement: reconcile route registrations and permission mappings; verify fail-closed behavior for privileged operations.
2. Secret configuration: prevent unsafe signing-secret and internal-secret defaults from reaching production.
3. Identity and tenant boundaries: verify ownership checks and internal-service authentication across the request path.
4. Refresh-token lifecycle: test rotation, concurrency, cache failures, and recovery.
5. Logout semantics: document the actual access-token revocation policy.
6. Regression coverage: add automated positive and negative tests for all authentication and authorization boundaries.

11. Source references¶

The primary files used for this documentation are listed below.

These paths identify the inspected source locations. Confirm them against the current application checkout when implementation details change.

12. Verification status and maintenance¶

This page describes authentication mechanisms identified in the inspected source snapshot and lists areas that require further verification.

It is not a complete authentication contract, a penetration-test report, or proof of production security.

Update this document only when changes are supported by source review, automated test results, or reproducible runtime evidence.

Before marking a finding resolved, record:

• The code change or control that addresses the finding.
• The relevant automated test or reproducible verification evidence.
• The affected routes and downstream services.
• Any remaining limitations or deployment-specific requirements.

Document scope: WhiteLotusAI REST API gateway authentication and authorization.