diff --git a/crates/worker-runtime/README.md b/crates/worker-runtime/README.md index 72d5768a..bc4cdfdf 100644 --- a/crates/worker-runtime/README.md +++ b/crates/worker-runtime/README.md @@ -10,7 +10,7 @@ From the repository root: cargo run -p worker-runtime \ --features ws-server,fs-store \ --bin worker-runtime-rest-server \ - -- --workspace . + -- --bind 127.0.0.1:38800 ``` By default the server listens on: @@ -25,9 +25,8 @@ To bind another address explicitly: cargo run -p worker-runtime \ --features ws-server,fs-store \ --bin worker-runtime-rest-server \ - -- --workspace . --bind 127.0.0.1:38800 + -- --bind 0.0.0.0:38800 ``` -`--workspace` is currently a legacy bootstrap input for the v0 local materializer / Worker profile resolution path. It is not intended to be the long-term Runtime identity or a single-workspace binding. Future Runtime launches should receive Workspace / Repository context through Worker launch requests and config bundles instead. - The REST server is intended for a trusted Backend/proxy, not direct browser access. +For authenticated remote Runtime setup, see [`../../docs/development/server-runtime-auth.md`](../../docs/development/server-runtime-auth.md). diff --git a/docs/README.md b/docs/README.md index 2589f28d..0c68eca0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,8 +16,9 @@ It is not a dumping ground for external research, old plans, API inventories, or 8. [`design/memory-knowledge.md`](design/memory-knowledge.md) — generated memory and audit records. 9. [`design/workspace-kanban-orchestrator-runtime.md`](design/workspace-kanban-orchestrator-runtime.md) — how Kanban operations become durable orchestration events and backend-internal routing decisions. 10. [`design/workspace-runtime-docker.md`](design/workspace-runtime-docker.md) — the WebUI / Backend / Runtime split, Docker image layout, worker launch path, and workdir materialization boundary. -11. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed. -12. [`development/validation.md`](development/validation.md) — how to check changes. +11. [`development/server-runtime-auth.md`](development/server-runtime-auth.md) — manual Workspace Server / Runtime public-key exchange and authenticated Runtime startup checks. +12. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed. +13. [`development/validation.md`](development/validation.md) — how to check changes. ## What belongs here diff --git a/docs/development/server-runtime-auth.md b/docs/development/server-runtime-auth.md new file mode 100644 index 00000000..c2965608 --- /dev/null +++ b/docs/development/server-runtime-auth.md @@ -0,0 +1,267 @@ +# Server / Runtime manual auth setup + +Workspace Server and Worker Runtime authenticate remote Runtime control traffic with manually exchanged Ed25519 public keys and short-lived Server-signed capability tokens. + +This is a non-interactive bootstrap flow. Commands fail when required flags are missing, and existing identity/trust records are not overwritten unless `--replace` is passed explicitly. + +## Authority boundary + +- Workspace Server is the workspace control plane. It owns trusted Runtime records in the Server DB and signs per-request Runtime capability tokens. +- Runtime owns Worker execution. It does not own a workspace registry or workspace list. +- Runtime API paths remain worker-centric; workspace scope is carried in the signed auth context and enforced by Runtime-side authorization/filtering code. +- Browser/Web clients should talk to Workspace Server, not directly to Runtime. + +## Identifiers used in examples + +Replace these values for the deployment: + +```text +SERVER_ID=server-main +RUNTIME_ID=runtime-main +RUNTIME_BASE_URL=http://127.0.0.1:38800 +``` + +`SERVER_ID` is the issuer id in Server-signed tokens. `RUNTIME_ID` is the token audience and must match the Runtime identity. + +## 1. Create and show the Server identity + +From the Workspace Server host: + +```bash +yoi-workspace-server identity init --server-id server-main +``` + +Show the public identity and copy the `public_key` value: + +```bash +yoi-workspace-server identity show --json +``` + +The Server private identity is stored in the Yoi data directory under the Server data root, currently: + +```text +/server/identity.toml +``` + +On Unix this file is written with `0600` permissions. Do not copy the private key to Runtime or commit it to the repository. + +## 2. Create and show the Runtime identity + +From the Runtime host, using the same Runtime storage flags that the Runtime server process will use: + +```bash +worker-runtime-rest-server identity init --runtime-id runtime-main +``` + +Show the public identity and copy the `public_key` value: + +```bash +worker-runtime-rest-server identity show --json +``` + +By default, Runtime auth state is stored at: + +```text +/runtime/auth.toml +``` + +If the Runtime process is launched with `--fs-root` or `--fs-runtime-dir`, pass the same flags to every `identity` and `trust-server` command. Otherwise the setup command may write an auth file that the server process never reads. + +Example with explicit Runtime storage: + +```bash +worker-runtime-rest-server identity init \ + --runtime-id runtime-main \ + --fs-root /var/lib/yoi-runtime + +worker-runtime-rest-server identity show \ + --json \ + --fs-root /var/lib/yoi-runtime +``` + +## 3. Register the Server public key on Runtime + +On the Runtime host, register the Server public key copied from `yoi-workspace-server identity show --json`: + +```bash +worker-runtime-rest-server trust-server add \ + --server-id server-main \ + --public-key '' +``` + +With explicit Runtime storage, keep using the same storage flags: + +```bash +worker-runtime-rest-server trust-server add \ + --server-id server-main \ + --public-key '' \ + --fs-root /var/lib/yoi-runtime +``` + +Verify: + +```bash +worker-runtime-rest-server trust-server list --json +``` + +## 4. Register the Runtime public key and endpoint on Server + +On the Workspace Server host, register the Runtime public key copied from `worker-runtime-rest-server identity show --json`: + +```bash +yoi-workspace-server trust-runtime add \ + --runtime-id runtime-main \ + --base-url http://127.0.0.1:38800 \ + --public-key '' \ + --display-name 'Runtime main' +``` + +This writes a trusted Runtime record to the Server DB. During `yoi-workspace-server serve`, active trusted Runtime records are loaded as remote Runtime sources and receive signed capability tokens. You do not need to duplicate the same Runtime in `runtimes.toml` for this trust-backed path. + +Verify: + +```bash +yoi-workspace-server trust-runtime list --json +``` + +## 5. Start Runtime and Workspace Server + +Start Runtime with the same storage flags used during Runtime identity/trust setup: + +```bash +worker-runtime-rest-server \ + --bind 127.0.0.1:38800 +``` + +For repository builds, the equivalent cargo command is: + +```bash +cargo run -p worker-runtime \ + --features ws-server,fs-store \ + --bin worker-runtime-rest-server \ + -- --bind 127.0.0.1:38800 +``` + +Start Workspace Server: + +```bash +yoi-workspace-server serve --listen 127.0.0.1:8787 +``` + +For repository builds: + +```bash +cargo run -p yoi-workspace-server -- serve --listen 127.0.0.1:8787 +``` + +If the Server DB has no workspace record yet, initialize it first: + +```bash +yoi-workspace-server init --workspace +``` + +## Smoke checks + +Check both trust stores: + +```bash +yoi-workspace-server trust-runtime list --json +worker-runtime-rest-server trust-server list --json +``` + +Check that Workspace Server can see Runtime workers through the authenticated path. From the CLI: + +```bash +yoi workers \ + --backend http://127.0.0.1:8787 \ + --runtime-id runtime-main +``` + +In Web, open the Workspace UI through Workspace Server and verify that Runtime worker listing, worker creation, and Console protocol input work. The protocol WebSocket uses the same Server-signed Runtime auth path as REST control calls. + +## Rotation and replacement + +Identity and trust records are intentionally not overwritten by default. + +Rotate Server identity: + +```bash +yoi-workspace-server identity init --server-id server-main --replace +``` + +After Server identity rotation, every Runtime that trusts that Server must be updated with the new Server public key: + +```bash +worker-runtime-rest-server trust-server add \ + --server-id server-main \ + --public-key '' \ + --replace +``` + +Rotate Runtime identity: + +```bash +worker-runtime-rest-server identity init --runtime-id runtime-main --replace +``` + +After Runtime identity rotation, Server must be updated with the new Runtime public key: + +```bash +yoi-workspace-server trust-runtime add \ + --runtime-id runtime-main \ + --base-url http://127.0.0.1:38800 \ + --public-key '' \ + --replace +``` + +## Revocation + +Revoke a trusted Runtime on Server: + +```bash +yoi-workspace-server trust-runtime revoke --runtime-id runtime-main +``` + +Remove a trusted Server from Runtime: + +```bash +worker-runtime-rest-server trust-server revoke --server-id server-main +``` + +## Troubleshooting + +### `trusted runtimes are registered but server identity is not initialized` + +The Server DB contains trusted Runtime records, but the Server signing identity file does not exist. Run: + +```bash +yoi-workspace-server identity init --server-id server-main +``` + +If the identity was created in another environment, ensure the Server process is using the same Yoi data directory. + +### Runtime accepts unauthenticated requests + +Runtime only enables signed capability-token auth when both a Runtime identity and at least one trusted Server are present in its auth file. Check: + +```bash +worker-runtime-rest-server identity show --json +worker-runtime-rest-server trust-server list --json +``` + +Also confirm the Runtime process was started with the same `--fs-root` / `--fs-runtime-dir` used for setup. + +### Wrong audience or unauthorized Runtime response + +Confirm the `--runtime-id` registered on Server exactly matches the Runtime identity id: + +```bash +worker-runtime-rest-server identity show --json +yoi-workspace-server trust-runtime list --json +``` + +`RUNTIME_ID` is the token audience; mismatches are rejected by Runtime. + +### Duplicate registration fails + +This is expected. Use `--replace` only when intentionally rotating or updating trust material.