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

23.7 KB
Raw Blame
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());
  });
});