stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

Add StellaOps Authority planning artifacts and config templates

Browse Source
This commit is contained in:
root
2025-10-10 06:52:41 +00:00
parent d0c95cf328
commit 3aed135fb5
14 changed files with 829 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
StellaOps.Authority.TODOS.md Normal file
View File

@@ -0,0 +1,120 @@
# StellaOps.Authority — Implementation Backlog
> Status owner: Platform Authentication Guild
> Source inspiration: `inspiration/Ablera.Serdica.*` (do **not** copy-paste; align with StellaOps coding standards)
## 0. Foundations
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| FND1 | Create solution scaffold under `src/StellaOps.Authority` (`StellaOps.Authority.sln` mirroring existing structure). | DevEx | **DONE** – Authority host + auth libraries + plugin stub scaffolded with net10.0 preview defaults. |
| FND2 | Extend `global.json`/Directory props to include new projects (net10.0). | DevEx | **DONE** – Directory props/targets cover Authority plugins; root `StellaOps.sln` enables repo-wide `dotnet build` (Feedser compile issues remain pre-existing). |
| FND3 | Define `StellaOpsAuthorityOptions` in `StellaOps.Configuration` (issuer, lifetimes, plugin directories, bypass masks). | BE-Base | **DONE** – Options class + bootstrapper with validation and tests; binds from YAML/JSON/env. |
| FND4 | Provide sample config `etc/authority.yaml.sample` with sensible defaults for offline-first deployments. | DevEx/Docs | **DONE** – Authority template published with token defaults + plug-in toggles and referenced in README/Quickstart. |
| FND5 | Add OpenTelemetry resource/version constants for Authority (service.name, namespace). | DevEx/Observability | **DONE** – Authority telemetry constants & helpers published for reuse by host/plugins. |
## 1. Core Authority Service
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| CORE1 | Bootstrap ASP.NET minimal API host with `StellaOps.Configuration` and plugin loading (reuse Feedser plugin host). | BE-Base | **DONE (2025-10-09)** – Host loads Authority options, Serilog, plugin registry; `/health` and `/ready` return 200. |
| CORE2 | Integrate OpenIddict server: configure issuer, endpoints (`/authorize`, `/token`, `/jwks`, `/introspect`, `/revoke`), token lifetimes. | BE-Auth | **DONE (2025-10-09)** – OpenIddict server wired with required endpoints, lifetimes, sliding refresh tokens, dev-only HTTPS relaxation. |
| CORE3 | Implement Mongo-backed stores (`AuthorityUser`, `AuthorityClient`, `AuthorityScope`, `AuthorityToken`, `AuthorityLoginAttempt`). | BE-Auth Storage | **DONE (2025-10-09)** – Mongo storage project with indexed collections, repository layer, and bootstrap migration runner wired to host. |
| CORE4 | Add `IUserCredentialStore`, `IClaimsEnricher`, `IClientCredentialStore`, `IIdentityProviderPlugin` abstractions (plugin contracts). | BE-Auth | Live under `StellaOps.Authority.Plugins.Abstractions`. |
| CORE5 | Port/customize OpenIddict event handlers (password grant, client credentials, token validation) using plugin contracts. | BE-Auth | **DONE (2025-10-10)** – Password, client-credentials, and token-validation handlers now enforce plugin capabilities, persist issued tokens, and run revocation checks. |
| CORE5A | Author integration tests verifying token persistence + revocation (client creds & refresh) through `IAuthorityTokenStore`. | QA, BE-Auth | Ensure revoked tokens are denied via handler + store wiring; cover reference token retrieval when implemented. |
| CORE5B | Document token persistence behaviour (revocation, enrichment) for resource servers + bootstrap guide. | Docs, BE-Auth | Update `docs/11_AUTHORITY.md` and plugin dev guide with new claims + store expectations before GA. |
| CORE6 | Implement API key protected bootstrap endpoints (`POST /internal/clients`, `POST /internal/users`) for initial provisioning. | BE-Auth | **DONE (2025-10-10)** – `/internal` APIs gated by bootstrap API key create users/clients through plugin stores. |
| CORE7 | Wire structured logging + OTEL spans for `/token`, `/authorize`, plugin actions. | BE-Auth Observability | Follows StellaOps logging conventions. |
| CORE8 | Add rate limiting middleware on `/token` and `/authorize`. | BE-Auth | Configurable via options; tests ensure throttle triggered. |
| CORE9 | Implement revocation (refresh + access) and publish signed offline revocation list. | BE-Auth | CLI hook to export list for air-gapped sync. |
| CORE10 | Provide JWKS endpoint backed by rotating signing/encryption keys (pluggable certificate loader). | BE-Auth | Document rotation workflow. |
## 2. Plugin System
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| PLG1 | Build `StellaOps.Authority.Plugins.Abstractions` (contracts, result models, constants). | BE-Auth | Align naming with StellaOps; add XML docs. |
| PLG2 | Implement plugin discovery via existing plugin host (search `PluginBinaries` for `StellaOps.Authority.Plugin.*`). | BE-Base | Provide diagnostics when plugin load fails. |
| PLG3 | Develop `StellaOps.Authority.Plugin.Standard` (Mongo-based user store, password hashing, lockout policy). | BE-Auth Storage | Includes configurable password policy + seed admin user. |
| PLG4 | Add plugin capability metadata (supportsPassword, supportsMfa, supportsClientProvisioning). | BE-Auth | **DONE (2025-10-10)** – Descriptor validation + registry logging wired; Standard plugin forces password capability and warns on misconfiguration. |
| PLG5 | Define plugin configuration schema under `etc/authority.plugins/*.yaml`; load via `StellaOps.Configuration`. | DevEx/Docs | **DONE** – Loader helpers + sample manifests committed; schema validated during bootstrap. |
| PLG6 | Publish developer guide for writing Authority plugins mirroring Feedser docs. | DevEx/Docs | **READY FOR DOCS REVIEW (2025-10-10)** – `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` finalised with capability guidance, ops alignment, testing checklist; awaiting copy-edit & diagram polish by Docs guild. |
| PLG7 | Future placeholder: outline backlog for LDAP plugin (`StellaOps.Authority.Plugin.Ldap`) with story-level TODOs. | BE-Auth | **RFC DRAFTED (2025-10-10)** – See `docs/rfcs/authority-plugin-ldap.md` for architecture, configuration schema, testing plan, and open questions awaiting guild review. |
## 3. Shared Auth Libraries
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| LIB1 | Create `StellaOps.Auth.Abstractions` (claims, scopes, ProblemResultFactory, PrincipalBuilder). | BE-Auth | **DONE (2025-10-10)** – Added claim/scope constants, deterministic principal builder, problem result helpers, and xUnit coverage for normalization paths. |
| LIB2 | Implement `StellaOps.Auth.ServerIntegration` DI extensions (JWT bearer, bypass masks, policy helpers). | BE-Auth | **DONE (2025-10-10)** – Delivered `AddStellaOpsResourceServerAuthentication`, scope policies, bypass evaluator, and integration tests. |
| LIB3 | Migrate CIDR-matching logic (`NetworkMaskMatcher`) with IPv4/6 support + tests. | BE-Auth | **DONE (2025-10-10)** – New matcher + `NetworkMask` parser with 100% branch coverage replacing legacy serdica helpers. |
| LIB4 | Add `StellaOps.Auth.Client` with discovery, JWKS caching, password/client credentials flows, token cache abstraction. | DevEx/CLI | **DONE (2025-10-10)** – Implemented typed client, discovery/JWKS caches, in-memory/file token caches, and CLI-focused unit tests. |
| LIB5 | Integrate Polly (configurable) and HttpClientFactory patterns in client library. | DevEx | Ensure retries/offline fallback configurable. |
| LIB6 | Publish NuGet packaging metadata (License, SourceLink) for new libraries. | DevEx | Align with repo packaging conventions. |
## 4. Feedser Integration
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| FSR1 | Extend `etc/feedser.yaml` with Authority section (issuer, client credentials, bypass masks). | DevEx/Docs | Document mandatory vs optional settings. |
| FSR2 | Update Feedser WebService startup to call `AddStellaOpsResourceServerAuthentication` and enforce scopes/roles on job endpoints. | BE-Base | **DONE (2025-10-10)** – Feedser conditionally wires the resource server auth helper, protects all `/jobs` routes, and documents `authority` config. |
| FSR3 | Add configuration-driven fallback for on-host cron (network mask bypass). | BE-Base | Must be auditable via logs. |
| FSR4 | Adjust Feedser CLI doc references to note new auth requirements. | Docs | Update quickstart & CLI reference. |
| FSR5 | Write end-to-end integration tests (Authority + Feedser) verifying token issuance and job trigger flow (use docker-compose). | QA | Runs in CI nightly. |
## 5. CLI Integration
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| CLI1 | Extend CLI config (`StellaOpsCliOptions`) with Authority fields (AuthorityUrl, ClientId, ClientSecret, Username, Password). | DevEx/CLI | Environment variable support. |
| CLI2 | Implement `stellaops-cli auth login/logout/status` commands using `StellaOps.Auth.Client`. | DevEx/CLI | Tokens stored via `ITokenCache`; support password + client creds. |
| CLI3 | Ensure all API calls attach bearer tokens; handle 401/403 with friendly output. | DevEx/CLI | Regression tests for unauthorized scenarios. |
| CLI4 | Update CLI docs & help text to reference authentication workflow. | Docs | Include example flows. |
## 6. Deployment & Ops
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| OPS1 | Provide distroless Dockerfile + compose example (Authority + Mongo + optional Redis). | DevOps | **DONE (scaffold)** – Dockerfile + compose sample published under `ops/authority/`; offline-friendly mounts + volumes ready for DevOps hardening. |
| OPS2 | Implement CI pipeline stages (build, unit tests, integration tests, publish artifacts). | DevOps | **DONE** – CI workflow now builds/tests Authority, publishes artifacts, and builds container image alongside Feedser. |
| OPS3 | Add automated key rotation job (CLI or script) and document manual procedure. | DevOps/BE-Auth | Integrate with JWKS endpoint. |
| OPS4 | Document backup/restore steps for Authority Mongo collections and key material. | Docs/DevOps | Cover offline site restore. |
| OPS5 | Define monitoring/alerting rules (token issuance failure rates, auth errors). | Observability | Provide Prometheus/OpenTelemetry guidance. |
## 7. Security & Compliance
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| SEC1 | Adopt ASP.NET Identity password hashing defaults (Argon2 if available). | BE-Auth | Verify with penetration test harness. |
| SEC2 | Implement audit log (structured) for token issuance, revocation, admin actions (including plugin events). | BE-Auth | Logs must include principal, scopes, client, IP. |
| SEC3 | Add configurable lockout/throttle rules (per user + per IP). | BE-Auth | Integration tests confirm lock after threshold. |
| SEC4 | Support offline revocation list generation/signing (for air-gapped exports). | BE-Auth/QA | CLI command + verification doc. |
| SEC5 | Conduct threat model review + update documentation with mitigations. | Security Guild | Include password grant hardening notes. |
## 8. Documentation & Enablement
| ID | Task | Owner | Notes / Acceptance |
|----|------|-------|---------------------|
| DOC1 | Author `docs/11_AUTHORITY.md` covering architecture, configuration, plugin model, operational playbooks. | Docs | Reference sample configs and CLI flows. |
| DOC2 | Produce API reference snippet (OpenAPI fragment) for `/token`, `/jwks`, `/introspect`, `/revoke`. | Docs/BE-Auth | Link in docs & README. |
| DOC3 | Write migration guide from anonymous Feedser to secured Feedser (staged rollout). | Docs/BE-Auth | Address bootstrap credentials and cut-over steps. |
| DOC4 | Create plugin developer how-to referencing new abstractions. | Docs/DevEx | Include example plugin skeleton. |
| DOC5 | Update repository README quickstart to point to Authority docs once live. | Docs | After Authority MVP lands. |
## 9. Backlog / Future Enhancements
| ID | Idea | Notes |
|----|------|-------|
| FUT1 | Multi-factor authentication plugin capability (TOTP / WebAuthn) via plugin metadata. | Requires UX + plugin changes. |
| FUT2 | Admin UI (React/Angular) for managing users/clients. | Defer until API stabilizes. |
| FUT3 | Federation with Microsoft Entra ID using OIDC upstream (Authority acts as broker). | Align with future integration strategy. |
| FUT4 | Device authorization flow support for offline agents. | Dependent on client library maturity. |
| FUT5 | Plugin marketplace packaging guidelines (versioning, signing). | Coordinate with product team. |
---
**Coordination Notes**
- Dedicated triage meetings weekly (Auth Guild) to review progress and unblock module owners.
- Plugin + Authority changes must coordinate with QA for end-to-end scenarios (Authority ↔ Feedser ↔ CLI).
- Security reviews required before enabling Authority in production environments.