> 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_16/session_02_backend_endpoint_parity_write_safety.md). # Session 02: Backend Endpoint Parity And Write-Safety Foundation **Session ID**: `phase16-session02-backend-endpoint-parity-write-safety` **Status**: Completed **Estimated Tasks**: \~20-25 **Estimated Duration**: 3-4 hours *** ## Objective Build the write-safety foundation and bring the dev/admin bridges to endpoint parity with v2.3: generalize path confinement into `confinePath`, add the 5 missing read endpoints and the 10 missing write endpoints (each satisfying the Write-Path Safety Contract), and add the security tests that gate every write. Source-code anchors are `V23/vite.config.ts`, `AIOS/scripts/lib/hermes-dev-bridge.ts`, and `AIOS/scripts/lib/hermes-admin-bridge.ts`. *** ## Scope ### In Scope (MVP) **Write-safety foundation (do first -- every write endpoint uses it):** * Generalize the existing path-confinement (`hermes-admin-bridge.ts:522-524`, `resolve` + `relative` + reject `..`) into a reusable `confinePath(base, userValue)` helper. * Reuse the existing write guard `requirePreflight(req, options, method, tokenRequired)` (`hermes-admin-bridge.ts:297`) and the secret-redaction regex (`hermes-admin-bridge.ts:27`); do not re-implement. * Reuse `isLoopback(req)` (`AIOS/vite.config.ts:57`), per-run `REFRESH_TOKEN` (`AIOS/vite.config.ts:42`, header `x-claude-os-token`), and the args-array spawn template (`hermes-admin-bridge.ts:696`). **Add 5 missing read endpoints** to `AIOS/scripts/lib/hermes-dev-bridge.ts` (register fn `:964`), GET-only and loopback-gated: * `/__hermes_connections` -- V23 `vite.config.ts:1303` * `/__hermes_profiles` -- V23 `:1231` (sensitive read: token-gated) * `/__hermes_pantheon_templates` -- V23 `:1734` * `/__hermes_missions` (GET) -- V23 `:780` * `/__hermes_documents` (GET/file/trash) -- V23 `:2832` (`/file` `:2843`, `/trash` `:3009`) **Add 10 missing write endpoints** to `AIOS/scripts/lib/hermes-admin-bridge.ts` (register fn `:926`) behind `requirePreflight` + `confinePath`, satisfying the full Write-Path Safety Contract: * `POST /__hermes_missions/create` -- V23 `:952` (FS write, confine to missions file) * `POST /__hermes_missions/optimize` -- V23 `:804` (**cmd exec**; clone chat spawn path `:696`) * `POST /__hermes_missions/tick` -- V23 `:1054` (FS write; validate goal id) * `POST /__hermes_missions/clear` -- V23 `:1103` (FS delete; confirm, confined) * `POST /__hermes_image_upload` -- V23 `:454` (body-size cap, content-type check, confined cache dir) * `POST /__hermes_pantheon_sync` -- V23 `:1984` (GET status) + git push (**net + exec**; args-array git, no shell interpolation of refs, confirm) * `DELETE /__hermes_documents?name=` -- V23 `:2914` (FS move->trash, name confined, reversible) * `POST /__hermes_documents/restore` -- V23 `:2952` (FS move, trashId confined) * `DELETE /__hermes_documents/trash` -- V23 `:3049` (FS delete perm, trashId confined, confirm) * `POST /__hermes_obsidian` (vault write) -- new; **FS write outside Hermes home**, requires explicit user-configured vault-path allow-list, confined, confirm. All new write endpoints route behind the existing `/__hermes_admin_status` gate (`hermes-admin-bridge.ts:218`). **Security tests (the merge gate)** for every new write endpoint: reject without token, reject non-loopback origin, reject wrong HTTP method, reject oversized body; for path-confined handlers assert `../` traversal in `name`/`id`/`trashId` is refused; for spawn endpoints (mission optimize, GitHub sync) assert shell metacharacters reach the binary as inert argv and a runaway process is killed by the timeout. ### Out of Scope * Client hook queries/mutations and typed payloads (Session 03). * Demo fixtures (Session 03). * Any UI/component (Phases 17-20). * The 6 already-ported writes (chat, persona validate/install/create/edit/ delete) -- they remain unchanged. *** ## Prerequisites * [x] Session 01 complete (architecture/IA decision and parity baseline). * [ ] `hermes-dev-bridge.ts` and `hermes-admin-bridge.ts` are the registration points; existing primitives (`isLoopback`, `REFRESH_TOKEN`, `requirePreflight`, redaction, args-array spawn) are confirmed reusable. *** ## Deliverables 1. A reusable `confinePath(base, userValue)` helper generalized from `hermes-admin-bridge.ts:522-524`, with traversal tests. 2. The 5 read endpoints registered in `hermes-dev-bridge.ts` (loopback-gated; `/__hermes_profiles` token-gated as a sensitive read). 3. The 10 write endpoints registered in `hermes-admin-bridge.ts`, each satisfying all 8 contract clauses and behind `/__hermes_admin_status`. 4. Security tests covering token/loopback/method/body/traversal/spawn for every new write endpoint. *** ## Success Criteria * [ ] `confinePath` exists, is reused by every file-op handler, and rejects `../` traversal in tests. * [ ] All 5 read endpoints return v2.3-parity payloads, GET-only and loopback-gated; `/__hermes_profiles` requires the token. * [ ] All 10 write endpoints are method-pinned, loopback-gated, token-gated, body-bounded, path-confined (or vault-allow-listed for Obsidian), spawn-safe where applicable, soft-delete/confirm where destructive, and audited. * [ ] Spawn endpoints pass the prompt/ref as inert argv (no shell expansion) and enforce timeout + output cap. * [ ] Security tests pass for every new write endpoint (the merge gate). * [ ] No secret values, raw paths, prompts, or command bodies appear in logs or responses. --- # 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_16/session_02_backend_endpoint_parity_write_safety.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.