git.stella-ops.org/docs/task-packs/registry.md

> **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).*