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:

{
  "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 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).