# Cognito RBAC Design and Integration

## Overview

This package uses AWS Cognito for authentication and implements Role-Based Access Control (RBAC) for API endpoints. The integration is tightly coupled with the Echo web framework and the OpenAPI (swagger) generated API code.

## Key Components

### 1. Cognito Auth Package (`internal/cognitoauth`)

- **auth.go**: Main exports for the package.
- **handler.go**: HTTP handlers for login, callback, logout, and home.
- **middleware.go**: Echo middleware for JWT extraction, validation, and RBAC enforcement.
- **jwks.go**: Handles JWKS key fetching and JWT signature validation.
- **token.go**: Token verification and management.
- **models.go**: Data models and types for tokens, users, etc.
- **utils.go**: Helper functions.
- **config.go**: Configuration structures for the auth system.

### 2. Service Config (`internal/serviceconfig`)

- **auth/config.go**: Loads and manages authentication-related configuration, including RBAC route permissions.
- **common.go**: Shared config logic.

### 3. API Layer (`api/queryAPI`)

- **api.gen.go**: Swagger-generated API handlers.
- **authHandlers.go**: Bridges generated code to Cognito logic; delegates to middleware for most flows.
- **homehandler.go**: Displays authentication status.
- **controllers.go**: Wires up controllers, but does not directly handle auth.

### 4. Server Setup (`internal/server/api/listener.go`)

- Creates the Echo server.
- Sets up config and logging middleware.
- Sets up Prometheus and OpenAPI validation middleware.
- **Registers Cognito RBAC middleware and routes before registering API handlers.**
- Sets route-level permissions via a map of route to allowed groups.

## Cognito client user group setup
The cognito client must be setup to redirect back to /login-callback for PKCE flow to work. 

## Integration Flow

1. **Config Initialization**: Auth config and route permissions are loaded at startup.
2. **Echo Server Setup**: The Echo instance is created and set on the config.
3. **RBAC Middleware Registration**:
    - `cognitoauth.RegisterRoutes(echoRouter, config)` is called.
    - This registers login, callback, logout, and home endpoints.
    - It also registers JWT extraction and validation middleware.
    - Route permissions are enforced via middleware that checks the user's Cognito groups/roles against the configured permissions map.
4. **API Handler Registration**:
    - OpenAPI-generated handlers are registered after the RBAC middleware.
    - All API endpoints are thus protected by the RBAC middleware.
5. **Request Flow**:
    - User requests a protected endpoint.
    - Middleware extracts JWT from cookies, validates it, and checks group membership.
    - If authorized, the request proceeds to the handler (which may be swagger-generated).
    - If not, a 401/403 is returned.

## Example

```go
// Set route permissions
routePermissions := map[string][]string{
    "/users": {"exporters", "uploaders", "querybuilders"},
    "/orders": {"exporters"},
    // ...
}
config.SetAuthRoutePermissions(routePermissions)

// Register Cognito auth routes and middleware
cognitoauth.RegisterRoutes(echoRouter, config)

// Register API handlers (swagger-generated)
RegisterHandlers(echoRouter, controllers)
```

## Customization

- Paths for login, callback, logout, and home can be configured.
- Route permissions are fully customizable.
- Middleware can be extended or replaced for fine-grained control.
- User info is accessible in handlers via helper functions.


## Cognito auth flow (mermaid)
For a live graph of the auto flow go [here.](https://mermaid.live/edit#pako:eNp9VE2P2jAQ_SsjH3pisyQQAlHLimVXvfQDle0eKqTK6wxgAXZqO7sFxH_vOISvhZKDFdvPb968GXvNhM6QpczinwKVwAfJJ4YvRgroy7lxUsicKwf3Rr9ZNOcbvTwfonlFA9zCgxarZS-X94_nwL6eKOn0dmM7VqQ33e6eJYUwgM-PT3A71xOptrhv2iFoH-MIFxEOFRpOez6L37QqxxLNxxdz2z3dElM-n6Oa4JZvz0KRKw0pNAL4gZk0KBw4fSr3ILRaTqFZydS8cNPo1o_ayBXeBUFwKeYhhz1FHMDAaIHWgj8OxhfBui2-Qh0rbAW7VfjizYEB37FfEJgE8JOWQBjMUDnJ5_a_StoBPPO5zErD3uMvKOkcefUmSbrP-FpN68dFvRHkzAsXszt_7BMZdqXMYehjOSPx9V2dz2u5zyek5hh8Hx7K4_QMVdkYu5AfTrguiTiwNY7toWPAVQanMg4mHWunJnnykS3V1uZaWbyWKfXDsyddQinXlnr7UxQzyNEspLWSKK60cEgd0qN8ffkEd4QGWwjfYONizmpsQSxcZnTf155lxAi6wBFL6TfjZjZiI7UhHHmmh0slWOpMgTVmdDGZsnRMLUGzIvdGVC_FDkJX_JfW-yk1h9Pm6_ZxKd-YGpsYH7piRJWh6etCOZZ2yuMsXbO_LA3rSdAMw7DRiOJOUo86cY0tWZokQb3ZbMRRFLWjsBVvamxVxqsH7aSexO1WHLX8X9TZ_AMOB5n7)
```mermaid
sequenceDiagram
    participant Browser
    participant AppServer as DoczyApiBE
    participant Cognito
    
    Browser->>AppServer: 1. GET /login
    Note over AppServer: 2. Generate code_verifier<br/>Generate code_challenge
    AppServer->>Browser: 3. Redirect to Cognito
    Browser->>Cognito: 4. GET /oauth2/authorize?...code_challenge
    Note over Cognito: 5. Process auth request
    Cognito->>Browser: 6. Cognito Login Page
    Browser->>Cognito: 7. User credentials
    Note over Cognito: 8. Validate credentials
    Cognito->>Browser: 9. Redirect with code
    Browser->>AppServer: 10. GET /login-callback?code=...
    Note over AppServer: 11. Retrieve code_verifier
    AppServer->>Cognito: 12. POST /oauth2/token<br/>code=...&code_verifier=...
    Note over Cognito: 13. Validate code and verifier
    Cognito->>AppServer: 14. Tokens response
    Note over AppServer: 15. Verify tokens<br/>Check permissions
    AppServer->>Browser: 16. Authentication successful
```