truf-server/openspec/changes/add-web-operations-control-plane/specs/managed-runtime-editing/spec.md

ADDED Requirements

Requirement: Shared strict document validation

Configuration and secrets preview, startup, and privileged apply SHALL use the same side-effect-free validator for bounded UTF-8 YAML, duplicate keys, mapping roots, strict scalar types and bounds, known keys, exact core profile, auth-pool schemas, unique entry names, reference integrity, package capabilities, and deployment paths.

Scenario: Valid configuration is previewed

• WHEN an operator submits a candidate satisfying the complete schema
• THEN preview returns normalized validation success and a bounded diff without activating the candidate

Scenario: Duplicate or unknown key is submitted

• WHEN a candidate contains a duplicate mapping key or unsupported field
• THEN validation fails before staging or restart and identifies the field without echoing secret values

Scenario: Secret reference is invalid

• WHEN configuration selects an auth-pool entry that does not exist in the candidate secrets
• THEN combined validation fails and neither document becomes active

Requirement: Separate immutable package authority

Worker package manifests SHALL resolve only beneath a separate root-owned, non-writable package authority, while runtime-generated initialization state, locks, and PostgreSQL credentials SHALL remain in the private writable data volume rather than the active config/secrets bind.

Scenario: Package manifest uses the active-document directory

• WHEN configuration references a package manifest beneath the config/secrets authority or outside the fixed package root
• THEN validation fails before startup or privileged apply

Scenario: Runtime initializes with active documents mounted read-only

• WHEN the runtime initializes or restarts with the active config/secrets directory mounted read-only
• THEN its initialization marker, singleton lock, and generated PostgreSQL password remain writable only through fixed private data paths

Requirement: Candidate revisions and compare-and-swap

The system SHALL stage validated candidate revisions separately from active files and SHALL require expected active and candidate SHA-256 identities when saving or applying them.

Scenario: Candidate is saved

• WHEN an operator saves valid bytes against the current active hash
• THEN the candidate is durably staged with a new hash and the active file is unchanged

Scenario: Active file changed through SSH

• WHEN the active hash differs from the expected hash submitted by a stale page
• THEN save or apply fails without replacing either active file

Scenario: Candidate changed concurrently

• WHEN the supplied candidate hash is no longer current
• THEN apply is rejected before host lifecycle changes begin

Requirement: Plaintext secrets editing without persistence leakage

The protected secrets page SHALL allow authorized operators to view and edit the complete plaintext YAML document while responses remain no-store and secret values remain absent from browser persistence, application logs, diffs outside that page, operation status, and audit records.

Scenario: Operator opens secrets page

• WHEN an authenticated operator requests the dedicated secrets editor
• THEN the current document is rendered in a server-side form over the protected no-store response

Scenario: Secrets candidate is validated

• WHEN an operator previews or saves changed secrets
• THEN validation results name safe field paths and hashes but do not repeat credential values

Scenario: Operator leaves the page

• WHEN the browser navigates to another admin page
• THEN the application has written no secret value to local storage, session storage, service workers, or client-side application state

Requirement: Closed host-agent protocol

The privileged host operations agent SHALL accept only a canonical operation UUID, one fixed action enum, expected active hashes, and expected candidate hashes from the authorized runtime peer over a local Unix socket. Deployment profile is root-installed host policy and SHALL NOT be added to that request.

Scenario: Valid apply request arrives

• WHEN the authorized runtime UID submits an exact valid request
• THEN the agent verifies the persisted operation and hashes before acquiring the singleton apply lock

Scenario: Request includes path or command data

• WHEN a request includes a service name, path, shell text, environment, Docker argument, or unknown field
• THEN the agent rejects it before any privileged action

Scenario: Request attempts topology selection

• WHEN a request includes a profile, ingress port, upstream, Caddy path, unit, service, command, environment, Compose file, or Compose argument
• THEN the agent rejects it before reading candidate documents or stopping the deployment

Scenario: Unauthorized local peer connects

• WHEN a process with an unapproved peer identity uses the socket
• THEN the agent rejects the request regardless of its JSON body

Requirement: Coordinated apply with health verification

For config, secrets, or combined apply, the host agent SHALL revalidate fixed candidate files, verify compare-and-swap hashes, create byte-identical backups, stop the fixed Truf deployment, atomically replace active files, recreate the exact root-selected runtime and edge profile, attest its fixed topology, and wait for required health before reporting success. In shared-host mode it SHALL NOT stop, restart, reload, reconfigure, or remove host Caddy, X-UI, or another unrelated service.

Scenario: Combined apply succeeds

• WHEN both candidates validate and the restarted deployment reaches Supervisor ACTIVE, PostgreSQL READY, Worker API, ingester, and projector health
• THEN the operation completes successfully with resulting hashes and retained rollback evidence

Scenario: Validation changes between preview and apply

• WHEN host-side revalidation or hash verification differs from the accepted candidate operation
• THEN the agent aborts before stopping the healthy runtime

Scenario: Apply is requested while another is active

• WHEN the singleton operation lock is held
• THEN the second request is rejected or remains queued without overlapping lifecycle mutations

Scenario: Shared-host profile is healthy

• WHEN shared-host apply recreates a host-network runtime with no published ports and an edge bound only to fixed loopback, and all runtime and edge health checks pass
• THEN the operation succeeds without a host-Caddy or X-UI lifecycle action

Scenario: Shared-host topology drifts

• WHEN runtime publishes a port, edge binds a non-loopback address, profile metadata changes, or Compose labels, mounts, network, capabilities, or Caddyfile differ from the fixed profile
• THEN the agent rejects the deployment before candidate replacement or reports failed health without claiming success

Scenario: Shared-host rollback succeeds

• WHEN candidate health fails and the previous Truf runtime and edge are restored
• THEN rollback completes exactly once without changing host Caddy, X-UI, or another unrelated service

Requirement: Automatic rollback and failed hold

If the new deployment fails its bounded health check, the agent SHALL restore byte-identical backups and verify the previous deployment; if rollback also fails, it SHALL stop retrying and retain a failed-hold state and all evidence for SSH recovery.

Scenario: New configuration fails startup

• WHEN the restarted runtime cannot reach required health within the deadline
• THEN the agent restores the prior active files and restarts the previous deployment

Scenario: Rollback succeeds

• WHEN the restored deployment reaches required health
• THEN the operation records rolled-back status and safe failure category without claiming apply success

Scenario: Rollback fails

• WHEN neither the candidate nor restored deployment becomes healthy
• THEN the agent enters failed hold, performs no replacement loop or forced authority release, and preserves backups and diagnostics

Requirement: Logical managed roots

The generic file page SHALL address only configured logical roots with explicit read, create/replace, and delete permissions, and SHALL never accept an absolute root from a client.

Scenario: Operator lists a managed runtime root

• WHEN a valid logical root ID for logs, keycheck projections, or result projections and a canonical relative directory are requested
• THEN the service returns a bounded read-only listing of permitted regular files and directories under that root

Scenario: Operator downloads rotated result projections

• WHEN the operator requests a permitted active or rotated result projection within its configured file-size bound
• THEN the service returns that regular single-link file without granting mutation access or exposing the backing runtime path

Scenario: Result projection names are allowlisted

• WHEN the result-projection root is listed or read
• THEN only active scan_results.jsonl and found_secrets.jsonl files and their exact six-digit generation names are visible, while locks, databases, ledgers, scan errors, temporary/quarantine directories, malformed generations, and recovery artifacts remain unavailable

Scenario: Large result projection is downloaded

• WHEN an allowed result projection is within the larger result-root byte bound
• THEN the service copies and hashes an unchanged source revision into an anonymous same-volume snapshot using bounded chunks, permits only one such snapshot at a time, streams the snapshot with bounded memory, and releases the snapshot and concurrency slot after response completion or failure

Scenario: Operator requests excluded storage

• WHEN a request targets application code, config/secrets through the generic page, PostgreSQL storage, sockets, host-agent metadata, raw result bundles, or an unknown root
• THEN the service rejects it without revealing host paths or existence details

Requirement: Descriptor-safe path containment

Managed-file traversal and mutation SHALL use a retained root directory descriptor, component-wise no-follow operations, canonical relative components, and regular single-link file checks.

Scenario: Relative traversal is attempted

• WHEN a path contains an empty, dot, dot-dot, absolute, drive-qualified, backslash, NUL, over-depth, or over-length component
• THEN the request is rejected before filesystem access outside the retained root

Scenario: Symlink is swapped during access

• WHEN a path component becomes a symlink between validation and open
• THEN no-follow descriptor traversal fails without accessing the link target

Scenario: Hardlink or special file is targeted

• WHEN the final object is multi-linked or is not a regular file
• THEN view, download, replace, and delete are rejected

Requirement: Durable bounded file mutation

An allowed managed-file create or replace SHALL use an exclusive same-directory temporary regular file, bounded bytes, fsync, atomic descriptor-relative replacement, directory fsync, and final ownership/type/mode verification.

Scenario: File replacement succeeds

• WHEN an authorized bounded replacement is submitted against the current file hash
• THEN readers observe either the complete old file or complete new file and audit records the safe before/after hashes

Scenario: File is concurrently changed

• WHEN the current file hash differs from the expected hash
• THEN replacement fails without overwriting the concurrent change

Scenario: Upload exceeds the root limit

• WHEN submitted bytes exceed the configured bounded file size
• THEN the service rejects and removes temporary data without changing the target

Requirement: Content-free operational audit

Configuration, secrets, and managed-file operations SHALL record actor, typed action, logical target, timestamps, result, safe category, byte counts where applicable, and before/after hashes, but SHALL NOT record file contents or credentials.

Scenario: Managed file is deleted

• WHEN an allowed delete succeeds against the expected hash
• THEN audit records the logical root/path and previous hash without retaining deleted content

Scenario: Secrets apply fails

• WHEN a secrets operation fails validation, startup, or rollback
• THEN status and audit expose only the bounded failure category and document hashes