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: contain GSD planning reads and writes within managed repositories

Adam Eivy9ae7b2bec1cd
diff --git a/server/routes/gsd.js b/server/routes/gsd.js
index e2c7bdf14e..3548630530 100644
--- a/server/routes/gsd.js
+++ b/server/routes/gsd.js
@@ -9,11 +9,11 @@ import { Router } from 'express'
import { z } from 'zod'
import { existsSync } from 'fs'
import { readFile } from 'fs/promises'
-import { join, resolve } from 'path'
import { asyncHandler, ServerError } from '../lib/errorHandler.js'
import { atomicWrite } from '../lib/fileUtils.js'
import { documentUpdateSchema, validateRequest } from '../lib/validation.js'
import * as gsdService from '../services/gsdService.js'
+import { resolveGsdPath } from '../services/gsdPaths.js'
import { addTask } from '../services/cos.js'
import { getActiveApps } from '../services/apps.js'
import * as git from '../services/git.js'
@@ -47,8 +47,8 @@ async function loadAppPlanning(req) {
const apps = await getActiveApps()
const app = apps.find(a => a.id === req.params.appId)
if (!app?.repoPath) return null
- const planningPath = join(app.repoPath, '.planning')
- if (!existsSync(planningPath)) return null
+ const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
+ if (!planningPath || !existsSync(planningPath)) return null
return { app, planningPath }
}
@@ -162,11 +162,7 @@ router.get('/projects/:appId/documents/:docName', asyncHandler(async (req, res)
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
- const filePath = join(ctx.planningPath, docName)
- const resolved = resolve(filePath)
- if (!resolved.startsWith(resolve(ctx.planningPath))) {
- throw new ServerError('Invalid document path', { status: 400, code: 'PATH_TRAVERSAL' })
- }
+ const resolved = await resolveGsdPath(ctx.app.repoPath, docName)
if (!existsSync(resolved)) {
throw new ServerError('Document not found', { status: 404, code: 'NOT_FOUND' })
@@ -188,11 +184,7 @@ router.put('/projects/:appId/documents/:docName', asyncHandler(async (req, res)
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
- const filePath = join(ctx.planningPath, docName)
- const resolved = resolve(filePath)
- if (!resolved.startsWith(resolve(ctx.planningPath))) {
- throw new ServerError('Invalid document path', { status: 400, code: 'PATH_TRAVERSAL' })
- }
+ const resolved = await resolveGsdPath(ctx.app.repoPath, docName)
const { content, commitMessage } = validateRequest(documentUpdateSchema, req.body)
const created = !existsSync(resolved)
diff --git a/server/routes/gsd.test.js b/server/routes/gsd.test.js
index 48c9a89c96..0448fdfa14 100644
--- a/server/routes/gsd.test.js
+++ b/server/routes/gsd.test.js
@@ -1,6 +1,7 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import express from 'express';
-import { mkdtemp, mkdir, rm, writeFile } from 'fs/promises';
+import { EventEmitter } from 'node:events';
+import { mkdtemp, mkdir, rm, writeFile, symlink, readFile, realpath } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
import { errorMiddleware } from '../lib/errorHandler.js';
@@ -8,6 +9,7 @@ import { request } from '../lib/testHelper.js';
const mocks = vi.hoisted(() => ({
activeApps: [],
+ authEnabled: false,
addTask: vi.fn(),
atomicWrite: vi.fn(),
generateConcernTasks: vi.fn(),
@@ -17,6 +19,20 @@ const mocks = vi.hoisted(() => ({
commit: vi.fn(),
}));
+// Credential verification is already covered by authGate.test.js; these fixtures
+// represent its verified human-cookie and delegated-agent bearer identities.
+vi.mock('../services/auth.js', () => ({
+ isAuthEnabled: async () => mocks.authEnabled,
+ verifyPassword: async () => false,
+ verifyRequestSession: async (req) => req.headers.cookie === 'portos_auth=synthetic-human'
+ || req.headers.authorization === 'Bearer synthetic-agent',
+}));
+vi.mock('../services/settings.js', () => ({
+ settingsEvents: new EventEmitter(), getSettings: async () => ({}),
+}));
+vi.mock('../services/instanceIdentity.js', () => ({ loadData: async () => ({ peers: [] }) }));
+vi.mock('../lib/securityAuditLog.js', () => ({ logSecurityEvent: vi.fn() }));
+
vi.mock('../services/apps.js', () => ({
getActiveApps: vi.fn(async () => mocks.activeApps),
}));
@@ -44,10 +60,15 @@ vi.mock('../lib/fileUtils.js', async (importOriginal) => ({
}));
import gsdRoutes from './gsd.js';
+import { authGate, hostControlRouteGate } from '../services/authGate.js';
-function makeApp() {
+function makeApp(address = '127.0.0.1') {
const app = express();
- app.use(express.json());
+ app.use((req, _res, next) => {
+ Object.defineProperty(req.socket, 'remoteAddress', { value: address });
+ next();
+ });
+ app.use(authGate, hostControlRouteGate, express.json());
app.use('/api/cos/gsd', gsdRoutes);
app.use(errorMiddleware);
return app;
@@ -60,8 +81,10 @@ describe('GSD routes', () => {
beforeEach(async () => {
vi.clearAllMocks();
+ mocks.getGsdProject.mockReset();
+ mocks.authEnabled = false;
app = makeApp();
- repoPath = await mkdtemp(join(tmpdir(), 'portos-gsd-route-'));
+ repoPath = await realpath(await mkdtemp(join(tmpdir(), 'portos-gsd-route-')));
planningPath = join(repoPath, '.planning');
await mkdir(planningPath);
mocks.activeApps = [{ id: 'app-1', name: 'Example App', repoPath }];
@@ -85,6 +108,88 @@ describe('GSD routes', () => {
expect(response.body).toEqual({ filename: 'PROJECT.md', content: '# Project\n' });
});
+ it.each(['leaf', 'directory'])('refuses a repository-controlled %s symlink before reading or writing outside', async (kind) => {
+ const outside = await mkdtemp(join(tmpdir(), 'portos-gsd-outside-'));
+ try {
+ const secret = join(outside, 'PROJECT.md');
+ await writeFile(secret, 'synthetic private content');
+ if (kind === 'directory') {
+ await rm(planningPath, { recursive: true });
+ await symlink(outside, planningPath, 'junction');
+ } else {
+ await symlink(secret, join(planningPath, 'PROJECT.md'));
+ }
+ const url = '/api/cos/gsd/projects/app-1/documents/PROJECT.md';
+ const read = await request(makeApp('192.0.2.10')).get(url);
+ const write = await request(app).put(url).send({ content: 'replacement' });
+ expect(read.status).toBe(400);
+ expect(read.body.code).toBe('PATH_TRAVERSAL');
+ expect(write.status).toBe(400);
+ expect(write.body.code).toBe('PATH_TRAVERSAL');
+ expect(mocks.atomicWrite).not.toHaveBeenCalled();
+ expect(mocks.stageFiles).not.toHaveBeenCalled();
+ expect(await readFile(secret, 'utf8')).toBe('synthetic private content');
+ } finally {
+ await rm(outside, { recursive: true, force: true });
+ }
+ });
+
+ it.each(['PROJECT.md', 'config.json', 'phases/01/01-PLAN.md', 'phases'])('contains project-detail reads of %s through the real GSD service', async (relativePath) => {
+ const outside = await mkdtemp(join(tmpdir(), 'portos-gsd-detail-'));
+ try {
+ const target = join(outside, 'private.txt');
+ await writeFile(target, 'synthetic private content');
+ await mkdir(join(planningPath, 'phases', '01'), { recursive: true });
+ if (relativePath === 'phases') {
+ await rm(join(planningPath, 'phases'), { recursive: true });
+ await symlink(outside, join(planningPath, 'phases'), 'junction');
+ } else {
+ await symlink(target, join(planningPath, relativePath));
+ }
+ const service = await vi.importActual('../services/gsdService.js');
+ mocks.getGsdProject.mockImplementation(service.getGsdProject);
+ mocks.activeApps[0].id = repoPath.split(/[\\/]/).pop(); // Unique cache key for this synthetic project.
+ const response = await request(app).get(`/api/cos/gsd/projects/${encodeURIComponent(mocks.activeApps[0].id)}`);
+ expect(response.status).toBe(400);
+ expect(response.body.code).toBe('PATH_TRAVERSAL');
+ expect(JSON.stringify(response.body)).not.toContain('synthetic private content');
+ } finally {
+ await rm(outside, { recursive: true, force: true });
+ }
+ });
+
+ it('reads a regular project and nested phase through a symlinked configured repository root', async () => {
+ const alias = join(repoPath, 'repo-alias');
+ await symlink(repoPath, alias, 'junction');
+ mocks.activeApps[0].repoPath = alias;
+ mocks.activeApps[0].id = repoPath.split(/[\\/]/).pop();
+ await writeFile(join(planningPath, 'PROJECT.md'), '# Synthetic Project');
+ await mkdir(join(planningPath, 'phases', '01'), { recursive: true });
+ await writeFile(join(planningPath, 'phases', '01', '01-PLAN.md'), '- [ ] Synthetic task');
+ const service = await vi.importActual('../services/gsdService.js');
+ mocks.getGsdProject.mockImplementation(service.getGsdProject);
+ const response = await request(app).get(`/api/cos/gsd/projects/${encodeURIComponent(mocks.activeApps[0].id)}`);
+ expect(response.status).toBe(200);
+ expect(response.body.projectDoc.raw).toBe('# Synthetic Project');
+ expect(response.body.phases[0].plans[0].tasks).toEqual([{ completed: false, text: 'Synthetic task' }]);
+ });
+
+ it('preserves verified human and agent writes while refusing anonymous remote writes', async () => {
+ const remote = makeApp('192.0.2.10');
+ const url = '/api/cos/gsd/projects/app-1/documents/STATE.md';
+ expect((await request(remote).put(url).send({ content: 'blocked' })).status).toBe(403);
+ expect(mocks.atomicWrite).not.toHaveBeenCalled();
+ mocks.authEnabled = true;
+ for (const [header, value] of [
+ ['Cookie', 'portos_auth=synthetic-human'],
+ ['Authorization', 'Bearer synthetic-agent'],
+ ]) {
+ const response = await request(remote).put(url).set(header, value).send({ content: '# Authorized' });
+ expect(response.status).toBe(200);
+ }
+ expect(mocks.atomicWrite).toHaveBeenCalledTimes(2);
+ });
+
it('rejects unallowlisted and traversal document names before side effects', async () => {
const unallowlisted = await request(app)
.put('/api/cos/gsd/projects/app-1/documents/NOTES.md')
diff --git a/server/services/gsdPaths.js b/server/services/gsdPaths.js
new file mode 100644
index 0000000000..981239bb6b
--- /dev/null
+++ b/server/services/gsdPaths.js
@@ -0,0 +1,21 @@
+/** Repository-controlled planning files must never redirect host file access. */
+import { realpath } from 'fs/promises'
+import { join } from 'path'
+import { isSymlinkFreeRepoPath } from '../lib/repoPublishPath.js'
+import { ServerError } from '../lib/errorHandler.js'
+
+export async function resolveGsdPath(repoPath, relativePath = '', leaf = 'file') {
+ const root = await realpath(repoPath).catch(err => {
+ if (err.code === 'ENOENT') return null
+ throw err
+ })
+ if (!root) return null
+ const target = join(root, '.planning', relativePath)
+ // Use the same no-symlink policy as repository publishing, including dangling
+ // leaves and missing destinations. A symlink at the configured repo root is
+ // legitimate; links below that root are untrusted repository content.
+ if (!await isSymlinkFreeRepoPath(root, target, { leaf })) {
+ throw new ServerError('Invalid planning path', { status: 400, code: 'PATH_TRAVERSAL' })
+ }
+ return target
+}
diff --git a/server/services/gsdService.js b/server/services/gsdService.js
index dc9ef50685..5ae2cf5ffa 100644
--- a/server/services/gsdService.js
+++ b/server/services/gsdService.js
@@ -9,6 +9,7 @@ import { readFile, readdir, stat } from 'fs/promises'
import { join } from 'path'
import { createHash } from 'crypto'
import { getActiveApps } from './apps.js'
+import { resolveGsdPath } from './gsdPaths.js'
// 30-second TTL cache per app
const projectCache = new Map()
@@ -46,7 +47,9 @@ function hashId(section, text) {
/**
* Safely read a file, returning null if it doesn't exist
*/
-async function safeReadFile(filePath) {
+async function safeReadFile(repoPath, relativePath) {
+ const filePath = await resolveGsdPath(repoPath, relativePath)
+ if (!filePath) return null
const content = await readFile(filePath, 'utf-8').catch(err => {
if (err.code === 'ENOENT') return null
throw err
@@ -74,13 +77,14 @@ export async function scanForGsdProjects() {
for (const app of apps) {
if (!app.repoPath) continue
- const planningPath = join(app.repoPath, '.planning')
+ const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
+ if (!planningPath) continue
const planningInfo = await safeStat(planningPath)
if (planningInfo?.isDirectory()) {
- const roadmapInfo = await safeStat(join(planningPath, 'ROADMAP.md'))
- const stateInfo = await safeStat(join(planningPath, 'STATE.md'))
- const concernsInfo = await safeStat(join(planningPath, 'CONCERNS.md'))
+ const roadmapInfo = await safeStat(await resolveGsdPath(app.repoPath, 'ROADMAP.md'))
+ const stateInfo = await safeStat(await resolveGsdPath(app.repoPath, 'STATE.md'))
+ const concernsInfo = await safeStat(await resolveGsdPath(app.repoPath, 'CONCERNS.md'))
projects.push({
appId: app.id,
@@ -101,8 +105,8 @@ export async function scanForGsdProjects() {
/**
* Parse ROADMAP.md to extract milestone table rows
*/
-export async function parseRoadmapMd(filePath) {
- const content = await safeReadFile(filePath)
+export async function parseRoadmapMd(repoPath, relativePath) {
+ const content = await safeReadFile(repoPath, relativePath)
if (!content) return null
const milestones = []
@@ -131,8 +135,8 @@ export async function parseRoadmapMd(filePath) {
/**
* Parse STATE.md to extract YAML frontmatter
*/
-export async function parseStateMd(filePath) {
- const content = await safeReadFile(filePath)
+export async function parseStateMd(repoPath, relativePath) {
+ const content = await safeReadFile(repoPath, relativePath)
if (!content) return null
const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
@@ -154,8 +158,8 @@ export async function parseStateMd(filePath) {
/**
* Parse CONCERNS.md to extract sections with severity
*/
-export async function parseConcernsMd(filePath) {
- const content = await safeReadFile(filePath)
+export async function parseConcernsMd(repoPath, relativePath) {
+ const content = await safeReadFile(repoPath, relativePath)
if (!content) return null
const sections = []
@@ -235,14 +239,15 @@ function parsePlanContent(content) {
* Scan phase directory for *-PLAN.md files (e.g. 01-01-PLAN.md, 03-02-PLAN.md)
* Returns array of sub-plans sorted by filename
*/
-export async function parsePhasePlans(phasePath) {
+export async function parsePhasePlans(repoPath, relativePath) {
+ const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
const entries = await readdir(phasePath).catch(() => [])
const planFiles = entries.filter(f => f.endsWith('-PLAN.md')).sort()
if (planFiles.length === 0) return []
const plans = []
for (const filename of planFiles) {
- const content = await safeReadFile(join(phasePath, filename))
+ const content = await safeReadFile(repoPath, join(relativePath, filename))
if (!content) continue
plans.push({ filename, ...parsePlanContent(content) })
}
@@ -252,14 +257,15 @@ export async function parsePhasePlans(phasePath) {
/**
* Parse SUMMARY.md files in a phase directory
*/
-export async function parsePhaseSummaries(phasePath) {
+export async function parsePhaseSummaries(repoPath, relativePath) {
+ const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
const entries = await readdir(phasePath).catch(() => [])
const summaryFiles = entries.filter(f => f.endsWith('-SUMMARY.md')).sort()
if (summaryFiles.length === 0) return []
const summaries = []
for (const filename of summaryFiles) {
- const content = await safeReadFile(join(phasePath, filename))
+ const content = await safeReadFile(repoPath, join(relativePath, filename))
if (!content) continue
summaries.push({ filename, ...parsePlanContent(content) })
}
@@ -269,12 +275,13 @@ export async function parsePhaseSummaries(phasePath) {
/**
* Scan phase directory for *-VERIFICATION.md (e.g. 01-VERIFICATION.md)
*/
-export async function parseVerification(phasePath) {
+export async function parseVerification(repoPath, relativePath) {
+ const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
const entries = await readdir(phasePath).catch(() => [])
const verifyFile = entries.find(f => f.endsWith('-VERIFICATION.md'))
if (!verifyFile) return null
- const content = await safeReadFile(join(phasePath, verifyFile))
+ const content = await safeReadFile(repoPath, join(relativePath, verifyFile))
if (!content) return null
let status = 'unknown'
@@ -292,12 +299,13 @@ export async function parseVerification(phasePath) {
/**
* Scan phase directory for *-RESEARCH.md (e.g. 01-RESEARCH.md)
*/
-export async function parsePhaseResearch(phasePath) {
+export async function parsePhaseResearch(repoPath, relativePath) {
+ const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
const entries = await readdir(phasePath).catch(() => [])
const researchFile = entries.find(f => f.endsWith('-RESEARCH.md'))
if (!researchFile) return null
- const content = await safeReadFile(join(phasePath, researchFile))
+ const content = await safeReadFile(repoPath, join(relativePath, researchFile))
if (!content) return null
return { filename: researchFile, raw: content }
}
@@ -313,28 +321,29 @@ export async function getGsdProject(appIdOrPath) {
const app = apps.find(a => a.id === appIdOrPath || a.repoPath === appIdOrPath)
if (!app) return null
- const planningPath = join(app.repoPath, '.planning')
+ const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
+ if (!planningPath) return null
const planningInfo = await safeStat(planningPath)
if (!planningInfo?.isDirectory()) return null
- const roadmap = await parseRoadmapMd(join(planningPath, 'ROADMAP.md'))
- const state = await parseStateMd(join(planningPath, 'STATE.md'))
- const concerns = await parseConcernsMd(join(planningPath, 'CONCERNS.md'))
- const projectDoc = await safeReadFile(join(planningPath, 'PROJECT.md'))
+ const roadmap = await parseRoadmapMd(app.repoPath, 'ROADMAP.md')
+ const state = await parseStateMd(app.repoPath, 'STATE.md')
+ const concerns = await parseConcernsMd(app.repoPath, 'CONCERNS.md')
+ const projectDoc = await safeReadFile(app.repoPath, 'PROJECT.md')
// Scan for phase directories
const phases = []
- const phasesDir = join(planningPath, 'phases')
+ const phasesDir = await resolveGsdPath(app.repoPath, 'phases', 'dir')
const phasesDirInfo = await safeStat(phasesDir)
if (phasesDirInfo?.isDirectory()) {
const entries = await readdir(phasesDir, { withFileTypes: true })
for (const entry of entries) {
if (!entry.isDirectory()) continue
- const phasePath = join(phasesDir, entry.name)
- const plans = await parsePhasePlans(phasePath)
- const summaries = await parsePhaseSummaries(phasePath)
- const verification = await parseVerification(phasePath)
- const research = await parsePhaseResearch(phasePath)
+ const phasePath = join('phases', entry.name)
+ const plans = await parsePhasePlans(app.repoPath, phasePath)
+ const summaries = await parsePhaseSummaries(app.repoPath, phasePath)
+ const verification = await parseVerification(app.repoPath, phasePath)
+ const research = await parsePhaseResearch(app.repoPath, phasePath)
const totalTasks = plans.reduce((sum, p) => sum + p.tasks.length, 0)
const completedTasks = plans.reduce((sum, p) => sum + p.tasks.filter(t => t.completed).length, 0)
phases.push({
@@ -351,7 +360,7 @@ export async function getGsdProject(appIdOrPath) {
}
// Read config if present
- const configContent = await safeReadFile(join(planningPath, 'config.json'))
+ const configContent = await safeReadFile(app.repoPath, 'config.json')
const config = configContent ? JSON.parse(configContent) : null
const result = {