git.stella-ops.org/docs/security/pack-signing-and-rbac.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.

Pack Signing & RBAC Controls

This document defines signing, verification, and authorization requirements for Task Packs across the CLI, Packs Registry, Task Runner, and Offline Kit. It aligns with Authority sprint tasks (AUTH-PACKS-41-001, AUTH-PACKS-43-001) and security guild expectations.

---

1 · Threat Model Highlights

Threat	Mitigation
Unsigned or tampered pack uploaded to registry	Mandatory cosign/DSSE verification before acceptance.
Unauthorized user publishing or promoting packs	Authority scopes (Packs.Write) + registry policy checks.
Privilege escalation during approvals	Approval gates require Packs.Approve + audit logging; fresh-auth recommended.
Secret exfiltration via pack steps	Secrets injection sandbox with redaction, sealed-mode network guardrails, evidence review.
Replay of old approval tokens	Approval payloads carry plan hash + expiry; Task Runner rejects mismatches.
Malicious pack in Offline Kit	Mirror verification using signed manifest and DSSE provenance.

---

2 · Signing Requirements

• Cosign signatures required for all bundles. Keys can be:
  • Keyless (Fulcio OIDC).
  • KMS-backed (HSM, cloud KMS).
  • Offline keys stored in secure vault (air-gapped mode).
• DSSE Attestations recommended to embed:
  • Manifest digest.
  • Build metadata (repo, commit, CI run).
  • CLI version (stella/pack).
• Signatures stored alongside bundle in registry object storage.
• stella pack push refuses to publish without signature (unless --insecure-publish used in dev).
• Registry enforces trust policy:

Policy	Description
anyOf	Accepts any key in configured trust store.
keyRef	Accepts specific key ID (kid).
oidcIssuer	Accepts Fulcio certificates from allowed issuers (e.g., https://fulcio.sigstore.dev).
threshold	Requires N-of-M signatures (future release).

---

3 · RBAC & Scopes

Authority exposes pack-related scopes:

Scope	Description
Packs.Read	View packs, download manifests/bundles.
Packs.Write	Publish, promote, deprecate packs.
Packs.Run	Execute packs (Task Runner, CLI).
Packs.Approve	Approve pack gates, override tenant visibility.

3.1 Role Mapping

Role	Scopes	Use Cases
pack.viewer	Packs.Read	Inspect packs, plan runs.
pack.publisher	Packs.Read, Packs.Write	Publish new versions, manage channels.
pack.operator	Packs.Read, Packs.Run	Execute packs, monitor runs.
pack.approver	Packs.Read, Packs.Approve	Fulfil approvals, authorize promotions.
pack.admin	All	Full lifecycle management (rare).

Roles are tenant-scoped; cross-tenant access requires explicit addition.

3.2 CLI Enforcement

• CLI requests scopes based on command:
  • stella pack plan → Packs.Read.
  • stella pack run → Packs.Run.
  • stella pack push → Packs.Write.
  • stella pack approve → Packs.Approve.
• Offline tokens must include same scopes; CLI warns if missing.

---

4 · Approvals & Fresh Auth

• Approval commands require recent fresh-auth (< 5 minutes). CLI prompts automatically; Console enforces via Authority.
• Approval payload includes:
  • runId
  • gateId
  • planHash
  • approver
  • timestamp
• Task Runner logs approval event and verifies plan hash to prevent rerouting.

---

5 · Secret Management

• Secrets defined in pack manifest map to Authority secret providers (e.g., HSM, Vault).
• Task Runner obtains secrets using service account with scoped access; CLI may prompt or read from profile.
• Secret audit trail:
  • secretRequested event with reason, pack, step.
  • secretDelivered event omitted (only aggregate metrics) to avoid leakage.
  • Evidence bundle includes hashed secret metadata (no values).

Sealed mode requires secrets to originate from sealed vault; external endpoints blocked.

---

6 · Audit & Evidence

• Registry, Task Runner, and Authority emit audit events to central timeline.
• Required events:
  • pack.version.published
  • pack.version.promoted
  • pack.run.started/completed
  • pack.approval.requested/granted
  • pack.secret.requested
• Evidence Locker stores DSSE attestations and run bundles for 90 days (configurable).
• Auditors can use stella pack audit --run <id> to retrieve audit trail.

---

7 · Offline / Air-Gap Policies

• Offline Kit includes:
  • Pack bundles + signatures.
  • Trusted key store (trust-bundle.pem).
  • Approval workflow instructions for manual signing.
• Air-gapped approvals:
  • CLI generates approval request file (.approval-request.json).
  • Approver uses offline CLI to sign with offline key.
  • Response imported to Task Runner.
• Mirror process verifies signatures prior to import; failure aborts import with ERR_PACK_SIGNATURE_INVALID.

---

8 · Incident Response

• Compromised pack signature:
  • Revoke key via Authority trust store.
  • Deprecate affected versions (registry deprecate).
  • Notify consumers via Notifier (pack.security.alert).
  • Forensically review run evidence for impacted tenants.
• Unauthorized approval:
  • Review audit log for Packs.Approve events.
  • Trigger pack.run.freeze (pauses run pending investigation).
  • Rotate approver credentials and require fresh-auth.
• Secret leak suspicion:
  • Quarantine evidence bundles.
  • Rotate secrets referenced by pack.
  • Run sealed-mode audit script to confirm guardrails.

---

9 · Compliance Checklist

• Signing requirements (cosign/DSSE, trust policies) documented.
• Authority scope mapping and CLI enforcement captured.
• Approval workflow + fresh-auth expectations defined.
• Secret lifecycle (request, injection, audit) described.
• Audit/evidence integration noted (timeline, Evidence Locker).
• Offline/air-gap controls outlined.
• Incident response playbook provided.
• Imposed rule reminder retained at top.

---

Last updated: 2025-10-27 (Sprint 43).