HDC Auth Proxy

Authentication and authorization proxy for the Humanitarian Data Cube (HDC) at WFP.

What it does

Protects access to S3 resources, HTTP endpoints and HDC applications, supporting:

OAuth2/OIDC, API keys and JWT
Human users (browser, session-based) and M2M services (stateless)
Identity Providers: AWS Cognito and federated CIAM for partners

Architecture

The project follows a hexagonal architecture (ports & adapters):

src/hdc_auth_proxy/
├── domain/       # Pure domain models (dataclasses, no external dependencies)
├── ports/        # Protocols: input/output boundaries
├── adapters/     # Concrete implementations (Cognito, JWT, HTTP, Pydantic DTOs)
├── core/         # ABCs for internal plugin systems
└── services/     # Business logic

Getting Started

See the Development Guide for how to run the proxy, configure settings via environment variables, and test locally.

Documentation

Development Guide — Running the proxy and configuration
Domain Layer — Bounded contexts and domain models
Ports and Services — Port Protocols and service layer
Architectural Decisions — ADRs and design choices

Living Architecture Catalog

An interactive architecture catalog built with EventCatalog documents the DDD bounded contexts, services, port contracts, domain events, and flows.

Open the Architecture Catalog

Local development:

cd architecture && npm run dev
# Opens at http://localhost:3100