feat(server): versioned REST API for ChurchTools Extension clients

[bwl21]

Motivation

A ChurchTools Extension should be able to maintain process parameters and use a running ct-cli instance as the trusted execution service:

1. the user starts the ct-cli server;
2. the Extension connects and pairs with it;
3. the Extension sends and optionally persists versioned process input;
4. the Extension invokes supported operations such as workspace initialization, login, validation, plan and apply;
5. ct-cli keeps responsibility for blueprint generation, ChurchTools access, state, backups and safety policy.

Conceptually, Commander and the HTTP server are peer adapters over a transport-neutral operation catalog that is the single source of truth. An application operation is defined and registered once, including its stable identity, typed input and result, mutating/read-only classification, required capabilities and long-running behavior. Every applicable projection derives its surface from, or is mechanically validated against, that definition: the Commander command tree and the HTTP router are both constructed from the same catalog. Each catalog entry defines the canonical parameter names, types, requiredness, defaults and validation as well as result and error schemas. Its projection metadata binds those parameters to CLI positional arguments and options and to an HTTP method, route path, path parameters, query parameters, headers or request body. Both bindings map to the same canonical input type; the operation contract and handler are not duplicated. Commander registration, HTTP routing and the OpenAPI document are generated from this metadata. Adding an operation therefore makes it appear in both CLI and REST with equivalent semantics and guardrails, without maintaining independent command and route lists. Adapter-only concerns such as HTTP health, pairing and sessions or terminal prompting are explicit exceptions; they do not define application operations. The HTTP contract models application requests and results, not Commander arguments, prompts, terminal output, or exit codes; new behavior belongs in the shared application/core layers rather than either adapter.

This makes a dedicated browser GUI inside ct-cli unnecessary. The earlier feat/gui and experiment/commander-generated-ui branches remain useful prototypes, but the ChurchTools Extension becomes the UI/client.

The server adapter must build on the shared application operations introduced by #156. It must not spawn the CLI, parse terminal output, or implement reconciliation and safety rules a second time.

Decisions for review

The contract below is a concrete candidate, not a record that every architectural choice has already been accepted. Review should explicitly decide the following points:

1. Server ownership: Should a maintained local HTTP server be part of ct-cli itself, or should the shared application operations be consumed by a separate adapter package/process?
2. API audience: Is REST a stable general-purpose client API, or an integration transport primarily for the ChurchTools Extension? Which compatibility obligations follow from that choice?
3. Resource hierarchy: Should clients navigate Workspace → Process → Environment → Operation? The current branch uses that projection, while the ownership and location of environments remains an open design decision in design(workspace): share environments while keeping process state local #166.
4. Authentication: Is short-lived pairing followed by capability-scoped bearer sessions the right local authentication model? Which capabilities and expiry/revocation semantics are required?
5. Versioning: What does the /api/v1 compatibility promise cover—routes, canonical parameter names, request/result schemas, error codes and OpenAPI operation IDs—and what qualifies as a breaking change?
6. Long-running work: Should plan/apply and similar operations be synchronous, polling-based jobs, SSE streams, or a combination? What cancellation and retention guarantees are required?
7. Mutation protocol: Is prepare → review/challenge → execute the correct transaction model for apply and other mutations? Which fingerprints, expiry rules and idempotency guarantees bind the prepared operation?
8. Network scope: Is non-loopback operation part of v1, deferred, or intentionally out of scope? If included, where must HTTPS terminate and which proxy trust model is acceptable?
9. Repository scope: Should the ChurchTools Extension eventually live in the ct-cli repository as an official reference client, or remain an independently released consumer?
10. Extension deployment and environment scope: Must v1 support both a central controller Extension that pushes processes from a model instance to managed target instances and an Extension running in a managed instance that pulls processes from a central catalog? How does pairing authorize the target-environment scope in each mode?

The choices made here should be recorded before the corresponding acceptance criteria are treated as mandatory. Security invariants still apply to every chosen design: no unrestricted shell, no remotely supplied executable configuration, no secret exposure, no arbitrary filesystem access, and no weakening of protected-environment confirmation.

Proposed contract

Publish a versioned OpenAPI contract below /api/v1. Exact resource names may change during design, but the first version must cover:

• health, version and capability discovery;
• pairing/session establishment;
• workspace initialization and selection;
• environment discovery and selection (aligned with feat(env): add environments to existing workspaces #153);
• ChurchTools login status, credential login and 2FA continuation;
• upload and validation of versioned process input;
• optional persistence and retrieval of immutable input snapshots, including schema version, client revision and digest;
• plan creation and retrieval, including warnings and a machine-readable diff;
• prepared apply followed by explicit execution;
• refresh and read-only state/coverage operations;
• progress and terminal results for long-running operations, via polling and/or SSE;
• structured, stable error responses.

Mutating requests should support idempotency keys. A prepared apply must be bound to the exact workspace, environment, configuration digest and plan digest, expire after a limited time, and be rejected if any of those inputs changed.

The configuration payload is process input, not executable JavaScript supplied by the browser. A locally installed/trusted generator turns that input into the normal ct-cli configuration/blueprint model.

Extension deployment and target environments

The ChurchTools instance in which the Extension UI runs is not necessarily the instance changed by an operation. The contract must therefore distinguish:

• the Extension origin, identifying the ChurchTools instance that hosts the UI;
• an optional source/model environment, from which a centrally maintained process originates;
• the target environment, against which plan and apply run.

Two operating modes should be considered:

1. Central push: The Extension runs in a central model instance and selects a process plus one of the managed target environments known to the server. It can then request plan/apply for that target.
2. Instance-bound pull: The Extension runs in a managed instance, obtains processes available from a central catalog and installs or updates them in that instance. The server normally maps the Extension origin to exactly that target environment.

The server is authoritative for environment discovery and authorization. The Extension does not read ct.envs.json, construct environment IDs, or declare arbitrary targets. After pairing, it discovers only the target environments allowed for that session and sends back server-issued environment IDs when invoking operations.

Pairing must bind the resulting session not only to capabilities such as read, plan, or apply, but also to a server-determined target-environment scope. In instance-bound mode this will normally contain only the environment matching the Extension origin. In central-push mode it may contain an explicitly authorized set of managed environments. The server must validate this scope again for every operation, especially plan and apply.

Local and network modes

Safe default:

• listen on loopback only;
• choose/configure a port explicitly;
• require a short-lived pairing flow instead of trusting any page in the browser;
• allow only explicitly configured Extension origins;
• do not enable ambient cross-origin credentials.

Non-loopback operation is required for setups where the Extension/browser and ct-cli server are on different hosts or where ct-cli runs in a VM/container. It must be an explicit mode, with separate listen and advertised/public addresses.

Network mode must require:

• authenticated, capability-scoped sessions;
• HTTPS, either terminated by ct-cli or by a declared trusted reverse proxy;
• exact origin allowlisting and appropriate CSRF/private-network protections;
• request-size limits, rate limiting and secret-redacted audit logs;
• configured workspace roots: API clients must never select arbitrary filesystem paths;
• serialized/locked state mutations and clear single-user versus multi-user semantics.

Starting with --host 0.0.0.0 alone is not an acceptable security model.

Credentials and secrets

For init/login the API may accept username and password as a one-shot request, plus a separate 2FA continuation. Credentials must never be returned, logged, included in snapshots, or written to process files. The resulting ChurchTools token remains host-bound and is stored through the existing secure token-store abstraction where available.

Remote credential submission is disabled unless the connection is HTTPS. Deployments that cannot provide secure transport should use a local login/pairing flow instead.

Safety invariants

• The HTTP adapter invokes the same typed application operations as Commander (refactor(core): expose shared application operations #156).
• Protected-environment policy, confirmation challenges, backups, mutation ordering and postconditions remain in the application/core layer.
• apply is never a single unbound “run this config” call: plan review and prepared execution remain distinct.
• Secrets and ChurchTools tokens are never exposed to the Extension.
• API requests cannot escape configured workspaces or choose arbitrary state/config paths.
• Concurrent writes to one workspace/environment cannot corrupt state.

Non-goals

• shipping or maintaining an embedded ct-cli GUI;
• exposing an unrestricted shell or a generic “run command” endpoint;
• allowing remotely supplied executable blueprint code;
• replacing the existing CLI;
• weakening protected-environment confirmations for UI convenience.

Acceptance criteria

• A reviewed OpenAPI document defines /api/v1, request/result/error envelopes and compatibility rules.
• Local loopback mode is secure by default and documented with a pairing flow.
• An Extension can initialize/select a workspace, authenticate to a named ChurchTools environment, push and retrieve a versioned input snapshot, validate it, create a plan and execute an explicitly prepared apply.
• Long-running calls expose progress and cancellation/terminal state without holding a fragile request open indefinitely.
• Network binding is explicit and refuses unsafe combinations (for example remote credentials over plaintext HTTP).
• CORS/origin, authentication, authorization, redaction, workspace containment, state locking and request limits have automated tests.
• Environment discovery is server-authoritative: paired sessions expose only their allowed target environments, and every operation validates its target against that scope. Tests cover both central-push and instance-bound-pull behavior.
• A transport-neutral operation catalog is the single source of truth: each application operation is defined and registered once, including canonical parameter and result schemas plus explicit CLI and HTTP bindings. The Commander command tree, HTTP router and OpenAPI document are generated from it; no independent command, route or contract lists are maintained.
• Adapter-parity tests enumerate that catalog and prove that every non-adapter-specific operation is exposed through both CLI and REST with the same semantics and guardrails; a missing projection fails automated checks.
• The server never shells out to ct and never parses CLI output.
• Documentation contains local, container/LAN and reverse-proxy examples plus a threat-model section.