docs: document runtime auth setup

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).

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.
+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/validation.md`](development/validation.md) — how to check changes.
+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
 

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
+<data_dir>/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
+<data_dir>/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 '<SERVER_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 '<SERVER_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 '<RUNTIME_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 <WORKSPACE_ROOT>
+```
+
+## 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 '<NEW_SERVER_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 '<NEW_RUNTIME_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.