Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix(security): require operator authority to name a host path PortOS reads or runs against

Adam Eivy4e02524dfd3d
diff --git a/docs/API.md b/docs/API.md
index 775de8e0d4..9ea5c4a347 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -736,7 +736,7 @@ Every mounted API prefix (see `server/index.js` for the authoritative list). Dom
| `/api/capabilities` | Feature capability flags |
| `/api/agent-context` | Opt-in, loopback-only MCP context plus separately granted semantic PortOS actions |
| `/api/workspace-contexts` | Workspace context management |
-| `/api/apps/:appId/reference-repos` | Per-app reference repos |
+| `/api/apps/:appId/reference-repos` | Per-app reference repos (create, a PATCH that changes `repoUrl`/`branch`, and `check` are host control: the path names a host directory the scheduled reference-watch runs git in) |
| `/api/managed-visitor-admin` | Owner-only provisioning and revocation of scoped managed-app visitor credentials; [contract](features/managed-visitors.md) |
| `/api/managed-visitors/v1` | Loopback managed visitor admission, observation, bounded actions and confirmed cleanup; requires a separate scoped app credential even when the instance password is off; [contract](features/managed-visitors.md) |
| `/api/network-exposure` | Network exposure checks |
@@ -777,7 +777,7 @@ Every mounted API prefix (see `server/index.js` for the authoritative list). Dom
| `/api/health` | Apple Health metrics, ingest, and XML import |
| `/api/human-actions` | Scheduled steps only the human can take, as Brain threads with reminders ([Human Actions](#human-actions)) |
| `/api/insights` | Cross-domain insights |
-| `/api/instances`, `/api/sync`, `/api/peer-sync`, `/api/sharing` | Federation / peer sync (see [COMPANION_APP_API.md](./COMPANION_APP_API.md)) |
+| `/api/instances`, `/api/sync`, `/api/peer-sync`, `/api/sharing` | Federation / peer sync (see [COMPANION_APP_API.md](./COMPANION_APP_API.md)); `POST /api/sharing/buckets` is host control (it names a host folder PortOS writes records into and imports manifests from) |
| `/api/federation/media/v1` | Authenticated queued peer audio provider (see [FEDERATED_MEDIA_PROVIDERS.md](./FEDERATED_MEDIA_PROVIDERS.md)) |
| `/api/federation/admin/v1` | Paired-peer administration preflights and temporary signed plans; execution remains unsupported (see [peer administration planning](./features/peer-administration.md)) |
| `/api/peer-administration` | Operator-only per-peer/action planning grants and outbound previews (see [peer administration planning](./features/peer-administration.md)) |
@@ -814,9 +814,9 @@ Every mounted API prefix (see `server/index.js` for the authoritative list). Dom
| `/api/rounds` | Rounds (music + Morse training) |
| `/api/ask` | Ask (LLM Q&A) |
| `/api/quota-burn` | Quota-burn plan (ordered scheduled-task references + per-invocation overrides), its live status, the app/provider catalog its pickers read, manual runs, and re-arm. The referenced work itself is read from — and only ever edited through — `/api/cos/schedule` and `/api/cos/jobs`. |
-| `/api/timeline` | Human-activity timeline (day + events) |
+| `/api/timeline` | Human-activity timeline (day + events); the path-based Gmail mbox import is host control (it names a host file or folder to read) |
| `/api/games` | Game projects |
-| `/api/sprites` | Sprite catalog / export |
+| `/api/sprites` | Sprite catalog / export; `POST /import` is host control (it names a host source tree to copy from) |
| `/api/threejs-models` | Procedural Three.js models |
| `/api/film-styles` | Read-only film style grammar catalog: picker list (`GET /`), full grammar record (`GET /:id`) and rendered prompt-section preview (`GET /:id/prompt?parts=motion,camera`) |
| `/api/code-animation` | Code Animation: LLM-written briefs, prompt building, persistent jobs gallery, generated HTML retrieval, frame-exact MP4 export (`POST /:id/export` → HTML-composition media job), the vendored three.js modules the `three` renderer's preview inlines (`GET /vendor/three`; the export stages the same files, hashed, beside the page), portable source download (`GET /:id/package`), and data-only package validation (`POST /packages/validate`; [contract](CODE_ANIMATION_PACKAGES.md)) |
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index d3b80cb5fd..cadece9922 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -104,6 +104,17 @@
* its non-loopback opt-in, the MortalLoom store path (all change-gated,
* below) and `PUT /api/lmstudio/config` (base URL plus timeout, in
* memory, with no UI writer).
+ * - Caller-named host paths: a request body that names a host directory or
+ * file PortOS then reads, writes or runs against is the same choice as a
+ * stored host-file setting, made once. A remote password-free caller
+ * could otherwise point PortOS at any path the host user owns. Gated:
+ * reference-repo create (and a PATCH that changes `repoUrl`/`branch`,
+ * which the scheduled reference-watch runs git in and hands to an
+ * analysis agent), share-bucket create (PortOS writes records into and
+ * imports manifests from the folder), the sprite source-tree import and
+ * the path-based Gmail mbox import. Rename/notes/mode PATCHes, bucket
+ * export into an operator-chosen bucket, and the upload-based importers
+ * stay open: they name no host path.
* - browser: navigate uses the configured browser with its URL/IP guards;
* downloads DELETE removes data. Harness models/refresh re-reads the
* configured harness catalog; neither selects or installs an executable.
@@ -974,8 +985,19 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
// Reference repos (#8742): a check that finds new commits queues a CoS
// analysis agent against them. `reviewed` only advances a recorded SHA.
+ // Create names the repo — a local path is a host directory the weekly
+ // reference-watch task runs git in and hands to that agent unattended, so
+ // choosing it is operator work; a PATCH gates per body (repoUrl/branch).
+ 'POST /api/apps/:appId/reference-repos',
'POST /api/apps/:appId/reference-repos/:refId/check',
+ // Caller-named host paths (rationale in the header): the folder, source
+ // tree or mailbox file each body names. Their record-only and upload-based
+ // neighbours stay open.
+ 'POST /api/sharing/buckets',
+ 'POST /api/sprites/import',
+ 'POST /api/timeline/import/gmail',
+
// Persistent Mind lifecycle (#8742): starting/waking/resuming the mind arms
// its own agentic loop, which can queue CoS tasks on its own initiative
// (services/persistentMindTaskCapability.js) without further user action —
@@ -1112,6 +1134,10 @@ const COMPILED_BODY_ROUTES = [
// Importer commit runs one LLM reformat call per excerpt only when asked to
// (#11036); the default deterministic commit stays open.
['POST /api/importer/commit', (body) => body?.cleanupFormatting === true ? ['cleanupFormatting'] : []],
+ // A reference-repo PATCH that re-points the repo or branch chooses what the
+ // scheduled reference-watch runs git in; name, notes and the reviewed SHA
+ // are records.
+ ['PATCH /api/apps/:appId/reference-repos/:refId', (body) => ['repoUrl', 'branch'].filter((key) => body?.[key] !== undefined)],
].map(([route, pick]) => ({ ...compileRoute(route), pick }));
/** The host-control keys a request body names, for `method path` of a policy store; [] elsewhere. */
diff --git a/server/lib/hostControlRoutes.test.js b/server/lib/hostControlRoutes.test.js
index 9cb61a4ee9..f8385dd542 100644
--- a/server/lib/hostControlRoutes.test.js
+++ b/server/lib/hostControlRoutes.test.js
@@ -1071,3 +1071,39 @@ describe('Telegram bot and bridge authority policy (#11431)', () => {
expect(HOST_CONTROL_SETTINGS_SLICES).toContain('telegram');
});
});
+
+describe('caller-named host paths', () => {
+ it('gates the routes whose body names a host path PortOS reads, writes or runs against', () => {
+ const mounted = new Set(getApiRouteCatalog().routes.map(({ method, path }) => `${method} ${path}`));
+ for (const route of [
+ 'POST /api/apps/:appId/reference-repos',
+ 'POST /api/sharing/buckets',
+ 'POST /api/sprites/import',
+ 'POST /api/timeline/import/gmail',
+ ]) {
+ const [method, path] = route.split(' ');
+ expect(mounted.has(route), route).toBe(true);
+ expect(hostControlRouteFor(method, path), route).toBe(route);
+ }
+ // The record-only neighbours and the upload-based importers stay open.
+ for (const [method, path] of [
+ ['PATCH', '/api/apps/:appId/reference-repos/:refId'],
+ ['POST', '/api/apps/:appId/reference-repos/:refId/reviewed'],
+ ['PUT', '/api/sharing/buckets/:id'],
+ ['DELETE', '/api/sharing/buckets/:id'],
+ ['POST', '/api/sharing/buckets/:id/export'],
+ ['POST', '/api/sprites'],
+ ['POST', '/api/timeline/import/whatsapp'],
+ ['POST', '/api/timeline/import/browser'],
+ ]) expect(isHostControlRoute(method, path), `${method} ${path}`).toBe(false);
+ });
+
+ it('gates a reference-repo PATCH only when it re-points the repo or branch', () => {
+ const path = '/api/apps/example-app/reference-repos/ref-1';
+ expect(hostControlBodyKeys('PATCH', path, { repoUrl: '~/example/repo' })).toEqual(['repoUrl']);
+ expect(hostControlBodyKeys('patch', `${path}/`, { branch: 'main', name: 'Example' })).toEqual(['branch']);
+ expect(hostControlBodyKeys('PATCH', path, { name: 'Example', notes: 'n', lastReviewedSha: 'a'.repeat(40) })).toEqual([]);
+ expect(hostControlBodyKeys('PATCH', path, undefined)).toEqual([]);
+ expect(hostControlBodyKeys('PUT', path, { repoUrl: '~/example/repo' })).toEqual([]);
+ });
+});