Add StellaOps Authority planning artifacts and config templates

2025-10-10 06:52:41 +00:00
parent d0c95cf328
commit 3aed135fb5
14 changed files with 829 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,28 @@
-# git.stella-ops.org
+# StellaOps Feedser & CLI
+
+This repository hosts the StellaOps Feedser service, its plug-in ecosystem, and the
+first-party CLI (`stellaops-cli`). Feedser ingests vulnerability advisories from
+authoritative sources, stores them in MongoDB, and exports deterministic JSON and
+Trivy DB artefacts. The CLI drives scanner distribution, scan execution, and job
+control against the Feedser API.
+
+## Quickstart
+
+1. Prepare a MongoDB instance and (optionally) install `trivy-db`/`oras`.
+2. Copy `etc/feedser.yaml.sample` to `etc/feedser.yaml` and update the storage + telemetry
+   settings.
+3. Copy `etc/authority.yaml.sample` to `etc/authority.yaml`, review the issuer, token
+   lifetimes, and plug-in descriptors, then edit the companion manifests under
+   `etc/authority.plugins/*.yaml` to match your deployment.
+4. Start the web service with `dotnet run --project src/StellaOps.Feedser.WebService`.
+5. Configure the CLI via environment variables (e.g. `STELLAOPS_BACKEND_URL`) and trigger
+   jobs with `dotnet run --project src/StellaOps.Cli -- db merge`.
+
+Detailed operator guidance is available in `docs/10_FEEDSER_CLI_QUICKSTART.md`. API and
+command reference material lives in `docs/09_API_CLI_REFERENCE.md`.
+
+Pipeline note: deployment workflows should template `etc/feedser.yaml` during CI/CD,
+injecting environment-specific Mongo credentials and telemetry endpoints. Upcoming
+releases will add Microsoft OAuth (Entra ID) authentication support—track the quickstart
+for integration steps once available.

--- a/StellaOps.Authority.Prompts.txt
+++ b/StellaOps.Authority.Prompts.txt
@@ -0,0 +1,46 @@
+StellaOps Authority Project – Phased Execution Prompts
+
+Teams:
+- Team 1: DevEx / Platform (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.DevEx.md)
+- Team 2: Authority Core Service (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.AuthorityCore.md)
+- Team 3: Plugin Workstream (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.Plugin.md)
+- Team 4: Auth Libraries (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.AuthLibraries.md)
+- Team 5: Feedser Integration (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.Feedser.md)
+- Team 6: CLI (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.CLI.md)
+- Team 7: DevOps / Observability (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.DevOps.md)
+- Team 8: Security Guild (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.Security.md)
+- Team 9: Docs & Enablement (see AGENTS.md, StellaOps.Authority.TODOS.md, StellaOps.Authority.TODOS.Docs.md)
+
+Phase 0 – Bootstrapping
+- Prompt Team 1: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.DevEx.md. Complete FND1 → FND3 (solution scaffold, build props, AuthorityOptions binding). Report when the Authority solution builds clean.”
+- Wait until FND1–FND3 are DONE before continuing.
+
+Phase 1 – Core Foundations
+- Prompt Team 1: “Continue with StellaOps.Authority.TODOS.DevEx.md. Deliver FND4, FND5, and PLG5 (config samples, telemetry constants, plugin config loader).”
+- Prompt Team 2: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.AuthorityCore.md. Implement CORE1 + CORE2 (minimal API host, OpenIddict endpoints). Verify /health and /ready before proceeding.”
+- Prompt Team 3: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.Plugin.md. Execute PLG1–PLG3 (abstractions, plugin loader integration, Mongo-based Standard plugin stub). Coordinate schema details with Team 1.”
+- Do not start Phase 2 until Team 2 finishes CORE1–CORE2 and Team 3 finishes PLG1–PLG3.
+
+Phase 2 – Core Expansion & Libraries
+- Prompt Team 2: “Continue with StellaOps.Authority.TODOS.AuthorityCore.md tasks CORE3–CORE6 (Mongo stores, plugin capability wiring, bootstrap admin APIs).”
+- Prompt Team 3: “Advance PLG4–PLG6 (capability metadata, config validation, plugin developer guide draft).”
+- Prompt Team 4: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.AuthLibraries.md. Deliver LIB1–LIB4 (abstractions, NetworkMaskMatcher, ServerIntegration DI, Auth.Client).”
+- Move to Phase 3 only after CORE3–CORE6, PLG4–PLG6, and LIB1–LIB4 are DONE.
+
+Phase 3 – Integration & Ops
+- Prompt Team 2: “Finish CORE7–CORE10 (telemetry, rate limiting, revocation list, key rotation/JWKS).”
+- Prompt Team 3: “Complete PLG6 handoff and draft PLG7 RFC if bandwidth allows.”
+- Prompt Team 4: “Implement LIB5–LIB6 (Polly integration, packaging metadata).”
+- Prompt Team 5: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.Feedser.md. Execute FSR1–FSR3 (config, auth wiring, bypass masks) then FSR4 docs updates.”
+- Prompt Team 6: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.CLI.md. Deliver CLI1–CLI4 (config, auth commands, bearer injection, docs).”
+- Prompt Team 7: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.DevOps.md. Execute OPS1–OPS5 (Dockerfile/compose, CI pipeline, key rotation tooling, backup docs, monitoring).”
+- Prompt Team 9: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.Docs.md. Draft DOC1–DOC4 in parallel; update DOC5 once Feedser/CLI changes land.”
+- Proceed to Phase 4 only when CORE10, PLG6, LIB6, FSR4, CLI4, OPS5, and DOC4 are complete.
+
+Phase 4 – Security & Final Integration
+- Prompt Team 8: “Read AGENTS.md, StellaOps.Authority.TODOS.md, and StellaOps.Authority.TODOS.Security.md. Execute SEC1–SEC5 (password hashing, audit log review, lockout/rate-limit validation, revocation signing, threat model). Review Feedser/CLI for security compliance.”
+- Prompt Team 5: “Run FSR5 (Authority ↔ Feedser integration tests) using the DevOps compose stack.”
+- Prompt Team 6: “Finalize CLI auth enhancements and ensure tests reflect Security feedback.”
+- Prompt Team 7: “Support integration testing, finalize runbooks, confirm monitoring dashboards.”
+- Prompt Team 9: “Incorporate Security findings, finalize DOC3 migration guide, DOC5 README/quickstart updates, release notes.”
+- Wrap up after SEC5 sign-off and successful FSR5 execution.
--- a/StellaOps.Authority.TODOS.AuthLibraries.md
+++ b/StellaOps.Authority.TODOS.AuthLibraries.md
@@ -0,0 +1,42 @@
+# 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.
--- a/StellaOps.Authority.TODOS.AuthorityCore.md
+++ b/StellaOps.Authority.TODOS.AuthorityCore.md
@@ -0,0 +1,56 @@
+# StellaOps Authority — Core Service Team
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Update status in both TODO trackers.
+
+## Mission
+Design and implement the Authority host (OpenIddict server, token lifecycles, administrative endpoints) on top of the DevEx scaffold, coordinating with Plugin, Library, and Security teams.
+
+## Work Breakdown
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | CORE1 | Wire minimal API host with configuration, logging, plugin discovery, `/health` + `/ready`. | DevEx FND1–FND5 | Manual smoke: `dotnet run` returns healthy responses. |
+| 2 | CORE2 | Configure OpenIddict server endpoints & flows (password, client credentials, refresh, jwks). | CORE1 | Supports HTTPS enforcement toggle via options. |
+| 3 | CORE3 | Implement Mongo repositories for users/clients/scopes/tokens/login attempts. | CORE1 | Collections + indices documented; unit tests for CRUD. |
+| 4 | CORE4 | Integrate plugin contracts (`IIdentityProviderPlugin`, etc.) into DI; load capabilities. | PLG1 | Plugins registered through host on startup. |
+| 5 | CORE5 | Port/customize OpenIddict handlers (password/client creds validation) to use plugin contracts. | CORE4 | Unit tests for success/failure scenarios. |
+| 5a | CORE5A | Add integration tests covering token persistence & revocation via `IAuthorityTokenStore`. | CORE5 | Ensure revoked tokens denied + fixtures for access/reference tokens. |
+| 5b | CORE5B | Document token persistence & enrichment flows for resource servers/plugins. | CORE5 | Docs updated with claim expectations + revocation sync guidance. |
+| 6 | CORE6 | Implement bootstrap admin endpoints (`/internal/users`, `/internal/clients`) secured via bootstrap API key. | CORE5 | Add rate limiting + audit logs. |
+| 7 | CORE7 & CORE8 | Add structured logging, OTEL spans, and ASP.NET rate limiting for `/token`, `/authorize`. | CORE5 | Verify via integration tests, metrics exported. |
+| 8 | CORE9 | Implement token revocation + signed offline revocation manifest generation hooks. | CORE5 | CLI call returns signed JSON; tests confirm revoked tokens denied. |
+| 9 | CORE10 | Configure signing/encryption key rotation, JWKS publishing, certificate loader. | CORE5 | Document rotation steps; integration test covers key rollover. |
+
+## Implementation Notes
+- All Mongo repositories must align with offline-first design (no TTL for critical data unless configurable).  
+- Expose metrics counters (issued tokens, failed attempts) for DevOps consumption.  
+- Coordinate with Security Guild for password hashing options (Argon2 vs PBKDF2), lockout thresholds.  
+- Ensure plugin capability metadata is honored (e.g., if plugin lacks password support, reject password grants gracefully).  
+- Provide integration hooks for future LDAP plugin (capability flag + TODO comment).
+
+## Status
+
+- [x] CORE1 – Completed 2025-10-09. Minimal API host loads validated configuration, configures Serilog, registers plugins, and exposes `/health` + `/ready`.
+- [x] CORE2 – Completed 2025-10-09. OpenIddict server configured with required endpoints, token lifetimes, sliding refresh tokens, and Development-only HTTPS relaxation.
+- [x] CORE3 – Completed 2025-10-09. Mongo storage project created with indexed Authority collections, repositories, and bootstrap migration runner.
+- [ ] CORE4 – Not started.
+- [x] CORE5 – Completed 2025-10-10 with client-credentials validation, token validation handlers, and token persistence wired through plugin contracts.
+- [ ] CORE5A – Pending integration tests for token persistence/revocation behaviour (QA + BE-Auth pairing).
+- [ ] CORE5B – Pending documentation refresh covering claims enrichment + token store expectations.
+- [x] CORE6 – Completed 2025-10-10. Bootstrap admin APIs behind API key provison users and clients through plugin stores.
+- [ ] CORE7 – Not started.
+- [ ] CORE8 – Not started.
+- [ ] CORE9 – Not started.
+- [ ] CORE10 – Not started.
+
+## Deliverables
+- `StellaOps.Authority` project with tested endpoints and handlers.  
+- Repository docs summarizing API responses (shared with Docs team).  
+- Integration tests (Authority-only) verifying token issuance + revocation.  
+- Audit logging implemented (structured with trace IDs).
+
+## Coordination
+- Daily stand-up with Plugin + Libraries teams until CORE5 complete (met objective 2025-10-10).  
+- Notify DevOps when `/token` contract stabilizes (OPS pipeline).  
+- Work with Docs to capture endpoint behavior for `docs/11_AUTHORITY.md`.  
+- Review PRs from Plugin & Libraries teams affecting Authority host.
--- a/StellaOps.Authority.TODOS.CLI.md
+++ b/StellaOps.Authority.TODOS.CLI.md
@@ -0,0 +1,35 @@
+# StellaOps Authority — CLI Team
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Keep status aligned in all trackers.
+
+## Mission
+Enable `stellaops-cli` to authenticate against StellaOps Authority, manage tokens, and surface auth-related UX for operators.
+
+## Task Queue
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | CLI1 | Extend `StellaOpsCliOptions` and configuration bootstrap to include Authority settings (AuthorityUrl, ClientId/Secret, Username/Password). | LIB4 | **DONE (2025-10-10)** – Options bind authority fields, env fallbacks documented, and cache directory defaults to `~/.stellaops/tokens`. |
+| 2 | CLI2 | Implement `auth` command group (`login`, `logout`, `status`) using `StellaOps.Auth.Client`. | CLI1, LIB4 | **DONE (2025-10-10)** – Commands support client-credentials/password flows, force re-auth, and surface status output. |
+| 3 | CLI3 | Ensure all backend calls attach bearer tokens; handle 401/403 with clear messaging and retry guidance. | CLI2, LIB2 | **DONE (2025-10-10)** – Backend client now resolves cached tokens via shared helper and attaches Authorization headers on every call. |
+| 4 | CLI4 | Update help text and docs (quickstart + API reference) to describe new auth workflow. | CLI1–CLI3 | Coordinate with Docs team for final copy. |
+| 5 | OPTIONAL | Add `auth whoami` to display token scopes/expiry (post-MVP if time allows). | CLI2 | Non-blocking enhancement. |
+
+## Implementation Notes
+- Token cache path defaults to `~/.stellaops/tokens`; allow override via config.  
+- Handle offline mode gracefully (cached token reuse, helpful errors).  
+- Provide verbose logging around token acquisition (without dumping secrets).  
+- Support non-interactive mode (env vars) for CI pipelines.  
+- Align CLI exit codes with backend problem types (401 -> exit 10, etc.).
+
+## Deliverables
+- Updated CLI project + tests.  
+- Docs/help updates referencing Authority integration.  
+- Sample command snippets for operators (login, job trigger with scope).  
+- Changelog entry describing auth changes.
+
+## Coordination
+- Collaborate with Auth Libraries team to stabilize client API.  
+- Sync with Feedser integration to ensure required scopes align.  
+- Provide feedback to Authority Core on error payloads for better CLI UX.  
+- Work with Docs team for documentation rollout.
--- a/StellaOps.Authority.TODOS.DevEx.md
+++ b/StellaOps.Authority.TODOS.DevEx.md
@@ -0,0 +1,35 @@
+# StellaOps Authority — DevEx / Platform Workstream
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this file.  
+> Keep task status synced in both TODO trackers whenever items move (TODO → DOING → DONE/BLOCKED).
+
+## Scope
+- Repository scaffolding, shared configuration plumbing, sample configs, telemetry constants.  
+- Provide the baseline everyone else builds on; unblock quickly, announce breaking changes on the shared channel.
+
+## Deliverables & Checklist
+
+| Order | Task ID | Description | Dependencies | Notes |
+|-------|---------|-------------|--------------|-------|
+| 1 | FND1 | Create `src/StellaOps.Authority` solution layout (Authority host, Plugins.Abstractions, Plugin.Standard stub, Auth libraries). | none | **DONE** – Solution scaffolding live with net10.0 preview defaults + project references. |
+| 2 | FND2 | Update repository build props/targets for new projects; ensure analyzers + nullable + treat warnings as errors. | FND1 | **DONE** – Directory.Build props/targets extended; root `StellaOps.sln` added (root build still surfaced existing Feedser compile failures). |
+| 3 | FND3 | Extend `StellaOps.Configuration` with `StellaOpsAuthorityOptions`, binder, validation stubs. | FND1 | **DONE** – Options schema + bootstrap helper + unit tests validating binding/normalisation. |
+| 4 | FND4 | Publish `etc/authority.yaml.sample` (with plugin toggles) + README mention. | FND3 | **DONE** – Sample config added with env var guidance; README + quickstart updated. |
+| 5 | FND5 | Register OTEL resource constants (service.name = `stellaops-authority`, etc.). | FND3 | **DONE** – Authority telemetry constants helper published for shared use. |
+| 6 | PLG5 | Define plugin config directory structure (`etc/authority.plugins/*.yaml`), loader helpers, sample files. | FND3 | **DONE** – Schema + loader shipped, standard/ldap samples published. |
+| 7 | OPS1 (support) | Pair with DevOps on Dockerfile/compose scaffolding to ensure directories, config names match. | FND4 | **DONE** – Provided distroless Dockerfile/compose guidance in `ops/authority/` for DevOps handoff. |
+
+### Exit Criteria
+- `dotnet build` succeeds from repo root with new projects.  
+- Configuration sample + docs referenced in README/Authority TODO file.  
+- Telemetry/resource constants ready for Authority Core team.  
+- Plugin config loader available before Plugin Team begins feature work.
+
+### Risks / Mitigations
+- **Risk:** Build props drift. → Run `dotnet format --verify-no-changes` before handoff.  
+- **Risk:** Config breaking changes mid-implementation. → Version `StellaOpsAuthorityOptions` and communicate via Slack + TODO updates.
+
+### Coordination
+- Daily async update until FND3 complete.  
+- Hand off AuthorityOptions schema to all other teams once finalized (tag repository issue).  
+- Keep an eye on PR queue—DevEx reviews required for structure/config changes.
--- a/StellaOps.Authority.TODOS.DevOps.md
+++ b/StellaOps.Authority.TODOS.DevOps.md
@@ -0,0 +1,36 @@
+# StellaOps Authority — DevOps & Observability Team
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Reflect status changes in both TODO trackers.
+
+## Mission
+Deliver deployable artefacts, CI/CD automation, runtime observability, and operational runbooks for StellaOps Authority.
+
+## Task Matrix
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | OPS1 | Author distroless Dockerfile + docker-compose sample (Authority + Mongo + optional Redis). | FND4, CORE1 | **DONE (DevEx scaffold)** – see `ops/authority/` Dockerfile + compose; verify with production secrets before release. |
+| 2 | OPS2 | Extend CI workflows (build/test/publish) for Authority + auth libraries (dotnet build/test, docker build, artefact publish). | OPS1 | **DONE** – Authority build/test/publish integrated into `.gitea/workflows/build-test-deploy.yml`. |
+| 3 | OPS3 | Implement key rotation script/CLI and wire pipeline job (manual trigger) to rotate signing keys + update JWKS. | CORE10 | Document rotation process + store secrets securely. |
+| 4 | OPS4 | Document backup/restore for Authority Mongo collections, plugin configs, key material. | CORE3 | Produce runbook in `/docs/ops`. |
+| 5 | OPS5 | Define monitoring metrics/alerts (token issuance failure rate, lockout spikes, bypass usage). Provide dashboards (Prometheus/Otel). | CORE7 | Share Grafana JSON or equivalent. |
+| 6 | SUPPORT | Assist other teams with docker-compose variations for integration tests (Feedser, CLI). | OPS1, FSR5 | Provide templates + guidance. |
+
+## Implementation Notes
+- Container image must remain offline-friendly (no package installs at runtime).  
+- Compose sample should include environment variable settings referencing `etc/authority.yaml`.  
+- Store key rotation artefacts in secure storage (vault/secrets).  
+- Align metrics naming with existing StellaOps conventions.  
+- Provide fallback instructions for air-gapped deployments (manual image load, offline key rotation).
+
+## Deliverables
+- Dockerfile(s), compose stack, and documentation.  
+- Updated CI pipeline definitions.  
+- Runbooks for rotation, backup, restore.  
+- Monitoring/alerting templates.
+
+## Coordination
+- Sync with DevEx on configuration paths + plugin directories.  
+- Coordinate with Authority Core regarding key management endpoints.  
+- Work with Feedser Integration + CLI teams on integration test environments.  
+- Engage Security Guild to review key rotation + secret storage approach.
--- a/StellaOps.Authority.TODOS.Docs.md
+++ b/StellaOps.Authority.TODOS.Docs.md
@@ -0,0 +1,36 @@
+# StellaOps Authority — Docs & Enablement Plan
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Keep progress synchronized across trackers.
+
+## Mission
+Produce operator and developer documentation for the new Authority stack, including configuration guides, API references, plugin tutorials, migration playbooks, and release notes.
+
+## Task Pipeline
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | DOC1 | Draft `docs/11_AUTHORITY.md` (architecture overview, configuration, plugin model, deployment scenarios). | FND4, CORE1 | Reviewed by DevEx + Authority Core. |
+| 2 | DOC2 | Generate API reference snippets for `/token`, `/jwks`, `/introspect`, `/revoke` (OpenAPI fragment + human-readable table). | CORE2, LIB4 | Linked from docs + README. |
+| 3 | DOC3 | Write migration guide for Feedser moving from anonymous to secured mode (staged rollout, config updates). | FSR1–FSR3 | Includes rollback plan + FAQ. |
+| 4 | DOC4 | Create plugin developer how-to (leveraging Plugin Team notes) covering packaging, capability flags, logging. | PLG1–PLG6 | **READY FOR DOCS REVIEW (2025-10-10)** – `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` aligned with PLG6 scope; pending Docs copy-edit, diagram export, and LDAP RFC cross-linking. |
+| 5 | DOC5 | Update root README, quickstarts (`docs/10_FEEDSER_CLI_QUICKSTART.md`), CLI help text references. | CLI4, FSR4 | Make sure new links validated. |
+| 6 | Cross | Collaborate on inline XML docs for public APIs across libraries. | LIB1–LIB5 | Ensure DocFX/IntelliSense friendly summaries. |
+
+## Implementation Notes
+- Maintain offline-friendly instructions (no implicit internet requirements).  
+- Highlight security-critical steps (bootstrap credentials, key rotation) in callouts.  
+- Include environment-variable tables for configuration.  
+- Provide diagrams where useful (architecture, plugin flow).  
+- Prepare release note entry summarizing Authority MVP deliverables and upgrade steps.
+
+## Deliverables
+- New documentation pages + updated existing guides.  
+- OpenAPI snippet (JSON/YAML) committed to repo.  
+- Migration checklist for operators.  
+- Plugin developer tutorial ready for community/internal teams.
+
+## Coordination
+- Attend cross-team syncs to capture latest API contracts.  
+- Request reviews from respective teams (Authority Core, Plugin, CLI, Security).  
+- Work with DevEx to ensure docs packaged in Offline Kit if applicable.  
+- Update docs as soon as breaking changes occur—subscribe to relevant PRs.
--- a/StellaOps.Authority.TODOS.Feedser.md
+++ b/StellaOps.Authority.TODOS.Feedser.md
@@ -0,0 +1,35 @@
+# StellaOps Authority — Feedser Integration Team
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Update both TODO trackers as tasks progress.
+
+## Mission
+Adopt the new authority stack inside Feedser: configure authentication, enforce scopes, update configuration, and validate end-to-end flows.
+
+## Task Timeline
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | FSR1 | Extend `etc/feedser.yaml` with Authority configuration block (issuer, client credentials, bypass masks, scopes). | DevEx FND4, LIB2 | Sample config + docs updated. |
+| 2 | FSR2 | Update Feedser WebService startup to use `AddStellaOpsResourceServerAuthentication`; annotate endpoints with `[Authorize]` and scope policies. | LIB2 | **DONE (2025-10-10)** – Auth wiring is optional but enabled via config; `/jobs*` endpoints demand `feedser.jobs.trigger` and tests cover bypass mode. |
+| 3 | FSR3 | Implement bypass mask handling for on-host cron jobs; log when mask used. | FSR2, LIB3 | Configurable via YAML; integration test ensures mask respected. |
+| 4 | FSR4 | Refresh Feedser docs (quickstart, operator guide) to explain auth requirements + config knobs. | FSR1–FSR3 | Coordinate with Docs team for final wording. |
+| 5 | FSR5 | Build integration test harness (Authority + Feedser docker-compose) verifying token issuance and job triggering. | CORE1–CORE5, LIB4 | CI job produces pass/fail artefact. |
+
+## Implementation Notes
+- Add feature flag to allow temporary anonymous mode for staged rollout (document sunset date).  
+- Ensure CLI + API docs reference required scopes and sample client creation.  
+- Logs should capture client ID, user ID, and scopes when jobs triggered for audit (without leaking secrets).  
+- Avoid coupling tests to specific plugin implementations—use Standard plugin via configuration.  
+- Share any new scopes/policies with Auth Libraries and Docs teams.
+
+## Deliverables
+- Updated Feedser configuration + startup code.  
+- Documentation updates in `docs/10_FEEDSER_CLI_QUICKSTART.md` and `docs/11_AUTHORITY.md` (in partnership with Docs team).  
+- Integration tests executed in CI (Authority + Feedser).  
+- Rollout checklist for existing deployments (feature flag, config changes).
+
+## Coordination
+- Sync with Authority Core on policy naming (`feedser.jobs.trigger`, `feedser.merge`).  
+- Coordinate with CLI team for shared sample configs.  
+- Work closely with DevOps to integrate integration tests into pipeline.  
+- Notify Security Guild once bypass masks implemented for review.
--- a/StellaOps.Authority.TODOS.Plugin.md
+++ b/StellaOps.Authority.TODOS.Plugin.md
@@ -0,0 +1,38 @@
+# StellaOps Authority — Plugin Workstream
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this document. Sync status across all trackers.
+
+## Scope
+Deliver the plugin abstraction layer and the default Mongo-backed identity plugin (`StellaOps.Authority.Plugin.Standard`), plus lay groundwork for future LDAP integration.
+
+## Task Plan
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | PLG1 | Implement plugin abstractions: `IIdentityProviderPlugin`, `IUserCredentialStore`, `IClaimsEnricher`, `IClientProvisioningStore`, result models, constants. | DevEx FND1 | **DONE** – Abstractions published with XML docs and unit tests covering success/failure factories. |
+| 2 | PLG2 | Integrate abstractions with plugin host (DI registration via `IAuthorityPluginRegistrar`). Emit diagnostics for load failures. | PLG1 | **DONE** – Authority host loads registrars, logs registration summary, and unit tests cover success/missing cases. |
+| 3 | PLG3 | Build Mongo-backed `Plugin.Standard` implementing password auth, lockout, claim enrichment, admin seeding. | CORE3 | **DONE** – Standard plugin binds options, enforces password policy/lockout, seeds bootstrap user, and ships integration/unit tests. |
+| 4 | PLG4 | Define capability metadata (supportsPassword, supportsMfa, supportsClientProvisioning). Update plugin registration to publish metadata. | PLG3 | **DONE (2025-10-10)** – Capability descriptors validated; Standard plugin enforces password flag and registry exposes aggregated metadata to the host. |
+| 5 | PLG5 (support) | Collaborate with DevEx on plugin config schema (`etc/authority.plugins/*.yaml`). Implement config parser + validation. | DevEx PLG5 | Provide typed options class + tests. |
+| 6 | PLG6 | Author plugin developer guide (structure, packaging, capability flags, logging expectations). | PLG1–PLG5 | **READY FOR DOCS REVIEW (2025-10-10)** – Guide finalised, includes capability metadata usage, ops alignment, and packaging checklist; handoff blocked only on Docs copy-edit + diagram export. |
+| 7 | PLG7 (backlog design) | Produce technical RFC for future `Plugin.Ldap` (data flows, dependencies, TODO list). | PLG1–PLG4 | **RFC DRAFTED (2025-10-10)** – `docs/rfcs/authority-plugin-ldap.md` outlines architecture, configuration schema, implementation plan; awaiting guild review & sign-off. |
+
+## Implementation Notes
+- Mongo plugin must support offline bootstrap: optional JSON file with initial users/clients hashed offline.  
+- Provide extensibility points for password hashing algorithm (allow Security team to swap Argon2).  
+- Ensure plugin logging leverages Authority logger, no console writes.  
+- Document expected configuration keys for plugin settings (`passwordPolicy`, `seedUsers`, etc.).  
+- Validate plugin configuration early at startup; fail fast with actionable errors.
+
+## Deliverables
+- `StellaOps.Authority.Plugins.Abstractions` project.  
+- `StellaOps.Authority.Plugin.Standard` project with tests + seed data sample.  
+- Plugin dev documentation + sample configuration files.  
+- Diagnostic logging verifying plugin load, capabilities, configuration.  
+- Future plugin RFC for LDAP integration.
+
+## Coordination
+- Coordinate with Authority Core for capability usage in handlers.  
+- Work with Security Guild on password hash settings/lockout thresholds.  
+- Notify DevEx when configuration schema changes.  
+- Review Docs PR for plugin developer guide.
--- a/StellaOps.Authority.TODOS.Security.md
+++ b/StellaOps.Authority.TODOS.Security.md
@@ -0,0 +1,36 @@
+# StellaOps Authority — Security Guild Plan
+
+> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Track progress in both TODO files.
+
+## Mission
+Define and verify the security posture of StellaOps Authority: password/secret policies, audit logging, throttling, threat modelling, and offline revocation guarantees.
+
+## Task Breakdown
+
+| Order | Task IDs | Description | Dependencies | Acceptance |
+|-------|----------|-------------|--------------|------------|
+| 1 | SEC1 | Select and configure password hashing (Argon2 preferred) + identity lockout parameters; contribute config defaults. | PLG3, CORE3 | Hash verified via unit test + red team review. |
+| 2 | SEC2 | Specify audit log schema/content (principal, client, scopes, IP) and ensure Authority Core implementation meets requirements. | CORE5–CORE7 | Review sample logs; ensure PII handled safely. |
+| 3 | SEC3 | Define lockout & rate limit policies (per user/IP) and validate implementation in Authority Core. | CORE8 | Test harness proves lockouts triggered appropriately. |
+| 4 | SEC4 | Design offline revocation list format + signing procedure; review implementation with Core/DevOps. | CORE9, OPS3 | Provide verification script for downstream systems. |
+| 5 | SEC5 | Conduct threat model / security review (STRIDE) covering plugins, token flows, admin endpoints; produce mitigation backlog if needed. | CORE1–CORE10 | Document stored in `/docs/security`. |
+| 6 | Oversight | Perform security review of CLI/Feedser integration changes (token handling, bypass masks). | FSR2, CLI2 | Approve PRs or request hardening changes. |
+
+## Implementation Notes
+- Require secrets (client, bootstrap API keys) to meet minimum entropy; document rotation expectations.  
+- Ensure bypass mask usage is fully logged + alertable.  
+- Recommend default TLS cipher suites for Authority deployments.  
+- Validate plugin capability metadata doesn’t expose insecure combinations (e.g., plugin without password support cannot be selected for password grant).  
+- Develop checklist for production readiness (penetration test, log review, key rotation rehearsal).
+
+## Deliverables
+- Security configuration recommendations (encoded in options + documentation).  
+- Approved audit log schema & sample records.  
+- Threat model document + mitigation backlog (if gaps discovered).  
+- Sign-off memo to enable production rollout.
+
+## Coordination
+- Work closely with Authority Core and Plugin teams during implementation; request changes early.  
+- Pair with DevOps on key rotation / secret storage solutions.  
+- Review Docs to ensure operator guidance includes security-critical steps.  
+- Attend weekly Auth Guild sync to surface risks/blockers.
--- a/StellaOps.Authority.TODOS.md
+++ b/StellaOps.Authority.TODOS.md
@@ -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.
--- a/docs/10_FEEDSER_CLI_QUICKSTART.md
+++ b/docs/10_FEEDSER_CLI_QUICKSTART.md
@@ -0,0 +1,232 @@
+# 10 · Feedser + CLI Quickstart
+
+This guide walks through configuring the Feedser web service and the `stellaops-cli`
+tool so an operator can ingest advisories, merge them, and publish exports from a
+single workstation. It focuses on deployment-facing surfaces only (configuration,
+runtime wiring, CLI usage) and leaves connector/internal customization for later.
+
+---
+
+## 0 · Prerequisites
+
+- .NET SDK **10.0.100-preview** (matches `global.json`)
+- MongoDB instance reachable from the host (local Docker or managed)
+- `trivy-db` binary on `PATH` for Trivy exports (and `oras` if publishing to OCI)
+- Plugin assemblies present in `PluginBinaries/` (already included in the repo)
+- Optional: Docker/Podman runtime if you plan to run scanners locally
+
+> **Tip** – air-gapped installs should preload `trivy-db` and `oras` binaries into the
+> runner image since Feedser never fetches them dynamically.
+
+---
+
+## 1 · Configure Feedser
+
+1. Copy the sample config to the expected location (CI/CD pipelines can stamp values
+   into this file during deployment—see the “Deployment automation” note below):
+
+   ```bash
+   mkdir -p etc
+   cp etc/feedser.yaml.sample etc/feedser.yaml
+   ```
+
+2. Edit `etc/feedser.yaml` and update the MongoDB DSN (and optional database name).
+   The default template configures plug-in discovery to look in `PluginBinaries/`
+   and disables remote telemetry exporters by default.
+
+3. (Optional) Override settings via environment variables. All keys are prefixed with
+   `FEEDSER_`. Example:
+
+   ```bash
+   export FEEDSER_STORAGE__DSN="mongodb://user:pass@mongo:27017/feedser"
+   export FEEDSER_TELEMETRY__ENABLETRACING=false
+   ```
+
+4. Start the web service from the repository root:
+
+   ```bash
+ dotnet run --project src/StellaOps.Feedser.WebService
+  ```
+
+   On startup Feedser validates the options, boots MongoDB indexes, loads plug-ins,
+   and exposes:
+
+   - `GET /health` – returns service status and telemetry settings
+   - `GET /ready` – performs a MongoDB `ping`
+   - `GET /jobs` + `POST /jobs/{kind}` – inspect and trigger connector/export jobs
+
+   > **Security note** – authentication is not wired yet; guard the service with
+   > network controls or a reverse proxy until auth middleware ships.
+
+### Authority companion configuration (preview)
+
+1. Copy the Authority sample configuration:
+
+   ```bash
+   cp etc/authority.yaml.sample etc/authority.yaml
+   ```
+
+2. Update the issuer URL, token lifetimes, and plug-in descriptors to match your
+   environment. Authority expects per-plugin manifests in `etc/authority.plugins/`;
+   sample `standard.yaml` and `ldap.yaml` files are provided as starting points.
+   For air-gapped installs keep the default plug-in binary directory
+   (`../PluginBinaries/Authority`) so packaged plug-ins load without outbound access.
+
+3. Environment variables prefixed with `STELLAOPS_AUTHORITY_` override individual
+   fields. Example:
+
+   ```bash
+   export STELLAOPS_AUTHORITY__ISSUER="https://authority.stella-ops.local"
+   export STELLAOPS_AUTHORITY__PLUGINDIRECTORIES__0="/srv/authority/plugins"
+   ```
+
+---
+
+## 2 · Configure the CLI
+
+The CLI reads configuration from JSON/YAML files *and* environment variables. The
+defaults live in `src/StellaOps.Cli/appsettings.json` and expect overrides at runtime.
+
+| Setting | Environment variable | Default | Purpose |
+| ------- | -------------------- | ------- | ------- |
+| `BackendUrl` | `STELLAOPS_BACKEND_URL` | _empty_ | Base URL of the Feedser web service |
+| `ApiKey` | `API_KEY` | _empty_ | Reserved for future auth; keep empty today |
+| `ScannerCacheDirectory` | `STELLAOPS_SCANNER_CACHE_DIRECTORY` | `scanners` | Local cache folder |
+| `ResultsDirectory` | `STELLAOPS_RESULTS_DIRECTORY` | `results` | Where scan outputs are written |
+
+Example bootstrap:
+
+```bash
+export STELLAOPS_BACKEND_URL="http://localhost:5000"
+export STELLAOPS_RESULTS_DIRECTORY="$HOME/.stellaops/results"
+dotnet run --project src/StellaOps.Cli -- db merge
+```
+
+To persist configuration, you can create `stellaops-cli.yaml` next to the binary or
+rely on environment variables for ephemeral runners.
+
+---
+
+## 3 · Operating Workflow
+
+1. **Trigger connector fetch stages**
+
+   ```bash
+   dotnet run --project src/StellaOps.Cli -- db fetch --source osv --stage fetch
+   dotnet run --project src/StellaOps.Cli -- db fetch --source osv --stage parse
+   dotnet run --project src/StellaOps.Cli -- db fetch --source osv --stage map
+   ```
+
+   Use `--mode resume` when continuing from a previous window:
+
+   ```bash
+   dotnet run --project src/StellaOps.Cli -- db fetch --source redhat --stage fetch --mode resume
+   ```
+
+2. **Merge canonical advisories**
+
+   ```bash
+   dotnet run --project src/StellaOps.Cli -- db merge
+   ```
+
+3. **Produce exports**
+
+   ```bash
+   # JSON tree (vuln-list style)
+   dotnet run --project src/StellaOps.Cli -- db export --format json
+
+   # Trivy DB (delta example)
+   dotnet run --project src/StellaOps.Cli -- db export --format trivy-db --delta
+   ```
+
+   Feedser always produces a deterministic OCI layout. The first run after a clean
+   bootstrap emits a **full** baseline; subsequent `--delta` runs reuse the previous
+   baseline’s blobs when only JSON manifests change. If the exporter detects that a
+   prior delta is still active (i.e., `LastDeltaDigest` is recorded) it automatically
+   upgrades the next run to a full export and resets the baseline so operators never
+   chain deltas indefinitely. The CLI exposes `--publish-full/--publish-delta` (for
+   ORAS pushes) and `--include-full/--include-delta` (for offline bundles) should you
+   need to override the defaults interactively.
+
+   **Smoke-check delta reuse:** after the first baseline completes, run the export a
+   second time with `--delta` and verify that the new directory reports `mode=delta`
+   while reusing the previous layer blob.
+
+   ```bash
+   export_root=${FEEDSER_EXPORT_ROOT:-exports/trivy}
+   base=$(ls -1d "$export_root"/* | sort | tail -n2 | head -n1)
+   delta=$(ls -1d "$export_root"/* | sort | tail -n1)
+
+   jq -r '.mode,.baseExportId' "$delta/metadata.json"
+
+   base_manifest=$(jq -r '.manifests[0].digest' "$base/index.json")
+   delta_manifest=$(jq -r '.manifests[0].digest' "$delta/index.json")
+   printf 'baseline manifest: %s\ndelta manifest:    %s\n' "$base_manifest" "$delta_manifest"
+
+   layer_digest=$(jq -r '.layers[0].digest' "$base/blobs/sha256/${base_manifest#sha256:}")
+   cmp "$base/blobs/sha256/${layer_digest#sha256:}" \
+       "$delta/blobs/sha256/${layer_digest#sha256:}"
+   ```
+
+   `cmp` returning exit code `0` confirms the delta export reuses the baseline’s
+   `db.tar.gz` layer instead of rebuilding it.
+
+4. **Manage scanners (optional)**
+
+   ```bash
+   dotnet run --project src/StellaOps.Cli -- scanner download --channel stable
+   dotnet run --project src/StellaOps.Cli -- scan run --entry scanners/latest/Scanner.dll --target ./sboms
+   dotnet run --project src/StellaOps.Cli -- scan upload --file results/scan-001.json
+   ```
+
+Add `--verbose` to any command for structured console logs. All commands honour
+`Ctrl+C` cancellation and exit with non-zero status codes when the backend returns
+a problem document.
+
+---
+
+## 4 · Verification Checklist
+
+- Feedser `/health` returns `"status":"healthy"` and Storage bootstrap is marked
+  complete after startup.
+- CLI commands return HTTP 202 with a `Location` header (job tracking URL) when
+  triggering Feedser jobs.
+- Export artefacts are materialised under the configured output directories and
+  their manifests record digests.
+- MongoDB contains the expected `document`, `dto`, `advisory`, and `export_state`
+  collections after a run.
+
+---
+
+## 5 · Deployment Automation
+
+- Treat `etc/feedser.yaml.sample` as the canonical template. CI/CD should copy it to
+  the deployment artifact and replace placeholders (DSN, telemetry endpoints, cron
+  overrides) with environment-specific secrets.
+- Keep secret material (Mongo credentials, OTLP tokens) outside of the repository;
+  inject them via secret stores or pipeline variables at stamp time.
+- When building container images, include `trivy-db` (and `oras` if used) so air-gapped
+  clusters do not need outbound downloads at runtime.
+
+---
+
+## 5 · Next Steps
+
+- Introduce authentication/authorization in the web service before exposing it on
+  shared networks.
+- Automate the workflow above via CI/CD (compose stack or Kubernetes CronJobs).
+- Pair with the Feedser connector teams when enabling additional sources so their
+  module-specific requirements are pulled in safely.
+
+---
+
+## 6 · Microsoft Authentication Integration (Planned)
+
+- The Feedser web service will integrate with the Microsoft identity stack (Entra ID)
+  using OAuth 2.0. Expect additional configuration keys for authority URLs, client
+  IDs/secrets, and audience scopes once the implementation lands.
+- CLI commands already pass `Authorization` headers when credentials are supplied.
+  When auth is enabled, point `stellaops-cli` at the token issuer (client credentials
+  flow) or run it behind a proxy that injects bearer tokens.
+- Keep network-facing deployments behind reverse proxies or firewalls until the
+  authentication middleware ships and is fully validated.
--- a/etc/feedser.yaml.sample
+++ b/etc/feedser.yaml.sample
@@ -0,0 +1,55 @@
+# Feedser configuration template for StellaOps deployments.
+# Copy to ../etc/feedser.yaml (relative to the web service content root)
+# and adjust the values to match your environment. Environment variables
+# (prefixed with FEEDSER_) override these settings at runtime.
+
+storage:
+  driver: mongo
+  # Mongo connection string. Use SRV URI or standard connection string.
+  dsn: "mongodb://feedser:feedser@mongo:27017/feedser?authSource=admin"
+  # Optional database name; defaults to the name embedded in the DSN or 'feedser'.
+  database: "feedser"
+  # Mongo command timeout in seconds.
+  commandTimeoutSeconds: 30
+
+plugins:
+  # Feedser resolves plug-ins relative to the content root; override as needed.
+  baseDirectory: ".."
+  directory: "PluginBinaries"
+  searchPatterns:
+    - "StellaOps.Feedser.Plugin.*.dll"
+
+telemetry:
+  enabled: true
+  enableTracing: false
+  enableMetrics: false
+  enableLogging: true
+  minimumLogLevel: "Information"
+  serviceName: "stellaops-feedser"
+  # Configure OTLP endpoint when shipping traces/metrics/logs out-of-band.
+  otlpEndpoint: ""
+  # Optional headers for OTLP exporters, for example authentication tokens.
+  otlpHeaders: {}
+  # Attach additional resource attributes to telemetry exports.
+  resourceAttributes:
+    deployment.environment: "local"
+  # Emit console exporters for local debugging.
+  exportConsole: true
+
+authority:
+  enabled: false
+  # Issuer advertised by StellaOps Authority (e.g. https://authority.stella-ops.local).
+  issuer: "https://authority.stella-ops.local"
+  # Optional explicit metadata address; defaults to {issuer}/.well-known/openid-configuration.
+  metadataAddress: ""
+  requireHttpsMetadata: true
+  backchannelTimeoutSeconds: 30
+  tokenClockSkewSeconds: 60
+  audiences:
+    - "api://feedser"
+  requiredScopes:
+    - "feedser.jobs.trigger"
+  # Networks allowed to bypass authentication (loopback by default for on-host cron jobs).
+  bypassNetworks:
+    - "127.0.0.1/32"
+    - "::1/128"