mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 15:51:14 +00:00
Oleksandr Bezdieniezhnykh
96cd3c4495
Adds Microsoft.AspNetCore.Authentication.JwtBearer 8.0.21 and the SatelliteProvider.Api.Authentication.AddSatelliteJwt extension that validates HS256 tokens against a shared JWT_SECRET (>=32 bytes, fail fast at startup). Every minimal-API endpoint now carries .RequireAuthorization(); the middleware chain is UseExceptionHandler -> UseHttpsRedirection -> UseCors -> UseAuthentication -> UseAuthorization -> endpoints. Swagger UI gets a Bearer security definition so the Authorize button works. Test infrastructure: JwtTokenFactory (unit) and JwtTestHelpers (integration) mint deterministic tokens against the same secret; the integration test runner attaches a default Bearer token to its shared HttpClient so existing tests continue to exercise protected endpoints. JwtIntegrationTests adds AC-1..AC-4 and AC-7 (Swagger advertises Bearer) end-to-end; AuthenticationServiceCollectionExtensionsTests covers AC-5 (missing/empty/short secret fail-fast) plus env-var precedence; JwtTokenFactoryTests covers AC-6 (claims pass through the JwtSecurityTokenHandler.ValidateToken path JwtBearer uses). docker-compose and scripts/run-tests.sh now propagate JWT_SECRET to the api and integration-tests containers, with a >=32-byte guard. .env.example documents the required keys; .env stays gitignored. Code review verdict: PASS_WITH_WARNINGS (2 Low findings surfaced in _docs/03_implementation/reviews/batch_01_cycle2_review.md). Cross-component coordination: gps-denied-onboard and the mission planner UI must attach Bearer tokens before this lands in dev. Co-authored-by: Cursor <cursoragent@cursor.com>
92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# Module: Api/Program.cs
|
||
|
||
## Purpose
|
||
Application entry point. Configures DI container, sets up middleware, defines minimal API endpoints, runs database migrations on startup, and starts background services.
|
||
|
||
## Public Interface
|
||
|
||
### API Endpoints
|
||
| Method | Route | Handler | Description |
|
||
|--------|-------|---------|-------------|
|
||
| GET | `/tiles/{z}/{x}/{y}` | `ServeTile` | Slippy map tile server with in-memory caching |
|
||
| GET | `/api/satellite/tiles/latlon` | `GetTileByLatLon` | Download single tile by lat/lon/zoom |
|
||
| GET | `/api/satellite/tiles/mgrs` | `GetSatelliteTilesByMgrs` | MGRS stub (returns empty) |
|
||
| POST | `/api/satellite/upload` | `UploadImage` | Image upload stub (returns `Success: false`) |
|
||
| POST | `/api/satellite/request` | `RequestRegion` | Queue region for async tile processing |
|
||
| GET | `/api/satellite/region/{id}` | `GetRegionStatus` | Get region processing status |
|
||
| POST | `/api/satellite/route` | `CreateRoute` | Create route with intermediate points |
|
||
| GET | `/api/satellite/route/{id}` | `GetRoute` | Get route with all points |
|
||
|
||
### Local Records (defined in Program.cs)
|
||
- `GetSatelliteTilesResponse`, `SatelliteTile` — MGRS response stubs
|
||
- `UploadImageRequest` — multipart form data request
|
||
- `SaveResult` — upload response stub
|
||
- `DownloadTileResponse` — tile download response
|
||
- `RequestRegionRequest` — region request body
|
||
- `ParameterDescriptionFilter` — Swagger operation filter
|
||
|
||
## Internal Logic
|
||
|
||
### DI Registration
|
||
1. Serilog configured from `appsettings.json`
|
||
2. Connection string extracted from `ConnectionStrings:DefaultConnection`
|
||
3. Config bindings: `MapConfig`, `StorageConfig`, `ProcessingConfig`
|
||
4. Singletons: repositories (`TileRepository`, `RegionRepository`, `RouteRepository`), `GoogleMapsDownloaderV2`, `ITileService`, `IRegionService`, `IRouteService`
|
||
5. `IRegionRequestQueue` with configurable capacity
|
||
6. Hosted services: `RegionProcessingService`, `RouteProcessingService`
|
||
7. CORS policy: `TilesCors` — configured origins from `CorsConfig:AllowedOrigins`, falls back to allow-any
|
||
8. JSON options: camelCase, case-insensitive
|
||
9. **JWT authentication (AZ-487)**: `AddSatelliteJwt(builder.Configuration)` (extension in `SatelliteProvider.Api.Authentication`) registers `JwtBearer` with `TokenValidationParameters` set per the suite auth contract (signature + lifetime, no issuer/audience validation, 30 s clock skew, ≥ 32-byte HMAC key). Followed by `AddAuthorization()`.
|
||
|
||
### Startup
|
||
1. Database migration via `DatabaseMigrator.RunMigrations()` — throws on failure
|
||
2. Creates tiles and ready directories
|
||
3. Swagger enabled in Development mode
|
||
4. Middleware chain (order matters): `UseExceptionHandler` → `UseHttpsRedirection` → `UseCors("TilesCors")` → `UseAuthentication` → `UseAuthorization` → endpoint mapping.
|
||
5. Every `MapGet`/`MapPost` endpoint is decorated with `.RequireAuthorization()`; the framework returns 401 before the handler runs for any anonymous, expired, or invalid-signature request.
|
||
|
||
### ServeTile Handler
|
||
1. Checks `IMemoryCache` for tile bytes (1h absolute, 30min sliding expiration)
|
||
2. If cache miss: queries `ITileRepository.GetByTileCoordinatesAsync`
|
||
3. If no DB record: downloads tile via `GoogleMapsDownloaderV2.DownloadSingleTileAsync`, creates `TileEntity`, inserts
|
||
4. Returns image bytes with cache headers (`Cache-Control: public, max-age=86400`)
|
||
|
||
### GetTileByLatLon Handler
|
||
Downloads a tile, persists it, returns metadata as `DownloadTileResponse`.
|
||
|
||
### RequestRegion Handler
|
||
Validates size (100–10000m), delegates to `IRegionService.RequestRegionAsync`.
|
||
|
||
## Dependencies
|
||
All project references: Common, DataAccess, Services.
|
||
NuGet: `Serilog.AspNetCore`, `Swashbuckle.AspNetCore`, `Microsoft.AspNetCore.OpenApi`, `Microsoft.AspNetCore.Authentication.JwtBearer` (8.0.21, AZ-487), `SixLabors.ImageSharp`, `Newtonsoft.Json`.
|
||
|
||
## Consumers
|
||
- HTTP clients (external)
|
||
- Integration tests (via HTTP)
|
||
|
||
## Data Models
|
||
Defines several local request/response records that are not shared with other projects.
|
||
|
||
## Configuration
|
||
All configuration sections are consumed here:
|
||
- `ConnectionStrings:DefaultConnection`
|
||
- `MapConfig`, `StorageConfig`, `ProcessingConfig`
|
||
- `CorsConfig:AllowedOrigins`
|
||
- `Jwt:Secret` — HMAC-SHA256 signing key for JWT validation (AZ-487). Resolution: `JWT_SECRET` env var (preferred, opaque production secret) → `Jwt:Secret` configuration key (`appsettings.Development.json` placeholder only). Startup fails fast if the resolved value is unset, empty, or shorter than 32 bytes.
|
||
- `Serilog` section
|
||
|
||
## External Integrations
|
||
- Google Maps (indirectly via `GoogleMapsDownloaderV2`)
|
||
- PostgreSQL (via repositories and DatabaseMigrator)
|
||
- File system (`./tiles/`, `./ready/`)
|
||
|
||
## Security
|
||
- CORS configured (permissive by default when no origins specified)
|
||
- Swagger only in Development; Bearer token "Authorize" button registered via `AddSecurityDefinition`/`AddSecurityRequirement` (AZ-487)
|
||
- HTTPS redirection enabled
|
||
- JWT bearer authentication (AZ-487) — every endpoint requires a valid HS256-signed token. Anonymous, expired, or signature-tampered requests return 401 before the handler runs. Per-endpoint permission claims are layered on top in subsequent PBIs (e.g. AZ-488 requires `permissions: ["GPS"]` on the upload endpoint).
|
||
|
||
## Tests
|
||
Integration tests exercise all endpoints. Unit test project has only a dummy test.
|