> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_38/session_05_runtime_bridge_hardening.md). # Session 05: Runtime Bridge Hardening **Session ID**: `phase38-session05-runtime-bridge-hardening` **Status**: Complete **Completed**: 2026-06-29 **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Make request-time Hermes, Graphify, and local control-plane endpoints platform-safe and DNS-rebinding resistant. *** ## Non-Negotiable Delivery Bar Bridge hardening is complete only when real endpoint paths reject hostile requests and still resolve valid Hermes, Graphify, and Dream commands on Windows and POSIX paths. Guard code that is not exercised by endpoint tests is not sufficient. *** ## Source Items * 1.5 `ADAPT`: Hermes/Graphify runtime CLI resolution and Host-header hardening. *** ## Scope ### In Scope (MVP) * Use the shared platform module for runtime Hermes and Graphify CLI resolution in bridge code. * Add Windows venv `Scripts`, `%APPDATA%\npm`, `%LOCALAPPDATA%\Programs`, and `.cmd` candidate handling where needed. * Harden Host-header validation in `/home/aiwithapex/projects/aios/vite.config.ts`. * Preserve existing loopback-only privileged endpoint checks. * Cover Hermes status, Hermes chat, Knowledge Graph graphify status/ingest, and Dream run endpoints. ### Out of Scope * Voice endpoint exposure; voice depends on this session. * Feature-level Hermes chat redesign. * Public hosted bridge behavior. * Aggregate-only app detection changes already owned by Session 03. *** ## Detailed Port Item ### 1.5 Runtime CLI Resolution And Host-Header Hardening Upstream `vite.config.ts` changed local control-plane runtime behavior: Windows-safe venv bin paths, `where` and known-location CLI resolution for Hermes and Graphify, and Host-header validation. This affects request-time live bridge spawning, not only aggregate detection. * Upstream source: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/vite.config.ts`. * Patch line: 6506. * Upstream hunks to inspect: `venvBin`, `cliBinCandidates`, `resolveCliBin`, `isLoopback` Host-header handling, Graphify status, Hermes status, `/__hermes_chat`, and `/__run_dream`. * AI OS platform target: `/home/aiwithapex/projects/aios/scripts/lib/platform.ts`. * AI OS detection target: `/home/aiwithapex/projects/aios/scripts/lib/tool-detection.ts`. * AI OS bridge targets: `/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts`, `/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts`, and `/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-admin-bridge.ts`. * AI OS Vite target: `/home/aiwithapex/projects/aios/vite.config.ts`. * Confirmed gaps: * `scripts/lib/hermes-admin-bridge.ts` hardcodes POSIX Hermes venv Python at `~/.hermes/hermes-agent/venv/bin/python` and POSIX Hermes binary candidates. * `scripts/lib/tool-detection.ts` handles Windows executable extensions but lacks common `%APPDATA%\npm`, `%LOCALAPPDATA%\Programs`, and venv `Scripts` locations. * `vite.config.ts` has loopback checks but lacks Host-header validation, so it lacks upstream DNS-rebinding hardening. * Adaptation: centralize runtime path helpers in `scripts/lib/platform.ts` instead of inlining them in Vite. Aggregate detection and request-time spawn paths must share one implementation. * Risk: medium because this touches privileged local endpoints. *** ## Prerequisites * [x] Session 02 completed. * [x] Current bridge tests and Vite middleware guard tests are identified. * [x] Existing endpoint guard behavior is characterized to avoid weakening loopback or token checks. *** ## Deliverables 1. Shared runtime binary resolution for aggregate detection and live bridge spawning. 2. Windows and POSIX CLI candidate support for Hermes and Graphify. 3. Host-header rejection for hostile hosts such as `localhost.evil.com`. 4. Bridge and Vite tests for Windows candidates, loopback-valid hosts, loopback socket plus hostile Host rejection, and existing endpoint regressions. *** ## Success Criteria * [x] Hermes status, Hermes chat, Knowledge Graph graphify status/ingest, and Dream run endpoints resolve binaries correctly on Windows and POSIX. * [x] Bridge tests cover Windows venv `Scripts` and `%APPDATA%\npm\*.cmd` candidates. * [x] Host-header tests reject hostile headers while allowing valid loopback requests. * [x] Existing Hermes chat, Knowledge Graph, and Dream run endpoint tests still pass. * [x] This hardening lands before Session 08 exposes voice launch behavior. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_38/session_05_runtime_bridge_hardening.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.