# 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.

## 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.