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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { EventEmitter } from 'events';
import { resolve } from 'path';
import express from 'express';
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { request } from '../lib/testHelper.js';
import { errorEvents, errorMiddleware } from '../lib/errorHandler.js';
import { DEV_PROXY_CLIENT_ADDRESS_HEADER } from '../../lib/portosAuthCore.js';
import { ALLOWED_COMMANDS } from '../lib/commandSecurity.js';
vi.mock('../services/apps.js', () => ({ getAppById: vi.fn() }));
import { getAppById } from '../services/apps.js';
import * as pm2Service from '../services/pm2.js';
const spawnMock = vi.hoisted(() => vi.fn());
vi.mock('../lib/childProcess.js', async (importOriginal) => ({
...await importOriginal(),
spawn: spawnMock,
}));
vi.mock('../services/history.js', () => ({
logAction: vi.fn(),
}));
// Command output reaches only subscribed sockets (#12019); the route never
// touches the global io instance.
vi.mock('../services/socket.js', () => ({
broadcastToCommandSubscribers: vi.fn(),
}));
vi.mock('../services/pm2.js', () => ({
listProcesses: vi.fn().mockResolvedValue([]),
listProcessesStrict: vi.fn().mockResolvedValue([]),
stopApp: vi.fn().mockResolvedValue({ success: true }),
restartApp: vi.fn().mockResolvedValue({ success: true }),
clearJlistCache: vi.fn(),
}));
vi.mock('../lib/workspaceRoots.js', () => ({
isWithinAllowedRoots: vi.fn(),
outsideAllowedRootsMessage: vi.fn((realPath) => `workspacePath is outside allowed directories: ${realPath}`),
}));
vi.mock('fs', async (importOriginal) => {
const actual = await importOriginal();
return {
...actual,
existsSync: vi.fn(),
statSync: vi.fn(),
realpathSync: vi.fn(),
};
});
vi.mock('../services/auth.js', async () => {
const { extractToken, extractTokens } = await import('../../lib/portosAuthCore.js');
const verifySession = vi.fn(async token => token === 'example-operator-session');
return {
extractToken,
isAuthEnabled: vi.fn().mockResolvedValue(false),
verifySession,
verifyRequestSession: async (req) => {
for (const token of extractTokens(req)) if (await verifySession(token)) return token;
return null;
},
verifyPassword: vi.fn(async password => password === 'example-peer-password'),
};
});
vi.mock('../services/settings.js', () => ({
getSettings: vi.fn().mockResolvedValue({}),
settingsEvents: new EventEmitter(),
}));
import { authGate } from '../services/authGate.js';
import { broadcastToCommandSubscribers } from '../services/socket.js';
import { logAction } from '../services/history.js';
import { isAuthEnabled } from '../services/auth.js';
import { existsSync, realpathSync, statSync } from 'fs';
import { isWithinAllowedRoots } from '../lib/workspaceRoots.js';
import commandsRoutes from './commands.js';
const WORKSPACE_PATH = resolve('fixtures', 'command-workspace');
const OUTSIDE_PATH = resolve('fixtures', '..', 'outside-workspace');
function createChildProcess() {
const child = new EventEmitter();
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.exitCode = null;
child.signalCode = null;
child.kill = vi.fn();
return child;
}
function createApp(io = { emit: vi.fn() }, { remoteAddress, withAuthGate = true } = {}) {
const app = express();
app.set('io', io);
app.use(express.json());
// Production parses form bodies globally (server/index.js), which is what
// makes a cross-site <form method=POST> a no-preflight attack path.
app.use(express.urlencoded({ extended: true }));
if (remoteAddress !== undefined) app.use((req, _res, next) => {
// Model the server's socket observation, never an HTTP header.
Object.defineProperty(req.socket, 'remoteAddress', { value: remoteAddress });
next();
});
if (withAuthGate) app.use(authGate);
app.use('/api/commands', commandsRoutes);
app.use(errorMiddleware);
return { app, io };
}
function allowWorkspace(realPath = WORKSPACE_PATH) {
existsSync.mockReturnValue(true);
statSync.mockReturnValue({ isDirectory: () => true });
realpathSync.mockReturnValue(realPath);
isWithinAllowedRoots.mockReturnValue(true);
}
describe('commands routes', () => {
const errorEventListener = vi.fn();
beforeAll(() => {
// Production registers the Socket.IO error bridge. Keep EventEmitter's
// reserved `error` event from throwing while error responses are tested.
errorEvents.on('error', errorEventListener);
});
afterAll(() => {
errorEvents.off('error', errorEventListener);
});
beforeEach(() => {
vi.clearAllMocks();
isAuthEnabled.mockResolvedValue(false);
});
afterEach(() => {
vi.restoreAllMocks();
});
it('reads the selected PM2 home, preserves unavailable status, and applies scoped actions', async () => {
getAppById.mockResolvedValue({ id: 'app-a', pm2Home: '/example/pm2' });
pm2Service.listProcessesStrict.mockResolvedValue([{ name: 'example-api', status: 'online' }]);
const { app } = createApp(undefined, { remoteAddress: '127.0.0.1' });
const list = await request(app).get('/api/commands/processes?appId=app-a');
expect(list.status).toBe(200);
expect(pm2Service.listProcessesStrict).toHaveBeenLastCalledWith('/example/pm2');
const result = await request(app).post('/api/commands/processes/example-api/action').send({ action: 'stop', appId: 'app-a' });
expect(result.status).toBe(200);
expect(pm2Service.stopApp).toHaveBeenCalledWith('example-api', '/example/pm2');
expect(result.body.processes).toEqual(list.body);
pm2Service.listProcessesStrict.mockResolvedValue(null);
expect((await request(app).get('/api/commands/processes?appId=app-a')).status).toBe(503);
});
it('preserves host-control and command-policy gates on process actions', async () => {
const remote = createApp(undefined, { remoteAddress: '192.0.2.10' }).app;
expect((await request(remote).post('/api/commands/processes/example-api/action').send({ action: 'stop' })).status).toBe(403);
const local = createApp(undefined, { remoteAddress: '127.0.0.1' }).app;
expect((await request(local).post('/api/commands/processes/all/action').send({ action: 'stop' })).status).toBe(403);
expect(pm2Service.stopApp).not.toHaveBeenCalled();
});
describe('host-control authorization through the real auth gate', () => {
const basic = `Basic ${Buffer.from(':example-peer-password').toString('base64')}`;
it.each([
['password-free remote peer', false, {}],
['spoofed forwarding headers', false, { 'X-Forwarded-For': '127.0.0.1', 'X-Real-IP': '::1', [DEV_PROXY_CLIENT_ADDRESS_HEADER]: '127.0.0.1' }],
['authenticated Basic peer', true, { Authorization: basic }],
['unauthenticated password-protected peer', true, {}],
['invalid operator session', true, { Authorization: 'Bearer invalid-session' }],
])('rejects %s before spawning or stopping a process', async (_name, enabled, headers) => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const local = createApp().app;
const started = await request(local).post('/api/commands/execute').send({ command: 'pwd' });
expect(started.status).toBe(202);
spawnMock.mockClear();
isAuthEnabled.mockResolvedValue(enabled);
const { app } = createApp(undefined, { remoteAddress: '192.0.2.10' });
app.set('trust proxy', true);
for (const path of ['/api/commands/execute', `/api/commands/${started.body.commandId}/stop`]) {
const pending = request(app).post(path).send({ command: 'npx --yes example-package' });
for (const [key, value] of Object.entries(headers)) pending.set(key, value);
const response = await pending;
expect(response.status).toBe(enabled && !headers.Authorization?.startsWith('Basic') ? 401 : 403);
expect(response.body.code).toBe(response.status === 401 ? 'AUTH_REQUIRED' : 'HOST_CONTROL_FORBIDDEN');
}
expect(spawnMock).not.toHaveBeenCalled();
expect(child.kill).not.toHaveBeenCalled();
child.emit('close', 0);
});
it.each(['192.0.2.10', 'unknown', '127.0.0.1, 192.0.2.10'])(
'rejects a dev-proxied nonlocal or ambiguous caller %s', async proxyClient => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const started = await request(app).post('/api/commands/execute').send({ command: 'pwd' });
expect(started.status).toBe(202);
spawnMock.mockClear();
for (const path of ['/api/commands/execute', `/api/commands/${started.body.commandId}/stop`]) {
const response = await request(app).post(path)
.set(DEV_PROXY_CLIENT_ADDRESS_HEADER, proxyClient)
.set('X-Forwarded-For', '127.0.0.1')
.send({ command: 'npx --yes example-package' });
expect(response.status).toBe(403);
expect(response.body.code).toBe('HOST_CONTROL_FORBIDDEN');
}
expect(spawnMock).not.toHaveBeenCalled();
expect(child.kill).not.toHaveBeenCalled();
child.emit('close', 0);
},
);
// #8707: the user's own browser relays a hidden form from any web page onto
// loopback, where password-free host control trusts the socket peer.
it.each([false, true])('refuses a cross-site form POST from the loopback browser (auth enabled: %s)', async enabled => {
isAuthEnabled.mockResolvedValue(enabled);
spawnMock.mockReturnValue(createChildProcess());
const { app } = createApp(undefined, { remoteAddress: '127.0.0.1' });
const response = await request(app).post('/api/commands/execute')
.set('Content-Type', 'application/x-www-form-urlencoded')
.set('Origin', 'https://attacker.example')
.set('Sec-Fetch-Site', 'cross-site')
.send('command=npx+--yes+example-package');
expect(response.status).toBe(403);
expect(response.body.code).toBe('CROSS_ORIGIN_BLOCKED');
expect(spawnMock).not.toHaveBeenCalled();
});
it('keeps a same-origin browser POST working on a password-free install', async () => {
spawnMock.mockReturnValue(createChildProcess());
const { app } = createApp(undefined, { remoteAddress: '127.0.0.1' });
const probe = await request(app).get('/api/commands/allowed');
expect(probe.status).toBe(200);
const started = await request(app).post('/api/commands/execute')
.set('Origin', 'http://localhost:5554')
.set('Sec-Fetch-Site', 'same-origin')
.send({ command: 'pwd' });
expect(started.status).toBe(202);
expect(spawnMock).toHaveBeenCalledTimes(1);
});
it('keeps local UI command control through the dev proxy', async () => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const started = await request(app).post('/api/commands/execute')
.set(DEV_PROXY_CLIENT_ADDRESS_HEADER, '::ffff:127.0.0.1').send({ command: 'pwd' });
expect(started.status).toBe(202);
const stopped = await request(app).post(`/api/commands/${started.body.commandId}/stop`)
.set(DEV_PROXY_CLIENT_ADDRESS_HEADER, '::1');
expect(stopped.status).toBe(200);
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
});
it.each(['127.0.0.1', '127.0.0.2', '::1', '::ffff:127.0.0.1'])(
'keeps password-free local command control on %s', async remoteAddress => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp(undefined, { remoteAddress });
const started = await request(app).post('/api/commands/execute').send({ command: 'pwd' });
expect(started.status).toBe(202);
const stopped = await request(app).post(`/api/commands/${started.body.commandId}/stop`);
expect(stopped.status).toBe(200);
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
},
);
it.each([
['Cookie', 'portos_auth=example-operator-session'],
['Authorization', 'Bearer example-operator-session'],
])('allows authenticated operator commands through %s', async (header, value) => {
isAuthEnabled.mockResolvedValue(true);
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp(undefined, { remoteAddress: '192.0.2.10' });
const started = await request(app).post('/api/commands/execute').set(header, value).set(DEV_PROXY_CLIENT_ADDRESS_HEADER, '192.0.2.10').send({ command: 'pwd' });
expect(started.status).toBe(202);
const stopped = await request(app).post(`/api/commands/${started.body.commandId}/stop`).set(header, value);
expect(stopped.status).toBe(200);
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
});
it('fails closed when mounted without the global auth gate', async () => {
const { app } = createApp(undefined, { withAuthGate: false });
const response = await request(app).post('/api/commands/execute').send({ command: 'pwd' });
expect(response.status).toBe(403);
expect(response.body.code).toBe('HOST_CONTROL_FORBIDDEN');
expect(spawnMock).not.toHaveBeenCalled();
});
});
describe('POST /api/commands/execute', () => {
it('rejects a missing command before touching the filesystem or process boundary', async () => {
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(400);
expect(response.body.code).toBe('VALIDATION_ERROR');
expect(existsSync).not.toHaveBeenCalled();
expect(spawnMock).not.toHaveBeenCalled();
});
it('rejects a workspace path that does not exist', async () => {
existsSync.mockReturnValue(false);
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(400);
expect(response.body.code).toBe('INVALID_PATH');
expect(spawnMock).not.toHaveBeenCalled();
});
it('rejects a workspace path that is not a directory', async () => {
existsSync.mockReturnValue(true);
statSync.mockReturnValue({ isDirectory: () => false });
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(400);
expect(response.body.code).toBe('INVALID_PATH');
expect(spawnMock).not.toHaveBeenCalled();
});
it('rejects a symlink target outside the allowed workspace roots', async () => {
existsSync.mockReturnValue(true);
statSync.mockReturnValue({ isDirectory: () => true });
realpathSync.mockReturnValue(OUTSIDE_PATH);
isWithinAllowedRoots.mockReturnValue(false);
vi.spyOn(console, 'error').mockImplementation(() => {});
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(400);
expect(response.body.code).toBe('INVALID_PATH');
expect(realpathSync).toHaveBeenCalledWith(WORKSPACE_PATH);
expect(isWithinAllowedRoots).toHaveBeenCalledWith(OUTSIDE_PATH);
expect(spawnMock).not.toHaveBeenCalled();
});
it('returns FORBIDDEN for a command outside the operator allowlist', async () => {
allowWorkspace();
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'definitely-not-allowed', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(403);
expect(response.body.code).toBe('FORBIDDEN');
expect(spawnMock).not.toHaveBeenCalled();
expect(broadcastToCommandSubscribers).not.toHaveBeenCalledWith(
expect.stringMatching(/^command:/),
expect.anything(),
);
});
it('starts an allowed command and relays its output and completion over Socket.IO', async () => {
allowWorkspace();
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app, io } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(202);
expect(response.body).toEqual({ commandId: expect.any(String), status: 'started' });
expect(spawnMock).toHaveBeenCalledWith('pwd', [], expect.objectContaining({
cwd: WORKSPACE_PATH,
shell: false,
}));
child.stdout.emit('data', Buffer.from('workspace output'));
child.stderr.emit('data', Buffer.from('workspace warning'));
child.emit('close', 0);
const eventPrefix = `command:${response.body.commandId}`;
expect(broadcastToCommandSubscribers).toHaveBeenCalledWith(`${eventPrefix}:data`, {
data: 'workspace output',
stream: 'stdout',
});
expect(broadcastToCommandSubscribers).toHaveBeenCalledWith(`${eventPrefix}:data`, {
data: 'workspace warning',
stream: 'stderr',
});
expect(broadcastToCommandSubscribers).toHaveBeenCalledWith(`${eventPrefix}:complete`, expect.objectContaining({
success: true,
exitCode: 0,
output: 'workspace outputworkspace warning',
}));
// Scoped to command subscribers — never the global io broadcast (#12019).
expect(io.emit).not.toHaveBeenCalled();
});
it('redacts secrets in every copy of the output: the streamed chunk, the completion frame, and the history row (#12019)', async () => {
allowWorkspace();
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'git config --list', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(202);
child.stdout.emit('data', Buffer.from('user.name=Example\ngithub.token=ghp_example_value\n'));
// A value split across two chunks is still redacted once the buffer is whole.
child.stdout.emit('data', Buffer.from('API_TO'));
child.stdout.emit('data', Buffer.from('KEN=split-example\n'));
child.emit('close', 0);
const eventPrefix = `command:${response.body.commandId}`;
const frames = broadcastToCommandSubscribers.mock.calls
.filter(([event]) => event === `${eventPrefix}:data`)
.map(([, payload]) => payload.data);
expect(frames[0]).toBe('user.name=Example\ngithub.token=[REDACTED]\n');
expect(frames.join('')).not.toContain('ghp_example_value');
const [, completion] = broadcastToCommandSubscribers.mock.calls.find(([event]) => event === `${eventPrefix}:complete`);
expect(completion.output).toBe('user.name=Example\ngithub.token=[REDACTED]\nAPI_TOKEN=[REDACTED]\n');
const [, , , historyRow] = logAction.mock.calls.find(([type, , , details]) => type === 'command' && details.exitCode === 0);
expect(historyRow.output).toBe('user.name=Example\ngithub.token=[REDACTED]\nAPI_TOKEN=[REDACTED]\n');
expect(JSON.stringify(logAction.mock.calls)).not.toMatch(/ghp_example_value|split-example/);
});
it('invokes onComplete exactly once with error details when child process fails to spawn, even if close emits after error', async () => {
allowWorkspace();
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const { logAction } = await import('../services/history.js');
const response = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', workspacePath: WORKSPACE_PATH });
expect(response.status).toBe(202);
const commandId = response.body.commandId;
const eventPrefix = `command:${commandId}`;
// Simulate spawn error: when a binary is not found, the error event fires
const spawnError = new Error('ENOENT: no such file or directory');
child.emit('error', spawnError);
// Node.js guarantees that close always emits after error. Verify we handle it safely.
child.emit('close', null);
// Verify onComplete was called exactly once with the error details
expect(broadcastToCommandSubscribers).toHaveBeenCalledWith(`${eventPrefix}:complete`, {
success: false,
error: 'ENOENT: no such file or directory',
exitCode: 1,
});
// Count completion events to ensure only one was emitted
const completionCalls = broadcastToCommandSubscribers.mock.calls.filter(
call => call[0] === `${eventPrefix}:complete`
);
expect(completionCalls).toHaveLength(1);
// Verify history was logged exactly once
expect(logAction).toHaveBeenCalledTimes(1);
expect(logAction).toHaveBeenCalledWith(
'command',
null,
expect.any(String),
expect.objectContaining({ command: 'pwd' }),
false,
'ENOENT: no such file or directory'
);
});
});
describe('POST /api/commands/:id/stop', () => {
it('terminates an active command and reports it stopped', async () => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const started = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd' });
const response = await request(app)
.post(`/api/commands/${started.body.commandId}/stop`);
expect(started.status).toBe(202);
expect(response.status).toBe(200);
expect(response.body).toEqual({ stopped: true });
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
// The child has not closed yet (it may be ignoring SIGTERM): a repeat
// stop inside the grace window is absorbed, not reported as gone (#12021).
const again = await request(app)
.post(`/api/commands/${started.body.commandId}/stop`);
expect(again.status).toBe(200);
expect(again.body).toEqual({ stopped: true });
expect(child.kill).toHaveBeenCalledTimes(1);
child.emit('close', null, 'SIGTERM');
const afterClose = await request(app)
.post(`/api/commands/${started.body.commandId}/stop`);
expect(afterClose.status).toBe(404);
expect(afterClose.body.code).toBe('NOT_ACTIVE');
expect(broadcastToCommandSubscribers).toHaveBeenCalledWith(
`command:${started.body.commandId}:complete`,
expect.objectContaining({ success: false, signal: 'SIGTERM', stopped: true, error: 'Stopped (SIGTERM)' }),
);
});
it('accepts an optional per-command timeoutMs and rejects a non-positive one (#12021)', async () => {
const child = createChildProcess();
spawnMock.mockReturnValue(child);
const { app } = createApp();
const rejected = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', timeoutMs: 0 });
expect(rejected.status).toBe(400);
expect(spawnMock).not.toHaveBeenCalled();
const started = await request(app)
.post('/api/commands/execute')
.send({ command: 'pwd', timeoutMs: 60_000 });
expect(started.status).toBe(202);
child.emit('close', 0);
});
it('returns NOT_ACTIVE for an unknown command id', async () => {
const { app } = createApp();
const response = await request(app)
.post('/api/commands/missing-command/stop');
expect(response.status).toBe(404);
expect(response.body.code).toBe('NOT_ACTIVE');
});
});
it('GET /api/commands/allowed returns the sorted operator allowlist', async () => {
const { app } = createApp();
const response = await request(app).get('/api/commands/allowed');
expect(response.status).toBe(200);
expect(response.body).toEqual(Array.from(ALLOWED_COMMANDS).sort());
});
});