stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
1d962ee6fc98ad8c53715bbff6d513246f5b1361
git.stella-ops.org/docs/task-packs/registry.md
master f98cea3bcf Add Authority Advisory AI and API Lifecycle Configuration 
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings.
- Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations.
- Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration.
- Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options.
- Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations.
- Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client.
- Updated project file to include necessary package references for the new Issuer Directory Client library.
2025-11-02 13:50:25 +02:00

175 lines
7.4 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
# Packs Registry Architecture & Operations
The Packs Registry stores, verifies, and serves Task Pack bundles across environments. It integrates with Authority for RBAC, Task Runner for execution, DevOps for release automation, and Offline Kit for air-gapped distribution.
---
## 1 · Service Overview
- **Service name:** `StellaOps.PacksRegistry`
- **Interfaces:** REST/GraphQL API, OCI-compatible registry endpoints, event streams for mirroring.
- **Data stores:** MongoDB (`packs`, `pack_versions`, `pack_provenance`), object storage (bundle blobs, signatures), timeline events.
- **Dependencies:** Authority scopes (`packs.*`), Export Center (manifests), DevOps signing service, Notifications (optional).
---
## 2 · Core Concepts
| Concept | Description |
|---------|-------------|
| **Pack record** | Immutable entry representing a pack version; includes metadata, digest, signatures, tenant visibility. |
| **Channel** | Logical distribution channel (`stable`, `edge`, `beta`, custom). Controls mirroring/promotion flows. |
| **Provenance** | DSSE statements + SBOM linking pack bundle to source repo, CLI build, and Task Runner compatibility. |
| **Mirroring policy** | Rules specifying which packs replicate to downstream registries or Offline Kit bundles. |
| **Audit trail** | Append-only log capturing publish/update/delete actions, approvals, and policy evaluations. |
---
## 3 · API Surface
### 3.1 REST Endpoints
| Method | Path | Description | Scopes |
|--------|------|-------------|--------|
| `GET` | `/api/packs` | List packs with filters (`name`, `channel`, `tenant`, `tag`). | `packs.read` |
| `GET` | `/api/packs/{packId}/versions` | List versions with metadata, provenance. | `packs.read` |
| `GET` | `/api/packs/{packId}/versions/{version}` | Retrieve manifest, signatures, compatibility matrix. | `packs.read` |
| `POST` | `/api/packs/{packId}/versions` | Publish new version (bundle upload or OCI reference). | `packs.write` |
| `POST` | `/api/packs/{packId}/promote` | Promote version between channels (edge→stable). | `packs.write` + approval policy |
| `DELETE` | `/api/packs/{packId}/versions/{version}` | Deprecate version (soft delete, immutability preserved). | `packs.write` |
| `GET` | `/api/packs/{packId}/events` | Stream audit events (SSE). | `packs.read` |
### 3.2 OCI Endpoints
The registry exposes OCI-compatible endpoints (`/v2/<namespace>/<pack>/...`) supporting:
- `PUT`/`PATCH`/`GET` for manifests and blobs.
- Content-addressed digests using SHA-256.
- Annotations for pack metadata (`org.opencontainers.image.title`, `io.stellaops.pack.metadata`).
### 3.3 GraphQL (Optional)
GraphQL endpoint (`/api/graphql`) enables advanced queries (filter by approvals, tags, compatibility). Under active development; reference API schema once published.
---
## 4 · Publishing Workflow
1. CLI/CI calls `POST /api/packs/{id}/versions` with signed bundle.
2. Registry verifies:
- Manifest schema compliance.
- Signature (cosign/DSSE) validity.
- Authority scopes (`packs.write`).
- Tenant visibility constraints.
3. On success, registry stores bundle, provenance, and emits event (`pack.version.published`).
4. Optional promotion requires additional approvals or integration with DevOps release boards.
All actions recorded in audit log:
```json
{
"id": "evt_01HF...",
"type": "pack.version.published",
"packId": "sbom-remediation",
"version": "1.3.0",
"actor": "user:alice",
"tenant": "west-prod",
"source": "cli/2025.10.0",
"signatures": ["sha256:..."],
"metadataHash": "sha256:..."
}
```
---
## 5 · Mirroring & Offline Support
- **Automatic mirroring:** Configure policies to push packs to secondary registries (edge clusters, regional mirrors) or object stores.
- **Offline Kit integration:** `ops/offline-kit` pipeline pulls packs matching specified channels and writes them to `offline/packs/manifest.json` with signatures.
- **Checksum manifest:** Registry maintains `digestmap.json` listing pack digests + signatures; offline installers verify before import.
- **Sealed mode:** Registry can operate in read-only mode for sealed environments; publishing disabled except via offline import command (`stella pack mirror import`).
---
## 6 · Security & Compliance
- Enforce Authority scopes; tokens without tenant or required scope are rejected (`ERR_PACK_SCOPE`).
- Signatures verified using trusted Fulcio/KMS roots; optional mirror trust bundles configured via `registry.trustBundle`.
- RBAC mapping:
| Role | Scopes | Capabilities |
|------|--------|--------------|
| `PackViewer` | `packs.read` | Browse, fetch manifests/bundles. |
| `PackPublisher` | `packs.read`, `packs.write` | Publish/promote, manage channels (subject to policy). |
| `PackApprover` | `packs.read`, `packs.approve` | Approve promotions, override tenant visibility (with audit logging). |
| `PackOperator` | `packs.read`, `packs.run` | Execute packs (via CLI/Task Runner). |
- Audit events forwarded to Authority + Evidence Locker.
- Built-in malware/secret scanning runs on bundle upload (configurable via DevOps pipeline).
See [pack signing & RBAC guidance](../security/pack-signing-and-rbac.md) for deeper controls.
---
## 7 · Observability
- Metrics (`registry` namespace):
- `pack_publish_total{result}` – success/failure counts.
- `pack_signature_verify_seconds` – verification latency.
- `pack_channel_promotions_total` – promotions per channel.
- `pack_mirror_queue_depth` – pending mirror jobs.
- Logs (structured JSON with `packId`, `version`, `actor`, `tenant`, `digest`).
- Traces instrument bundle verification, storage writes, and mirror pushes.
- Alerting suggestions:
- Publish failure rate > 5 % (5 m window) triggers DevOps escalation.
- Mirror lag > 15 m surfaces to Ops dashboard.
---
## 8 · Schema & Metadata Extensions
- Default metadata stored under `metadata.*` from manifest.
- Registry supplements with:
- `compatibility.cli` (supported CLI versions).
- `compatibility.runner` (Task Runner build requirements).
- `provenance.attestations[]` (URIs).
- `channels[]` (current channel assignments).
- `tenantVisibility[]`.
- `deprecated` flag + replacement hints.
Extensions must be deterministic and derived from signed bundle data.
---
## 9 · Operations
- **Backups:** Daily snapshots of Mongo collections + object storage, retained for 30 days.
- **Retention:** Old versions retained indefinitely; mark as `deprecated` instead of deleting.
- **Maintenance:**
- Run `registry vacuum` weekly to prune orphaned blobs.
- Rotate signing keys per security policy (document in `pack-signing-and-rbac`).
- Validate trust bundles quarterly.
- **Disaster recovery:**
- Restore database + object storage.
- Rebuild OCI indexes (`registry rebuild-index`).
- Replay audit events for downstream systems.
---
## 10 · Compliance Checklist
- [ ] REST + OCI endpoints documented with required scopes.
- [ ] Publishing flow covers signature verification, audit logging, and promotion policies.
- [ ] Mirroring/offline strategy recorded (policies, manifests, sealed mode notes).
- [ ] RBAC roles and scope mapping defined.
- [ ] Observability metrics, logs, and alerts described.
- [ ] Operations guidance covers backups, rotation, disaster recovery.
- [ ] Imposed rule reminder included at top of document.
---
*Last updated: 2025-10-27 (Sprint 43).*
Reference in New Issue View Git Blame Copy Permalink