# StellaOps Authority — Authentication Libraries Team

> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Keep status synchronized across trackers.

## Mission
Deliver shared authentication components consumed by resource servers, clients, and tooling: abstractions, DI helpers, token clients, and supporting utilities.

## Task Breakdown

| Order | Task IDs | Description | Dependencies | Acceptance |
|-------|----------|-------------|--------------|------------|
| 1 | LIB1 | Stand up `StellaOps.Auth.Abstractions` (claims, scopes, principal builder, ProblemResultFactory). | DevEx FND1 | Unit tests covering claim normalization + problem responses. |
| 2 | LIB3 | Implement `NetworkMaskMatcher` with IPv4/IPv6 CIDR support; port tests from Serdica inspiration. | LIB1 | 100% branch coverage on mask utilities. |
| 3 | LIB2 | Build `StellaOps.Auth.ServerIntegration` (DI extension wiring JwtBearer, bypass masks, policy helpers). | LIB1, LIB3 | Add integration test with stub Authority JWKS. |
| 4 | LIB4 | Build `StellaOps.Auth.Client` (discovery, JWKS caching, password/client credential flows, token cache abstraction). | LIB1 | Provide `IStellaOpsTokenClient` interfaces. |
| 5 | LIB5 | Integrate Polly + HttpClientFactory patterns (configurable retries/backoff) in Auth.Client. | LIB4 | Config tested via options binding. |
| 6 | LIB6 | Prepare NuGet packaging metadata (license, tags) and update build pipeline to push once stabilized. | LIB1–LIB5 | Validate `dotnet pack` outputs signed packages. |

## Implementation Notes
- All option classes should bind via `StellaOps.Configuration` naming conventions.  
- Token client must support file-based cache (for CLI) and in-memory cache (for services).  
- Provide sample usage snippets for Feedser integration (to hand off).  
- Consider adding `IClaimsTransformation` helper for ASP.NET resource servers.  
- Ensure authentication failures map to standard problem responses (missing/expired token, insufficient scope).

## Deliverables
- Three new projects: `StellaOps.Auth.Abstractions`, `.ServerIntegration`, `.Client`.  
- Unit + integration tests, coverage reports.  
- Example integration docs/snippets for Feedser and CLI teams.  
- Packaging metadata ready for CI once green-lit.

## Coordination
- Weekly sync with Authority Core + Feedser Integration to align on scopes/policies.  
- Share NuGet package versions with DevEx once published.  
- Notify CLI team when client API stabilizes (unlock CLI1–CLI3).  
- Coordinate with Security Guild on bypass mask semantics and default policies.

## Status (2025-10-10)
- LIB1 DONE – Principal builder/problem factory complete with unit coverage.
- LIB3 DONE – `NetworkMaskMatcher` replaces Serdica helpers with IPv4/6 tests.
- LIB2 DONE – `AddStellaOpsResourceServerAuthentication` with scope/bypass policies implemented.
- LIB4 DONE – Auth client, discovery/JWKS caches, in-memory/file token caches with happy-path tests delivered.