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 browse host directories

Adam Eivy3b54cec4e240
diff --git a/docs/API.md b/docs/API.md
index 018a059954..775de8e0d4 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -236,7 +236,7 @@ Context tools remain read-only. Semantic reads and writes are independent, defau
| Method | Endpoint | Description |
|--------|----------|-------------|
-| GET | `/scaffold/directories` | List candidate parent directories |
+| GET | `/scaffold/directories` | Browse host directories for the location picker (host control: enumerates any readable directory) |
| GET | `/scaffold/templates` | List available templates |
| POST | `/scaffold/templates/create` | Create app from template |
| POST | `/scaffold` | Scaffold a new app |
diff --git a/docs/features/app-wizard.md b/docs/features/app-wizard.md
index ca4c13e78c..66e3024159 100644
--- a/docs/features/app-wizard.md
+++ b/docs/features/app-wizard.md
@@ -57,7 +57,7 @@ Scaffold a new project from template:
| POST /api/apps | Register existing app |
| POST /api/scaffold | Create new app from template |
| GET /api/scaffold/templates | List available templates |
-| GET /api/scaffold/directories | Browse directories for the location picker |
+| GET /api/scaffold/directories | Browse directories for the location picker (host control — operator session, or a local connection when no password is set) |
| POST /api/scaffold/templates/create | Create an app from a template (user-friendly wrapper around POST /api/scaffold) |
| POST /api/detect/port | Detect process on port |
| POST /api/detect/repo | Validate repo path, detect type |
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index 4279aaff3f..d3b80cb5fd 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -13,7 +13,9 @@
* the host, or when it sets what one will run (a repo path, a start command, a
* task prompt, a shell job), or accesses live camera/microphone streams.
* Ordinary read-only GETs stay open; raw backup archives require operator
- * authority because they export private records and credentials. Mutating routes in the
+ * authority because they export private records and credentials, and so does
+ * the directory picker (GET /api/scaffold/directories), which enumerates any
+ * readable host directory rather than a PortOS record. Mutating routes in the
* same families that are deliberately left OUT:
* - apps: delete/archive/unarchive, scope-adherence — they
* change only PortOS's own records or read files; nothing runs.
@@ -485,7 +487,11 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
'POST /api/backup/restore',
'POST /api/backup/restore-db',
- // Scaffolding writes a new repo and runs git/npm in it.
+ // Scaffolding writes a new repo and runs git/npm in it. The picker lists
+ // directory and file names anywhere on the host (not only under the
+ // workspace roots: the same component browses /Applications for a Chrome
+ // binary), so it is operator-only too; the template catalog stays open.
+ 'GET /api/scaffold/directories',
'POST /api/scaffold',
'POST /api/scaffold/templates/create',
diff --git a/server/lib/hostControlRoutes.test.js b/server/lib/hostControlRoutes.test.js
index 3f26b8ce05..9cb61a4ee9 100644
--- a/server/lib/hostControlRoutes.test.js
+++ b/server/lib/hostControlRoutes.test.js
@@ -152,6 +152,9 @@ describe('HOST_CONTROL_ROUTES (#8716)', () => {
expect(isHostControlRoute('POST', '/api//runs')).toBe(false);
expect(isHostControlRoute('PUT', '/api/apps/example-app/documents/docs/example.md')).toBe(true);
+ // The host directory picker is the gated read; the template catalog beside it is not.
+ expect(isHostControlRoute('GET', '/api/scaffold/directories')).toBe(true);
+ expect(isHostControlRoute('GET', '/api/scaffold/templates')).toBe(false);
// Read-only GETs and neighbouring paths stay open.
expect(isHostControlRoute('GET', '/api/apps/example-app/start')).toBe(false);
expect(isHostControlRoute('GET', '/api/git/submodules/status')).toBe(false);
diff --git a/server/lib/validation.js b/server/lib/validation.js
index e60253f117..d1ed5c0cd9 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -1501,6 +1501,13 @@ const scaffoldPortSchema = z.preprocess(
z.number().int().min(1).max(65535).nullable().optional()
);
+// GET /api/scaffold/directories. `includeFiles` is a query flag, so it arrives
+// as the string 'true' rather than a boolean.
+export const scaffoldDirectoriesQuerySchema = z.object({
+ path: z.string().trim().min(1).max(4096).optional(),
+ includeFiles: z.enum(['true', 'false']).optional(),
+});
+
// Full request schema for POST /api/scaffold. Validated before the route
// touches the filesystem — template enum, port range, and a name that yields a
// usable directory slug are all enforced up front.
diff --git a/server/routeValidationConventions.test.js b/server/routeValidationConventions.test.js
index c9e72004b8..33f4accccf 100644
--- a/server/routeValidationConventions.test.js
+++ b/server/routeValidationConventions.test.js
@@ -284,7 +284,6 @@ const UNVALIDATED_QUERY_BASELINE = [
'routes/providers.js POST /runtimes/install',
'routes/quotaBurn.js GET /',
'routes/review.js GET /items',
- 'routes/scaffold.js GET /directories',
'routes/sharing.js GET /subscriptions',
'routes/spotify.js GET /oauth/callback',
'routes/sprites.js GET /',
diff --git a/server/routes/scaffold.js b/server/routes/scaffold.js
index 40da0a81df..f45d3c7ad3 100644
--- a/server/routes/scaffold.js
+++ b/server/routes/scaffold.js
@@ -9,7 +9,7 @@ import { promisify } from 'util';
import { platform } from 'os';
import { createApp, getReservedPorts, notifyAppsChanged } from '../services/apps.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { validateRequest, scaffoldSchema, scaffoldTemplateCreateBodySchema } from '../lib/validation.js';
+import { validateRequest, scaffoldDirectoriesQuerySchema, scaffoldSchema, scaffoldTemplateCreateBodySchema } from '../lib/validation.js';
import { ensureDir, expandHome } from '../lib/fileUtils.js';
import { isWithinAllowedRoots, outsideAllowedRootsMessage } from '../lib/workspaceRoots.js';
import { scaffoldVite } from './scaffoldVite.js';
@@ -27,9 +27,11 @@ const __dirname = dirname(__filename);
const router = Router();
-// GET /api/scaffold/directories - Browse directories for directory picker
+// GET /api/scaffold/directories - Browse directories for directory picker.
+// Operator-only (HOST_CONTROL_ROUTES): it enumerates any readable host
+// directory, so the workspace roots that scope POST / below do not apply.
router.get('/directories', asyncHandler(async (req, res) => {
- const { path: dirPath } = req.query;
+ const { path: dirPath, includeFiles } = validateRequest(scaffoldDirectoriesQuerySchema, req.query);
// Default to parent of PortOS project if no path provided
const defaultPath = resolve(join(__dirname, '../../..'));
@@ -90,7 +92,7 @@ router.get('/directories', asyncHandler(async (req, res) => {
currentPath: targetPath,
parentPath: canGoUp ? parentPath : null,
directories,
- ...(req.query.includeFiles === 'true' && { files: entries
+ ...(includeFiles === 'true' && { files: entries
.filter(entry => (entry.isFile() || entry.isSymbolicLink()) && !entry.name.startsWith('.'))
.map(entry => ({ name: entry.name, path: join(targetPath, entry.name) }))
.sort((a, b) => a.name.localeCompare(b.name)) }),
diff --git a/server/routes/scaffold.test.js b/server/routes/scaffold.test.js
index 08c4a841fa..ebcc4221e6 100644
--- a/server/routes/scaffold.test.js
+++ b/server/routes/scaffold.test.js
@@ -331,4 +331,11 @@ describe('GET /api/scaffold/directories', () => {
expect(files.body.files).toEqual([{ name: 'chrome', path: join(resolve('/tmp/workspace'), 'chrome') }]);
expect(files.body.directories).toEqual(folders.body.directories);
});
+
+ it('rejects an includeFiles value that is not a flag before reading the directory', async () => {
+ const app = makeApp();
+ const res = await request(app).get('/api/scaffold/directories?path=/tmp/workspace&includeFiles=yes');
+ expect(res.status).toBe(400);
+ expect(readdir).not.toHaveBeenCalled();
+ });
});