Files

T

thanhnv 5745519126 feat(casan): establish assurance kernel and harden control plane

2026-08-02 23:24:51 +07:00

12 KiB

Raw Permalink Blame History

CASAN Ops Console (Plan-13 Track 1/2/3/4 + Command Center) — Control Panel

Real NestJS API + React UI that surfaces CASAN harness telemetry and governed settings management. This is the casan-platform Control Plane preview. “Platform” is a product edition, not a CASAN Maturity L3 claim. Monitoring remains read-only ("Đọc ≠ Ghi"). Settings writes go through RBAC and the harness-owned governance CLI; the UI never writes harness files directly or bypasses a gate.

backend/   NestJS API (/api/v1 + /healthz) over .specify telemetry + governed settings
frontend/  React + Vite + Tailwind + TanStack Query Ops Console + Settings/Approvals/Kill-switch/FinOps/Command/Chat pages

Run (local)

Preferred golden path from an adopted project:

casan dashboard start             # starts API + UI, enrolls the local deep link
casan dashboard status
casan view                        # opens the most recent prompt trace
casan dashboard stop

Manual developer mode:

npm install                      # from repo root (picks up the workspaces)
npm run console:api              # NestJS API  → http://127.0.0.1:3010/api/v1
npm run console:ui               # Vite UI     → http://127.0.0.1:5174 (proxies to the API)

Open http://127.0.0.1:5174 — panels show REAL metrics from .specify/logs/**.

API (`ok()`-enveloped except `/healthz`)

GET /api/v1/overview · runs (+ runs/:traceId) · governance · security · incidents · tools · traceability · drift · cost · GET /healthz (200 fresh / 503 stale — fail-loud, mirrors dashboard-server.py).

Harness reports:

GET /api/v1/reports — versioned H1–H7 report catalog and availability.
GET /api/v1/reports/h6?project=<id>&from=<ISO>&to=<ISO>&run=<id> — H6 AgentOps report from the same runtime metrics, provider usage and alert files as the Control Panel.
GET /api/v1/reports/h6/export?format=html|json&... — standalone, print-ready HTML or machine-readable JSON export. Both formats serialize the same filtered report object; no maturity score is hard-coded.
/reports/h6 — UI report view with project, time-range and run filters plus source-level freshness and data-quality warnings.
GET /api/v1/reports/run/:traceId and /export?format=html|json — complete per-prompt H1–H7 assurance receipt with truthful H6 availability.
POST /api/v1/ingest/turn — optional central ingestion. Disabled unless CASAN_CP_INGEST_TOKEN is set; requests require a five-minute timestamp and HMAC-SHA256 signature. Raw prompt/tool content keys are rejected.

Core always writes a sanitized pending envelope locally first. Central delivery is asynchronous and never delays or changes a prompt verdict:

export CASAN_CONTROL_PLANE_TOKEN='use-a-secret-manager-in-production'
casan init \
  --dashboard-url https://casan.example \
  --ingest-url https://casan.example/api/v1/ingest/turn

The server receives the same secret as CASAN_CP_INGEST_TOKEN. The secret name, not the secret value, is stored in project configuration.

Metrics export: GET /api/v1/metrics provides Prometheus text exposition for aggregate freshness, run/failure/cost/token and H4/H5/action/incident counters. It intentionally contains no tenant, actor, trace, prompt or Evidence Pack labels. In production restrict the path at the authenticated reverse proxy to the monitoring network or service account.

Command Center:

GET /api/v1/command — Plan-13 §8.6 read-only executive surface. Returns eight evidence-backed widgets with provenance envelopes {source, artifact_path, commit, run_at, verified, status}, plus executive briefing rows and a live governance ticker. The /command UI exposes the same data with a VI/EN briefing toggle and evidence drawer.

Settings management:

GET /api/v1/settings — list policy/current values/audit tail; viewer-readable.
POST /api/v1/settings — governed setting write. Requires x-casan-role with write permission; calls rbac-check.py before control-plane-settings.py set.
POST /api/v1/settings/rollback — governed rollback through the same core CLI.

Goal workspace context:

GET /api/v1/goals/projects — lists active project IDs and context roots from the harness-owned project registry after RBAC filtering; browser-supplied paths are never accepted.
POST /api/v1/goals requires { goal, projectId }. H1 resolves the registry again, produces a size-limited redacted manifest/snapshot, and gives the exact same snapshot to local and cloud models. Account-model CLIs remain inside an empty temporary sandbox.
Goals requesting workspace side effects make the producer and reviewer return a unified patch. CASAN validates its paths and preconditions, stores it as a tenant-scoped artifact, creates a goal.workspace.execute proposal, and finishes as requires_approval without modifying source files.
POST /api/v1/goals/:id/apply accepts only a patch whose proposal is already approved by a different actor. The executor verifies the artifact hash, applies it, runs fixed project build/test commands, and reverses the patch if verification fails.

In explicit loopback development mode only, local management headers are x-casan-actor, x-casan-role, x-casan-project, and x-casan-tenant. Missing role defaults to viewer, so writes fail closed. JWT mode discards these caller assertions and derives them only from verified token claims.

Kill-switch management:

GET /api/v1/kill-switch — list active kill-switches from kill-switch.sh status.
POST /api/v1/kill-switch/engage — RBAC-gated engage (operator or stronger).
POST /api/v1/kill-switch/clear — RBAC-gated clear (org-admin; strict approval remains enforced by the harness CLI in production mode).

Approval inbox / HITL:

GET /api/v1/approvals?status=pending — list proposals and oversight tail.
POST /api/v1/approvals/submit — submit a governed proposal; delegation is resolved by harness approval-inbox.py + delegation-policy.yaml.
POST /api/v1/approvals/decide — approve/reject with SoD and reason; strict mode or supplied approvalJwt is verified by harness approval-verify.sh; approved settings proposals apply through control-plane-settings.py.

Governed Chat (Plan-18 MVP-0/1/2):

POST /api/v1/chat/ask — Ask CASAN endpoint. The API only wraps harness chat-turn.py; router verdicts, H4 input/output scan, action-gate decisions, Plan-17 loop-run certification, H5 chat audit, H6 token metrics, evidence source selection, and operator action execution remain harness-owned.
GET /api/v1/chat/actions — list registered operator actions from operator-actions.yaml; no free-command execution is exposed.
GET /api/v1/chat/agents — list governed agents from agent-registry.yaml with role visibility; selected agent/skill/delegation are bound by harness chat-agent-resolver.py.
GET /api/v1/chat/audit/verify — verifies the chat audit hash chain.
GET /api/v1/chat/replay?chatId=<id>&tenant=<id> — verifies chat-chain integrity, evidence artifact hashes, and OPERATOR loop trace replay through harness chat-replay.py; non-default tenants read only their tenant partition.
GET /api/v1/command — includes the chat_loop Command Center widget backed by chat audit/replay evidence, loop ticker rows, and token budget gauge.
Delegation escalation returns ESCALATED and creates a pending chat.escalate proposal in the approval inbox.
CODEGEN requests are draft-only: codegen-draft outputs a state artifact, runs artifact-scan.sh + tool-output-scan.sh, certifies through Plan-17 loop-run, and never writes to the source tree.
Non-default tenant chat state is resolved through tenant-store.sh; replay path overrides are guarded, audit snapshots are encrypted with tenant-crypt.sh, and tenant kill-switch/quota checks run before chat work.
/chat UI shows actor/role scope, mode/risk/decision badges, certified answer, evidence sources, registered operator actions, agent binding, loop certification, codegen draft scan status, action-gate status, router details, and audit hash. Side-effect requests outside registered actions return governed BLOCK or NOT_SUPPORTED responses; operator side effects are held until the loop draft is certified.
/command UI renders the Chat/Loop widget in the existing evidence drawer flow.
/approvals UI accepts an approval JWT for strict reviewer identity checks.

FinOps/SLO:

/finops UI reads GET /api/v1/cost plus GET /api/v1/settings.
Provider cost/tokens come from provider usage telemetry.
KPI/SLO tiles come from 14-business-kpi-report.json.
Budget status uses cost.absolute_cap_usd when configured; otherwise it shows not configured.

Data sources + aggregation mirror packages/casan-harness/tests/generate-agentops-dashboard.py. App root + telemetry paths resolve via the same marker walk-up as casan-paths.sh (.specify or packages/casan-harness). The canonical source variables are CASAN_TELEMETRY_METRICS_LOG, CASAN_TELEMETRY_PROVIDER_LOG, and CASAN_TELEMETRY_ALERTS_LOG; legacy dashboard/control-panel names remain accepted as compatibility aliases. Freshness is calculated independently from each file's mtime using CASAN_DASHBOARD_STALE_S (default 3600).

Security posture

Binds 127.0.0.1 in explicit local development mode. Every non-loopback bind, and every production profile, requires CASAN_CP_AUTH_MODE=jwt. Production requires an RS256 public key plus configured issuer and audience; missing or invalid configuration refuses startup. The API verifies signature, expiry, issuer, audience, nbf/iat, and bounded clock skew in-process, then maps verified group claims through rbac-check.py. Arbitrary X-CASAN-* and forwarded-user headers are not an authentication mechanism.

Production variables are documented in infra/production/runtime.env.example. The packaged boundary is oauth2-proxy → Nginx header stripping/bearer forwarding → API cryptographic verification. The current provider uses a mounted RS256 public key; automated JWKS discovery/rotation remains future work.

Test

npm run console:test             # backend telemetry/settings/approvals/kill-switch/auth mapping/command/chat contract
npm run console:build            # backend tsc + frontend typecheck/vite build

Production-Like Smoke

bash packages/casan-control-panel/scripts/local-prod-smoke.sh

The scaffold includes Dockerfile.control-panel-api, Dockerfile.control-panel-ui, and nginx/control-panel.conf. Nginx protects UI/API through oauth2-proxy auth_request, removes browser-supplied identity headers, and forwards the signed bearer token for API verification. The local smoke starts a self-signed HTTPS stack with a mock OIDC IdP and expects CP_LOCAL_SMOKE_PASS https_oidc=true actor=oidc-ops role=org-admin; it also asserts the Command Center returns all nine widgets with provenance envelopes and invokes managed-prod-smoke.sh with the authenticated mock-IdP cookie jar. A passing local run therefore emits both CP_LOCAL_SMOKE_PASS ... and CP_MANAGED_SMOKE_PASS actor=oidc-ops role=org-admin widgets=9.

Managed production readiness is intentionally a stronger, fail-closed contract: it requires a DNS-matching TLS certificate, enterprise OIDC, non-dev Vault Transit, an actual S3 Object Lock COMPLIANCE write, and CI-attested digest-pinned images. Follow the Linux handoff guide, then run:

CASAN_CP_PROD_ENV=infra/production/casan-prod.env \
  bash packages/casan-control-panel/scripts/prod-readiness-check.sh

Managed production endpoint smoke, once DNS/TLS/OIDC are deployed:

CASAN_CP_BASE_URL=https://control-panel.example.com \
  bash packages/casan-control-panel/scripts/managed-prod-smoke.sh

That unauthenticated smoke must report auth protection and spoofed-header blocking. To also verify authenticated identity mapping and Command Center behind the enterprise IdP, pass an exported browser cookie jar for a real logged-in session:

CASAN_CP_BASE_URL=https://control-panel.example.com \
CASAN_CP_COOKIE_JAR=/secure/path/control-panel-cookies.txt \
  bash packages/casan-control-panel/scripts/managed-prod-smoke.sh

Not in this pass

Live managed host/cert/enterprise IdP traffic cutover. See docs/plans/CASAN_PLAN_13_CONTROL_PLANE.md.

12 KiB Raw Permalink Blame History Unescape Escape