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 the signing, verification, and authorization requirements for Stella Ops Task Packs across the CLI, Packs Registry, Task Runner, and Offline Kit. It is written for operators who publish and approve packs and for engineers building pack tooling. It aligns with Authority sprint tasks (AUTH-PACKS-41-001, AUTH-PACKS-43-001) and security-guild expectations. For the canonical scope catalogue and role model, see authority-scopes.md and scopes-and-roles.md.

Implementation status (reconciled 2026-05-30). Several controls in this document are the target posture; the shipped implementation is narrower. Where they diverge, an explicit Status note is given. Ground truth: StellaOpsScopes.cs (scope catalog), StellaOps.PacksRegistry.* (registry service), PasswordGrantHandlers.cs / StellaOpsScopeAuthorizationHandler.cs (Authority approval-token enforcement), and StellaOps.Cli (PackClient.cs, CommandFactory.cs).

Key gaps to be aware of before relying on this page:

• The Packs Registry service signature verifier is SimpleSignatureVerifier (SHA-256 digest match, accepts unsigned) or RsaSignatureVerifier (RSA-PKCS1 over the digest string). Cosign/Fulcio/KMS and DSSE verification are not implemented in the registry service — those rows are roadmap.
• The Packs Registry WebService authorizes with a single static X-API-Key (PacksRegistry:Auth:ApiKey); when no key is configured, auth is disabled. It does not enforce the packs.* OAuth scopes — scope enforcement lives in the CLI token requests and the shared Authority resource-server policies (StellaOpsResourceServerPolicies), applied when the registry is fronted by the gateway/router.

1 · Threat Model Highlights

2 · Signing Requirements

2.1 Implemented today

• On upload, the registry recomputes the bundle digest as sha256:<hex> (PackService.ComputeSha256) and validates the supplied signature via the configured IPackSignatureVerifier:
  • SimpleSignatureVerifier(default when no public key is configured): accepts an empty signature (treated as “unsigned, digest-only”), a signature equal to the computed sha256: digest, or the base64 of that digest string. This is a placeholder, explicitly marked in source as “Replace with real signature verification when keys/attestations are available.”
  • RsaSignatureVerifier(selected when PacksRegistry:Verification:PublicKeyPem is set): verifies a base64 RSA-PKCS1 signature over the UTF-8 digest text using SHA-256.
• Signature, digest, and (optional) provenance digest are stored alongside the bundle in registry storage (PackRecord).
• A signature can be required by policy: PacksRegistry:Policy:RequireSignature (default false). When true, upload with an empty signature is rejected ("Signature is required by policy.").
• Signatures can be rotated post-upload via POST /api/v1/packs/{packId}/signature (re-verified against the stored content; emits a signature.rotated audit event).
• CLI: stella pack push <path> [--sign] [--key-id <id>] [--force] sends the bundle to the registry; --sign/--key-id set upload metadata flags. The CLI does not refuse to publish unsigned bundles client-side, and there is no --insecure-publish flag.

2.2 Roadmap (NOT IMPLEMENTED in the registry service)

The following describe the intended target posture and are not present in StellaOps.PacksRegistry:

• Cosign signatures (keyless/Fulcio OIDC, KMS/HSM-backed, offline-vault keys).
• DSSE attestations embedding manifest digest, build metadata (repo, commit, CI run), and CLI version (stella/pack).
• Trust-policy verification modes:

3 · RBAC & Scopes

Authority exposes exactly four pack-related scopes (canonical source: StellaOpsScopes.cs):

All four are exposed as resource-server policies in StellaOpsResourceServerPolicies and seeded into the authority.permissions catalog by S002_seed_full_scope_permissions.sql. Tenant assignment is mandatory for any pack scope under the client-credentials grant (ClientCredentialsHandlers rejects with "Pack scopes require a tenant assignment.").

Note. The CLI PackClient additionally requests two scopes — packs.secrets (secret injection) and packs.cache (cache management) — that are not registered in StellaOpsScopes.cs. They are therefore unknown scopes and will not be issued in an OpTok; treat the corresponding CLI surfaces (InjectSecretAsync, ManageCacheAsync) as not yet scope-backed.

3.1 Role Mapping (illustrative)

These role bundles are guidance only — they are not defined as named roles in the codebase. Operators assemble custom roles from the four scopes above via the Console Admin role editor.

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

3.2 CLI Enforcement

• The CLI requests a scope per operation when acquiring the access token (PackClient.AuthorizeRequestAsync):
  • stella pack plan → packs.read.
  • stella pack run → packs.run.
  • stella pack push → packs.write.
  • stella pack pull / verify / runs logs → packs.read.
  • stella pack runs cancel / pause / resume → packs.run.
• The shipped CLI command tree under stella pack is: plan, run, push, pull, verify, and runs (cancel, pause, resume, logs). There is no stella pack approvecommand — approval of a paused run is performed with stella pack runs resume <run-id> --approve [--reason ...] [--step ...], which uses the packs.run scope.
• Approval tokens (packs.approve) are obtained directly from the Authority token endpoint, not via a dedicated CLI subcommand. When packs.approve is requested, the /token endpoint requires the pack_run_id, pack_gate_id, and pack_plan_hash request parameters (PasswordGrantHandlers). Validation rules:
  • pack_run_id, pack_gate_id: non-empty, ≤ 128 characters.
  • pack_plan_hash: a 32–128 character lowercase hexadecimal digest.
  • Authority rejects grants that omit or truncate any field and records the values as sensitive audit properties pack.run_id, pack.gate_id, pack.plan_hash.

4 · Approvals & Fresh Auth

• Approval commands require recent fresh-auth (< 5 minutes). When the packs.approve scope is requested, /token demands pack_run_id, pack_gate_id, and pack_plan_hash (PasswordGrantHandlers), and the resource-layer scope handler (StellaOpsScopeAuthorizationHandler) re-verifies that the corresponding claims are present plus that authentication_time falls within the five-minute window before authorizing the request.
• Failure surfaces:
  • At issuance, a missing/invalid metadata field rejects the grant and records packs.approve under the audit InvalidScope property (AuditInvalidScopeProperty).
  • The authority.pack_scope_violation activity tag is emitted specifically by the client-credentials grant when pack scopes are requested without a tenant assignment (ClientCredentialsHandlers).
  • At the resource layer, missing metadata or stale auth fails authorization with reasons such as "packs.approve tokens require pack_run_id claim." or "packs.approve tokens require fresh authentication.", and stamps pack.fresh_auth_satisfied (and, when present, pack.auth_time) audit properties.
• Approval token metadata (as carried / audited):
  • pack_run_id / pack.run_id
  • pack_gate_id / pack.gate_id
  • pack_plan_hash / pack.plan_hash (validated 32–128 char hex)
• The plan hash binds the approval to a specific plan to prevent rerouting; the run pause/resume/approval flow is driven through the Packs Registry / Task Runner endpoints (runs:pause, runs:resume).

5 · Secret Management

Status: largely roadmap / partially wired. The CLI exposes a secret-injection call (PackClient.InjectSecretAsync → POST /api/v1/packs/runs/{runId}/secrets, requesting the unregistered packs.secrets scope), but the documented secret audit events below (secretRequested / secretDelivered) are not emitted by the Packs Registry service. Treat this section as the intended design.

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

Sealed mode is intended to require secrets to originate from a sealed vault, with external endpoints blocked.

6 · Audit & Evidence

• The Packs Registry emits append-only audit records (IAuditRepository.AppendAsync) plus structured audit events (IAuditEventEmitter).
• Audit events actually emitted by the registry (source: PackService, LifecycleService, ParityService, MirrorService, AttestationService, ExportService, Program.cs):
  • pack.uploaded (on publish/upload)
  • signature.rotated
  • lifecycle.updated (deprecation and other lifecycle transitions)
  • parity.updated
  • attestation.uploaded
  • mirror.upserted, mirror.sync
  • offline.seed.exported
• The richer event taxonomy previously listed here (pack.version.published, pack.version.promoted, pack.run.started/completed, pack.approval.requested/granted, pack.secret.requested) is not implemented — it is a target design, not the current emitter set.
• Dashboards can track the authority.pack_scope_violation activity tag (emitted by ClientCredentialsHandlers on tenant-missing pack-scope grants) alongside authority.aoc_scope_violation to highlight mis-scoped automation clients. Break down counts by authority.client_id to surface stale automation/registry configurations quickly.
• Evidence Locker retention of attestations and run bundles for 90 days (configurable) is a target — verify against the Evidence Locker configuration before relying on the exact window.
• No stella pack audit command exists. The shipped registry audit surface is the append-only audit log; run history is retrieved via stella pack runs .... A dedicated stella pack audit --run <id> subcommand is not implemented.

7 · Offline / Air-Gap Policies

Status: partly roadmap. Offline-seed export is implemented (POST /api/v1/export/offline-seed → offline.seed.exported); the manual offline-signing approval workflow (.approval-request.json, trust-bundle.pem) is a target design and is not wired in the registry/CLI today.

• Offline Kit is intended to include:
  • Pack bundles + signatures.
  • Trusted key store (trust-bundle.pem).
  • Approval workflow instructions for manual signing.
• Air-gapped approvals (target design):
  • CLI generates an approval request file (.approval-request.json).
  • Approver uses offline CLI to sign with an offline key.
  • Response imported to the Task Runner.
• The CLI defines the relevant pack error codes (StellaOps.Cli.Output.CliError): ERR_PACK_SIGNATURE_INVALID, ERR_PACK_VERIFY_FAILED, ERR_PACK_PULL_FAILED, ERR_PACK_APPROVAL_REQUIRED, ERR_PACK_OFFLINE_VIOLATION. A signature/verification failure during pull or verify surfaces ERR_PACK_SIGNATURE_INVALID / ERR_PACK_VERIFY_FAILED; offline-mode violations surface ERR_PACK_OFFLINE_VIOLATION.

8 · Incident Response

• Compromised pack signature:
  • Revoke key via Authority trust store.
  • Deprecate affected versions by transitioning lifecycle state to deprecated (POST /api/v1/packs/{packId}/lifecycle, state deprecated). There is no registry deprecate CLI command; deprecation is via the lifecycle API.
  • Notify consumers via Notifier. Status: a dedicated pack.security.alert notification event is not defined in source today — use a general Notifier rule.
  • Forensically review run evidence for impacted tenants.
• Unauthorized approval:
  • Review audit log for packs.approve issuance failures (InvalidScope = packs.approve) and pack approval metadata (pack.run_id, pack.gate_id, pack.plan_hash).
  • Pause the affected run via stella pack runs pause <run-id> (or POST /api/v1/packs/runs/{runId}:pause). Status: there is no distinct pack.run.freeze action; pause is the implemented mechanism.
  • Rotate approver credentials and require fresh-auth (the five-minute window forces re-authentication on the next approval token).
• 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). Reconciled against implementation 2026-05-30 — see the “Implementation status” note at the top; sections 2, 5, 6, 7, and 8 distinguish shipped behavior from roadmap.