How wealdtech/hawk works
Project Type and Purpose
• This is a multi‐module Java library implementing the Hawk authentication protocol (v1.0).
• It provides:
• A core module with generic Hawk client/server APIs and configuration
• A Jersey‐specific client implementation
• A Jersey‐specific server implementation
• It is not a full application by itself, but a reusable SDK for Java services and clients that wish to use Hawk.
File Structure Analysis
• Top‐level build files: build.gradle, settings.gradle, Gradle wrapper, .travis.yml
• Modules:
• hawk-core/
• hawk-client-jersey/
• hawk-server-jersey/
• Each module follows standard Maven/Gradle layout under src/main/java/... and src/test/java/....
• Core module contains domain classes (Hawk, HawkClient, HawkServer, credentials, configuration) and a Guice module.
• Client and server modules only contain Jersey filters and providers that plug into web apps.
Key Components
a. Core Module
– Classes: Hawk, HawkClient, HawkServer
– Config: HawkClientConfiguration, HawkServerConfiguration
– Credentials: HawkCredentials
– Guice support: HawkServerConfigurationModule
b. hawk-client-jersey
– Jersey Filter: HawkAuthorizationFilter
– Depends on core’s HawkClient APIs and configuration
c. hawk-server-jersey
– Jersey Filters and Providers:
· HawkAuthenticationFilter
· HawkAuthenticator
· HawkCredentialsProvider
· HawkPrincipalProvider
· HawkUnauthorizedFilter
– Glues Jersey’s request pipeline to core’s HawkServer
d. External Pieces (for example apps/tests)
– HTTP clients calling endpoints protected with Hawk
– HTTP servers exposing endpoints secured with Hawk
– Configuration files (JSON) used to bootstrap clients/servers
Relationships and Data Flow
• Client App → HTTP Request → HawkAuthorizationFilter (client‐jersey) → HawkClient (core)
• HawkClient signs the request → sends to remote Service
• HTTP Service receives request → HawkAuthenticationFilter (server‐jersey) → HawkServer (core)
• HawkServer verifies the signature → extracts credentials/principal → passes control to resource
• Any unauthorized or malformed requests are blocked by filters in server module
Architectural Patterns & Principles
• Modular, layered design: core abstractions + pluggable implementations
• Separation of concerns:
• Core handles protocol logic
• Jersey modules handle web framework integration
• Dependency injection with Guice (core provides a module)
• Single responsibility: filters only manage authentication/authorization
Detailed Steps for the Engineer
1. A high‐level canvas labeled “Hawk Java SDK”