feat: Implement console session management with tenant and profile handling
- Add ConsoleSessionStore for managing console session state including tenants, profile, and token information. - Create OperatorContextService to manage operator context for orchestrator actions. - Implement OperatorMetadataInterceptor to enrich HTTP requests with operator context metadata. - Develop ConsoleProfileComponent to display user profile and session details, including tenant information and access tokens. - Add corresponding HTML and SCSS for ConsoleProfileComponent to enhance UI presentation. - Write unit tests for ConsoleProfileComponent to ensure correct rendering and functionality.
This commit is contained in:
master
249
docs/task-packs/spec.md
Normal file
249
docs/task-packs/spec.md
Normal file
@@ -0,0 +1,249 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Specification (Sprint 43 Draft)
|
||||
|
||||
The Task Pack specification defines a deterministic, auditable format that enables operators to encode multi-step maintenance, validation, and deployment workflows. Packs are executed by the Task Runner service, distributed through the Packs Registry, and invoked via the StellaOps CLI (`stella pack ...`) or Orchestrator integrations.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Goals & Scope
|
||||
|
||||
- **Deterministic execution.** Identical inputs yield identical run graphs, output manifests, and evidence bundles across environments (online, sealed, or offline).
|
||||
- **Secure-by-default.** Pack metadata must capture provenance, signatures, RBAC requirements, and secret usage; execution enforces tenant scopes and approvals.
|
||||
- **Portable.** Packs are distributed as signed OCI artifacts or tarballs that work in connected and air-gapped deployments, including Offline Kit mirrors.
|
||||
- **Composable.** Packs can reference reusable steps, expressions, and shared libraries without sacrificing determinism or auditability.
|
||||
|
||||
Non-goals: full-blown workflow orchestration, unbounded scripting, or remote code injection. All logic is declarative and constrained to Task Runner capabilities.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Terminology
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **Pack manifest** | Primary YAML document (`pack.yaml`) describing metadata, inputs, steps, policies, and evidence expectations. |
|
||||
| **Step** | Atomic unit of work executed by Task Runner (e.g., command, API call, policy gate, approval). Steps can be sequential or parallel. |
|
||||
| **Expression** | Deterministic evaluation (JMESPath-like) used for branching, templating, and conditionals. |
|
||||
| **Policy gate** | Declarative rule that blocks execution until conditions are met (e.g., approval recorded, external signal received). |
|
||||
| **Artifact** | File, JSON blob, or OCI object produced by a step, referenced in manifests and evidence bundles. |
|
||||
| **Pack bundle** | Distribution archive (`.stella-pack.tgz` or OCI ref) containing manifest, assets, schemas, and provenance metadata. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Pack Layout
|
||||
|
||||
```
|
||||
my-pack/
|
||||
├─ pack.yaml # Required manifest
|
||||
├─ assets/ # Optional static assets (scripts, templates)
|
||||
├─ schemas/ # JSON schemas for inputs/outputs
|
||||
├─ docs/ # Markdown docs rendered in Console/CLI help
|
||||
├─ provenance/ # DSSE statements, SBOM, attestations
|
||||
└─ README.md # Author-facing summary (optional)
|
||||
```
|
||||
|
||||
Publishing via Packs Registry or OCI ensures the directory is canonical and hashed.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Manifest Schema (v1.0)
|
||||
|
||||
```yaml
|
||||
apiVersion: stellaops.io/pack.v1
|
||||
kind: TaskPack
|
||||
metadata:
|
||||
name: sbom-remediation
|
||||
version: 1.3.0
|
||||
description: >
|
||||
Audit SBOM drift, quiet high-risk findings, and export mitigation evidence.
|
||||
tags: [sbom, remediation, policy]
|
||||
tenantVisibility: ["west-prod", "east-stage"] # optional allowlist
|
||||
maintainers:
|
||||
- name: Jane Doe
|
||||
email: jane@example.com
|
||||
license: AGPL-3.0-or-later
|
||||
annotations:
|
||||
imposedRuleReminder: true
|
||||
|
||||
spec:
|
||||
inputs:
|
||||
- name: sbomBundle
|
||||
type: object
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
required: true
|
||||
- name: dryRun
|
||||
type: boolean
|
||||
default: false
|
||||
secrets:
|
||||
- name: jiraToken
|
||||
scope: Packs.Run # Authority scope required
|
||||
description: Optional token for ticket automation
|
||||
approvals:
|
||||
- id: security-review
|
||||
grants: ["Packs.Approve"]
|
||||
expiresAfter: PT4H
|
||||
reasonTemplate: "Approve remediation for SBOM {{ inputs.sbomBundle.metadata.image }}"
|
||||
steps:
|
||||
- id: validate-input
|
||||
run:
|
||||
uses: builtin:validate-schema
|
||||
with:
|
||||
target: "{{ inputs.sbomBundle }}"
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
- id: plan-remediation
|
||||
when: "{{ not inputs.dryRun }}"
|
||||
run:
|
||||
uses: builtin:policy-simulate
|
||||
with:
|
||||
sbom: "{{ inputs.sbomBundle }}"
|
||||
policy: "policies/remediation.yaml"
|
||||
- id: approval-gate
|
||||
gate:
|
||||
approval: security-review
|
||||
message: "Security must approve remediation before changes apply."
|
||||
- id: apply-remediation
|
||||
run:
|
||||
uses: builtin:cli-command
|
||||
with:
|
||||
command: ["stella", "policy", "promote", "--from-pack"]
|
||||
- id: export-evidence
|
||||
run:
|
||||
uses: builtin:evidence-export
|
||||
with:
|
||||
includeArtifacts: ["{{ steps.plan-remediation.outputs.planPath }}"]
|
||||
outputs:
|
||||
- name: evidenceBundle
|
||||
type: file
|
||||
path: "{{ steps.export-evidence.outputs.bundlePath }}"
|
||||
success:
|
||||
message: "Remediation applied; evidence bundle ready."
|
||||
failure:
|
||||
retries:
|
||||
maxAttempts: 1
|
||||
backoffSeconds: 0
|
||||
message: "Remediation failed; see evidence bundle for context."
|
||||
```
|
||||
|
||||
### 4.1 Field Summary
|
||||
|
||||
| Field | Description | Requirements |
|
||||
|-------|-------------|--------------|
|
||||
| `metadata` | Human-facing metadata; used for registry listings and RBAC hints. | `name` (DNS-1123), `version` (SemVer), `description` ≤ 2048 chars. |
|
||||
| `spec.inputs` | Declarative inputs validated at plan time. | Must include type; custom schema optional but recommended. |
|
||||
| `spec.secrets` | Secrets requested at runtime; never stored in pack bundle. | Each secret references Authority scope; CLI prompts or injects from profiles. |
|
||||
| `spec.approvals` | Named approval gates with required grants and TTL. | ID unique per pack; `grants` map to Authority roles. |
|
||||
| `spec.steps` | Execution graph; each step is `run`, `gate`, `parallel`, or `map`. | Steps must declare deterministic `uses` module and `id`. |
|
||||
| `spec.outputs` | Declared artifacts for downstream automation. | `type` can be `file`, `object`, or `url`; path/expression required. |
|
||||
| `success` / `failure` | Messages + retry policy. | `failure.retries.maxAttempts` + `backoffSeconds` default to 0. |
|
||||
|
||||
---
|
||||
|
||||
## 5 · Step Types
|
||||
|
||||
| Type | Schema | Notes |
|
||||
|------|--------|-------|
|
||||
| `run` | Executes a built-in module (`builtin:*`) or registry-provided module. | Modules must be deterministic, side-effect constrained, and versioned. |
|
||||
| `parallel` | Executes sub-steps concurrently; `maxParallel` optional. | Results aggregated; failures trigger abort unless `continueOnError`. |
|
||||
| `map` | Iterates over deterministic list; each iteration spawns sub-step. | Sequence derived from expression result; ordering stable. |
|
||||
| `gate.approval` | Blocks until approval recorded with required grants. | Supports `autoExpire` to cancel run on timeout. |
|
||||
| `gate.policy` | Calls Policy Engine to ensure criteria met (e.g., no critical findings). | Fails run if gate not satisfied. |
|
||||
|
||||
`when` expressions must be pure (no side effects) and rely only on declared inputs or prior outputs.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Determinism & Validation
|
||||
|
||||
1. **Plan phase** (`stella pack plan`, `TaskRunner.Plan` API) parses manifest, resolves expressions, validates schemas, and emits canonical graph with hash.
|
||||
2. **Simulation** compares plan vs dry-run results, capturing differences in `planDiff`. Required for approvals in sealed environments.
|
||||
3. **Execution** uses plan hash to ensure runtime graph matches simulation. Divergence aborts run.
|
||||
4. **Evidence**: Task Runner emits DSSE attestation referencing plan hash, input digests, and output artifacts.
|
||||
|
||||
Validation pipeline:
|
||||
|
||||
```text
|
||||
pack.yaml ──▶ schema validation ──▶ expression audit ──▶ determinism guard ──▶ signing
|
||||
```
|
||||
|
||||
Packs must pass CLI validation before publishing.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Signatures & Provenance
|
||||
|
||||
- Pack bundles are signed with **cosign** (keyless Fulcio/KMS supported) and optionally DSSE envelopes.
|
||||
- `provenance/` directory stores signed statements (SLSA Build L1+) linking source repo, CI run, and manifest hash.
|
||||
- Registry verifies signatures on push/pull; Task Runner refuses unsigned packs unless in development mode.
|
||||
- Attestations include:
|
||||
- Pack manifest digest (`sha256`)
|
||||
- Pack bundle digest
|
||||
- Build metadata (`git.ref`, `ci.workflow`, `cli.version`)
|
||||
|
||||
---
|
||||
|
||||
## 8 · RBAC & Scopes
|
||||
|
||||
Authority scopes introduced by `AUTH-PACKS-41-001`:
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `Packs.Read` | Discover packs, download manifests. |
|
||||
| `Packs.Write` | Publish/update packs in registry (requires signature). |
|
||||
| `Packs.Run` | Execute packs via CLI/Task Runner. |
|
||||
| `Packs.Approve` | Fulfil approval gates defined in packs. |
|
||||
|
||||
Task Runner enforces scopes per tenant; pack metadata may further restrict tenant visibility (`metadata.tenantVisibility`).
|
||||
|
||||
---
|
||||
|
||||
## 9 · Observability & Evidence
|
||||
|
||||
- Metrics: `pack_run_duration_seconds`, `pack_step_retry_total`, `pack_gate_wait_seconds`.
|
||||
- Logs: Structured JSON per step with scrubbed inputs (`secretMask` applied).
|
||||
- Timeline events: `pack.started`, `pack.approval.requested`, `pack.approval.granted`, `pack.completed`.
|
||||
- Evidence bundle includes:
|
||||
- Plan manifest (canonical JSON)
|
||||
- Step transcripts (redacted)
|
||||
- Artifacts manifest (sha256, size)
|
||||
- Attestations references
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compatibility Matrix
|
||||
|
||||
| CLI Version | Pack API | Task Runner | Notes |
|
||||
|-------------|----------|-------------|-------|
|
||||
| 2025.10.x | `pack.v1` | Runner build `>=2025.10.0` | Approvals optional, loops disabled. |
|
||||
| 2025.12.x | `pack.v1` | Runner build `>=2025.12.0` | Approvals resume, secrets injection, localization strings. |
|
||||
| Future | `pack.v2` | TBD | Will introduce typed outputs & partial replay (track in Epic 13). |
|
||||
|
||||
CLI enforces compatibility: running pack with unsupported features yields `ERR_PACK_UNSUPPORTED`.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Publishing Workflow
|
||||
|
||||
1. Author pack (`pack.yaml`, assets, docs).
|
||||
2. Run `stella pack validate` (schema + determinism).
|
||||
3. Generate bundle: `stella pack build --output my-pack.stella-pack.tgz`.
|
||||
4. Sign: `cosign sign-blob my-pack.stella-pack.tgz`.
|
||||
5. Publish: `stella pack push registry.example.com/org/my-pack:1.3.0`.
|
||||
6. Registry verifies signature, records provenance, and exposes pack via API.
|
||||
|
||||
---
|
||||
|
||||
## 12 · Compliance Checklist
|
||||
|
||||
- [ ] Manifest schema documented for all fields, including approvals, secrets, and outputs.
|
||||
- [ ] Determinism requirements outlined with plan/simulate semantics and CLI validation steps.
|
||||
- [ ] Signing + provenance expectations spelled out with cosign/DSSE references.
|
||||
- [ ] RBAC scopes (`Packs.*`) and tenant visibility rules captured.
|
||||
- [ ] Observability (metrics, logs, evidence) described for Task Runner integrations.
|
||||
- [ ] Compatibility matrix enumerates CLI/Runner requirements.
|
||||
- [ ] Publishing workflow documented with CLI commands.
|
||||
- [ ] Imposed rule reminder included at top of document.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
Reference in New Issue
Block a user