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