eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00

5.6 KiB

WishForge IDE policy integration

This is a real Theia 1.76 frontend/backend extension, loaded by the independent IDE build. It implements collaboration routing, editor coordination and backend DAP gates. It does not replace operating-system process isolation.

Commands and editor lifecycle

Use the command palette (Cmd/Ctrl+Shift+P):

  • WishForge: Create Verified Workspace Snapshot asks every registered client to freeze its text editors, run ApplicationShell.saveAll, return the complete document version vector, and confirm that vector again. The backend freezes the participant set and disk digest, requires each acknowledgement, and commits an immutable-content snapshot with a monotonically increasing saved revision.
  • A dirty/unsavable buffer, changed version, new/disconnected participant, expired acknowledgement or changed disk refuses the snapshot. Frozen editors are released on success, failure or connection closure. The saved revision is independent from a requirement's WishRevision and from a Git commit SHA.
  • WishForge: Recover Unsaved Draft reads workspace/actor-scoped IndexedDB records. Dirty content plus its original baseline survives page reload. Recovery opens a comparison against the current saved file and an unsaved recovery copy; it never automatically writes the original. Changed saved contents are explicitly reported. Saving the current buffer removes its current recovery record, not unrelated older unconfirmed drafts. Text plus baseline is limited to 2 MiB UTF-8.
  • Acquire Debug Control, Transfer Debug Control, and Release Debug Control manage a 30-second renewable backend lease. A same-actor second tab does not obtain another tab's token. Tokens remain backend-only; transfer rotates them and notifies the target client. Connection closure releases its ownership.

The snapshot orchestration is exposed over the actual Theia service path /services/wishforge-coordination. It is connected to editor/command lifecycle, not an unattached sample API. Automated Git integration/build must explicitly use an accepted workspace snapshot if it depends on live human workspace contents; this RPC does not by itself wire that gate into every platform workflow.

Backend identity and DAP enforcement

The gateway strips caller-supplied x-wishforge-* headers and signs the API-granted actor/role/tenant/workspace with Ed25519. Theia verifies the signature, audience, scope and expiry. Only the gateway has the private key; the workspace receives only a pinned public key. Unsigned/forged actor strings cannot acquire the normal coordination or debug API. Viewer access is denied before the IDE session starts.

Two actual backend paths are guarded:

  1. Native /services/debug-adapter/:id wraps ForwardingDebugChannel and checks the live lease before passing each DAP message to the adapter callback.
  2. Bundled VS Code/js-debug adapters travel through HostedPluginProcess.onMessage. The policy validates Theia's nested MessagePack batch and intercepts DebugExt.$createDebugSession / $terminateDebugSession and ConnectionExt.$sendMessage / $deleteConnection. Unauthorized requests are never forwarded. A blocked DAP request receives both its RPC failure and a matching DAP failure notification so the client is not left waiting forever.

Unrelated plugin RPC bytes are preserved. Tests use real Theia encoders, RPCProtocol, ConnectionImpl and ForwardingDebugChannel rather than a made-up wire shape. Real UI acceptance also exercised the bundled js-debug: F5 was denied without a lease; after acquisition, Node paused, showed stack/variables, and stepped to a state with count: 1.

Runtime configuration

Gateway only: WF_IDE_GATEWAY_PRIVATE_KEY_FILE.

Theia: WF_IDE_GATEWAY_PUBLIC_KEY_FILE, WF_TENANT_ID, WF_WORKSPACE_ID, WISHFORGE_WORKSPACE_PATH, WF_COORDINATION_STATE_DIR outside the source tree. Use node apps/ide/security/create-local-keys.cjs for an isolated local fixture key pair. It prints paths only and never replaces an existing key pair silently. Missing coordination identity/configuration fails closed for snapshots/debug while ordinary IDE startup remains possible. Provisioned production instances must use reviewed public-key configuration and durable state storage.

Threat and acceptance boundary

A separate directory or PVC is not an OS privilege boundary. The current Theia backend and human terminal run under the same UID. A malicious terminal can modify same-UID writable state or stop/replace that backend. Mode 0700, read-only snapshot files and signed gateway assertions do not prevent that threat. These are authenticated cooperative-client controls and local integrity/recovery checks, not hard isolation between malicious editors sharing a workspace.

Do not promote these workspace snapshots into independently trusted release proof. Final Git verification/build evidence still belongs to the separately isolated verifier. Strong same-workspace isolation needs direct gateway-to- coordination-sidecar routing and independently controlled debugger/target processes, with state inaccessible to the terminal UID; merely moving the state volume is insufficient. The tenant/workspace Kata boundary remains a separate requirement.

The lease can transfer between clients, but attaching another user's UI to an already-running plugin-host-owned debugger session is not implemented by the lease itself. Room state remains in-memory OCT state: draft comparison recovery is implemented, not lossless room reconstruction. Python debugger acceptance, production OIDC identity variants, HA coordination and hostile-terminal containment remain separate checks.