docs: UI-driven local setup sprints + module dossier sync

Add SPRINT_20260413_004 (platform UI-only setup bootstrap closure)
with BOOTSTRAP-001..006 delivery tracker, and update sprint 003 and
sprint 20260410-001 execution logs to reflect the completed
persistence / orchestrator / secret-authority work.

Sync module dossiers and operator guides with the new reality: setup
wizard UX, platform-service architecture, CLI setup guide, integrations
architecture + local services, release-orchestrator architecture,
install guide, and compose README.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-14 07:56:45 +03:00
parent 286c1f758a
commit 398d0659eb
12 changed files with 648 additions and 262 deletions

View File

@@ -102,6 +102,54 @@ public interface IIntegrationPlugin
- **Harbor** - Operators provide the Harbor base URL. Stella Ops probes the provider-specific `/api/v2.0/health` route for connection tests and health checks.
- **Docker Registry / GitLab Container Registry** - Operators provide the registry base URL. When the registry responds with `WWW-Authenticate: Bearer ...`, the connector exchanges the configured secret against the advertised token realm and retries with the returned bearer token. The local GitLab registry uses `authref://vault/gitlab#registry-basic`, storing `username:personal-access-token`.
## Secret Authority
The Integrations service now exposes a provider-agnostic Secret Authority boundary for onboarding flows that need to stage credential material before creating an integration.
### Goals
- Keep raw secrets out of the integration catalog.
- Let UI and CLI stage credentials once and receive `authref://...` bindings in return.
- Audit secret bundle creation/update separately from integration CRUD.
- Fail truthfully when a secrets-manager provider is visible but not writable in this release.
### API surface (`/api/v1/secret-authority`)
- `GET /targets`
- Lists tenant-visible secrets-manager integrations that can be used as staging targets.
- Returns integration metadata only: `integrationId`, `name`, `provider`, `endpoint`, `status`, `logicalPathHint`, `supportsWrite`.
- `PUT /bundles/{bundleId}`
- Stages or updates a credential bundle in the selected target.
- Request body: `targetIntegrationId`, optional `logicalPath`, `entries[]`, optional `labels`, `overwrite`.
- Response returns only metadata plus generated authrefs:
- `bundleId`
- `logicalPath`
- `authRefs`
- target provider and endpoint
### Current writer support
- Vault KV v2 is the first shipped writer.
- Other secrets-manager providers remain visible in discovery, but write attempts fail explicitly with `501 not_implemented`.
- For Vault targets, the service writes directly to the target secret engine and returns authrefs such as:
- `authref://vault/gitlab/server#access-token`
- `authref://vault/gitlab/registry#registry-basic`
### Security model
- Read policy: `integration:read` via `IntegrationPolicies.SecretAuthorityRead`
- Write policy: `integration:write` via `IntegrationPolicies.SecretAuthorityWrite`
- Secret bundle writes emit the `upsert_secret_bundle` audit action in the Integrations audit module.
- The API never echoes raw secret values back to the caller.
### UI / CLI usage
- The Web Integrations Hub uses Secret Authority for inline GitLab Server, GitLab CI, and GitLab Container Registry onboarding.
- The CLI exposes the same flow through:
- `stella config integrations secrets targets`
- `stella config integrations secrets upsert-bundle --bundle <id> --target <integration-id> --entry key=value`
- Integration create/update operations still persist only `authRefUri`; the secret bundle and authref lifecycle are owned by the secret-authority target, not by the catalog row.
## Security Considerations
- **AuthRef URI credential model:** Credentials are stored in an external vault (e.g., HashiCorp Vault, Azure Key Vault). The integration catalog stores only the URI reference (`authref://vault/path/to/secret`), never the raw secret.