@openchamber/web 2.0.2 → 2.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/lib/DOCUMENTATION.md +1 -1
- package/bin/lib/commands-connect-url.js +6 -5
- package/bin/lib/commands-tunnel.js +24 -5
- package/dist/assets/{CodeMirrorCommentWidgets-CmKmyb9T.js → CodeMirrorCommentWidgets-C_zL-eri.js} +1 -1
- package/dist/assets/{DiffView-8-PFpZ2p.js → DiffView-BeN2_YYF.js} +3 -3
- package/dist/assets/FilesView-CN34wm_N.js +17 -0
- package/dist/assets/{GitView-DNUSu00w.js → GitView-DLDazOo1.js} +4 -4
- package/dist/assets/{GuestAttachDialog-Cv6QzjHC.js → GuestAttachDialog-C0xe_Lyy.js} +1 -1
- package/dist/assets/{GuestSurfacePane-Bt3jB_Ye.js → GuestSurfacePane-BdaurnDr.js} +1 -1
- package/dist/assets/{JsonTreeView-BlyHTRhM.js → JsonTreeView-B1Xq-k2t.js} +1 -1
- package/dist/assets/LinearIssuesView-BryoAHow.js +1 -0
- package/dist/assets/{MarkdownImageGallery-2UXJF-5B.js → MarkdownImageGallery-DfuEoaGq.js} +1 -1
- package/dist/assets/MarkdownRendererImpl-B_ZcWOvX.js +12 -0
- package/dist/assets/OnboardingScreen-C22bGmnP.js +1 -0
- package/dist/assets/{PatchDiff-ByvnbG5T.js → PatchDiff-0xd6UeFB.js} +1 -1
- package/dist/assets/{PierreDiffViewer-BXieg0mH.js → PierreDiffViewer-BC950e3F.js} +3 -3
- package/dist/assets/PlanView-B7Xgihqk.js +5 -0
- package/dist/assets/PluginPane-2C71F8uF.js +3 -0
- package/dist/assets/SettingsView-m_zoFiaT.js +30 -0
- package/dist/assets/{SettingsWindow-BIz224xs.js → SettingsWindow-CofS020b.js} +1 -1
- package/dist/assets/{SubmoduleDiffSummary-CXKmlps9.js → SubmoduleDiffSummary-BSA9gnIO.js} +1 -1
- package/dist/assets/{ToolOutputDialog-BsgAK8xu.js → ToolOutputDialog-DprkVKcj.js} +7 -7
- package/dist/assets/{ToolPartDiffPreview-vdPObXOf.js → ToolPartDiffPreview-Dq0go_fX.js} +2 -2
- package/dist/assets/{VirtualizedFileDiff-BkFNKWS5.js → VirtualizedFileDiff-Kp8hKJdT.js} +1 -1
- package/dist/assets/WalkthroughView-DGnTzqIU.js +4 -0
- package/dist/assets/{appThemeRegistry-aHUNHoqP.js → appThemeRegistry-BdEHBA4s.js} +1 -1
- package/dist/assets/{commitAndPush-Bon9r94r.js → commitAndPush-LwtVa2Oc.js} +1 -1
- package/dist/assets/{computeVirtualFileMetrics-DKqr_1AQ.js → computeVirtualFileMetrics-6V1xNpO9.js} +2 -2
- package/dist/assets/de-DlgBHUAI.js +10 -0
- package/dist/assets/es-BC8G41U8.js +16 -0
- package/dist/assets/fr-I0z3vVjy.js +14 -0
- package/dist/assets/index-CgR5rJq_.js +41 -0
- package/dist/assets/{index-DpFttslC.js → index-CmNPYddV.js} +1 -1
- package/dist/assets/index-adyy_sEk.css +1 -0
- package/dist/assets/{isDiffPlainText-kzAgpIgi.js → isDiffPlainText-1bXcWCrw.js} +1 -1
- package/dist/assets/{isFilePlainText-Uj6y-jzz.js → isFilePlainText-CBAppvy1.js} +1 -1
- package/dist/assets/ja-BIElEsY8.js +16 -0
- package/dist/assets/ko-DRnnHetA.js +16 -0
- package/dist/assets/{main-CbfMxn-I.js → main-CzjTMTfW.js} +2 -2
- package/dist/assets/main-DVX34beR.js +886 -0
- package/dist/assets/markdownCore-Cxbkn5NR.js +7 -0
- package/dist/assets/{miniChat-CiAKBC10.js → miniChat-CP68IL8Q.js} +2 -2
- package/dist/assets/{mobile-CsT4sJwC.js → mobile-BrlBrNfZ.js} +2 -2
- package/dist/assets/nl-DzUV-kwp.js +16 -0
- package/dist/assets/{patchFileDiff-DeaE08W0.js → patchFileDiff-pqRSHLHI.js} +2 -2
- package/dist/assets/pl-Bb-cb7k7.js +16 -0
- package/dist/assets/pt-BR-CyIWrTcE.js +16 -0
- package/dist/assets/renderElectronMiniChatApp-DKIilR7N.js +2 -0
- package/dist/assets/renderMobileApp-B0z6-x58.js +25 -0
- package/dist/assets/runtimeEndpointReset-uu1DBwLL.js +52 -0
- package/dist/assets/{scheduledTasksApi-BZCNJ588.js → scheduledTasksApi-BuzWT445.js} +1 -1
- package/dist/assets/{shikiHighlight-BSUEa3yF.js → shikiHighlight-BWGrY5YU.js} +1 -1
- package/dist/assets/{textMateThemeFromAppTheme-CsATFZIV.js → textMateThemeFromAppTheme-BSUFChBY.js} +1 -1
- package/dist/assets/tr-DXEDSoYO.js +7 -0
- package/dist/assets/uk-C8hN--q_.js +16 -0
- package/dist/assets/useAppFontEffects-Dsl_sLrj.js +7366 -0
- package/dist/assets/useInlineCommentController-d5vntsQ_.js +2 -0
- package/dist/assets/{useRootScrollLock-Cp1eFoM2.js → useRootScrollLock-2rd5Y6gR.js} +2 -2
- package/dist/assets/{vendor-base-ui-CsXYnR5c.js → vendor-base-ui-DnNniUWp.js} +1 -1
- package/dist/assets/{vendor-codemirror-language-data-BwwommM0.js → vendor-codemirror-language-data-B1EetJur.js} +2 -2
- package/dist/assets/vendor-opencode-client-DSZl7jSi.js +12 -0
- package/dist/assets/{vendor-tanstack-react-virtual-ClYN8CzB.js → vendor-tanstack-react-virtual--0sBrLRh.js} +1 -1
- package/dist/assets/{vendor-tanstack-virtual-core-BewVQryB.js → vendor-tanstack-virtual-core-BoA4iGMw.js} +1 -1
- package/dist/assets/{vendor-zod-BSoePkpP.js → vendor-zod-CxRSdNoV.js} +4 -4
- package/dist/assets/{web-components-D3Yjr4Zx.js → web-components-ngpHPEDU.js} +1 -1
- package/dist/assets/zh-CN-CtzXdjMZ.js +16 -0
- package/dist/assets/zh-TW-Ds0CADSz.js +16 -0
- package/dist/index.html +5 -5
- package/dist/mini-chat.html +5 -5
- package/dist/mobile.html +5 -5
- package/package.json +5 -5
- package/server/index.js +82 -4
- package/server/lib/agent-tool/DOCUMENTATION.md +8 -1
- package/server/lib/agent-tool/runtime.js +13 -4
- package/server/lib/agent-tool/runtime.test.js +15 -0
- package/server/lib/context-obligatory/DOCUMENTATION.md +10 -7
- package/server/lib/context-obligatory/runtime.js +2 -1
- package/server/lib/context-obligatory/runtime.test.js +76 -30
- package/server/lib/dictation/DOCUMENTATION.md +4 -1
- package/server/lib/dictation/openai-compatible-session.js +7 -0
- package/server/lib/enterprise-mode.d.ts +30 -0
- package/server/lib/enterprise-mode.js +253 -0
- package/server/lib/enterprise-mode.test.js +247 -0
- package/server/lib/event-stream/translate-v2.js +6 -0
- package/server/lib/event-stream/translate-v2.test.js +6 -0
- package/server/lib/git/DOCUMENTATION.md +2 -1
- package/server/lib/git/routes.js +44 -1
- package/server/lib/git/routes.test.js +98 -1
- package/server/lib/git/service.js +146 -11
- package/server/lib/git/service.test.js +195 -0
- package/server/lib/github/routes.js +9 -19
- package/server/lib/github/routes.test.js +112 -0
- package/server/lib/guests/DOCUMENTATION.md +4 -2
- package/server/lib/guests/background.test.js +1 -1
- package/server/lib/guests/catalog.js +56 -2
- package/server/lib/guests/catalog.test.js +24 -1
- package/server/lib/guests/clone-network.test.js +52 -0
- package/server/lib/guests/clone.js +30 -4
- package/server/lib/guests/enterprise.js +68 -0
- package/server/lib/guests/enterprise.test.js +106 -0
- package/server/lib/guests/grant-scope.js +8 -2
- package/server/lib/guests/grant-scope.test.js +9 -0
- package/server/lib/guests/html-styles.js +16 -2
- package/server/lib/guests/html-styles.test.js +53 -4
- package/server/lib/guests/install.js +10 -0
- package/server/lib/guests/persist.js +1 -0
- package/server/lib/guests/routes.js +40 -5
- package/server/lib/guests/updates.js +9 -2
- package/server/lib/notifications/DOCUMENTATION.md +1 -1
- package/server/lib/notifications/runtime.js +22 -8
- package/server/lib/notifications/trigger-runtime.test.js +45 -0
- package/server/lib/openchamber-sessions/session-metadata-store.js +27 -0
- package/server/lib/openchamber-sessions/session-metadata-store.test.js +18 -0
- package/server/lib/opencode/DOCUMENTATION.md +13 -9
- package/server/lib/opencode/auth-state-runtime.js +2 -2
- package/server/lib/opencode/config-paths.test.js +1 -0
- package/server/lib/opencode/env-runtime.js +26 -3
- package/server/lib/opencode/env-runtime.test.js +57 -0
- package/server/lib/opencode/feature-routes-runtime.js +2 -0
- package/server/lib/opencode/hmr-state-runtime.js +4 -3
- package/server/lib/opencode/lifecycle.js +10 -5
- package/server/lib/opencode/lifecycle.test.js +6 -2
- package/server/lib/opencode/managed-config-file.js +2 -1
- package/server/lib/opencode/managed-config-file.test.js +18 -0
- package/server/lib/opencode/npm-registry-config.d.ts +1 -0
- package/server/lib/opencode/npm-registry-config.js +123 -0
- package/server/lib/opencode/npm-registry-config.test.js +167 -0
- package/server/lib/opencode/npm-registry.js +5 -6
- package/server/lib/opencode/npm-registry.test.js +30 -0
- package/server/lib/opencode/openchamber-routes.js +8 -0
- package/server/lib/opencode/project-icon-routes.js +2 -2
- package/server/lib/opencode/project-icon-routes.test.js +44 -0
- package/server/lib/opencode/provider-source-route.test.js +32 -0
- package/server/lib/opencode/routes.js +17 -2
- package/server/lib/opencode/settings-helpers.js +26 -3
- package/server/lib/opencode/settings-helpers.test.js +12 -5
- package/server/lib/opencode/settings-registry.json +35 -1
- package/server/lib/opencode/settings-runtime.js +1 -0
- package/server/lib/opencode/shutdown-runtime.js +2 -0
- package/server/lib/opencode/static-routes-runtime.js +9 -1
- package/server/lib/opencode/static-routes-runtime.test.js +58 -1
- package/server/lib/package-manager.js +4 -1
- package/server/lib/package-manager.test.js +24 -0
- package/server/lib/permission-auto-accept/DOCUMENTATION.md +23 -15
- package/server/lib/permission-auto-accept/modes.js +26 -0
- package/server/lib/permission-auto-accept/runtime.js +146 -40
- package/server/lib/permission-auto-accept/runtime.test.js +93 -9
- package/server/lib/quota/DOCUMENTATION.md +6 -0
- package/server/lib/quota/providers/zhipuai-coding-plan.js +74 -30
- package/server/lib/quota/providers/zhipuai-coding-plan.test.js +124 -0
- package/server/lib/relay/DOCUMENTATION.md +1 -1
- package/server/lib/relay/service.js +32 -12
- package/server/lib/relay/service.test.js +30 -0
- package/server/lib/routing/DOCUMENTATION.md +150 -41
- package/server/lib/routing/classifier.js +156 -0
- package/server/lib/routing/defaults.js +27 -0
- package/server/lib/routing/jev.js +5 -17
- package/server/lib/routing/routes.http.test.js +9 -0
- package/server/lib/routing/routes.js +27 -1
- package/server/lib/routing/runtime.js +199 -33
- package/server/lib/routing/runtime.test.js +299 -15
- package/server/lib/routing/store.js +57 -0
- package/server/lib/routing/store.test.js +37 -0
- package/server/lib/session-assist/DOCUMENTATION.md +17 -7
- package/server/lib/session-assist/context.js +42 -2
- package/server/lib/session-assist/context.test.js +38 -1
- package/server/lib/session-assist/runtime.js +57 -13
- package/server/lib/session-assist/runtime.test.js +45 -0
- package/server/lib/session-goal/DOCUMENTATION.md +47 -22
- package/server/lib/session-goal/audit.js +112 -0
- package/server/lib/session-goal/audit.test.js +58 -0
- package/server/lib/session-goal/runtime.js +113 -134
- package/server/lib/session-goal/runtime.test.js +146 -13
- package/server/lib/session-lineage.js +52 -0
- package/server/lib/session-lineage.test.js +45 -0
- package/server/lib/session-work/DOCUMENTATION.md +108 -0
- package/server/lib/session-work/questions.js +126 -0
- package/server/lib/session-work/runtime.js +278 -0
- package/server/lib/session-work/runtime.test.js +255 -0
- package/server/lib/session-work/state.js +48 -0
- package/server/lib/session-work/state.test.js +34 -0
- package/server/lib/small-model/DOCUMENTATION.md +14 -7
- package/server/lib/small-model/client.js +7 -4
- package/server/lib/small-model/index.js +11 -21
- package/server/lib/small-model/index.test.js +13 -26
- package/server/lib/spaces/DOCUMENTATION.md +79 -25
- package/server/lib/spaces/gatekeeper-channel.js +63 -11
- package/server/lib/spaces/gatekeeper-channel.test.js +34 -4
- package/server/lib/spaces/gatekeeper-program.cjs +64 -13
- package/server/lib/spaces/gatekeeper-program.test.js +115 -3
- package/server/lib/spaces/host.js +58 -13
- package/server/lib/spaces/host.test.js +34 -1
- package/server/lib/spaces/idle-stop.js +98 -0
- package/server/lib/spaces/idle-stop.test.js +130 -0
- package/server/lib/spaces/journey.js +427 -17
- package/server/lib/spaces/journey.test.js +592 -5
- package/server/lib/spaces/layout.js +27 -6
- package/server/lib/spaces/manager.test.js +1 -1
- package/server/lib/spaces/places/contract-suite.js +4 -2
- package/server/lib/spaces/places/docker-live-support.js +27 -4
- package/server/lib/spaces/places/docker.js +32 -5
- package/server/lib/spaces/places/docker.test.js +38 -8
- package/server/lib/spaces/places/escape-suite.js +32 -0
- package/server/lib/spaces/places/fake-docker.js +3 -1
- package/server/lib/spaces/places/grants.docker.live.test.js +197 -0
- package/server/lib/spaces/places/memory-place.js +3 -3
- package/server/lib/spaces/places/sessions.docker.live.test.js +4 -2
- package/server/lib/spaces/routes.js +49 -1
- package/server/lib/spaces/routes.test.js +31 -3
- package/server/lib/spaces/space-opencode.js +52 -0
- package/server/lib/spaces/space-opencode.test.js +41 -0
- package/server/lib/spaces/space-records.js +90 -2
- package/server/lib/spaces/space-records.test.js +58 -1
- package/server/lib/spaces/space-server.js +13 -1
- package/server/lib/spaces/space-server.test.js +13 -0
- package/server/lib/spaces/space-setup.js +173 -0
- package/server/lib/spaces/space-setup.test.js +174 -0
- package/server/lib/tts/DOCUMENTATION.md +3 -0
- package/server/lib/tts/base-url.js +8 -0
- package/server/lib/tts/routes.js +13 -1
- package/server/lib/tts/routes.test.js +26 -0
- package/server/lib/tunnels/DOCUMENTATION.md +2 -0
- package/server/lib/tunnels/routes.js +14 -0
- package/server/lib/tunnels/routes.test.js +26 -0
- package/server/lib/walkthrough/index.js +11 -7
- package/server/lib/walkthrough/jobs.test.js +8 -0
- package/server/lib/walkthrough/languages.js +1 -0
- package/server/lib/walkthrough/routes.js +7 -1
- package/dist/assets/FilesView-0Ie20mEk.js +0 -17
- package/dist/assets/LinearIssuesView-CSl2MUfA.js +0 -1
- package/dist/assets/MarkdownRendererImpl-DVHqZoug.js +0 -12
- package/dist/assets/OnboardingScreen-CIdXJpfc.js +0 -1
- package/dist/assets/PlanView-DEIi3Q7M.js +0 -5
- package/dist/assets/PluginPane-BEPUWVho.js +0 -3
- package/dist/assets/SettingsView-CiNh-RbW.js +0 -30
- package/dist/assets/WalkthroughView-6oE-MuDL.js +0 -4
- package/dist/assets/de-CgAJ51z7.js +0 -10
- package/dist/assets/es-zGi_ravM.js +0 -16
- package/dist/assets/fr-CPfogrWx.js +0 -14
- package/dist/assets/index-CHfphYL3.js +0 -41
- package/dist/assets/index-DvMJ3w6V.css +0 -1
- package/dist/assets/ja-DMk6wd-U.js +0 -16
- package/dist/assets/ko-BFpzJ8jc.js +0 -16
- package/dist/assets/main-anyZFMIs.js +0 -896
- package/dist/assets/markdownCore-CmM47cAE.js +0 -7
- package/dist/assets/pl-VdRPcZrB.js +0 -16
- package/dist/assets/pt-BR-BRys_lOW.js +0 -16
- package/dist/assets/renderElectronMiniChatApp-C5677jy0.js +0 -2
- package/dist/assets/renderMobileApp-D4dBBAqQ.js +0 -25
- package/dist/assets/runtimeEndpointReset-5r0hkd-2.js +0 -27
- package/dist/assets/tr-CA9ckNnm.js +0 -7
- package/dist/assets/uk-byjR-y8D.js +0 -16
- package/dist/assets/useAppFontEffects-BWQZ5DeI.js +0 -7341
- package/dist/assets/useInlineCommentController-DlFyVfBu.js +0 -2
- package/dist/assets/vendor-opencode-client-DYdsLbCM.js +0 -12
- package/dist/assets/zh-CN-DRabgxdG.js +0 -16
- package/dist/assets/zh-TW-rbY5c9UK.js +0 -16
|
@@ -23,7 +23,7 @@ Creating, finding, stopping, starting, and removing isolated spaces on a place,
|
|
|
23
23
|
- `tools-pack.js`: `packLocalTools` packs the local `web` and `sdk` packages of a checkout for a development build. Nothing calls it yet except tests. Deciding when a host is a development build is wiring for a later stage.
|
|
24
24
|
- `dispatcher.js`: `createSpaceDispatcher({ transport })`. The thin layer in front of the host's routes that forwards a request addressed to a space, and the two guards. See "Dispatcher".
|
|
25
25
|
- `host.js`: `createSpacesHost({ dataDir, dockerPath, gitPath, hostEnvironment, listProjectDirectories })`. What `server/index.js` builds when the switch is on: the owner id, the Docker place, the registry, the manager, the dispatcher, the gatekeeper channel, code in and code out on one host git, the records and the journey, with the hooks the rest of the server takes from it.
|
|
26
|
-
- `journey.js`: `createSpaceJourney({ manager, place, gatekeeper, codeIn, codeOut, records, listProjectDirectories, announce, onSpacesChanged })`. The journey of a space as the host drives it, written once on top of those: create in the background with progress, list with state, start with the network said again, stop, remove with the refs and the record, stop all for the switch, the journal, the apply preview and the apply. See "The journey".
|
|
26
|
+
- `journey.js`: `createSpaceJourney({ manager, place, gatekeeper, codeIn, codeOut, records, serverInside, restartOpenCodeInside, listProjectDirectories, announce, onSpacesChanged })`. The journey of a space as the host drives it, written once on top of those: create in the background with progress, list with state and what is broken, start with the network said again, stop, the two restarts of the repair, remove with the refs and the record, stop all for the switch, the journal, the apply preview and the apply. See "The journey".
|
|
27
27
|
- `routes.js`: `registerSpaceRoutes(app, { getJourney, getPlaces, readSwitch, setSwitch })`, the HTTP of the journey under `/api/openchamber/spaces`, which translates and nothing else; and `createSwitchController({ getHost, setHost, buildHost, startHost, persist })`, the switch as `index.js` runs it, one change at a time.
|
|
28
28
|
- `space-records.js`: `createSpaceRecords({ dataDir })`. What the host remembers about a space beside the labels: the network choice, the repository, the space path, the base of the history and whether the history arrived. One file per space under `spaces/records/`, no secret in it.
|
|
29
29
|
- `places/registry.js`: place registry, same pattern as the tunnel provider registry. Sealed after boot.
|
|
@@ -229,6 +229,7 @@ Environment:
|
|
|
229
229
|
| `NODE_USE_ENV_PROXY=1` | Node 22 ignores proxy variables without it. Measured: `EAI_AGAIN` for every fetch, and with it Node honours the uppercase spelling. |
|
|
230
230
|
| `OPENCODE_DISABLE_MODELS_FETCH=1`, `OPENCODE_DISABLE_AUTOUPDATE=1` | The catalog and the update check would spend corridor attempts on downloads a space does not need. Measured with OpenCode 2.0.15: without `OPENCODE_DISABLE_MODELS_FETCH` the journal shows `models.opencode.ai:443 deny:not-on-allowlist`, and with it the journal stays empty. The 2.0.15 binary does read `OPENCODE_DISABLE_AUTOUPDATE`, `1` or `true`, and then logs that it skipped the update check. What it changes in a space was not seen: `opencode serve` made no update attempt with it or without it. It stays because the binary honours it and it costs nothing. |
|
|
231
231
|
| `OPENCHAMBER_RELAY_HOST=off` | The server inside a space must never host the relay passively. It has a way out now, and paired devices must not land on a space. `server/index.js` reads this variable when it computes `allowPassiveHost`. |
|
|
232
|
+
| `OPENCHAMBER_SPACE_IDLE_STOP_FILE=/home/space/.openchamber-space/idle-stop.json` | Since 5d-3: where the server inside reads the idle stop's setting. Only a space has it, so the idle timer runs nowhere else. See "Idle stop" under "The journey". |
|
|
232
233
|
|
|
233
234
|
`npm_config_fetch_retries=0` is gone. Stage 1b set it because a space had no route at all, and OpenCode 1.18.31's background install of its plugin package, then `@opencode-ai/plugin`, held its tool registry for a long time: with no network, the first request for a project with `.opencode/tool/*.ts` took 131 seconds. Measured again in stage 2 with `npm view opencode-ai version` from a space-like container: with no route, 70 seconds; through a corridor that answers an immediate 403, 0.3 seconds with npm's own retry settings, because npm does not retry a 403. That measurement is about npm, not OpenCode. So the corridor's refusal does the work the variable did, and the agent's own `npm install` gets its retries back. OpenCode 2.0.15 has no such install for a local plugin at all: it imports the file and either finds the package or fails at once.
|
|
234
235
|
|
|
@@ -240,7 +241,7 @@ The plugin must also resolve from project files. OpenCode 2 loads a project's pl
|
|
|
240
241
|
|
|
241
242
|
The honest limit: the agent runs as the same user. It can read the token file and the environment of the server process. The token is not a secret from the agent. It keeps the server closed to anything else, and it stays out of container metadata.
|
|
242
243
|
|
|
243
|
-
The host keeps no copy. `readToken` reads it back over `exec`. `stop` and `start` keep it, so the server comes up by itself. **Decided in 4a: the host does not issue a fresh token at its own start.** The token is read back over `exec` at the first request to a space and kept in the host's memory for the life of the process, and read again only when the server inside refuses a session made from it. A fresh token would need a restart of the server inside, which ends whatever the agent is doing there, and buys nothing: the token protects the server inside from others and never from the agent, who can read the file, and the file and the host's copy both live where only the user reaches them.
|
|
244
|
+
The host keeps no copy. `readToken` reads it back over `exec`. `stop` and `start` keep it, so the server comes up by itself. **Decided in 4a: the host does not issue a fresh token at its own start.** The token is read back over `exec` at the first request to a space and kept in the host's memory for the life of the process, and read again only when the server inside refuses a session made from it. A fresh token would need a restart of the server inside, which ends whatever the agent is doing there, and buys nothing: the token protects the server inside from others and never from the agent, who can read the file, and the file and the host's copy both live where only the user reaches them. Since 5d-2 the rotation is part of restarting the container, the repair action where restarting the server inside is what the user asked for: see "Repair" under "The journey".
|
|
244
245
|
|
|
245
246
|
### The exec channel
|
|
246
247
|
|
|
@@ -306,10 +307,10 @@ Docker refuses `--network-alias` together with a second `--network`, so `create`
|
|
|
306
307
|
`gatekeeper-program.cjs` is one self-contained CommonJS script on Node's standard library. It is far larger than the tools filler, and stage 1a only ever verified a 2,641 character `node -e` argument on Windows, so it does not travel as an argument. The container's command waits for the file in its tmpfs and then execs Node on it, the same shape as the space's wait for its token file:
|
|
307
308
|
|
|
308
309
|
```
|
|
309
|
-
while [ ! -s /tmp/openchamber-gatekeeper/gatekeeper.cjs ]; do /bin/sleep 0.2; done; exec /usr/local/bin/node /tmp/openchamber-gatekeeper/gatekeeper.cjs
|
|
310
|
+
while [ ! -s /tmp/openchamber-gatekeeper/gatekeeper.cjs ]; do /bin/sleep 0.2; done; exec /usr/local/bin/node /tmp/openchamber-gatekeeper/gatekeeper.cjs /tmp/openchamber-gatekeeper/bind 3128 8080 9099 300000 128 64 8
|
|
310
311
|
```
|
|
311
312
|
|
|
312
|
-
The host writes the file over `exec` on stdin, through a temporary name, so the waiting container never runs half a file. `docker cp` is not an option: measured, it fails with "container rootfs is marked read-only" against a read-only container, even for a tmpfs destination.
|
|
313
|
+
The host writes the file over `exec` on stdin, through a temporary name, so the waiting container never runs half a file. Since 5b the same script first writes the bind file the command names, holding the gatekeeper's own address on the space's inner network, which the place reads from `docker inspect` after the start; the program reads it when it starts and listens there, see "Known limits" for why. A bind file that is missing, empty, not an address, or that names every interface ends the program with exit code 2, and so does such an address given directly; the readiness wait then fails the create or the start: nothing of ours listens on the outer network. The checker does not compare the container's command, so a gatekeeper made before 5b, whose command still says `0.0.0.0`, is caught here instead: it does not start, and its space has to be made again. The feature was never released, so only development spaces meet this. `docker cp` is not an option: measured, it fails with "container rootfs is marked read-only" against a read-only container, even for a tmpfs destination.
|
|
313
314
|
|
|
314
315
|
Its size crosses no boundary, and the question is worth answering once rather than every time it grows. It travels on the stdin of `docker exec --interactive` and never as an argument, `run-command.js` writes it and ends that stdin with the pipe's own backpressure, so no single write of ours can block or truncate, and it is in any case under the 65,536-byte default pipe buffer on Windows. The 2,641 characters stage 1a verified were the limit of a `node -e` argument, which is exactly what this path avoids.
|
|
315
316
|
|
|
@@ -351,7 +352,7 @@ An HTTP CONNECT proxy on the space-facing interface. Stage 0 proved that OpenCod
|
|
|
351
352
|
|
|
352
353
|
### Window
|
|
353
354
|
|
|
354
|
-
A reverse proxy on the same interface, for services whose secret must not enter the space. `/model/<grant id>/<rest>` goes to that grant's upstream with `<rest>` appended to the upstream's path unchanged, and with the grant's own header set: `Authorization: Bearer <key>` for OpenAI-style APIs, `x-api-key: <key>` for Anthropic. Whatever the space sent as `authorization`, `x-api-key
|
|
355
|
+
A reverse proxy on the same interface, for services whose secret must not enter the space. `/model/<grant id>/<rest>` goes to that grant's upstream with `<rest>` appended to the upstream's path unchanged, and with the grant's own header set: `Authorization: Bearer <key>` for OpenAI-style APIs, `x-api-key: <key>` for Anthropic, `x-goog-api-key` for Google. Whatever the space sent as `authorization`, `x-api-key`, `proxy-authorization` or under the grant's own header name is removed first. Since 5b a grant may have no secret, an opened domain: the window then adds nothing and forwards the request as the space made it, less those credential headers. The path stays `/model/` for both kinds; it names the window, not what is behind it. An unknown grant id is 403 and journalled. A grant id is never guessable from inside, and it is treated as public anyway: nothing relies on it being secret.
|
|
355
356
|
|
|
356
357
|
A grant opens a place on a host, not the host: a rest of the path that climbs out of it is refused with `deny:path-walks-out`, because with git and a private registry the path is what says which repository or which package. It is the same host and the same credential either way, so this is a door closed before those windows land rather than an escape today.
|
|
357
358
|
|
|
@@ -363,7 +364,7 @@ The window is written for any upstream and any header name, because git over htt
|
|
|
363
364
|
|
|
364
365
|
The upstream may be `https`, and stage 0 only ever proved a plain-HTTP one. TLS to the upstream is tested live: a grant that points at a public HTTPS endpoint answers through the window, with no credential of anyone's.
|
|
365
366
|
|
|
366
|
-
The window applies no private-address rule to a grant's upstream, on purpose. A grant is the user's decision, delivered over the control channel, and a private npm registry on the user's own network is exactly the case the design wants
|
|
367
|
+
The window applies no private-address rule to a grant's upstream, on purpose. A grant is the user's decision, delivered over the control channel, and a private npm registry on the user's own network is exactly the case the design wants. The space cannot choose an upstream, only a grant id that the host has already set. The one refusal is the gatekeeper itself: any of its own addresses, not only loopback, on one of its three ports; a grant pointing at the window would feed it into itself until its 64 sockets out were gone. The consequence is a rule the host must keep: never build a grant out of anything a space said. The grant route takes its upstream from the client, which is the user at the screen with the host's own provider catalog, never from the space.
|
|
367
368
|
|
|
368
369
|
### Control
|
|
369
370
|
|
|
@@ -373,7 +374,8 @@ An HTTP listener on the gatekeeper's own loopback, which the space cannot reach.
|
|
|
373
374
|
|---|---|
|
|
374
375
|
| `GET /health` | Answers 200 once all three listeners are up. It is the last to bind, so an answer means the corridor accepts connections. |
|
|
375
376
|
| `POST /network` | `{ mode, domains }`. Replaces both. |
|
|
376
|
-
| `POST /grants` | `{ id, upstream, header, secret }
|
|
377
|
+
| `POST /grants` | `{ id, upstream, header, secret }`, or `{ id, upstream }` for an opened domain. Adds or replaces one grant. A header without a secret, or a secret without a header, is refused. |
|
|
378
|
+
| `GET /policy` | Since 5b: `{ mode, domains, grants }`, the ids of the grants and never a secret, so the host can tell a gatekeeper that forgot from one that remembers. |
|
|
377
379
|
| `GET /journal` | The records and how many were dropped. |
|
|
378
380
|
|
|
379
381
|
Anything else is 404, and a body that is not an object is 400. Grants and the allowlist live in the program's memory only.
|
|
@@ -395,7 +397,7 @@ The decisions are `allow`, `failed:<error code>` for a host that was allowed and
|
|
|
395
397
|
- `stop` stops the space and then the gatekeeper. `start` starts the gatekeeper, waits for its corridor, and only then starts the space, whether the space starts as it is or moves to new tools first. A space is never running while its way out is not under the host's control, and a failed stop of the gatekeeper leaves the space stopped, which is the safe side of that order.
|
|
396
398
|
- A `start` that races a `stop` can leave the space running with its gatekeeper stopped, because `stop` waits for a start of the same space and then stops the space first. That direction is the safe one: the space has no way out at all while its gatekeeper is down, `list` reports it as damaged, and the next `start` brings the gatekeeper back. It is written here so that nobody has to find it twice.
|
|
397
399
|
- `start` looks after the gatekeeper even when the space container is already running, and that is the one thing it does to a running space. "A running space is never touched" is about the space's own container and its tools. A gatekeeper can die on its own, from its memory limit among other things, and `list` reports such a space as damaged; without this, the one action a user would take would skip the only step that repairs it, and only a stop and a start would help.
|
|
398
|
-
- The program lives in a tmpfs, so it is gone after every stop, and `start` writes it again. Grants and the allowlist are gone with it and are not restored
|
|
400
|
+
- The program lives in a tmpfs, so it is gone after every stop, and `start` writes it again, with the bind file before it. Grants and the allowlist are gone with it and are not restored by the place: the journey says the network again and every grant it can, see "Grants", and what it cannot is "needs access" in the list, which is what DESIGN.md asks for after a machine restart. No container of ours has a restart policy, so a Docker machine that comes back up leaves both containers stopped and the next `start` brings them up in this order.
|
|
399
401
|
- The move to new tools does not touch the gatekeeper. It mounts no tools volume, so a new tools version changes nothing about it, and the move remakes the space container only.
|
|
400
402
|
- `remove` removes both containers, both networks and the volumes, by label, containers first. `create`'s name check covers the two new names, and so does the second by-name sweep after an interrupted step.
|
|
401
403
|
- A space whose gatekeeper container is gone does not start, and neither does one that is already running: `start` rejects with `gatekeeper_missing` and changes nothing. Known limit: the gatekeeper is not made again, although it holds no state, so such a space has to be applied or discarded and made again. Making it again would be a repair path with a rollback of its own, and stage 2 does not build one.
|
|
@@ -403,10 +405,8 @@ The decisions are `allow`, `failed:<error code>` for a host that was allowed and
|
|
|
403
405
|
|
|
404
406
|
### Known limits
|
|
405
407
|
|
|
406
|
-
- The corridor and the window listen on
|
|
407
|
-
|
|
408
|
-
The space cannot use it: it still cannot reach the host, and that is what the escape tests prove. What it means is that an unprivileged local process on a Linux desktop could spend the user's model key once a real one sits behind the window. Nothing in this stage puts one there, and the stage that first does has to close it. Two ways are on the table, neither chosen here: a secret the host hands the window together with the grant, which every request must carry, or binding the window to the space's inner network address alone. The second needs no change to the create order, whatever an earlier draft of this paragraph said: the bind address is an argument of the program, and the program arrives over `exec` after the container is running, when Docker has already given it both addresses. `STAGES.md` carries this as an obligation on that stage.
|
|
409
|
-
- Anything else attached to the space's outer network could use the two listeners as well. The place attaches nothing else, and the escape suite's stand-in upstream is the only exception, in tests.
|
|
408
|
+
- The corridor and the window listen on the gatekeeper's address on the space's inner network only, since 5b. Before that they listened on every interface, and **on Linux that included the user's own machine**: a Linux Docker host routes into the bridge subnet, so any local process could reach both listeners without a published port. Measured on Debian 13, amd64, Engine 29.8.1, before the change: from the host, `curl http://<the gatekeeper's outer address>:8080/` connected and read the window's answer. On macOS and Windows a virtual machine stands between the host and the bridge, which is why a Mac-only run could never have shown it. The space could never use it, and that was not the point: an unprivileged local process on a Linux desktop could have spent the user's model key once a real one sat behind the window, which 5b is the first stage to do. Of the two ways STAGES.md named, the bind address was taken: the host decides where the gatekeeper listens, and the program has no policy of its own. The escape suite proves it with a neighbour on the outer network, which reaches the stand-in upstream beside it and is refused on the gatekeeper's outer address on all three ports, and the same measurement from a Linux host is repeated with each stage that touches the listeners.
|
|
409
|
+
- Nothing attached to the space's outer network can use the two listeners either, for the same reason; the stand-in upstream of the escape suite is the neighbour that proves it.
|
|
410
410
|
- A tunnel the upstream half-closed stays open, because a close travels in each direction on its own. Measured: 64 of those with live clients means the 65th is refused, and all 64 places come back as the clients let go. That is the tunnel cap doing its job on genuinely open tunnels rather than a leak, and the idle limit ends one that goes quiet.
|
|
411
411
|
- Port 443 only. A tool that needs another port cannot be reached until the grant dialog can open one.
|
|
412
412
|
- The corridor takes names, so a tool that only knows an address, and that the user cannot give a name, cannot be reached either.
|
|
@@ -414,9 +414,10 @@ The decisions are `allow`, `failed:<error code>` for a host that was allowed and
|
|
|
414
414
|
- A host with an underscore in it is refused, for the same reason: the name rule is the allowlist's, and that one takes letters, digits and hyphens. Such names are not valid hostnames, and the ones that exist are service records rather than things a space connects to.
|
|
415
415
|
- A grant's upstream is not checked against the private-address block, on purpose, because the user's own registry is a legitimate upstream. See "Window" for the one refusal that does apply and the rule it puts on the host.
|
|
416
416
|
- In open mode, refusing `auth.openai.com` is a lock and not a guarantee. See the corridor's rules.
|
|
417
|
-
- The gatekeeper is not made again when it is gone.
|
|
417
|
+
- The gatekeeper is not made again when it is gone. Since 5d-2 the list says so as `damage: 'gatekeeper_gone'`, see "Repair".
|
|
418
|
+
- A space that stopped itself for the idle stop leaves its gatekeeper running, because nothing inside can reach it, until the host next lists the spaces and stops it. It serves nobody meanwhile. See "Idle stop" under "The journey".
|
|
418
419
|
- The journal is memory only. A restart of the gatekeeper loses it, and so does a host that never reads it between two starts.
|
|
419
|
-
- Grants and the allowlist have to be set again after every start of a space.
|
|
420
|
+
- Grants and the allowlist have to be set again after every start of a space; since 5b the journey does that, and a key the user typed once is the one thing it cannot say again, see "Grants".
|
|
420
421
|
|
|
421
422
|
## Dispatcher
|
|
422
423
|
|
|
@@ -426,7 +427,7 @@ The design is in DESIGN.md, "Dispatcher, sessions, events". 4a built HTTP and SS
|
|
|
426
427
|
|
|
427
428
|
`isolatedSpacesEnabled` in `settings.json`, a boolean, false by default, in the settings registry as an instance field with no UI binding. `server/index.js` reads it once at start: when it is true it makes the host of `host.js`. The place of the dispatcher in the middleware chain, after the `/api` auth gate and before every feature route and the OpenCode proxy, and the `upgrade` handler of the server are each a slot mounted once, which reads the host at call time and passes on when there is none; the body parsers and the directory gate read their hooks from the host at call time as well. So while the switch is off none of the feature exists: the module is imported and nothing of it runs, no `docker` is started, no file is written, and a request under `/api/spaces/` falls through to the host's own routes and the OpenCode proxy, which know nothing about it. A request that names a space's directory without the prefix runs on the host as any other while the switch is off: the guards belong to the feature, and the feature is absent.
|
|
428
429
|
|
|
429
|
-
Since 5a the switch changes live, through `GET` and `PUT /api/openchamber/spaces/switch` in `routes.js`, the one route of the feature that exists while it is off, because turning it on is what makes the feature exist (decision 19). `GET` answers `{ enabled, spaces }`, the spaces with their id, name and state while it is on and an empty list while it is off, so the banner of decision 18 can say what turning it off would stop; while off it runs nothing. When the place cannot be asked, Docker being down among the reasons, `spaces` is null with a `failure` beside it, so the switch stays reachable and the screen can say that the list is unknown rather than showing an error where the switch was. `PUT { enabled: false }` stops every running space, one by one, writes the setting, closes the host and takes it out of the slots; the answer carries `stopped` and `stillRunning`, a space that could not be stopped named with its code and never counted as stopped. A creation under way refuses the turn-off with `space_preparing`, and from the first stop on the journey takes no new creation and no start, `isolated_spaces_off`, so nothing slips in between the stops and the moment the feature is gone; a setting that cannot be written leaves the feature on and the journey open again. `PUT { enabled: true }` writes the setting, makes the host and starts its event connections, exactly what the next start would do; when the host cannot be made, the setting is written all the same and the answer is the failure, as a start with the switch on logs it. The controller runs one change at a time: a second request waits for the first and sees what it left, so a double click builds one host and closes one host, never two.
|
|
430
|
+
Since 5a the switch changes live, through `GET` and `PUT /api/openchamber/spaces/switch` in `routes.js`, the one route of the feature that exists while it is off, because turning it on is what makes the feature exist (decision 19). `GET` answers `{ enabled, spaces }`, the spaces with their id, name and state while it is on and an empty list while it is off, so the banner of decision 18 can say what turning it off would stop; while off it runs nothing. When the place cannot be asked, Docker being down among the reasons, `spaces` is null with a `failure` beside it, so the switch stays reachable and the screen can say that the list is unknown rather than showing an error where the switch was. `PUT { enabled: false }` stops every running space, one by one, writes the setting, closes the host and takes it out of the slots; the answer carries `stopped` and `stillRunning`, a space that could not be stopped named with its code and never counted as stopped. When the place cannot list its spaces at all, Docker being down among the reasons, the switch still goes off and the answer says so in `unknown`, with the failure: the switch must stay reachable, and the screen warned before that what runs may keep running. A creation under way refuses the turn-off with `space_preparing`, and from the first stop on the journey takes no new creation and no start, `isolated_spaces_off`, so nothing slips in between the stops and the moment the feature is gone; a setting that cannot be written leaves the feature on and the journey open again. `PUT { enabled: true }` writes the setting, makes the host and starts its event connections, exactly what the next start would do; when the host cannot be made, the setting is written all the same and the answer is the failure, as a start with the switch on logs it. The controller runs one change at a time: a second request waits for the first and sees what it left, so a double click builds one host and closes one host, never two. Since 5c the settings row calls this route: it reads the switch when it opens, and before a turn-off it asks what would be stopped and shows the banner of decision 18 with the count, or says that the list is unknown.
|
|
430
431
|
|
|
431
432
|
### What is forwarded
|
|
432
433
|
|
|
@@ -518,9 +519,16 @@ All under `/api/openchamber/spaces`, a namespace of the host's beside `/api/open
|
|
|
518
519
|
| `GET /switch`, `PUT /switch` | The switch, see "The switch" above. |
|
|
519
520
|
| `GET /places` | Every place asked `check()` now, because the user is looking: `{ places: [{ id, available, version, os, arch, hostIsolation }] }`, or `{ id, available: false, code, message }`. |
|
|
520
521
|
| `GET /` | `{ spaces }`: the place's list with what the host remembers about each, the creations under way in their place, and the failed ones after it. |
|
|
521
|
-
| `POST /` | `{ projectDirectory, name, start, network }`. Answers 202 at once with the entry the list carries; the steps follow as events. |
|
|
522
|
+
| `POST /` | `{ projectDirectory, name, start, network, setupCommands }`. Answers 202 at once with the entry the list carries; the steps follow as events. |
|
|
522
523
|
| `POST /<id>/start`, `POST /<id>/stop` | The place's start and stop; start says the network again. Answers the listed entry, start with `networkRestored`. |
|
|
524
|
+
| `POST /<id>/restart-opencode` | Since 5d-2: asks the server inside a running space to restart its OpenCode, and answers the listed entry once it is ready again. See "Repair". |
|
|
525
|
+
| `POST /<id>/restart` | Since 5d-2: restarts the container of a running space with a fresh token, then says the network and the grants again as a start does. Answers as start does. See "Repair". |
|
|
523
526
|
| `DELETE /<id>` | Removes the containers, networks and volumes, the service refs in the user's repository and the record; forgets a failed creation. `{ id, removed, refsRemoved, failures }`. |
|
|
527
|
+
| `POST /<id>/setup` | Since 5d-4: `{ commands }`. Runs the project's setup commands again in a running space; answers the listed entry once the run began. See "Setup commands". |
|
|
528
|
+
| `GET /<id>/setup` | Since 5d-4: `{ setup, output }`, the setup as the list carries it and the end of the failed command's output, or null. |
|
|
529
|
+
| `GET /idle-stop`, `PUT /idle-stop` | Since 5d-3: the idle stop setting, `{ enabled, hours }`, kept in the host's settings and told to every running space. See "Idle stop". |
|
|
530
|
+
| `POST /<id>/grants` | Since 5b: `{ kind: 'model', provider, upstream, secret: { kind: 'typed', value } \| { kind: 'env', name } }` or `{ kind: 'domain', upstream }`. Answers `{ grant }`, the grant as the list carries it, with its window URL and never a value. See "Grants". |
|
|
531
|
+
| `POST /<id>/network/domains` | Since 5d: `{ domain }`. Adds a name to a running space's allowlist, live, then to the record, so every later start says it again. Answers `{ network }`. See "Grants". |
|
|
524
532
|
| `GET /<id>/journal` | The gatekeeper's journal, `{ records, dropped, since }`; 409 `space_not_running` for a stopped space, because the journal is gone with it. |
|
|
525
533
|
| `GET /<id>/apply` | Brings the work out and describes what an apply would do, writing nothing of the user's: `bringCodeOut`'s answer and `describeApplyState`'s in one object. |
|
|
526
534
|
| `POST /<id>/apply` | `{ as: 'branch', branch, removeAfterwards }` or `{ as: 'changes', removeAfterwards }`. Brings the work out once more and applies it; what is applied is what this call fetched. `{ brought, applied, removal }`, `removal` null unless the space was removed. |
|
|
@@ -531,19 +539,65 @@ A failure is one JSON answer, `{ code, message, details }`, with the status `rou
|
|
|
531
539
|
|
|
532
540
|
`POST /` answers as soon as the space has an id, and the rest runs in the background, because a first create pulls the image, fills the tools volume and pushes the code, which can take minutes. The steps, each announced on the host's hub as `openchamber:space-progress` with `{ spaceId, step, failure, timestamp }` in `properties`, the way `openchamber:space-stream` is announced: `checking_place`, the place's `check()`, refused with the place's own code when it is unavailable and with `place_cannot_restrict_network` when an allowlist was asked of an engine without host isolation; `creating`, the manager's create, which is the image, the tools volume, both networks, the gatekeeper and the space container, verified; `setting_network`, the record written and the mode and allowlist said to the gatekeeper, which allowed nothing until then; `bringing_code`, the snapshot and the transfer of code in, with the space path and the base kept in the record; `ready`. The history goes after `ready`, in the background, and its outcome is kept in the record as `history`: `sent`, `already_complete`, `host_shallow` or `failed`, `pending` until then. A start of a space whose history is still `pending` sends it again.
|
|
533
541
|
|
|
534
|
-
A failure after `creating` removes what was made: the containers, the refs in the user's repository and the record, and the answer of the failed step is kept in the list as `state: 'failed'` with `failure: { code, message, details, cleanup }` until the user dismisses it with `DELETE /<id>`, so an error is never silent; when that clean-up itself failed, `cleanup` says so and the dismissal removes what is still there, so the space cannot come back in the list as damaged after the user was told it was gone. A creation under way is listed as `preparing` with its `step`, over the place's view of it, and refuses start, stop, remove and apply with `space_preparing` until it is ready or failed; a failed one refuses them with `space_creation_failed`. One action runs per space at a time: start, stop, remove, the journal, the preview and the apply take a lock on the space's id and a second action meets `space_busy`, so a remove from another client cannot pull the service refs from under an apply that is writing them. A start of a space whose history is `pending` or `failed` sends it again, because a stop right after the creation is the usual way it fails. The project must be one the host has registered, compared as the label's hash and the path, because the sidebar resolves a space to its project the same way. The four choices are parsed at the boundary, each field refusing with a code of its own: `project_not_registered`, `invalid_space_name`, `invalid_snapshot_mode`, `invalid_network`.
|
|
542
|
+
A failure after `creating` removes what was made: the containers, the refs in the user's repository and the record, and the answer of the failed step is kept in the list as `state: 'failed'` with `failure: { code, message, details, cleanup }` until the user dismisses it with `DELETE /<id>`, so an error is never silent; when that clean-up itself failed, `cleanup` says so and the dismissal removes what is still there, so the space cannot come back in the list as damaged after the user was told it was gone. A creation under way is listed as `preparing` with its `step`, over the place's view of it, and refuses start, stop, remove and apply with `space_preparing` until it is ready or failed; a failed one refuses them with `space_creation_failed`. One action runs per space at a time: start, stop, remove, the journal, the preview and the apply take a lock on the space's id and a second action meets `space_busy`, so a remove from another client cannot pull the service refs from under an apply that is writing them. A start of a space whose history is `pending` or `failed` sends it again, because a stop right after the creation is the usual way it fails. The project must be one the host has registered, compared as the label's hash and the path, because the sidebar resolves a space to its project the same way. The four choices are parsed at the boundary, each field refusing with a code of its own: `project_not_registered`, `invalid_space_name`, `invalid_snapshot_mode`, `invalid_network`, and since 5d-4 `invalid_setup_commands` for the project's setup commands, which start in the background right after `ready`.
|
|
535
543
|
|
|
536
544
|
### The record
|
|
537
545
|
|
|
538
|
-
The labels stay the source of truth about which spaces exist. What the host adds is one file per space under `<data dir>/spaces/records/<id>.json`, mode 0600, written through a temporary name: `{ version, network: { mode, domains }, repository, spacePath, base, history }`. It exists so that a gatekeeper that starts with an empty memory is told the network the user chose, and so that the history and the result find the repository and the space path that code in used, which differ from the project directory when the project is a subfolder of its repository. A record the host cannot read is reported as unreadable, never as a fresh one, and is not written over: `start` then leaves the network closed and answers `networkRestored: false`, and the list carries `network: null`, which a screen shows as unknown and never as open. No secret is in a record; that is decision 5, and 5b
|
|
546
|
+
The labels stay the source of truth about which spaces exist. What the host adds is one file per space under `<data dir>/spaces/records/<id>.json`, mode 0600, written through a temporary name: `{ version, network: { mode, domains }, repository, spacePath, base, history, grants, setup }`. It exists so that a gatekeeper that starts with an empty memory is told the network the user chose, and so that the history and the result find the repository and the space path that code in used, which differ from the project directory when the project is a subfolder of its repository. A record the host cannot read is reported as unreadable, never as a fresh one, and is not written over: `start` then leaves the network closed and answers `networkRestored: false`, and the list carries `network: null`, which a screen shows as unknown and never as open. No secret is in a record; that is decision 5. Since 5b `grants` holds each grant without its value: `{ kind: 'model', id, provider, upstream, header, source }` with `source` `{ kind: 'typed' }` or `{ kind: 'env', name }`, or `{ kind: 'domain', id, upstream }`. The schema is strict, so a value under any name is refused rather than written, and a record from before 5b reads back with no grants.
|
|
539
547
|
|
|
540
|
-
###
|
|
548
|
+
### Repair
|
|
549
|
+
|
|
550
|
+
DESIGN.md, user journey step 8 and decision 10; built in 5d-2. The group of a space says what is wrong with it and offers the action that repairs it, and its menu has the three actions from soft to hard.
|
|
551
|
+
|
|
552
|
+
- **Restart OpenCode.** `POST /<id>/restart-opencode`. The host asks the server inside, through the dispatcher's own `requestInside`, for `POST /api/config/reload`, the route the host's own settings use to restart a managed OpenCode. The answer comes from inside and is data: anything but a 200 whose body says `success: true` and `requiresReload: true`, within 180 seconds, is `opencode_restart_failed`; the same route answers `success` with no restart for an OpenCode it does not manage, and its text goes no further than that code. The container, the gatekeeper and its grants stay as they are.
|
|
553
|
+
- **Restart the container.** `POST /<id>/restart`, a running space only. A fresh token is written into the token file while the space runs, the space and its gatekeeper are stopped, and the space is started as a start would, with the network and the grants said again. The server inside reads the new token when it starts. The dispatcher needs no word of it: the old session is refused, the remembered token is refused, and it reads the token again, as it does after the agent rewrote the file. The token is no secret from the agent, so a write that fails is logged and the restart goes on with the old one.
|
|
554
|
+
- **Delete** is `DELETE /<id>`, above.
|
|
555
|
+
- **What is broken.** The list carries `damage` for a damaged space: `gatekeeper_gone` when its gatekeeper container no longer exists, and `repairable` for everything else, a gatekeeper that stopped while the space runs among them, which the next start brings back. The place's list names the gatekeeper as missing in both cases, so for such a space alone the journey asks the place's `verify`, whose `gatekeeper_missing` violation tells them apart; a `verify` that cannot answer leaves it `repairable`, so the user is offered a restart and not told on a guess that the space is lost. A gatekeeper that is gone is never made again (see "Lifecycle"), so the screen says in plain words that the space has to be deleted and made again, and a start of it answers `gatekeeper_missing` with status 409.
|
|
556
|
+
- A state that is not listed but seen: a running space whose server did not answer the host's last read of its sessions is "not answering" on the screen, from the session list's mark, and the screen offers the restart of the container.
|
|
557
|
+
|
|
558
|
+
### Idle stop
|
|
559
|
+
|
|
560
|
+
DESIGN.md, decision 11 and the last line of "Dispatcher, sessions, events"; built in 5d-3. `idle-stop.js` holds both sides.
|
|
561
|
+
|
|
562
|
+
- **Inside.** The server inside a space checks once a minute, `startIdleStop` in `server/index.js`, only when `OPENCHAMBER_SPACE_IDLE_STOP_FILE` names the setting's file. Idle means no session busy or retrying, read from the server's own session status; any status change counts as activity at the time it came, so a turn between two checks is not missed. A session waiting for the user's answer counts as idle: the maintainer's call of 2026-09-28, since the point is to give the memory back. OpenCode keeps such a session `busy` while it waits, so the server's own list of pending permission asks and forms decides it. When the hours pass, the server shuts down as it would on a signal and exits with `SPACE_IDLE_EXIT_CODE`, 75, and the container stops with it. Files stay in the volumes.
|
|
563
|
+
- **The setting.** `{ enabled, hours }`, whole hours from 1 to 168, 4 by default, the key `isolatedSpacesIdleStop` in the host's `settings.json`. The host writes it into `$HOME/.openchamber-space/idle-stop.json` over `exec`, through a temporary name, when a space is made, at every start and restart, and to every running space when the user changes it. All of these writes go one after the other, so a space started during a change gets the changed setting. A write that fails is logged and the space keeps the setting it had. The server inside reads the file at every check: a missing file, one that is not a plain file of at most 1 KiB, or one that does not parse stops nothing, because a space never stops on a guess and a FIFO must not hold the server's event loop.
|
|
564
|
+
- **What the host sees.** The place's list carries `stoppedIdle`, an exited space whose exit code is 75, and `gatekeeperRunning`. A server stopped by `docker stop` exits 143. The journey's list passes `stoppedIdle` on, and the group says the space stopped after sitting idle, with Start.
|
|
565
|
+
- **The gatekeeper.** Nothing inside can stop it, so an idle stop leaves it running. The journey's list stops a gatekeeper it finds running beside an exited space, and leaves it when another action holds the space; a start that comes meanwhile waits for that stop instead of being refused as busy. Turning the switch off stops it too. A key typed into it goes with it, as after a stop by hand. The maintainer's call of 2026-09-28: a self-stopping gatekeeper is more machinery than 24 MiB for a while is worth.
|
|
566
|
+
- **Not a boundary.** The agent can change the file, keep a session busy, or exit with 75 itself. That keeps its space running or changes a line of text; it restricts nothing.
|
|
567
|
+
- In the UI, a space stream that drops while the list says the space runs makes the client read the list again, at the host's reconnect pace, so an idle stop shows as stopped and not as "not answering".
|
|
568
|
+
|
|
569
|
+
### Setup commands
|
|
570
|
+
|
|
571
|
+
DESIGN.md, "Code in and out", and STAGES.md, row 5; built in 5d-4. `space-setup.js`.
|
|
572
|
+
|
|
573
|
+
- **Which commands.** The ones OpenChamber runs for a new worktree of the project, chosen by the client the same way: the shared ones from `.openchamber/project.json` in the repository only after the trust prompt, the personal ones always. The trust prompt and its memory are the host's, unchanged, and like the host's they are the client's: the route runs what it is given, as `POST /api/git/worktrees` does. The maintainer's call of 2026-09-28: the same prompt inside a space, because it is also about the user knowing what runs. At most 100 commands of 4000 characters, the host's own limits of 50 shared and 50 personal ones; blank ones are dropped.
|
|
574
|
+
- **When.** At a creation, right after `ready`, in the background, so the agent can start while dependencies install (DESIGN.md, journey step 2); and again when the user asks, `POST /<id>/setup`, with the commands as the project has them then. One run per space at a time, `space_setup_running` otherwise. The waiting first message goes at `ready`, unless the project's "wait for setup commands" setting is on: then the client holds it until the run ended, passed or not.
|
|
575
|
+
- **How.** One `exec` per command, as the space user, `timeout -k 10 3600 /bin/sh -c 'cd -- "$1" || exit 1; exec /bin/bash -c "$2" 2>&1'` with the project path inside and the command as arguments; `$ROOT_PROJECT_PATH` and `$ROOT_WORKTREE_PATH` become the project path inside, where the space's copy of the project is. The command gets the space's own environment, the corridor's proxy variables and PATH among them, so it reaches what the agent reaches. They run one after the other and stop at the first that fails, as the host's `&&` chain does. `timeout` ends a command after an hour with everything it started, which a kill of the host's `docker exec` would not, and answers 124; the host waits a minute longer. The `exec` runs with `killTree`, so a host that quits takes it along; the command inside then goes on to its end or its hour.
|
|
576
|
+
- **What is kept.** A creation that will run commands is listed with `{ state: 'queued', total }` until its code arrived, so the client knows to wait for them; a host before 5d-4 lists none. While a run goes, this process knows which command runs; the list says `{ state: 'running', index, total, command }`, and each step is announced as `openchamber:space-setup` so the clients read the list again. The record keeps `running` when a run begins, then `done`, or `failed` with the command, its exit code, whether the hour ended it, and the end of its output. Exit code 124 counts as the hour only when an hour passed, because a command of the project's own can answer 124 too. A record that says `running` with no run in this process is listed as `interrupted`: the host did not live to see the run end.
|
|
577
|
+
- **The output is data.** The host reads a window of the last 256 KiB, turns a line a progress bar rewrote into what it said last, takes out the terminal's sequences whole, a link's text among them, every other control character but a tab and a line break, the C1 controls and the marks that turn text direction, and keeps the last 200 lines and 32 KiB. The record's schema refuses more. The client shows it as plain text in a monospace block.
|
|
578
|
+
- **Not a boundary.** A command is code of the project running in the space, like anything the agent runs. The network filter decides what it reaches; an `npm install` in a space that reaches only the addresses the user allowed fails, and the output window says where to open an address.
|
|
579
|
+
|
|
580
|
+
### Grants
|
|
581
|
+
|
|
582
|
+
DESIGN.md, "Words" and "Gatekeeper", and decisions 4, 5 and 13. Stage 5b takes two kinds, decided with the maintainer on 2026-09-26: a model API key for a provider, a "uses without seeing" grant, and an opened domain with no credential, for a private registry or a mirror that the corridor would refuse by address. Git over https and npm tokens wait for the stage that verifies npm through the window end to end.
|
|
583
|
+
|
|
584
|
+
- A model grant names the provider as the host's catalog does, `anthropic`, `openai` and so on, and its id is the provider id, so a second grant for the same provider replaces the first: that is how a key is changed, and a grant is never taken back. The upstream is the provider's API. The create dialog takes it from each provider's own SDK default, listed in the UI's `lib/spaces/model-access.ts` and matching what the bundled OpenCode uses, and never from the host's catalog: a catalog entry can be a browser login that points somewhere else. The header is decided here by provider, `x-api-key` for Anthropic, `x-goog-api-key` for Google, a bearer token for the rest. The key comes typed once, or as the name of an environment variable of the host's, read from the host's own environment now; OpenChamber remembers the name and never the value, and a variable that is not set is refused with `secret_source_missing`.
|
|
585
|
+
- An opened domain gets a random id, `open-<12 hex>`, and its window URL, `http://gatekeeper:8080/model/<id>`, which the answer carries so a screen can show it. Nothing inside is configured for it in this stage.
|
|
586
|
+
- The key goes to the gatekeeper first, then the grant without its value goes to the record, and for a model grant OpenCode inside is told: `space-opencode.js` writes the whole global configuration, `$HOME/.config/opencode/opencode.json`, from the record's model grants, each provider with `options.baseURL` at its window URL and a placeholder `apiKey`, so OpenCode's own auth plugins stay out of the way and the window throws the placeholder away. That file cooperates and enforces nothing: the agent can change it, and the gatekeeper is what keeps the key out. The catalog a space offers is the host's, so the model chosen in the composer works inside unchanged; that was the second decision of 2026-09-26. A grant the gatekeeper refused is not remembered. A grant goes to a running space only, `space_not_running` otherwise, and to one whose record can be read, `space_record_unreadable` otherwise, because a grant that cannot be remembered would be gone at the next start without a word. The configuration is the whole file, so anything the agent wrote into its global `opencode.json` is gone at the next model grant or start; a project's own `opencode.json` is not touched.
|
|
587
|
+
- The providers a model grant takes are the ones whose header this module knows: `anthropic` and `google` with their own headers, and `openai`, `openrouter`, `groq`, `mistral`, `deepseek` and `xai` with a bearer token. Any other is refused with `provider_not_supported` rather than accepted and failing every turn with a 401 upstream; Azure, Bedrock and Vertex read their key another way or sign requests. The grant dialog decides how the list grows.
|
|
588
|
+
- After every start the journey says the record's grants again, after the network: an environment key is read again and delivered, an opened domain is delivered, and a typed key cannot be, because it was never kept. The provider configuration inside is written again from the record too, so a write that failed at the grant is repaired by the next start; a write that fails at the start is logged and the start goes on. A grant the host cannot read in the record, from a later version, is dropped with a warning and the rest of the record stays readable. The start answers `grantsRestored` and `needsAccess` with the ids. A gatekeeper that refuses one at the start leaves the space running and that grant in `needsAccess`, logged; the alternative, a start that fails with the space up and the network said, would be worse.
|
|
589
|
+
- The list, with `access`, asks each running space that has grants what its gatekeeper holds, `GET /policy`, one request per such space and none for a space without grants or one that is stopped, and says `access: 'granted'`, `'needs_access'` with the missing ids in `needsAccess`, or `'unknown'` when the gatekeeper could not be asked, never "granted" on a failed read. While an action holds the space, a start saying its grants again among them, `access` is null rather than a "needs access" that is about to be untrue. `GET /` asks with `access`; the other routes answer the list without it, `access: null`. This is the "needs access" of DESIGN.md after a machine restart, read from the gatekeeper rather than from what this process remembers, so a host that restarted shows the truth.
|
|
590
|
+
|
|
591
|
+
- An opened domain of the grant dialog is a name added to the allowlist, the corridor's, and not the window grant above: since 5d `POST /<id>/network/domains` tells the gatekeeper the list with the name first and the record after, so a record that cannot be written leaves the name open only until the next start, which closes it. It is the same action as "Open" on a blocked attempt of the journal, whose name the agent wrote: the user reading it and pressing the button is the decision, and the allowlist's name rule, applied here as in the corridor, refuses anything that is not a name. A space whose network is open refuses it with `network_is_open`, and the list holds at most 200 names, `too_many_domains` past that. A window grant for a domain has no screen yet, because nothing inside a space uses it before npm and git go through the window.
|
|
541
592
|
|
|
542
593
|
- The list route runs one `docker ps` and one record read per space on every call; there is no cache, because the user is looking and the answer must be the state now.
|
|
543
594
|
- A creation is one process's memory: a host that restarts in the middle of one leaves the space where the step got to, listed from the labels with whatever the record holds; a space whose code never arrived has an empty `spacePath` in its record and its apply fails on the project path. Removing such a space is the way out.
|
|
544
595
|
- The history transfer is not retried on its own; a start of the space retries it while the record says `pending` or `failed`.
|
|
545
596
|
- The lock on a space is one process's memory, like code out's turns: two OpenChamber processes on one Docker daemon are not coordinated.
|
|
546
|
-
- Nothing of the
|
|
597
|
+
- Nothing of the chat archive is here; stage 5e adds it.
|
|
598
|
+
- A run of the setup commands is one process's memory: a host that restarts in the middle lists it as interrupted, while the command inside may still go on to its end or its hour. A second run started then may run beside it.
|
|
599
|
+
- Whether OpenCode inside takes a provider granted after the instance of the space's project started, without a restart, is what the live file of 5b measures; see the pull request of 5b for the outcome. The restart action of the repair stage is the lever if it does not.
|
|
600
|
+
- A grant for a provider the host's catalog does not know is written inside all the same; OpenCode inside then has no `npm` package for it and the turn fails with a provider error. The grant dialog offers the host's catalog, so this is a request nothing in the app makes.
|
|
547
601
|
|
|
548
602
|
## Code in
|
|
549
603
|
|
|
@@ -923,7 +977,7 @@ The manager verifies again after `create` and removes a space that reports viola
|
|
|
923
977
|
|
|
924
978
|
A timeout kills the `docker` CLI only. A command started with `exec` keeps running inside the space or the gatekeeper.
|
|
925
979
|
|
|
926
|
-
`killTree: true` makes a kill end the child's whole process tree instead. Only the pushes of code in use it, see "Killing a transfer".
|
|
980
|
+
`killTree: true` makes a kill end the child's whole process tree instead. Only the pushes of code in use it, see "Killing a transfer". Since 5d-4 the setup commands' `docker exec` uses it too, with `keepTail` for their output; the Docker place's `exec` passes `maxOutputBytes`, `keepTail` and `killTree` through to the runner.
|
|
927
981
|
|
|
928
982
|
Since 3b the fetches of code out use `killTree` as well, and so does every git command of code out that can start one of the user's filters or run long on the user's working tree: reading it back, the dry runs and the apply; see "Apply". `keepAtExit: true` beside `killTree` keeps the kill for a timeout or an abort, leaves the child out of the exit handler's set, and gives it no pipe on its output: stdout goes nowhere and resolves empty, stderr goes to an already removed temporary file read back at `close`, its last `maxOutputBytes` with `keepTail`, and `command_output_too_large` after the end without it. Only the real `git apply` of code out uses it. The fetches also use one more option: `signal`, an `AbortSignal` that lets the caller stop the child from outside. The child is killed the way a timeout kills it, the tree with `killTree`, and the rejection waits for that kill the same way; its value is the signal's reason when that reason is a `SpaceError`, and `command_aborted` otherwise, so every rejection of `runCommand` is a `SpaceError` whatever the caller aborted with. The caller then knows that it stopped the child, which the exit code cannot tell on Windows. A signal that is already aborted starts nothing, the listener goes when the run settles in any way, and an abort after the run settled, or after the timeout has already begun its kill, does nothing: the kill happens once. Code out uses it for the transfer cap.
|
|
929
983
|
|
|
@@ -1074,7 +1128,7 @@ OPENCHAMBER_TEST_DOCKER=1 bun run --cwd packages/web test -- server/lib/spaces
|
|
|
1074
1128
|
OPENCHAMBER_TEST_DOCKER_PACKED=1 bun run --cwd packages/web test -- server/lib/spaces/places/packed
|
|
1075
1129
|
```
|
|
1076
1130
|
|
|
1077
|
-
The second command also runs the live files against the local Docker daemon: `places/contract.docker.live.test.js`, `places/escape.docker.live.test.js`, `places/server.docker.live.test.js`, and since 3a `places/code-in.docker.live.test.js`. Since 3b it also runs `places/code-out.docker.live.test.js`, since 4a `places/dispatcher.docker.live.test.js`,
|
|
1131
|
+
The second command also runs the live files against the local Docker daemon: `places/contract.docker.live.test.js`, `places/escape.docker.live.test.js`, `places/server.docker.live.test.js`, and since 3a `places/code-in.docker.live.test.js`. Since 3b it also runs `places/code-out.docker.live.test.js`, since 4a `places/dispatcher.docker.live.test.js`, since 4b `places/sessions.docker.live.test.js`, and since 5b `places/grants.docker.live.test.js`: a space made through the journey, a real key behind the window against the stand-in upstream, which sees its hash, the key absent from the record, both containers' metadata and everything the space can read, a turn of OpenCode inside arriving at the stand-in with the key, a provider granted after the instance started, measured, and the grants said again after a stop and a start. The escape suite gained two tests in 5b: a neighbour on the outer network refused on the gatekeeper's outer address on all three ports while the space still reaches both listeners by name, and an opened domain that gets no credential from the window. The third runs `places/packed.docker.live.test.js`. It compiles the sdk and packs the local `web` and `sdk`, so it needs the workspace dependencies installed.
|
|
1078
1132
|
|
|
1079
1133
|
Each live file uses an owner id of its own, removes its spaces, helper containers, and tools volumes in `afterAll`, and then fails if any container, network, or volume with that owner label remains. An owner of its own also means a tools volume of its own, so every live file pays for one fill of about 40 seconds. The first run pulls the image, about 1.6 GB. The whole live run is timed in "Verified and not verified" above.
|
|
1080
1134
|
|
|
@@ -1084,11 +1138,11 @@ Each live file uses an owner id of its own, removes its spaces, helper container
|
|
|
1084
1138
|
|
|
1085
1139
|
`dispatcher.test.js` runs the dispatcher in front of a stand-in for the server inside: an Express app behind the host's own `createUiAuth`, so the login, the cookie name with the port in it and the refusal of a wrong token are the real ones, reached over a plain socket. It covers the prefix and the credentials coming off and the session going on, one login and one connection pool for many requests, a three-megabyte body streamed in, a form-encoded body kept whole by the parser predicate, an event stream read event by event with the request inside ended when the client leaves, a four-megabyte event stream whole, both guards in every spelling they take with their controls, the host-only and refused routes with their neighbours forwarded, an unknown id and one that appears, the cookie stripped and the page and raw-file content types, a redirect and `Clear-Site-Data` and `Refresh` never leaving the dispatcher for any method, an answer without a content type served as text, a stopped space answered with its code while a three-megabyte body is still on its way in, the renewed session and the repeated request after a 401, the body request that is not repeated, the renewal before expiry, the codes for a stopped space and an unreachable server, and the token absent from every answer and log line when the login fails. Each guard's test was run once with its guard removed and went red; so did the parser predicate's test, where the request hangs without it. `command-stream.test.js` runs `openCommandStream` and the bridge on the host's Node: bytes both ways, the error with the command's stderr, the kill on destroy, the idle timeout, the spawn failure, HTTP over a keep-alive agent with one process for many requests, the four-megabyte full-duplex exchange compared by sha256, `ECONNREFUSED` reported, and the command gone when the host lets go and when the server closes. `host.test.js` covers the owner file and the wiring over the memory place, with no process started, and since 4b, over a stand-in place whose spaces are Express apps behind the real UI auth, the merged list with its drops and the stale mark of a stopped space, the event connections into the real hub with the host's ids learned from it, and a socket forwarded through the mounted upgrade handler. `websocket.test.js` runs the forwarder against such a stand-in with an echo socket: the handshake built without the user's credentials and with the loopback origin, a header with a line break refused, the answer parsed with the bytes after it, the close frame's bytes, the terminal socket forwarded with the query token gone and the space session on, a 4 MiB frame both ways, every refusal before the upgrade with its code, the place's and the space's own refusals, the host's auth and origin rules per socket, the session renewed once after a 401, the close frame when the stream inside dies and the stream killed when the client leaves, and every socket ended at close. `space-sessions.test.js` is the table of what a space may claim: each directory spelling kept or dropped, a host id never taken, an id another space listed dropped, the field allowlist, each event rule, the merge order and marks, and the index's stale, partial, unknown and forgotten states. `space-events.test.js` runs the connection against a stand-in stream and the real hub: the announcement, the status seed, an event entered with the space's id and directory, the three drops with the directory absent from the log, the backoff after the stream ends with the gap announced, the connection dropped for a space that is gone, and a refused connection retried quietly. `places/sessions.docker.live.test.js` is the live file of 4b, see "Verified and not verified".
|
|
1086
1140
|
|
|
1087
|
-
`space-server.test.js` feeds the channel every hostile answer listed under "The exec channel", and `gatekeeper-channel.test.js` does the same for the gatekeeper's channel, including a journal that is not JSON, one without records, records of another shape, one larger than the host reads,
|
|
1141
|
+
`space-server.test.js` feeds the channel every hostile answer listed under "The exec channel", and `gatekeeper-channel.test.js` does the same for the gatekeeper's channel, including a journal that is not JSON, one without records, records of another shape, one larger than the host reads, since 5a the `since` field taken as text only, and since 5b the bind file written before the program with every address that is not one refused on the host, an opened domain sent with no header and no secret, and the policy read as data with its lists capped and a broken one refused. `space-opencode.test.js` covers the configuration built from the grants and the fixed script that writes it.
|
|
1088
1142
|
|
|
1089
|
-
`journey.test.js` runs the journey over the memory place with recording stand-ins for the gatekeeper channel, code in and code out: the order of the steps and the events of a create, what the record holds after it, a history that fails alone, a failure at the network or at code in that removes the space and lists the failure until it is dismissed, an unavailable place, an allowlist refused without host isolation, each bad field of the request refused before anything runs, stop and start with the network said again, a start without a record, the history sent again at start, remove with the refs and the record and with refs that would not go, every action refused while a creation is held at code in, stop all with one space that would not stop, no creation after the turn-off began until it is undone, a failed creation whose clean-up failed removed at its dismissal, the journal of a running and of a stopped space, the apply preview, the apply as a branch with the removal after it, as changes with the space kept, no removal when there was nothing to apply or the apply refused, and a remove, a stop and a journal read refused as busy while an apply holds the space. `routes.test.js` runs the routes over a stand-in journey: every route 404 while the feature is off with the switch still answering, the switch's preview and its turn-off, each route translated into its journey call, an id that is not a space id and a body that is not an object refused before the journey is asked, and the status of every code; and the switch controller: the unknown list when the place cannot be asked, one host built for two turn-ons at once and closed once for two turn-offs, the order of stop, write and close, and a setting that cannot be written leaving the feature on and open. `space-records.test.js` covers the file, its mode, the update, an unreadable file never taken for a fresh record, the id check
|
|
1143
|
+
`journey.test.js` runs the journey over the memory place with recording stand-ins for the gatekeeper channel, code in and code out: the order of the steps and the events of a create, what the record holds after it, a history that fails alone, a failure at the network or at code in that removes the space and lists the failure until it is dismissed, an unavailable place, an allowlist refused without host isolation, each bad field of the request refused before anything runs, stop and start with the network said again, a start without a record, the history sent again at start, remove with the refs and the record and with refs that would not go, every action refused while a creation is held at code in, stop all with one space that would not stop, no creation after the turn-off began until it is undone, a failed creation whose clean-up failed removed at its dismissal, the journal of a running and of a stopped space, the apply preview, the apply as a branch with the removal after it, as changes with the space kept, no removal when there was nothing to apply or the apply refused, and a remove, a stop and a journal read refused as busy while an apply holds the space. Since 5b also the grants: a typed key and an environment key delivered to the stand-in gatekeeper, remembered without their values and OpenCode inside told; the same provider replaced and a domain opened with no header; every bad request, a stopped space, a missing environment variable and an unreadable record refused; a refused grant not remembered; the grants said again after a start with the typed one and a variable no longer set in `needsAccess`, and a gatekeeper that refuses at the start leaving the space running; and the list asking only where there is something to ask and answering unknown on a failed read. `routes.test.js` runs the routes over a stand-in journey: every route 404 while the feature is off with the switch still answering, the switch's preview and its turn-off, each route translated into its journey call, an id that is not a space id and a body that is not an object refused before the journey is asked, and the status of every code, the grant route among them since 5b; and the switch controller: the unknown list when the place cannot be asked, one host built for two turn-ons at once and closed once for two turn-offs, the order of stop, write and close, and a setting that cannot be written leaving the feature on and open. `space-records.test.js` covers the file, its mode, the update, an unreadable file never taken for a fresh record, the id check, the domain rule, and since 5b a grant remembered without its value, a value under any name refused, and a record from before grants read back with none.
|
|
1090
1144
|
|
|
1091
|
-
`gatekeeper-program.test.js` covers the program two ways. It requires the file and calls the rules directly: every blocked range with its edges, every IPv6 embedded form, the public addresses that must stay allowed, `refuseTarget` for both modes and both ports, thirty target forms that must be refused as addresses or non-names, including the integer, hex, short and octal spellings, ten ordinary names that must still pass, the address-family choice, and what `splitTarget` refuses. The program runs its listeners only as the container's main module, so requiring it binds nothing and there is no switch that changes a decision. Then it spawns the program the way `tools-filler.test.js` runs the filler and reads decisions back from its own journal: a name that does not resolve, `localhost` as the name that proves the check is on the resolved address, exact-match domains, the port rules of both modes, `auth.openai.com` by name and in fifteen address and non-name forms, the three Unicode full stops, which Node's own parser refuses before any rule of ours sees them and which are therefore checked against the rules directly, a plain proxy request, malformed CONNECT lines, a reset in the middle of the handshake, a 200,000 character header block, a flood of 600 sockets on each listener, the window's header rules against a local upstream, a grant that points back at the gatekeeper, journal redaction, the ring buffer's overflow,
|
|
1145
|
+
`gatekeeper-program.test.js` covers the program two ways. It requires the file and calls the rules directly: every blocked range with its edges, every IPv6 embedded form, the public addresses that must stay allowed, `refuseTarget` for both modes and both ports, thirty target forms that must be refused as addresses or non-names, including the integer, hex, short and octal spellings, ten ordinary names that must still pass, the address-family choice, and what `splitTarget` refuses. The program runs its listeners only as the container's main module, so requiring it binds nothing and there is no switch that changes a decision. Then it spawns the program the way `tools-filler.test.js` runs the filler and reads decisions back from its own journal: a name that does not resolve, `localhost` as the name that proves the check is on the resolved address, exact-match domains, the port rules of both modes, `auth.openai.com` by name and in fifteen address and non-name forms, the three Unicode full stops, which Node's own parser refuses before any rule of ours sees them and which are therefore checked against the rules directly, a plain proxy request, malformed CONNECT lines, a reset in the middle of the handshake, a 200,000 character header block, a flood of 600 sockets on each listener, the window's header rules against a local upstream, a grant that points back at the gatekeeper, journal redaction, the ring buffer's overflow, what the control channel refuses, and since 5b a grant without a secret that adds no header and still takes the space's credentials away, the grant's own header name taken away as well, the policy read back without a secret, and the bind file: the program listens on the address it holds and does not start when it is missing, empty, every interface or not an address. A tunnel that carries bytes needs a name that resolves to a public address, so the tunnel cap and every tunnel that carries something live in the escape suite, inside real containers.
|
|
1092
1146
|
|
|
1093
1147
|
`tools-filler.test.js` runs the real filler program with Node against temporary directories, with a stand-in `npm` on PATH.
|
|
1094
1148
|
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
// curl config. It is in no argument list, on the host or inside, in no label and in no file.
|
|
7
7
|
|
|
8
8
|
import { readFileSync } from 'node:fs';
|
|
9
|
+
import net from 'node:net';
|
|
9
10
|
|
|
10
11
|
import { SpaceError } from './errors.js';
|
|
11
12
|
import {
|
|
@@ -19,6 +20,7 @@ import {
|
|
|
19
20
|
} from './exec-http.js';
|
|
20
21
|
import { ROLE_GATEKEEPER } from './labels.js';
|
|
21
22
|
import {
|
|
23
|
+
GATEKEEPER_BIND_PATH,
|
|
22
24
|
GATEKEEPER_CONTROL_HOST,
|
|
23
25
|
GATEKEEPER_CONTROL_PORT,
|
|
24
26
|
GATEKEEPER_PROGRAM_DIRECTORY,
|
|
@@ -46,16 +48,22 @@ const MAX_JOURNAL_RECORDS = 1_000;
|
|
|
46
48
|
const MAX_JOURNAL_BODY_CHARACTERS = 1024 * 1024;
|
|
47
49
|
const MAX_JOURNAL_FIELD_CHARACTERS = 256;
|
|
48
50
|
|
|
49
|
-
// The program
|
|
51
|
+
// The bind address first, then the program, each through a temporary name, so the waiting
|
|
52
|
+
// container never runs half a file and never runs the program before its address is there.
|
|
50
53
|
const WRITE_PROGRAM_SCRIPT = [
|
|
51
54
|
IMAGE_ONLY_PATH,
|
|
52
55
|
`mkdir -p ${GATEKEEPER_PROGRAM_DIRECTORY}`,
|
|
56
|
+
`&& printf '%s' "$1" > ${GATEKEEPER_BIND_PATH}.new && mv ${GATEKEEPER_BIND_PATH}.new ${GATEKEEPER_BIND_PATH}`,
|
|
53
57
|
`&& cat > ${GATEKEEPER_PROGRAM_PATH}.new && mv ${GATEKEEPER_PROGRAM_PATH}.new ${GATEKEEPER_PROGRAM_PATH}`,
|
|
54
58
|
].join(' ');
|
|
55
59
|
|
|
60
|
+
// A policy is three small lists. These caps are what the host is willing to read back.
|
|
61
|
+
const MAX_POLICY_BODY_CHARACTERS = 256 * 1024;
|
|
62
|
+
const MAX_POLICY_ENTRIES = 1_000;
|
|
63
|
+
|
|
56
64
|
const pause = (milliseconds) => new Promise((resolve) => { setTimeout(resolve, milliseconds); });
|
|
57
65
|
|
|
58
|
-
const unreadableAnswer = (why) => new SpaceError('gatekeeper_answer_unreadable', `The
|
|
66
|
+
const unreadableAnswer = (why) => new SpaceError('gatekeeper_answer_unreadable', `The network filter of the space ${why}`);
|
|
59
67
|
|
|
60
68
|
/**
|
|
61
69
|
* One field of a journal record, as text and no longer than the host reads. A list or an object
|
|
@@ -73,11 +81,20 @@ const text = (value) => (value === null || value === undefined || value instance
|
|
|
73
81
|
export function createGatekeeperChannel({ exec, wait = pause, now = Date.now }) {
|
|
74
82
|
const execInGatekeeper = (spaceId, argv, options) => exec(spaceId, argv, { ...options, target: ROLE_GATEKEEPER });
|
|
75
83
|
|
|
76
|
-
/**
|
|
77
|
-
|
|
78
|
-
|
|
84
|
+
/**
|
|
85
|
+
* The program travels on stdin. It is in no argument, on the host or inside. `bindAddress` is
|
|
86
|
+
* the gatekeeper's own address on the space's network, which the place read from the runtime
|
|
87
|
+
* after the container started; it goes into the file the container command names, and the
|
|
88
|
+
* program listens there and nowhere else. It is an address and not a secret, so it may be an
|
|
89
|
+
* argument of the script.
|
|
90
|
+
*/
|
|
91
|
+
const writeProgram = async (spaceId, { bindAddress }) => {
|
|
92
|
+
if (net.isIP(bindAddress) === 0 || bindAddress === '0.0.0.0' || bindAddress === '::') {
|
|
93
|
+
throw new SpaceError('gatekeeper_address_unknown', 'The address of the network filter on the space\'s network is not known, so its listeners cannot be bound to it.');
|
|
94
|
+
}
|
|
95
|
+
const result = await execInGatekeeper(spaceId, [IMAGE_SH, '-c', WRITE_PROGRAM_SCRIPT, 'sh', bindAddress], { stdin: GATEKEEPER_PROGRAM });
|
|
79
96
|
if (result.code !== 0) {
|
|
80
|
-
throw new SpaceError('gatekeeper_setup_failed', `Could not store the
|
|
97
|
+
throw new SpaceError('gatekeeper_setup_failed', `Could not store the network filter's program: ${tail(result.stderr) || `exit code ${result.code}`}`);
|
|
81
98
|
}
|
|
82
99
|
};
|
|
83
100
|
|
|
@@ -99,7 +116,7 @@ export function createGatekeeperChannel({ exec, wait = pause, now = Date.now })
|
|
|
99
116
|
}
|
|
100
117
|
// No Docker step was interrupted here, so this must not look like one to a rollback.
|
|
101
118
|
if (EXEC_INTERRUPTED_CODES.includes(error.code)) {
|
|
102
|
-
throw new SpaceError('gatekeeper_unreachable', `The request to the
|
|
119
|
+
throw new SpaceError('gatekeeper_unreachable', `The request to the network filter did not finish in time: ${error.message}`, { curlExitCode: null, execFailed: false });
|
|
103
120
|
}
|
|
104
121
|
throw error;
|
|
105
122
|
}
|
|
@@ -117,7 +134,7 @@ export function createGatekeeperChannel({ exec, wait = pause, now = Date.now })
|
|
|
117
134
|
const command = async (spaceId, path, body, what) => {
|
|
118
135
|
const answer = await request(spaceId, { method: 'POST', path, body: JSON.stringify(body) });
|
|
119
136
|
if (answer.status !== 200) {
|
|
120
|
-
throw new SpaceError('gatekeeper_refused', `The
|
|
137
|
+
throw new SpaceError('gatekeeper_refused', `The network filter refused to ${what}: ${tail(answer.body) || `status ${answer.status}`}`, { status: answer.status });
|
|
121
138
|
}
|
|
122
139
|
};
|
|
123
140
|
|
|
@@ -157,8 +174,43 @@ export function createGatekeeperChannel({ exec, wait = pause, now = Date.now })
|
|
|
157
174
|
*/
|
|
158
175
|
const setNetwork = (spaceId, { mode, domains = [] }) => command(spaceId, '/network', { mode, domains }, 'change the network of this space');
|
|
159
176
|
|
|
160
|
-
/**
|
|
161
|
-
|
|
177
|
+
/**
|
|
178
|
+
* One grant: a "uses without seeing" credential, whose secret is in the body and so out of every
|
|
179
|
+
* argument list, or an opened domain with no secret and no header, which the window forwards to
|
|
180
|
+
* as the space sent it.
|
|
181
|
+
*/
|
|
182
|
+
const addGrant = (spaceId, { id, upstream, header = null, secret = null }) => command(
|
|
183
|
+
spaceId,
|
|
184
|
+
'/grants',
|
|
185
|
+
secret === null ? { id, upstream } : { id, upstream, header, secret },
|
|
186
|
+
`add the grant '${id}'`,
|
|
187
|
+
);
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* What the gatekeeper holds now: its mode, its allowlist and the ids of its grants, never a
|
|
191
|
+
* secret. Read as data, capped, so the host can tell a gatekeeper that forgot its grants after
|
|
192
|
+
* a start from one that has them.
|
|
193
|
+
*/
|
|
194
|
+
const readPolicy = async (spaceId) => {
|
|
195
|
+
const answer = await request(spaceId, { path: '/policy' });
|
|
196
|
+
if (answer.status !== 200) throw unreadableAnswer(`answered ${answer.status} for its policy`);
|
|
197
|
+
if (answer.body.length > MAX_POLICY_BODY_CHARACTERS) throw unreadableAnswer('answered with a policy larger than the host reads');
|
|
198
|
+
let parsed;
|
|
199
|
+
try {
|
|
200
|
+
parsed = JSON.parse(answer.body);
|
|
201
|
+
} catch {
|
|
202
|
+
throw unreadableAnswer('answered with a policy that is not JSON');
|
|
203
|
+
}
|
|
204
|
+
if (!(parsed instanceof Object) || Array.isArray(parsed) || !Array.isArray(parsed.grants) || !Array.isArray(parsed.domains)) {
|
|
205
|
+
throw unreadableAnswer('answered with a policy that holds no lists');
|
|
206
|
+
}
|
|
207
|
+
const names = (list) => list.slice(0, MAX_POLICY_ENTRIES).map(text).filter((entry) => entry !== '');
|
|
208
|
+
return {
|
|
209
|
+
mode: parsed.mode === 'open' ? 'open' : 'allowlist',
|
|
210
|
+
domains: names(parsed.domains),
|
|
211
|
+
grants: names(parsed.grants),
|
|
212
|
+
};
|
|
213
|
+
};
|
|
162
214
|
|
|
163
215
|
/**
|
|
164
216
|
* What the gatekeeper allowed and refused. The answer comes out of a container, so it is read
|
|
@@ -200,5 +252,5 @@ export function createGatekeeperChannel({ exec, wait = pause, now = Date.now })
|
|
|
200
252
|
};
|
|
201
253
|
};
|
|
202
254
|
|
|
203
|
-
return { writeProgram, waitUntilReady, setNetwork, addGrant, readJournal };
|
|
255
|
+
return { writeProgram, waitUntilReady, setNetwork, addGrant, readPolicy, readJournal };
|
|
204
256
|
}
|
|
@@ -31,23 +31,33 @@ describe('gatekeeper channel: the program', () => {
|
|
|
31
31
|
expect(GATEKEEPER_PROGRAM.length).toBeGreaterThan(2_000);
|
|
32
32
|
});
|
|
33
33
|
|
|
34
|
-
it('travels on stdin into the tmpfs, through a temporary name, and is in no argument', async () => {
|
|
34
|
+
it('travels on stdin into the tmpfs, through a temporary name, after the bind address, and is in no argument', async () => {
|
|
35
35
|
const { channel, calls } = channelWith(ok());
|
|
36
|
-
await channel.writeProgram(ID);
|
|
36
|
+
await channel.writeProgram(ID, { bindAddress: '172.19.0.2' });
|
|
37
37
|
|
|
38
38
|
expect(calls).toEqual([{
|
|
39
39
|
spaceId: ID,
|
|
40
40
|
argv: [
|
|
41
41
|
'/bin/sh', '-c',
|
|
42
|
-
'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; mkdir -p /tmp/openchamber-gatekeeper
|
|
42
|
+
'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; mkdir -p /tmp/openchamber-gatekeeper'
|
|
43
|
+
+ " && printf '%s' \"$1\" > /tmp/openchamber-gatekeeper/bind.new && mv /tmp/openchamber-gatekeeper/bind.new /tmp/openchamber-gatekeeper/bind"
|
|
44
|
+
+ ' && cat > /tmp/openchamber-gatekeeper/gatekeeper.cjs.new && mv /tmp/openchamber-gatekeeper/gatekeeper.cjs.new /tmp/openchamber-gatekeeper/gatekeeper.cjs',
|
|
45
|
+
'sh', '172.19.0.2',
|
|
43
46
|
],
|
|
44
47
|
options: { stdin: GATEKEEPER_PROGRAM, target: 'gatekeeper' },
|
|
45
48
|
}]);
|
|
46
49
|
});
|
|
47
50
|
|
|
51
|
+
// The program refuses these too; the host refuses them first, so a gatekeeper is never asked to listen everywhere.
|
|
52
|
+
it.each(['', '0.0.0.0', '::', 'gatekeeper', '172.19.0'])('refuses to write the program with %j as the bind address', async (bindAddress) => {
|
|
53
|
+
const { channel, calls } = channelWith(ok());
|
|
54
|
+
await expect(channel.writeProgram(ID, { bindAddress })).rejects.toMatchObject({ code: 'gatekeeper_address_unknown' });
|
|
55
|
+
expect(calls).toEqual([]);
|
|
56
|
+
});
|
|
57
|
+
|
|
48
58
|
it('says what failed inside the gatekeeper', async () => {
|
|
49
59
|
const { channel } = channelWith({ code: 1, stdout: '', stderr: 'sh: 1: cannot create: No space left on device\n' });
|
|
50
|
-
await expect(channel.writeProgram(ID)).rejects.toMatchObject({ code: 'gatekeeper_setup_failed', message: expect.stringContaining('No space left on device') });
|
|
60
|
+
await expect(channel.writeProgram(ID, { bindAddress: '172.19.0.2' })).rejects.toMatchObject({ code: 'gatekeeper_setup_failed', message: expect.stringContaining('No space left on device') });
|
|
51
61
|
});
|
|
52
62
|
});
|
|
53
63
|
|
|
@@ -76,6 +86,26 @@ describe('gatekeeper channel: control requests', () => {
|
|
|
76
86
|
expect(calls[0].options.stdin).toContain(SECRET);
|
|
77
87
|
});
|
|
78
88
|
|
|
89
|
+
it('sends an opened domain as a grant with no header and no secret', async () => {
|
|
90
|
+
const { channel, calls } = channelWith(ok(http(200, '{"ok":true}')));
|
|
91
|
+
await channel.addGrant(ID, { id: 'open-0a1b2c3d4e5f', upstream: 'https://registry.example.com/npm/' });
|
|
92
|
+
const data = calls[0].options.stdin.split('\n').find((line) => line.startsWith('data-raw = '));
|
|
93
|
+
expect(JSON.parse(JSON.parse(data.slice('data-raw = '.length)))).toEqual({ id: 'open-0a1b2c3d4e5f', upstream: 'https://registry.example.com/npm/' });
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
it('reads what the gatekeeper holds as data: mode, names and grant ids, capped, and never a secret', async () => {
|
|
97
|
+
const { channel } = channelWith(ok(http(200, JSON.stringify({ mode: 'open', domains: ['a.example.com', 7, {}], grants: ['anthropic', ['x'], 'open-1'], secret: SECRET }))));
|
|
98
|
+
expect(await channel.readPolicy(ID)).toEqual({ mode: 'open', domains: ['a.example.com', '7'], grants: ['anthropic', 'open-1'] });
|
|
99
|
+
const { channel: allowlist } = channelWith(ok(http(200, '{"mode":"anything","domains":[],"grants":[]}')));
|
|
100
|
+
expect(await allowlist.readPolicy(ID)).toEqual({ mode: 'allowlist', domains: [], grants: [] });
|
|
101
|
+
for (const body of ['not json', '[]', '{"grants":"anthropic"}', '{"grants":[]}']) {
|
|
102
|
+
const { channel: broken } = channelWith(ok(http(200, body)));
|
|
103
|
+
await expect(broken.readPolicy(ID)).rejects.toMatchObject({ code: 'gatekeeper_answer_unreadable' });
|
|
104
|
+
}
|
|
105
|
+
const { channel: refused } = channelWith(ok(http(404, '{}')));
|
|
106
|
+
await expect(refused.readPolicy(ID)).rejects.toMatchObject({ code: 'gatekeeper_answer_unreadable' });
|
|
107
|
+
});
|
|
108
|
+
|
|
79
109
|
it('reports a refusal from the control channel, with what it said', async () => {
|
|
80
110
|
const { channel } = channelWith(ok(http(400, '{"error":"mode is \\"allowlist\\" or \\"open\\""}')));
|
|
81
111
|
await expect(channel.setNetwork(ID, { mode: 'everything', domains: [] })).rejects.toMatchObject({
|