truf-server/openspec/changes/add-web-operations-control-plane/specs/web-operations-console/spec.md

ADDED Requirements

Requirement: Protected typed admin routes

The operations console SHALL expose explicit server-rendered routes and exact mutation forms behind the existing random admin path, Caddy Basic authentication, trusted edge marker, exact same-origin check, CSRF validation, no-store responses, and restrictive security headers.

Scenario: Authorized operator opens a page

• WHEN Caddy authenticates the request and injects the trusted marker and operator identity
• THEN the requested operations page renders escaped server-side HTML with no client-side secret persistence

Scenario: Direct backend request lacks marker

• WHEN a request reaches an admin route without the trusted edge marker
• THEN the backend rejects it regardless of supplied operator headers

Scenario: Mutation has stale or invalid CSRF

• WHEN a POST has a missing, duplicate, or invalid CSRF value or wrong Origin
• THEN the backend rejects the mutation without side effects

Scenario: Unknown route or form action is submitted

• WHEN a request contains an unsupported method, route shape, action, field, or duplicate field
• THEN it fails closed without invoking Supervisor, database mutations, or host operations

Requirement: Trusted operator attribution

Caddy SHALL strip any inbound operator identity header and inject the authenticated Basic-auth username, and the backend SHALL trust that identity only with the private edge marker.

Scenario: Client spoofs operator header

• WHEN a public request supplies its own operator identity header
• THEN Caddy removes it and the audit actor is the authenticated Basic-auth user

Scenario: Mutation is accepted

• WHEN an authenticated operator performs a valid mutation
• THEN the control or operation record and its audit event identify that operator

Requirement: Exact production ingress profiles

The production deployment SHALL use exactly one root-installed profile: standalone-edge-v1 or shared-host-edge-v1. The selected profile SHALL NOT be supplied by an admin request, host-agent request, runtime document, or other unprivileged input.

Scenario: Standalone edge is selected

• WHEN standalone-edge-v1 is installed
• THEN the managed Truf edge remains the sole Truf listener on host port 443 and retains the exact runtime-network-namespace contract

Scenario: Shared-host edge is selected

• WHEN shared-host-edge-v1 is installed
• THEN the existing root-owned host Caddy remains the sole owner of ports 80/443 and proxies only fixed Truf routes to a managed edge bound at 127.0.0.1:18766

Scenario: A request attempts to select topology

• WHEN a request supplies a deployment mode, upstream, port, Caddy path, unit, service, command, or Compose argument
• THEN it is rejected before lifecycle work

Requirement: Shared-host route confinement

The shared-host profile SHALL install a fixed root-owned route-only host-Caddy snippet. It SHALL claim only /api/v1/worker/*, the exact random admin-prefix root, and that prefix's subtree. It SHALL strip inbound private and transit headers, inject an independent ingress marker and canonical client address, and preserve the managed edge's authentication, operator attribution, denylist, redacted logging, and security-header behavior without adding a listener, TLS policy, global error handler, trusted-proxy policy, catch-all, or unrelated route.

Scenario: An unrelated host route is requested

• WHEN a request does not match a Truf worker or admin path
• THEN the Truf snippet does not handle or alter the request

Scenario: The loopback Truf edge is unavailable

• WHEN a matching route cannot reach 127.0.0.1:18766
• THEN host Caddy fails that Truf request without forwarding it to X-UI or another fallback upstream

Scenario: A client supplies transit headers

• WHEN a public request supplies an ingress marker, forwarded address, private edge marker, or operator identity
• THEN host Caddy strips those values and injects only its reviewed ingress marker and observed client address

Requirement: Runtime overview

The overview page SHALL report bounded structured health for Supervisor, PostgreSQL, required pipeline workers, discovery producers, queue status, active remote assignments, result bundles, operation controls, and recent operation outcomes.

Scenario: Runtime is healthy

• WHEN all required components hold valid authority and health
• THEN the overview reports the runtime active and identifies each required component without exposing secrets

Scenario: Component is unavailable

• WHEN a health source times out or returns malformed state
• THEN the overview reports that component unavailable without blocking the rest of the page

Requirement: Search controls

The search page SHALL expose each core producer's structured state and typed start, stop, restart, pause, resume, and interval controls while clearly separating process lifecycle from the persistent discovery gate.

Scenario: Operator pauses search

• WHEN an operator submits pause with the current control revision
• THEN the persistent discovery gate changes atomically and every producer stops admitting new discovered targets

Scenario: Operator restarts one producer

• WHEN an operator selects restart for an allowed producer ID
• THEN only that managed discovery process restarts and the persistent pause state is unchanged

Requirement: Dispatch and drain controls

The workers/dispatch page SHALL expose persistent dispatch pause/resume, drain start/cancel, drain progress, compatible package state, worker users/devices, assignment counts, and upload availability.

Scenario: Operator pauses dispatch

• WHEN the current revision is submitted to the pause action
• THEN no new worker assignment can commit while valid existing uploads remain accepted

Scenario: Operator starts drain

• WHEN drain is started
• THEN the page reports draining progress from authoritative assignment and bundle counts until the state becomes drained

Scenario: Stale page attempts resume

• WHEN another operator has changed the control revision before resume is submitted
• THEN the console reports a revision conflict and does not overwrite the newer state

Requirement: Typed Supervisor operations

The console SHALL use a closed Supervisor protocol for structured snapshot, allowlisted managed-source lifecycle actions, and bounded log tail, and SHALL NOT forward generic command strings.

Scenario: Operator requests source status

• WHEN the Supervisor page loads
• THEN it displays structured source IDs, roles, phases, process state, restart state, and safe errors without parsing a text dashboard

Scenario: Operator tails logs

• WHEN an allowed managed source and bounded line count are submitted
• THEN Supervisor returns only that source's bounded log tail

Scenario: Input resembles a shell command

• WHEN an operator submits command text, a path, or an unrecognized source ID
• THEN the request is rejected and no generic Supervisor command or operating-system shell is called

Requirement: Durable asynchronous operation status

Long-running restart and apply actions SHALL create a PostgreSQL operation record before execution and SHALL remain queryable by operation ID across runtime/admin restarts.

Scenario: Apply restarts the admin process

• WHEN the process that accepted an apply request terminates during the coordinated restart
• THEN the operator can reopen the operation URL and observe reconciled success, rollback, or failure state

Scenario: Unknown operation is requested

• WHEN an operator requests an operation ID that does not exist or is not canonical
• THEN the console returns not found without searching filesystem paths or host-agent state by user input

Requirement: Append-only audit view

The audit page SHALL show bounded append-only events for accepted and completed controls, Supervisor actions, configuration/secrets operations, and managed-file mutations, including actor, action, logical target, time, result, and safe before/after identity.

Scenario: Secret apply is audited

• WHEN a secrets candidate is accepted and later applied or rolled back
• THEN audit events record hashes and outcomes but no secret value, candidate bytes, authorization data, or CSRF value

Scenario: Audit pagination is requested

• WHEN an operator navigates audit history
• THEN the backend returns a bounded deterministic page without unbounded database or browser output

Requirement: Existing worker API availability

Adding the operations console SHALL NOT weaken or couple public worker endpoints to admin page availability.

Scenario: Admin feature is disabled or unhealthy

• WHEN the admin console is disabled or a Supervisor/host-agent status dependency is unavailable
• THEN authenticated worker status, upload, terminal report, and receipt paths continue under their existing authority