47665927ab
Closes the bootstrap gap two parallel QA agents surfaced on 2026-04-22: fresh Authority DBs lacked the `default` tenant row so setup-wizard admin creation failed with users_tenant_id_fkey and /connect/token returned invalid_grant. Fix is on the migration path per AGENTS.md §2.7; the init script stays seeds-only as established in SPRINT_20260422_003. - New embedded migration 003_seed_default_tenants.sql performs `INSERT ... ON CONFLICT (tenant_id) DO NOTHING` for `default` and `installation`. Numeric prefix (not S-prefix) so the migration runner's Startup category auto-applies it; S-prefix files route to Seed category which is intentionally manual-only per StartupMigrationHost.cs:158. - `default` is strictly required (Authority's StandardPluginBootstrapper.DefaultTenantId; /internal/users bootstrap inserts under this FK). `installation` is not Authority-FK-referenced today but matches the empirical workaround both QA agents converged on and serves as defense for cross-service inserts that join authority.tenants.tenant_id. Fresh-volume verification (docs/qa/authority-default-tenant-20260422/): 1. docker compose down -v (20 volumes removed incl. compose_postgres-data) 2. docker compose up -d — 62 containers, Authority healthy in ~15s. 3. Startup log: applying 001 (144ms) → 002 (13ms) → 003 (7ms). authority.tenants contains default + installation. 4. POST /api/v1/setup/sessions → 201; database/valkey/migrations prereqs ran; admin/execute with admin/Admin@Stella2026! → 200 "Bootstrap administrator 'admin' ensured successfully." 5. POST /connect/token (password, stellaops-cli, ui.admin openid) → 200 + JWT carrying role=admin, stellaops:tenant=default. 6. docker compose restart authority → "Database is up to date for Authority." Clean no-op. Docs: docs/modules/authority/architecture.md §1.1 "Seeded bootstrap tenants (migration-owned)". Cross-link added to the archived prior sprint's Decisions & Risks so the lineage is traceable. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
StellaOps Authority
Authority is the platform OIDC/OAuth2 control plane that mints short-lived, sender-constrained operational tokens (OpToks) for every StellaOps service and tool.
Latest updates (2026-04-16)
- Authority no longer uses live in-memory DPoP replay or nonce state outside
Testing; non-testing DPoP-enabled runtime now requires durable Valkey-backed state and restart-survival proof exists inAuthorityDpopRuntimeTests. - Added gap remediation package for AU1–AU10 and RR1–RR10 (31-Nov-2025 FINDINGS) under
docs/modules/authority/gaps/; includes deliverable map + evidence layout. - Sprint tracker
docs/implplan/SPRINT_0314_0001_0001_docs_modules_authority.mdand moduleTASKS.mdmirror status. - Monitoring/observability references consolidated; Grafana JSON remains offline import (
operations/grafana-dashboard.json). - Prior content retained: OpTok/DPoP/mTLS responsibilities, backup/restore, key rotation.
Responsibilities
- Expose device-code, auth-code, and client-credential flows with DPoP or mTLS binding.
- Manage signing keys, JWKS rotation, and PoE integration for plan enforcement.
- Emit structured audit events and enforce tenant-aware scope policies.
- Provide plugin surface for custom identity providers and credential validators.
Key components
StellaOps.Authorityweb host.StellaOps.Authority.Plugin.*extensions for secret stores, identity bridges, and OpTok validation.- Telemetry and audit pipeline feeding Security/Observability stacks.
Integrations & dependencies
- Signer/Attestor for PoE and OpTok introspection.
- CLI/UI for login flows and token management.
- Scheduler/Scanner for machine-to-machine scope enforcement.
Operational notes
- PostgreSQL (schema
authority) for tenant, client, and token state. - Standard plugin bootstrap provisioning retries transient storage failures during startup so first-party local clients converge after PostgreSQL becomes reachable; the first human admin is created through setup, not pre-seeded.
- Key material in KMS/HSM with rotation runbooks (
operations/key-rotation.md). - Monitoring runbook (
operations/monitoring.md) and offline-import Grafana JSON (operations/grafana-dashboard.json).
Related resources
- ./operations/backup-restore.md
- ./operations/key-rotation.md
- ./operations/monitoring.md
- ./operations/grafana-dashboard.json
- ./crypto-provider-contract.md
- ./gaps/2025-12-04-auth-gaps-au1-au10.md
- ./gaps/2025-12-04-rekor-receipt-gaps-rr1-rr10.md
- Sprint/status mirrors:
docs/implplan/SPRINT_0314_0001_0001_docs_modules_authority.md,docs/modules/authority/TASKS.md
Backlog references
- DOCS-SEC-62-001 (scope hardening doc) in ../../TASKS.md.
- AUTH-POLICY-20-001/002 follow-ups in src/Authority/StellaOps.Authority/TASKS.md.
Epic alignment
- Epic 1 – AOC enforcement: enforce OpTok scopes and guardrails supporting raw ingestion boundaries.
- Epic 2 – Policy Engine & Editor: supply policy evaluation/principal scopes and short-lived tokens for evaluator workflows.
- Epic 4 – Policy Studio: integrate approval/promotion signatures and policy registry access controls.
- Epic 14 – Identity & Tenancy: deliver tenant isolation, RBAC hierarchies, and governance tooling for authentication.
Implementation Status
Epic Milestones:
- Epic 1 (AOC enforcement) – Complete: OpTok scopes, guardrails, AOC role templates, and scope policies operational
- Epic 2 (Policy Engine & Editor) – Complete: DPoP validation and mTLS sender-constraint flows operational
- Epic 4 (Policy Studio) – Complete: pack signing policies, approval RBAC, CLI CI token scopes, audit logging
- Epic 14 (Identity & Tenancy) – In progress: tenancy contract published, sovereign crypto provider integration ongoing
- Future (Attestation support) – Not started: DSSE predicate types and verification helpers pending upstream dependencies
Key Technical Decisions:
- DPoP validation on token grants with cnf.jkt inheritance for interactive tokens
- Refresh grants enforce original client cert with x5t#S256 metadata persistence
- Sealed-mode CI gating refuses tokens when sealed install lacks confirmation
- Tenant-scope contract published for cross-module coordination
Risks & Mitigations:
- Sovereign crypto keystore migration in progress, key-loading path updates required
- DSSE predicate schema draft pending coordination with Signer guild
- Provenance harness dependency for verification helpers